NAME¶
Net::Remctl::Backend - Helper infrastructure for remctl backend programs
SYNOPSIS¶
use Net::Remctl::Backend;
my %commands = (
cmd1 => { code => \&run_cmd1 },
cmd2 => { code => \&run_cmd2 },
);
my $backend = Net::Remctl::Backend->new({
commands => \%commands,
});
exit $backend->run();
DESCRIPTION¶
Net::Remctl::Backend provides a framework for remctl backend commands (commands
run by
remctld). It can be configured with a list of supported
subcommands and handles all the command-line parsing and syntax checking,
dispatching the command to the appropriate sub if it is valid.
CLASS METHODS¶
- new(CONFIG)
- Create a new backend object with the given configuration.
CONFIG should be an anonymous hash with one or more of the following
keys:
- 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.
INSTANCE METHODS¶
- help()
- Returns the formatted help summary for the commands
supported by this backend. This is the same as would be printed to
standard output in response to the command "help" with no
arguments. The output will consist of the syntax and summary attributes
for each command that has a syntax attribute defined, as described above
under the command specification. It will be wrapped to 80 columns.
- run([COMMAND[, ARG ...]])
- Parse the command line and perform the appropriate action.
The return value will be the return value of the command run (if any),
which should be the exit status that the backend script should use.
The command (which is the remctl subcommand) and arguments can be passed
directly to run() as parameters. If no arguments are passed,
run() expects @ARGV to contain the parameters passed to the backend
script. Either way the first argument will be the subcommand, used to find
the appropriate command to run, and any remaining arguments will be
arguments to that command. (Note that if the "options" parameter
is set, the first argument passed to the underlying command will be the
options hash.)
If there are errors in the parameters to the command, run() will die
with an appropriate error message.
DIAGNOSTICS¶
Since Net::Remctl::Backend is designed to handle command line parsing for a
script and report appropriate errors if there are problems with the argument,
its
run() method may die with various errors. The possible errors are
listed below. All will be terminated with a newline so the Perl context
information won't be appended.
- %s: insufficient arguments
- The given command was configured with a
"args_min" parameter, and the user passed in fewer arguments
than that.
- %s: invalid argument: %s
- The given argument to the given command failed to match a
regular expression that was set with an "args_match"
parameter.
- %s: too many arguments
- The given command was configured with a
"args_max" parameter, and the user passed in more arguments than
that.
COMPATIBILITY¶
This module was added in the 3.4 release of remctl. Since 3.5, the module
version matches the remctl version but with a leading zero added so that the
minor version always has two numbers (so Net::Remctl::Backend 3.05 was
included in remctl 3.5).
All currently-supported methods and options have been supported since the
original release of the module.
BUGS¶
There is no way to check all arguments with a regex when the command supports
any number of arguments.
AUTHOR¶
Russ Allbery <eagle@eyrie.org>
COPYRIGHT AND LICENSE¶
Copyright 2012, 2013, 2014 The Board of Trustees of the Leland Stanford Junior
University
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
SEE ALSO¶
remctld(8)
The current version of this module is available from its web page at
<
http://www.eyrie.org/~eagle/software/remctl/>.