From c919a49da20290045f06e541229ff50a387c7f39 Mon Sep 17 00:00:00 2001 From: Patrick Durold Date: Thu, 7 Mar 2024 14:22:51 +0100 Subject: [PATCH 1/3] Add examples of arguments and options, based on my findings --- docs/types/command.md | 116 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 110 insertions(+), 6 deletions(-) diff --git a/docs/types/command.md b/docs/types/command.md index b8624454..879b8dae 100644 --- a/docs/types/command.md +++ b/docs/types/command.md @@ -15,6 +15,110 @@ 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 []'): + 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: = boolToString(input.option('option')) + exec: | + #!bash + echo "'${VERBATIM}'" + echo "'${YES_OR_NO}'" +``` + +For a boolean option, `input.option` will read a `'1'` if given, `''` (empty string) otherwise. + +``` +command('cmd [-iou]'): + env: + OPT_I: = input.option('i') + OPT_O: = input.option('o') + OPT_U: = input.option('u') +``` + +Sequence hortcut for defining multiple bool options. + +### Value options +``` +command('cmd [--option=]'): + env: + AS_OPTION: = input.option('option') + ... +``` + +### Mutually exclusive options +``` +command('cmd [-b|--bool] [-s=|--string=]'): + 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=]... (on|off)... ...'): +``` + +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 +129,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 +162,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 +181,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 From f7cc88ba236681992901bbe58a7f0245c0cd21d2 Mon Sep 17 00:00:00 2001 From: Patrick Date: Thu, 7 Mar 2024 14:45:11 +0100 Subject: [PATCH 2/3] Typo Co-authored-by: Kieren Evans --- docs/types/command.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/types/command.md b/docs/types/command.md index 879b8dae..733845eb 100644 --- a/docs/types/command.md +++ b/docs/types/command.md @@ -83,7 +83,7 @@ command('cmd [-iou]'): OPT_U: = input.option('u') ``` -Sequence hortcut for defining multiple bool options. +Sequence shortcut for defining multiple bool options. ### Value options ``` From 3dbd481ecf60063c6a59fad717f090c69ac8243e Mon Sep 17 00:00:00 2001 From: Patrick Durold Date: Thu, 7 Mar 2024 15:15:02 +0100 Subject: [PATCH 3/3] boolToString() belongs to docker-harness --- docs/types/command.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/types/command.md b/docs/types/command.md index 733845eb..ef08f3ea 100644 --- a/docs/types/command.md +++ b/docs/types/command.md @@ -66,7 +66,7 @@ as the last part in the command and must be read using `input.command(index)`, 0 command('cmd [--option]'): env: VERBATIM: = input.option('option') - YES_OR_NO: = boolToString(input.option('option')) + YES_OR_NO: = input.option('option') ? 'yes' : 'no' exec: | #!bash echo "'${VERBATIM}'" @@ -74,6 +74,8 @@ command('cmd [--option]'): ``` 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]'):