NAME

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

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;

• 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

Returns an IPC::PrettyPipe::Queue object containing the arguments 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.

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 an IPC::PrettyPipe::Queue object containing the streams 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 occurance of a match will be replaced with this.

lastvalue

If true, the last occurance 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.

COPYRIGHT & LICENSE

Copyright 2014 Smithsonian Astrophysical Observatory

This software is released under the GNU General Public License. You may find a copy at

   http://www.fsf.org/copyleft/gpl.html

AUTHOR

Diab Jerius <djerius@cfa.harvard.edu>