command

If set, defines the base remctl command implemented by this backend. The primary use of this string is in usage and help output. If set, it will be added to the beginning of each command syntax description so that the help output will match the remctl command that the user actually runs.

commands

The value of this key should be an anonymous hash describing all of the commands that are supported. See below for the supported keys in the command configuration.

help_banner

If set, the value will be displayed as the first line of help output. Recommended best practice is to use a string of the form:

    <service> remctl help:
    

where <service> is something like "Event handling" or "User database" or whatever this set of commands generally does or manipulates.

The commands key, described above, takes a hash of properties for each subcommand supported by this backend. The possible keys in that hash are:

args_match

A reference to an array of regexes that must match the arguments to this function. Each element of the array is matched against the corresponding element in the array of arguments, and if the corresponding regular expression does not match, the command will be rejected with an error about an invalid argument. Set the regular expression to undef to not check the corresponding argument.

There is currently no way to check all arguments in commands that take any number of arguments.

args_max

The maximum number of arguments. If there are more than this number of arguments, run() will die with an error message without running the command.

args_min

The minimum number of arguments. If there are fewer than this number of arguments, run() will die with an error message without running the command.

code

A reference to the sub that implements this command. This sub will be called with the arguments passed on the command line as its arguments (possibly preceded by the options hash if the "options" parameter is set as described below). It should return the exit status that should be used by the backend as a whole: 0 for success and some non-zero value for an error condition. This sub should print to STDOUT and STDERR to communicate back to the remctl client.

nested

If set, indicates that this is a nested command. The value should be a nested hash of command definitions, the same as the parameter to the "commands" argument to new(). When this is set, the first argument to this command is taken to be a subcommand name, which is looked up in the hash. All of the hash parameters are interpreted the same as if it were a top-level command.

If this command is called without any arguments, behavior varies based on whether the "code" parameter is also set alongside the "nested" parameter. If "code" is set, the command is called normally, with no arguments. If "code" is not set, calling this command without a subcommand is treated as an unknown command.

options

A reference to an array of Getopt::Long option specifications. If this setting is present, the arguments passed to run() will be parsed by Getopt::Long using this option specification first, before any other option processing (including checking for minimum and maximum numbers of arguments, checking the validity of arguments, or replacing arguments with data from standard input). The result of parsing options will be passed, as a reference to a hash, as the first argument to the code that implements this command, with all remaining arguments passed as the subsequent arguments.

For example, if this is set to "['help|h', 'version|v']" and the arguments passed to run() are:

    command -hv foo bar
    

then the code implementing "command" will be called with the following arguments:

    { help => 1, version => 1 }, 'foo', 'bar'
    

Getopt::Long will always be configured with the options "bundling", "no_ignore_case", and "require_order". This means, among other things, that the first non-option argument will stop option parsing and all remaining arguments will be passed through verbatim.

If Getopt::Long rejects the options (due to an unknown option or an invalid argument to an option, for example), run() will die with the error message from Getopt::Long without running the command.

stdin

Specifies that one argument to this function should be read from standard input. All of the data on standard input until end of file will be read into memory, and that data will become the argument number given by the value of this key is the argument (based at 1). So if this property is set to 1, the first argument will be the data from standard input, and any other arguments will be shifted down accordingly. The value may be -1, in which case the data from standard input will become the last argument, no matter how many arguments there currently are.

Checks for the number of arguments and for the validity of arguments with regular expression verification are done after reading the data from standard input and transforming the argument list accordingly.

summary

The summary of what this subcommand does, as text. Ideally, this should fit on the same line with the syntax after the help output has been laid out in columns. If it is too long to fit, it will be wrapped, with each subsequent line indented to the column where the summaries start.

If this key is omitted, the subcommand will still be shown in help output, provided that it has a syntax key, but without any trailing summary.

syntax

The syntax of this subcommand. This should be short, since it needs to fit on the same line as the summary of what this subcommand does. Both the command and subcommand should be omitted; the former will be set by the command parameter to the new() constructor for Net::Remctl::Backend, and the latter will come from the command itself. A typical example will look like:

    syntax => '<object>'
    

which will result in help output (assuming command is set to "object" and this parameter is set on the "delete" command) that looks like:

    object delete <object>
    

Use abbreviations heavily to keep this string short so that the help output will remain readable.

Set this key to the empty string to indicate that this subcommand takes no arguments or flags.

If this key is omitted, the subcommand will be omitted from help output.