NAME

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

VERSION

version 0.13

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.

ATTRIBUTES

cmd

The program to execute. Required.

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

METHODS

new

  # constructor with named arguments
  $cmd = IPC::PrettyPipe::Cmd->new( cmd => $cmd, %attributes );

  # 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. See "ATTRIBUTES" for a description of the available attributes.

cmd

  $name = $cmd->cmd

Return the name of the program to execute.

args

  $args = $cmd->args;

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

streams

  $streams = $cmd->streams

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

argpfx

argsep

argfmt

  $obj->argpfx( $new_pfx );
  $obj->argsep( $new_sep );
  $obj->argfmt( $format_obj );

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

$format_obj is an IPC::PrettyPipe::Arg::Format object;

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.

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.

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.

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.

OPERATORS

|

The | operator is equivalent to creating a new pipe and adding the operands of the | operator, e.g.

  $cmd | $obj

is the same as

  do {
    my $tpipe = IPC::PrettyPipe->new;
    $tpipe->add( $cmd );
    $tpipe->add( $obj );
    $tpipe
  };

where $obj may be either an IPC::PrettyPipe or IPC::PrettyPipe::Cmd object.

SUPPORT

Bugs

Please report any bugs or feature requests to bug-ipc-prettypipe@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=IPC-PrettyPipe

Source

Source is available at

  https://gitlab.com/djerius/ipc-prettypipe

and may be cloned from

  https://gitlab.com/djerius/ipc-prettypipe.git

SEE ALSO

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

• IPC::PrettyPipe

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

cpanm IPC::PrettyPipe

perl -MCPAN -e shell
install IPC::PrettyPipe