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

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

ATTRIBUTES

cmd

args

argpfx

argsep

argfmt

METHODS

new

cmd

args

streams

argpfx

argsep

argfmt

quoted_cmd

add

ffadd

stream

valmatch

valsubst

OPERATORS

|

SUPPORT

Bugs

Source

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions