IPC::PrettyPipe::Cmd - A command in an IPC::PrettyPipe pipeline
version 0.12
use IPC::PrettyPipe::Cmd; # named arguments $cmd = IPC::PrettyPipe::Cmd->new( cmd => $cmd, args => $args, %attrs ); # concise constructor interface $cmd = IPC::PrettyPipe::Cmd->new( $cmd ); $cmd = IPC::PrettyPipe::Cmd->new( [ $cmd, $args ] ); ##### # different argument prefix for different arguments $cmd = IPC::PrettyPipe::Cmd->new( 'ls' ); $cmd->argpfx( '-' ); # prefix applied to subsequent arguments $cmd->add( 'f' ); # -f $cmd->add( 'r' ); # -r # "long" arguments, random order $cmd->add( { width => 80, sort => 'time' }, argpfx => '--', argsep => '=' ); # "long" arguments, specified order $cmd->add( [ width => 80, sort => 'time' ], argpfx => '--', argsep => '=' ); # attach a stream to the command $cmd->stream( $spec, $file ); # be a little more free form in adding arguments $cmd->ffadd( '-l', [-f => 3, -b => 9 ], '>', 'stdout' ); # perform value substution on a command's arguments' values $cmd->valsubst( %stuff );
IPC::PrettyPipe::Cmd objects are containers for the individual commands in a pipeline created by IPC::PrettyPipe. A command may have one or more arguments, some of which are options consisting of a name and an optional value.
Options traditionally have a prefix (e.g. -- for "long" options, - for short options). IPC::PrettyPipe::Cmd makes no distinction between option and non-option arguments. The latter are simply specified as arguments with a blank prefix.
--
-
# constructor with named arguments $cmd = IPC::PrettyPipe::Cmd->new( cmd => $cmd, %attr ); # concise constructor interface $cmd = IPC::PrettyPipe::Cmd->new( $cmd ); $cmd = IPC::PrettyPipe::Cmd->new( [ $cmd, $args ] );
Construct a IPC::PrettyPipe::Cmd object encapsulating $cmd. $cmd must be specified.
$cmd
The available attributes are:
cmd
The program to execute.
args
Optional. Arguments for the program. args may be
A scalar, e.g. a single argument;
An IPC::PrettyPipe::Arg object;
A hashref with pairs of names and values. The arguments will be supplied to the command in a random order.
An array reference containing more complex argument specifications. Its elements are processed with the "ffadd" method.
argpfx
argsep
Optional. The default prefix and separation attributes for command arguments. See IPC::PrettyPipe::Arg for more details. These override any specified via the "argfmt" object.
"argfmt"
argfmt
Optional. An IPC::PrettyPipe::Arg::Format object which will be used to specify the default prefix and separation attributes for arguments to commands. May be overridden by "argpfx" and "argsep".
"argpfx"
"argsep"
$cmd->add( $args ); $cmd->add( arg => $args, %options );
Add one or more arguments to the command. If a single parameter is passed, it is assumed to be the arg parameter.
arg
This is useful if some arguments should be conditionally given, e.g.
$cmd = IPC::PrettyPipe::Cmd->new( 'ls' ); $cmd->add( '-l' ) if $want_long_listing;
The available options are:
The argument or arguments to add. It may take one of the following values:
an IPC::PrettyPipe::Arg object;
An arrayref with pairs of names and values. The arguments will be supplied to the command in the order they appear.
These override the object's argpfx and argsep attributes for this argument only.
This will override the format attributes for this argument only.
$args = $cmd->args;
Return a IPC::PrettyPipe::Queue object containing the IPC::PrettyPipe::Arg objects associated with the command.
Retrieve (when called with no arguments) or modify (when called with an argument) the similarly named object attributes. See IPC::PrettyPipe::Arg for more information. Changing them affects new, not existing, arguments;
$name = $cmd->cmd
Return the name of the command.
$name = $cmd->quoted_cmd
Return the name of the command, appropriately quoted for passing as a single word to a Bourne compatible shell.
$cmd->ffadd( @arguments );
A more relaxed means of adding argument specifications. @arguments may contain any of the following items:
@arguments
an IPC::PrettyPipe::Arg object
A scalar, representing an argument without a value.
An IPC::PrettyPipe::Arg::Format object, specifying the prefix and separator attributes for successive arguments.
An IPC::PrettyPipe::Stream object
A string which matches a stream specification ("Stream Specification" in IPC::PrettyPipe::Stream::Utils), which will cause a new I/O stream to be attached to the command. If the specification requires an additional parameter, the next value in @arguments will be used for that parameter.
$cmd->stream( $stream_obj ); $cmd->stream( $spec ); $cmd->stream( $spec, $file );
Add an I/O stream to the command. It may be passed either a stream specification ("Stream Specification" in IPC::PrettyPipe::Stream::Utils) or an IPC::PrettyPipe::Stream object.
See IPC::PrettyPipe::Stream for more information.
$streams = $cmd->streams
Return a IPC::PrettyPipe::Queue object containing the IPC::PrettyPipe::Stream objects associated with the command.
$n = $cmd->valmatch( $pattern );
Returns the number of arguments whose value matches the passed regular expression.
$cmd->valsubst( $pattern, $value, %options );
Replace the values of arguments whose names match the Perl regular expression $pattern with $value. The following options are available:
firstvalue
If true, the first occurence of a match will be replaced with this.
lastvalue
If true, the last occurence of a match will be replaced with this. In the case where there is only one match and both firstvalue and lastvalue are specified, lastvalue takes precedence.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=IPC-PrettyPipe or by email to bug-IPC-PrettyPipe@rt.cpan.org.
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
The development version is on github at https://github.com/djerius/ipc-prettypipe and may be cloned from git://github.com/djerius/ipc-prettypipe.git
Please see those modules/websites for more information related to this module.
IPC::PrettyPipe
Diab Jerius <djerius@cpan.org>
This software is Copyright (c) 2018 by Smithsonian Astrophysical Observatory.
This is free software, licensed under:
The GNU General Public License, Version 3, June 2007
To install IPC::PrettyPipe, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IPC::PrettyPipe
CPAN shell
perl -MCPAN -e shell install IPC::PrettyPipe
For more information on module installation, please visit the detailed CPAN module installation guide.