Improve command type documentation

docs/types/command.md

@@ -15,6 +15,112 @@ command('usage pattern', 'help page'):
     script
 ```
 
+## Options and arguments (usage pattern)
+
+`input.*` can also be used in expression filtered exec blocks (`|=`, see below). 
+
+### Arguments
+```
+command('cmd <required> [<optional>]'):
+  env:
+    REQUIRED: = input.argument('required')
+    OPTIONAL: = input.argument('optional')
+  exec: |
+    #!bash
+    echo "'${REQUIRED}'"
+    echo "'${OPTIONAL}'" 
+```
+Defines arguments. The command will not be recognized without required arguments.
+
+```
+command('cmd %'):
+  env:
+    ALL: = input.argument('%')
+  exec: |
+    #!bash
+    echo "'${ALL}'"
+```
+
+The special token `%` describes an argument that contains
+the rest of the input, it can only be the last character in the command.
+
+### Arguments with select values
+
+```
+command('cmd [on|off]'):
+  env:
+    OPTIONAL_ARG: = input.command(1)
+```
+or
+```
+command('cmd (on|off])'):
+  env:
+    REQUIRED_ARG: = input.command(1)
+```
+
+Defines arguments that can only have select values, these only work correctly
+as the last part in the command and must be read using `input.command(index)`, 0-based.
+
+### Boolean options
+```
+command('cmd [--option]'):
+  env:
+    VERBATIM: = input.option('option')
+    YES_OR_NO: = input.option('option') ? 'yes' : 'no'
+  exec: |
+    #!bash
+    echo "'${VERBATIM}'"
+    echo "'${YES_OR_NO}'" 
+```
+
+For a boolean option, `input.option` will read a `'1'` if given, `''` (empty string) otherwise.
+The Inviqa base docker harness contains a convenient `boolToString()` function that provides
+the yes/no conversion done here manually.  
+
+```
+command('cmd [-iou]'):
+  env:
+    OPT_I: = input.option('i')
+    OPT_O: = input.option('o')
+    OPT_U: = input.option('u')
+```
+
+Sequence shortcut for defining multiple bool options.
+
+### Value options
+```
+command('cmd [--option=<value>]'):
+  env:
+    AS_OPTION: = input.option('option')
+  ...
+```
+
+### Mutually exclusive options
+```
+command('cmd [-b|--bool] [-s=<value>|--string=<value>]'):
+  env:
+    BOOL_OPTION: = input.option('bool') || input.option('b')
+    VALUE_OPTION: = input.option('string') ?: input.option('s')
+  exec: |
+    #!bash
+    echo "'${BOOL_OPTION}'"
+    echo "'${VALUE_OPTION}'"
+```
+
+You can use these to define mutually exclusive options including long/shortform alternatives.
+Be aware these options are technically considered different options, so you have to read both if
+you're using them for long/short alternatives.
+
+### Technicalities
+
+The console parser builder is capable of building loops like this:
+```
+command('cmd [-v=<value>]... (on|off)... <arg>...'):
+```
+
+However, in all of these cases, either workspace or the console itself errors out because arrays are passed
+where strings are expected.
+
 ## Examples
 
 ### Hello world in bash
@@ -25,14 +131,14 @@ command('hello world'): |
   echo "Hello World"
 ```
 
-Only the usage pattern and body of the script are required, everything else is optional. Note the pipe after the header declaration to signify a multi-line string.
+Only the usage pattern and body of the script are required, everything else is optional. Note the pipe after the header declaration to signify a multi-line YAML string.
 
 ### Using environment variables
 
 ```
 command('hello from environment'):
   env:
-    - MESSAGE: Hello World
+    MESSAGE: Hello World
   exec: |
     #!bash
     echo "$MESSAGE"
@@ -58,8 +164,8 @@ attribute('aws'):
 
 command('assets download'):
   env:
-    - AWS_ID:  =@('aws.id')
-    - AWS_KEY: =@('aws.key')
+    AWS_ID:  =@('aws.id')
+    AWS_KEY: =@('aws.key')
   exec: |
     #!interpreter(workspace:/)|@
     passthru ws-aws s3 sync @('aws.s3') assets/development
@@ -77,8 +183,8 @@ attribute('aws'):
 
 command('assets download'):
   env:
-    - AWS_ID:  =@('aws.id')
-    - AWS_KEY: =@('aws.key')
+    AWS_ID:  =@('aws.id')
+    AWS_KEY: =@('aws.key')
   exec: |
     #!interpreter(workspace:/)|=
     passthru ws-aws s3 sync ={ @('aws.s3') ~ '/assets/development' } assets/development