SimpleScripting::Argv Guide

Switches

Switches are defined as arrays; in the result, the key is the long (or, if not present, the short one) version name, as symbol (ie. :xxx):

['-x', '--xxx [VALUENAME]'[, description]]

If VALUENAME is not specified, the switch is considered a boolean, and evaluates to true/false.

If VALUENAME includes commas, eg.:

['-a', '--my-array V1,V2,...', 'Pass an array of values'] # definition
$ my_command -a 1,2,3                                     # command

The switch argument is automatically decoded into an array of strings, in this case {my_array: ["1", "2", "3"]}.

The switches -h and --help are added automatically.

Arguments

Arguments are defined as strings; in the result, the key is the name, as symbol (ie. :aaa).

'aaa'
'*aaa'
'[bbb]'/[*bbb]'

The star (*) indicates varargs; when there are brackets, indicates that the args are optional.
Brackets define optional arguments.
Optional arguments must follow mandatory ones.
Regular arguments and varargs can't be used together.

Method options

:long_help
:input:     for testing purposes; defaults to ARGV
:output:    for testing purposes; defaults to $stdout. IMPORTANT: if the value is different from
            $stdout, `:decode_argv` will not call :exit, instead, it will return (nil).

Commands

SOP supports "commands", which are top-level arguments, like git checkout (checkout being the command).

In order to define commands, use a Hash as first argument, for example:

decode_argv(
  'checkout' => {
    ['-q', '--quiet'],
    'branch'
  },
  'commit' => {
    ['-m', '--message']
  },
  long_help: 'This is the long help for git.',
)

When commands are defined, specifying one is required.
If a command is not specified (or the -h/--help switches are passed), then commands help is printed; for the above definition:

Valid commands:

  checkout, commit

Important note

While the library validate the user input, it doesn't do so on the (developer) definitions; behavior for ill definitions is undefined.