Documentation

Parser

How elements are parsed

Elements are parsed using usages and automatically added to your context variables. Commands and positional arguments become top-level variables, and options are grouped under options.

#!/usr/bin/env rash
#
# Usage: ./program [options] (start|stop|restart)
#
# Options:
#   --count=<n>  Number of iterations [default: 1]

- debug:
    msg: "{{ options }}"

- debug:
    msg: "{{ start }}"

Command parsing

Commands are parsed as false by default and when they are passed they will appear as true:

{
  "command1": true,
  "command2": false,
  "command3": false
}

Example: with the usage pattern ./program (start|stop|restart), if you call ./program start, the variables will be:

{
  "start": true,
  "stop": false,
  "restart": false
}

Note: Command with dashes are converted to underscores in the resulting JSON. E.g., ./program my-command:

{
  "my_command": true
}

A command that can occur more than once in a pattern, such as ./program go (up|down)..., is a count instead: ./program go up up gives "up": 2, "down": 0.

The - and -- commands are stored as _ and __: with ./program [--] <file>..., the call ./program -- -x gives "__": true, "file": ["-x"].

Option parsing

Options are grouped under the options key in the resulting JSON:

{
  "options": {
    "apply": false,
    "dry_run": false,
    "help": false,
    "number": "10",
    "timeout": null,
    "version": false,
    "q": true
  },
  "port": "443"
}

In the example above:

Boolean options not provided are false
Options with values have their string value (like "number": "10"); if a value option is given several times, the last value is kept
Options without default values that weren’t provided will be null
Options are keyed by their long name; short options without a long alias use their single-letter key (like "q": true)
Options with dashes are converted to underscores in the resulting JSON
Flags that can occur more than once ([-v...], [--verbose]...) are counts, 0 when not given

Special case - help: The help option is handled specially. If help is passed as an argument or option, the program will show all documentation and exit with a status code of 0 without running any task:

./program --help   # Shows help text and exits, if --help (or an alias like -h) is declared
./program help     # Same behavior if 'help' is defined as a command

A help option (--help, its alias, or a -h flag without a long name) shows the help wherever it appears before --, even if the other arguments are invalid. See Help and errors.

Default values for options

When you specify a default value for an option in the options section, that value will be used when the option isn’t explicitly provided in the command line. For example:

# Options:
#   --timeout=<seconds>    Connection timeout [default: 30]
#   --retries=<count>      Number of retry attempts [default: 3]

If your script is invoked without these options, the values in your script would be:

{
  "options": {
    "timeout": "30", // Default value applied
    "retries": "3" // Default value applied
  }
}

If you provide a different value in the command line, it overrides the default:

./script.rh --timeout=60

Would result in:

{
  "options": {
    "timeout": "60", // Command-line value overrides default
    "retries": "3" // Default value applied
  }
}

Positional argument parsing

Positional arguments are parsed as strings or arrays depending on whether they’re repeatable (followed by ..., inside a repeated group, or written more than once in a pattern). A positional that is repeatable in one usage pattern is an array in all of them:

{
  "argument": "value",
  "repeating_argument": ["value1", "value2", "value3"]
}

If a positional argument isn’t provided in the command line, it will be omitted from the variables JSON, so use the default filter for optional ones: {{ dest | default('.') }} or {{ files | default([]) }}.

Note: Positional arguments with dashes are converted to underscores in the resulting JSON. E.g., ./program <repeating-argument>...:

{
  "repeating_argument": ["value1", "value2", "value3"]
}

Examples:

For a usage pattern ./program <file>:
```
./program document.txt
```
Results in:
```
{
  "file": "document.txt"
}
```
Note: Uppercase arguments are converted to lowercase in the resulting JSON.

For usage pattern ./program FILE:
```
./program document.txt
```
Results in:
```
{
  "file": "document.txt"
}
```

For a usage pattern ./program <file>...:

./program file1.txt file2.txt file3.txt

Results in:

{
  "file": ["file1.txt", "file2.txt", "file3.txt"]
}

For a usage pattern ./program (<source> <dest>)...:

./program file1.txt dir1 file2.txt dir2

Results in:

{
  "source": ["file1.txt", "file2.txt"],
  "dest": ["dir1", "dir2"]
}

For a usage pattern ./program [--verbose] <command>:

./program --verbose start

Results in:

{
  "options": {
    "verbose": true
  },
  "command": "start"
}

Accessing parsed values in rash scripts

Within your rash script, you can access these values using standard variable access syntax:

#!/usr/bin/env -S rash --
#
# Usage: ./script.rh <name> [--count=<n>]
#
# Options:
#   --count=<n>  Number of iterations [default: 1]

- name: Print a greeting
  debug:
    msg: "Hello, {{ name }}! ({{ options.count }} times)"

The comment block must start right after the shebang line. When invoked with ./script.rh World --count=3, it prints Hello, World! (3 times). Without --count, the default 1 is used.