App::MrShell - do everything the mrsh commandline tool can do and more
my $mrsh = App::MrShell -> new -> set_hosts('host1', 'host2', 'host3') -> queue_command('uptime') -> queue_command('mii-tool', 'eth0') -> queue_command('dmesg | head') -> run_queue;
This package can do all the things mrsh can do and possibly more. The methods mostly support chaining to make script writing easier and more attractive. The API hides the POE nature of the project, but the author is not opposed to exposing it if anybody wants such a thing.
The first argument is normally a space separated list of command-and-arguments (with some basic quoting support). If called with no arguments, a null-command will be set indicating that there isn't a shell command to prepend hostnames with -- the author can't imagine why this would be useful, but allows that it could be someday for someone.
If the first argument is an arrayref, all following arguments will be ignored. The arrayref will be copied as the shell command.
 can be used as the arrayref to set a null-command.
Setup groups of hosts. Pairs are spliced off the stack with first element as the name of a group, the second element as either a space delimited set of hostnames or an arrayref of hostnames. Example:
$mrsh->set_group_option( group1 => [qw(host1 host2 host3)], group2=>['localhost'] );
When provided, write a logfile of all lines received, where and when they were executed.
Turn on various debugging messages. The optional argument specifies the debug level. No argument, 0, and 1 are all equivalent. While levels greater than one indicate an increased amount of debugging noise.
When expanding hosts in host-routing mode, slashes and spaces are escaped so they function correctly when subshelled. This disables that functionality.
Pass in a function name to call on error. Useful for showing pod2usage() information. Example:
my $mrsh = App::MrShell->new->set_usage_error("pod2usage");
Set the hosts, groups, and routed strings for the next "queue_command". Hosts have some special magic concerning groups. Hosts that being with an
@ character are considered groups are are expanded that way (see config file).
Commands are pushed as an array, although, given the nature of http://openssh.com/ it's probably ok to pass in the command as a single string; or even to pass in multiple commands,
; separated and let the shell sort it out.
Set any built in or extra subst vars. These will only ever be set once per "subst_cmd_vars"() call, so setting built-in keys will override the built-in values, with the exception of
%u at least and
%u during host-routing mode -- since those are special subst vars, their substitutions will be difficult to override.
Substitute command vars, including the special magic of host routing and the escaping associated with it (e.g.
%h for the hostname). These are better documented in the COMMAND ESCAPES section.
Others (that is non-internal substs) can be added with "set_subst_vars"(), although
%u are magic and setting them manually probably won't work.
As arguments, the function takes the command, upon which substitution should occur, as an array.
For feature requests, just go ahead and email me. I've never minded a discussion of this nature yet.
Dennis Boone -- http://github.com/drboone
Copyright 2009-2010 Paul Miller -- released under the GPL