IPC::PrettyPipe::DSL - shortcuts to building an IPC::PrettyPipe object
version 0.12
use IPC::PrettyPipe::DSL qw[ :all ]; $pipe = ppipe # one command per array [ 'mycmd', argsep '=', # set default formatting attributes argpfx '-', $arg1, $arg2, # boolean/switch arguments argpfx '--', # switch argument prefix \@args_with_values # ordered arguments with values \%args_with_values, # unordered arguments with values argpfx '', # no prefixes for the rest @args_without_values, '2>', 'stderr_file' # automatic recognition of streams ], # another command [ 'myothercmd' => ... ], # manage pipeline streams '>', 'stdout_file'; ; # or, create a command $cmd = ppcmd 'mycmd', argpfx '-', # default for object $arg1, $arg2, argpfx '--', # change for next arguments $long_arg1, $long_arg2; # and add it to a pipeline $pipe = ppipe $cmd; # and for completeness (but rarely used ) $arg = pparg '-f'; $arg = pparg [ -f => 'Makefile' ]; $arg = pparg, argpfx '-', [ f => 'Makefile' ];
IPC::PrettyPipe::DSL provides some shortcut subroutines to make building pipelines easier.
Pipelines are created by chaining together commands with arguments. Arguments which are options may have prefixes, and options which have values may have their names separated from their values by a separator string.
The "ppipe", "ppcmd", and "pparg" subroutines are used to create pipelines, commands, and arguments.
The "argpfx", and "argsep" subroutines are used to change the argument prefix and separator strings. Calls to these are embedded in lists of arguments and commands, and change the argument prefixes and separator strings for the succeeding entries. These are called argument attribute modifiers and are documented in "Argument Attribute Modifiers".
To specify stream redirection for either pipelines or commands, insert either a IPC::PrettyPipe::Stream object or a string stream specification (see "Stream Specification" in IPC::PrettyPipe::Stream::Utils). If the redirection requires another parameter, it should immediately follow the object or string specification.
The Argument Attribute modifiers ("argpfx" and "argsep" ) are subroutines which change the default values of the argument prefix and separator strings (for more information see IPC::PrettyPipe::Arg).
Calls to them are typically embedded in lists of arguments and commands, e.g.
$p = ppipe argpfx '-', [ 'cmd0', 'arg0' ], argpfx '--', [ 'cmd1', argpfx('-'), 'arg1' ], [ 'cmd2', 'arg0' ];
and affect the default value of the attribute for the remainder of the context in which they are specified.
For example, after the above code is run, the following holds:
$p->argpfx eq '-' $p->cmds->[0]->argpfx eq '-' $p->cmds->[1]->argpfx eq '--' $p->cmds->[1]->args->[0]->argpfx eq '-' $p->cmds->[2]->argpfx eq '--' $p->cmds->[2]->args->[0]->argpfx eq '--'
These change the default values of the argument prefix and separator strings. They take a single argument, the new value of the attribute.
$arg = pparg @attribute_modifiers, $name, $value;
pparg creates an IPC::PrettyPipe::Arg object. It is passed (in order)
An optional list of argument attribute modifiers.
The argument name.
An optional value.
$stream = ppstream $spec; $stream = ppstream $spec, $file;
ppstream creates an IPC::PrettyPipe::Stream object. It is passed (in order):
A stream specification
An optional file name (if required by the stream specification).
$cmd = ppcmd @attribute_modifiers, $cmd, @cmd_args; $cmd = ppcmd 'cmd0', 'arg0', [ arg1 => $value1 ]; $cmd = ppcmd argpfx '--', 'cmd0', 'arg0', [ arg1 => $value1 ];
ppcmd creates an IPC::PrettyPipe::Cmd object. It is passed (in order)
An optional list of argument attribute modifiers, providing the defaults for the returned IPC::PrettyPipe::Cmd object.
The command name
A list of command arguments, argument attribute modifiers, and stream specifications. This list may contain
Scalars, representing single arguments;
IPC::PrettyPipe::Arg objects;
Arrayrefs with pairs of names and values. The arguments will be supplied to the command in the order they appear;
Hashrefs with pairs of names and values. The arguments will be supplied to the command in a random order;
IPC::PrettyPipe::Stream objects or stream specifications ("Stream Specification" in IPC::PrettyPipe::Stream::Utils). If the specification requires an additional parameter, the next value in @cmd_args will be used for that parameter.
@cmd_args
argument attribute modifiers, changing the attributes for the arguments which follow in @cmd_args.
$pipe = ppipe @arg_attr_mods, @args; $pipe = ppipe # set the default for this pipe argpfx( '--'), # cmd0 --arg0 [ 'cmd0', 'arg0' ], # cmd1 --arg0 --arg1 $value1 --arg2 $value2 [ 'cmd1', 'arg0', [ arg1 => $value1, arg2 => $value2 ], ], # tweak this for the following commands argpfx(''), # cmd2 arg0 arg1=$value1 arg2=$value2 [ 'cmd2', 'arg0', argsep( '=' ), [ arg1 => $value1, arg2 => $value2 ], ], # tweak this for the following commands argpfx('--'), # cmd3 --arg0 [ 'cmd3', 'arg0' ], # cmd4 'cmd4';
ppipe creates an IPC::PrettyPipe object. It is passed (in order)
An optional list of argument attribute modifiers, providing the defaults for the returned IPC::PrettyPipe object.
A list of one or more of the following
A command name (i.e. a string), for a command without arguments.
an IPC::PrettyPipe::Cmd object
a IPC::PrettyPipe::Pipe object
An arrayref. The array may contain either a single IPC::PrettyPipe::Pipe object or a number of elements, the first of which being the command name with the rest being
arguments;
argument attribute modifiers (which affect subsequent entries in the array); and
stream specifications or objects.
These are passed to IPC::PrettyPipe::Cmd::new as the cmd and args parameters.
cmd
args
Argument Attribute modifiers, which affect attributes for all of the commands and arguments which follow.
A stream specification ("Stream Specification" in IPC::PrettyPipe::Stream::Utils), or an IPC::PrettyPipe::Stream object. If the specification requires an additional parameter, the next value in @args is used.
@args
Note that ppipe will use up all arguments passed to it. When specifying nested pipes, make sure that the inner pipes don't grab arguments meant for the outer ones. For example,
ppipe
ppipe [ 'cmd1' ], ppipe [ 'cmd2' ], '>', 'file';
redirects the output of the second, inner pipe, not the outer one. Either of these will do that:
ppipe [ 'cmd1' ], [ ppipe [ 'cmd2' ] ], '>', 'file'; ppipe [ 'cmd1' ], ppipe( [ 'cmd2' ]), '>', 'file';
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.