Commands may have "sub-commands" and arguments. A given sub-command is allowed to have alternate argument lists. Sub-commands may be queries as well as directives, and thus will return information.
Commands are specified as arrays. Each element in the array is a separate sub-command. Sub-commands are specified via arrays, the first element of which defines the sub-command tokens, the rest the alternate argument lists.
Sub-command tokens are presented as an array of strings or regular expressions. If there is more than one, the input list of tokens must match exactly in order.
An argument list is a hash which describes the order and type of arguments and whether and how the sub-command can be queried with the specified argument list.
In detail, here's what a sub-command specification looks like:
This is an arrayref which contains strings or RE's to match. all must match, in the specified order. It may be empty.
A hashref with the following possible keys:
An array of argument types. The types may be strings, regular expressions (generated with the qr operator), or subroutine refs. The arguments must match the types, in the specified order.
This determines how and if the sub-command with the specified arguments may be queried. It may have the following values:
This sub-command with the specified argument list may not be queried.
This sub-command with the specified argument list may only be queried. All of the arguments must specified.
This sub-command may only be queried. No arguments may be specified.
This sub-command may be queried. No arguments may be specified for the query. This is the default if query isn't specified.
The last argument passed to the command should be sent via the XPASet buf argument.
If true (the default) returned results are converted if their type has a conversion routine available. The list of arguments is used to determine the return types.
If true, a reference to the queried value is returned if the user queries the command in a scalar context.
If this is present and the last element in the argument list is a hashref,
it will be scanned for attributes which will modify the query or directive.
Attributes are command specific,
and may be specified in combination or exclusion.
Attributes are specified in an array as keyword/type pairs.
Attributes which must appear together should be in their own array,
preceded by the token
Attributes which must not appear together should be in their own array,
preceded by the token
Such clauses may be nested.
xdimmust both be specified:
-a => [ xdim => FLOAT, ydim => FLOAT ]
daymust not both be specified:
-o => [ night => BOOL, day => BOOL ]
xdimmust both be specified, but cannot be specified with
-o => [ ( -a => [ xdim => FLOAT, ydim => FLOAT ] ), ( dim => FLOAT ) ]
Note that all clauses are evaluated, to catch possibly typos by the user.