/ 
IPC-PrettyPipe-0.12
River stage zero No dependents
/ IPC::PrettyPipe::Cmd

NAME

IPC::PrettyPipe::Cmd - A command in an IPC::PrettyPipe pipeline

VERSION

version 0.12

SYNOPSIS

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 );

DESCRIPTION

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.

METHODS

Constructor

new
# 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.

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

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".

Other methods

add
$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.

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:

arg

The argument or arguments to add. It may take one of the following values:

  • an IPC::PrettyPipe::Arg object;

  • A scalar, e.g. a single argument;

  • An arrayref with pairs of names and values. The arguments will be supplied to the command in the order they appear.

  • A hashref with pairs of names and values. The arguments will be supplied to the command in a random order.

argpfx => string
argsep => string

These override the object's argpfx and argsep attributes for this argument only.

argfmt => IPC::PrettyPipe::Arg::Format object

This will override the format attributes for this argument only.

args
$args = $cmd->args;

Return a IPC::PrettyPipe::Queue object containing the IPC::PrettyPipe::Arg objects associated with the command.

argpfx,
argsep
argfmt

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;

cmd
$name = $cmd->cmd

Return the name of the command.

quoted_cmd
$name = $cmd->quoted_cmd

Return the name of the command, appropriately quoted for passing as a single word to a Bourne compatible shell.

ffadd
$cmd->ffadd( @arguments );

A more relaxed means of adding argument specifications. @arguments may contain any of the following items:

  • an IPC::PrettyPipe::Arg object

  • A scalar, representing an argument without a value.

  • An arrayref with pairs of names and values. The arguments will be supplied to the command in the order they appear.

  • A hashref with pairs of names and values. The arguments will be supplied to the command in a random order.

  • 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.

stream
$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
$streams = $cmd->streams

Return a IPC::PrettyPipe::Queue object containing the IPC::PrettyPipe::Stream objects associated with the command.

valmatch
$n = $cmd->valmatch( $pattern );

Returns the number of arguments whose value matches the passed regular expression.

valsubst
$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.

BUGS

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.

SOURCE

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

SEE ALSO

Please see those modules/websites for more information related to this module.

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

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