NAME

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

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 functions to make building pipelines easier.

FUNCTIONS

Pipelines are created by chainging 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" functions are used to create pipelines, commands, and arguments.

The "argpfx", and "argsep" functions are used to change the argument prefix and separator strings. Calls to these are embeded 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.

Pipeline component construction

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

   • A command name (i.e. a string), for a command without arguments.

   • an IPC::PrettyPipe::Cmd object

   • An arrayref. The first element is the command name; the rest are

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

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

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.

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

Argument Attribute Modifiers

Argument Attribute modifiers are functions which change the default values of the argument prefix and separator strings (for more information see IPC::PrettyPipe::Arg). There are two functions,

argpfx

argsep

which take a single argument (the new value of the attribute).

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

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>