Documentation

Parser

How elements are parsed

Elements are parsed using usages and automatically added to your context variables. The parsed values are available as JSON objects within your script.

#!/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
}

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")
Options without default values that weren’t provided will be null
Short options are available with their single-letter key (like "q": true)
Options with dashes are converted to underscores in the resulting JSON

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:

./program --help   # Shows help text and exits
./program help     # Same behavior if 'help' is defined as a command

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:

{
  "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.

Note: Command 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 rash

# Usage: ./script.rh <name> [--count=<n>]
#
# Options:
#   --count=<n>  Number of iterations [default: 1]

- name: Print a greeting
  shell:
    cmd: echo "Hello, {{name}}! ({{options.count}} times)"

When invoked with ./script.rh World --count=3, it would print: Hello, World! (3 times)