David Boyce > Argv-1.27 > Argv

Download:
Argv-1.27.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  2
View/Report Bugs
Module Version: 1.27   Source   Latest Release: Argv-1.28

NAME ^

Argv - Provide an OO interface to an arg vector

SYNOPSIS ^

    use Argv;

    # A roundabout way of getting perl's version.
    my $pl = Argv->new(qw(perl -v));
    $pl->exec;

    # Run /bin/cat, showing how to provide "predigested" options.
    Argv->new('/bin/cat', [qw(-u -n)], @ARGV)->system;

    # A roundabout way of globbing.
    my $echo = Argv->new(qw(echo M*));
    $echo->glob;
    my $globbed = $echo->qx;
    print "'echo M*' globs to: $globbed";

    # A demonstration of head-like behavior (aborting early).
    my $maxLinesToPrint = 5;
    my $callback = sub {
        print shift;
        return --$maxLinesToPrint;
    };
    my $head = Argv->new('ls', [qw(-l -a)]);
    $head->readonly("yes"); 
    $head->pipecb($callback); 
    $head->pipe;

    # A demonstration of the builtin xargs-like behavior.
    my @files = split(/\s+/, $globbed);
    my $ls = Argv->new(qw(ls -d -l), @files);
    $ls->parse(qw(d l));
    $ls->dbglevel(1);
    $ls->qxargs(1);
    my @long = $ls->qx;
    $ls->dbglevel(0);
    print @long;

    # A demonstration of how to use option sets in a wrapper program.
    @ARGV = qw(Who -a -y foo -r);       # hack up an @ARGV
    my $who = Argv->new(@ARGV);         # instantiate
    $who->dbglevel(1);                  # set verbosity
    $who->optset(qw(UNAME FOO WHO));    # define 3 option sets
    $who->parseUNAME(qw(a m n p));      # parse these to set UNAME
    $who->parseFOO(qw(y=s z));          # parse -y and -z to FOO
    $who->parseWHO('r');                # for the 'who' cmd
    warn "got -y flag in option set FOO\n" if $who->flagFOO('y');
    print Argv->new('uname', $who->optsUNAME)->qx;
    $who->prog(lc $who->prog);          # force $0 to lower case
    $who->exec(qw(WHO));                # exec the who cmd

More advanced examples can be lifted from the test script or the ./examples subdirectory.

RAISON D'ETRE ^

Argv presents an OO approach to command lines, allowing you to instantiate an 'argv object', manipulate it, and eventually execute it, e.g.:

    my $ls = Argv->new('ls', ['-l']));
    my $rc = $ls->system;       # or $ls->exec or $ls->qx

Which raises the immediate question - what value does this mumbo-jumbo add over Perl's native way of doing the same thing:

    my $rc = system(qw(ls -l));

The answer comes in a few parts:

All of these behaviors are optional and may be toggled either as class or instance attributes. See EXECUTION ATTRIBUTES below.

DESCRIPTION ^

An Argv object treats a command line as 3 separate entities: the program, the options, and the args. The options may be further subdivided into user-defined option sets by use of the optset method. When one of the execution methods is called, the parts are reassembled into a single list and passed to the underlying Perl execution function.

Compare this with the way Perl works natively, keeping the 0th element of the argv in $0 and the rest in @ARGV.

By default there's one option set, known as the anonymous option set, whose name is the null string. All parsed options go there. The advanced user can define more option sets, parse options into them according to Getopt::Long-style descriptions, query or set the parsed values, and then reassemble them in any way desired at exec time. Declaring an option set automatically generates a set of methods for manipulating it (see below).

All argument-parsing within Argv is done via Getopt::Long.

AUTOLOADING ^

Argv employs the same technique made famous by the Shell module to allow any command name to be used as a method. E.g.

        $obj->date->exec;

will run the 'date' command. Internally this is translated into

        $obj->argv('date')->exec;

See the argv method below.

FUNCTIONAL INTERFACE ^

Because the extensions to system/exec/qx described above may be helpful in writing portable programs, the methods are also made available for export as traditional functions. Thus:

    use Argv qw(system exec qv pipe);

will override the Perl builtins. There's no way (that I know of) to override the operator qx() so an alias qv() is provided.

CONSTRUCTOR ^

    my $obj = Argv->new(@list)

The @list is what will be parsed/executed/etc by subsequent method calls. During initial construction, the first element of the list is separated off as the program; the rest is lumped together as part of the args until and unless option parsing is done, in which case matched options are shifted into collectors for their various option sets. You can also create a "predigested" instance by passing any or all of the prog, opt, or arg parts as array refs. E.g.

    Argv->new([qw(cvs ci)], [qw(-l -n)], qw(file1 file2 file3));

Predigested options are placed in the default (anonymous) option set.

The constructor can be used as a class or instance method. In the latter case the new object is a deep (full) clone of its progenitor. In fact there's a clone method which is an alias to new, allowing clones to be created via:

        my $copy = $orig->clone;

The first argument to new() or clone() may be a hash-ref, which will be used to set execution attributes at construction time. I.e.:

    my $obj = Argv->new({autochomp => 1, stderr => 0}, @ARGV);

You may choose to create an object and add the command line later:

    my $obj = Argv->new;
    $obj->prog('cat');
    $obj->args('/etc/motd');

Or

    my $obj = Argv->new({autochomp=>1});
    my $motd = $obj->argv(qw(cat /etc/motd))->qx;

Or (using the autoloading interface)

    my $motd = $obj->cat('/etc/motd')->qx;

METHODS ^

INSTANCE METHODS

EXECUTION METHODS

The three methods below are direct analogues of the Perl builtins. They simply reassemble a command line from the prog, opts, and args parts according to the option-set rules described below and invoke their builtin equivalent on it.

EXECUTION ATTRIBUTES

The behavior of the execution methods system, exec, and qx is governed by a set of execution attributes, which are in turn manipulated via a set of eponymous methods. These methods are auto-generated and thus share certain common characteristics:

PORTABILITY ^

ClearCase::Argv should work on all ClearCase platforms. It's primarily maintained on Solaris 9 and Windows XP with CC 7.0, using Perl5.8.x.

PORTABILITY ^

This module is primarily maintained on Solaris 9 and Windows XP using Perl 5.8.x or newer. There is no known reason it should fail to work on any POSIX or Windows (NT4.0 and above) platform with a sufficiently modern Perl.

PERFORMANCE ^

If you make frequent use of the clone method, you might consider installing the Clone module by Ray Finch. This tends to speed up instance cloning a good bit.

BUGS ^

It's not exactly a bug but ... this module served as my laboratory for learning about Perl OO, autoloading, and various other advanced Perl topics. Therefore it was not written in a disciplined manner; rather, I stuck in every neat idea I was playing with at the time. As a result, though it works well as far as I know, there's a hopeless array of ways to do everything. I know the motto of Perl is TMTOWTDI but Argv goes one further: TWTMWTDE (There's Way Too Many Ways To Do Everything).

For instance, to run commands with different values for execution attributes such as autoquote or stderr, you can keep multiple instances around with different attribute sets, or you can keep one template instance which you clone-and-modify before each execution, letting the clone go out of scope immediately:

    $obj->clone->stderr(0)->system;

Or you can keep one instance around and modify its state before each use. Or toggle the class attributes while leaving the instance attributes untouched. Which is better? I don't know the answer, but choosing a consistent style is a good idea.

AUTHOR ^

David Boyce <dsbperl AT boyski.com>

COPYRIGHT ^

Copyright (c) 1999-2006 David Boyce. All rights reserved. This Perl program is free software; you may redistribute and/or modify it under the same terms as Perl itself.

GUARANTEE ^

Double your money back!

SEE ALSO ^

perl(1), Getopt::Long(3), IPC::ChildSafe(3)

syntax highlighting: