mikaelpatel/Cosa — pull request #268 by jediunix (2014-11-28 19:28:34+00:00)
Title: Aligned shell help

The current Shell help is difficult to read. For example,

```
arduino:$ help
analogread all|ALL|vcc|PIN.. -- read analog pin(s)
args OPTS ARGS -- display options and arguments
blink MS -- turn led on and off
date [YEAR-MON-DAY HOUR:MIN:SEC] -- display or set the system date and time
delay MS -- delay for milliseconds
dump [-b|-d] ADDR [SIZE] -- dump memory block
echo [-n] STRING.. -- print a line of text
epoch -- display start time
digitalread all|ALL|led|PIN.. -- read digital pin(s)
digitaltoggle led|PIN -- toggle digital pin
digitalwrite led|PIN VALUE -- write digital pin
help -- list command help
idle -- display idle time
led on|off -- turn led on or off
logout -- logout from shell
memory -- display amount of free memory
micros -- clock in micro-seconds
millis -- clock in milli-seconds
owi scan PIN -- scan 1-wire bus
pinmode all|ALL|led|PIN [input|output|pullup] -- display or set pin mode
repeat [-t] COUNT [DELAY] COMMAND -- repeat command line
stty [eol=CR|LF|CRLF] -- display or set tty mode
tone off | FREQ [VOLUME [DURATION]] -- play tone
twi scan -- scan I2C bus
uptime -- seconds since latest date set or system start
arduino:$ help date
help: illegal command
```

This PR does the following:

1. Creates a *help separator* string that will appear between all commands/args and the help text. Default is **"-- "**.
2. Creates a *gap fill* character that is used to fill space between commands/args and the help separator. Default is **' '**.
3. Breaks up what was *help* into *args* and *help*.
4. Aligns the *help separator* of all output to the longest command/arg.
5. If the entire *line* is greater than 80 characters the *help separator* and *help* appears on the following line indented 4 spaces.
6. Shell::help will now handle an argument that is the command that help is desired for. If none is provided all commands are listed as before.

In addition, two helper macros provide for cleaner definition and reference of commands. They are https://github.com/jediunix/Cosa/blob/aligned-shell-help/cores/cosa/Cosa/Shell.hh#L27 and https://github.com/jediunix/Cosa/blob/aligned-shell-help/cores/cosa/Cosa/Shell.hh#L33. The current branch gives example of the usage at https://github.com/jediunix/Cosa/blob/aligned-shell-help/examples/Sandbox/CosaShell/Commands.cpp#L186 and https://github.com/jediunix/Cosa/blob/aligned-shell-help/examples/Sandbox/CosaShell/Commands.cpp#L716. **If you like this style I will apply it everywhere; if not I will remove it.**

Some examples of what help could look like beginning with the new default. (Wish GitHub would allow actual fixed width font!)

```
arduino:$ help
analogread all|ALL|vcc|PIN.. -- read analog pin(s)
args OPTS ARGS -- display options and arguments
blink MS -- turn led on and off
date [YEAR-MON-DAY HOUR:MIN:SEC]
-- display or set the system date and time
delay MS -- delay for milliseconds
dump [-b|-d] ADDR [SIZE] -- dump memory block
echo [-n] STRING.. -- print a line of text
epoch -- display start time
digitalread all|ALL|led|PIN.. -- read digital pin(s)
digitaltoggle led|PIN -- toggle digital pin
digitalwrite led|PIN VALUE -- write digital pin
help -- list command help
idle -- display idle time
led on|off -- turn led on or off
logout -- logout from shell
memory -- display amount of free memory
micros -- clock in micro-seconds
millis -- clock in milli-seconds
owi scan PIN -- scan 1-wire bus
pinmode all|ALL|led|PIN [input|output|pullup] -- display or set pin mode
repeat [-t] COUNT [DELAY] COMMAND -- repeat command line
stty [eol=CR|LF|CRLF] -- display or set tty mode
tone off | FREQ [VOLUME [DURATION]] -- play tone
twi scan -- scan I2C bus
uptime
-- seconds since latest date set or system start
arduino:$ help date
date [YEAR-MON-DAY HOUR:MIN:SEC] -- display or set the system date and time
```

```
arduino:$ help
analogread all|ALL|vcc|PIN.. : read analog pin(s)
args OPTS ARGS : display options and arguments
blink MS : turn led on and off
date [YEAR-MON-DAY HOUR:MIN:SEC]
: display or set the system date and time
delay MS : delay for milliseconds
dump [-b|-d] ADDR [SIZE] : dump memory block
echo [-n] STRING.. : print a line of text
epoch : display start time
digitalread all|ALL|led|PIN.. : read digital pin(s)
digitaltoggle led|PIN : toggle digital pin
digitalwrite led|PIN VALUE : write digital pin
help : list command help
idle : display idle time
led on|off : turn led on or off
logout : logout from shell
memory : display amount of free memory
micros : clock in micro-seconds
millis : clock in milli-seconds
owi scan PIN : scan 1-wire bus
pinmode all|ALL|led|PIN [input|output|pullup] : display or set pin mode
repeat [-t] COUNT [DELAY] COMMAND : repeat command line
stty [eol=CR|LF|CRLF] : display or set tty mode
tone off | FREQ [VOLUME [DURATION]] : play tone
twi scan : scan I2C bus
uptime
: seconds since latest date set or system start
arduino:$ help date
date [YEAR-MON-DAY HOUR:MIN:SEC] : display or set the system date and time
```

```
arduino:$ help
analogread all|ALL|vcc|PIN.. ................. : read analog pin(s)
args OPTS ARGS .............................. : display options and arguments
blink MS ..................................... : turn led on and off
date [YEAR-MON-DAY HOUR:MIN:SEC] .............
: display or set the system date and time
delay MS ..................................... : delay for milliseconds
dump [-b|-d] ADDR [SIZE] ..................... : dump memory block
echo [-n] STRING.. ........................... : print a line of text
epoch ........................................ : display start time
digitalread all|ALL|led|PIN.. ................ : read digital pin(s)
digitaltoggle led|PIN ........................ : toggle digital pin
digitalwrite led|PIN VALUE ................... : write digital pin
help ......................................... : list command help
idle ......................................... : display idle time
led on|off ................................... : turn led on or off
logout ....................................... : logout from shell
memory ....................................... : display amount of free memory
micros ....................................... : clock in micro-seconds
millis ....................................... : clock in milli-seconds
owi scan PIN ................................. : scan 1-wire bus
pinmode all|ALL|led|PIN [input|output|pullup] : display or set pin mode
repeat [-t] COUNT [DELAY] COMMAND ............ : repeat command line
stty [eol=CR|LF|CRLF] ........................ : display or set tty mode
tone off | FREQ [VOLUME [DURATION]] .......... : play tone
twi scan ..................................... : scan I2C bus
uptime .......................................
: seconds since latest date set or system start
arduino:$ help date
date [YEAR-MON-DAY HOUR:MIN:SEC] : display or set the system date and time
```