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

NAME

IPC::PrettyPipe::DSL - shortcuts to building an IPC::PrettyPipe object

VERSION

version 0.12

SYNOPSIS

  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' ];

DESCRIPTION

IPC::PrettyPipe::DSL provides some shortcut subroutines to make building pipelines easier.

Pipeline construction

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.

Argument Attribute Modifiers

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 '--'

SUBROUTINES

argpfx

argsep

These change the default values of the argument prefix and separator strings. They take a single argument, the new value of the attribute.

pparg

$arg = pparg @attribute_modifiers, $name, $value;

pparg creates an IPC::PrettyPipe::Arg object. It is passed (in order)

  1. An optional list of argument attribute modifiers.

  2. The argument name.

  3. An optional value.

ppstream

$stream = ppstream $spec;
$stream = ppstream $spec, $file;

ppstream creates an IPC::PrettyPipe::Stream object. It is passed (in order):

  1. A stream specification

  2. An optional file name (if required by the stream specification).

ppcmd

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

  1. An optional list of argument attribute modifiers, providing the defaults for the returned IPC::PrettyPipe::Cmd object.

  2. The command name

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

    • argument attribute modifiers, changing the attributes for the arguments which follow in @cmd_args.

ppipe

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

  1. An optional list of argument attribute modifiers, providing the defaults for the returned IPC::PrettyPipe object.

  2. A list of one or more of the following

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 [ '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';

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