Perl x Open Food Facts Hackathon: Paris, France - May 24-25 Learn more

 / 
Getopt-Chain-0.017
River stage one • 3 direct dependents • 3 total dependents
/ Getopt::Chain::v005

NAME

Getopt::Chain::v005 - Command-line processing like svn and git

VERSION

Version 0.005

SYNPOSIS


            

              
              
#!/usr/bin/perl -w
use strict;
use Getopt::Chain::v005;
# A partial, pseudo-reimplementation of git(1):
Getopt::Chain::v005->process(
    options => [qw/ version bare git-dir=s /]
    run => sub {
        my $context = shift;
        my @arguments = @_; # Remaining, unparsed arguments
        # ... do stuff before any subcommand ...
    }
    commands => {
        init => {
            options => [qw/ quiet|q --template=s /]
            run => sub {
                my $context = shift;
                my @arguments = @_; # Again, remaining unparsed arguments 
                # ... do init stuff ...
            }
        }
        commit => {
            options => [qw/ all|a message|m=s /]
            run => sub {
                my $context = shift;
                 
                # ... do commit stuff ..
            }
        }
        add => ...
        help => ...
        ...
    }
)
# The above will allow the following (example) usage:
#
# ./script --version
# ./script --git-dir path/to/repository init
# ./script --git-dir path/to/repository commit -a --message '...'
# ./script commit -m '~'

DESCRIPTION

Getopt::Chain::v005 can be used to provide svn(1)- and git(1)-style option and subcommand processing. Any option specification covered by Getopt::Long is fair game.

CAVEAT: Unfortunately, Getopt::Long slurps up the entire arguments array at once. Usually, this isn't a problem (as Getopt::Chain::v005 uses pass_through). However, if a subcommand has an option with the same name or alias as an option for a parent, then that option won't be available for the subcommand. For example:


            

              
              
./script --verbose --revision 36 edit --revision 48 --file xyzzy.c
# Getopt::Chain::v005 will not associate the second --revision with "edit"

So, for now, try to use distinct option names/aliases :)

Finally, this code fairly new so aspects of the API *might* change (particularly abort/error-handling). Let me know if you're using it and have any suggestions.

TODO: Default values, option descriptions (like Getopt::Long::Descriptive) and constraints (validation).

Basic configuration

A Getopt::Chain::v005 configuration is pretty straightforward

Essentially you declare a command, which consists of (optional) <options> and an (optional) <run> subroutine (a CODE reference)

<options> should be an ARRAY reference consisting of a Getopt::Long specification

<run> should be a CODE reference which is a subroutine that accepts a Getopt::Chain::v005::Context as the first argument and any remaining command-line arguments (left after option parsing) as the rest of @_

A third parameter exists, <commands> in which you associate a <name> with a command, consisting (recursively) of <options>, <run>, and <commands>

The <name> indicates what should be typed on the command-line to "trigger" the command. All-in-all, a configuration looks something like this:


            

              
              
options => [ ... ]
run => sub {}
commands => {
    <name1> => {
        options => [ ... ]
        run => sub {}
        commands => ...
    },
    <name2> => {
        ...
    },
    ... Rinse, repeat, etc.
}

See SYNPOSIS for an example

Error-handling configuration

Alongside <options>, <run>, and <commands>, you can designate a third parameter, <error> which is a either a CODE or HASH reference

This is an error handler for dealing with the following situations:


            

              
              
option_processing_error     A Getopt::Long parsing error 
have_remainder              When a dash or dash-dash string remains on the argument stack without being processed 
unknown_command             When you've indicated that you want to accept a command but the user entered an unknown one

You can either give a single subroutine to deal with all three, or give a HASH with:

A subroutine for dealing with that specific error
A value of '0' for disabling/ignoring that error

For more detail (for now), look at the source:


            

              
              
perldoc -m Getopt::Chain::v005

METHODS

Getopt::Chain::v005->process( <arguments>, ... )

<arguments> should be an ARRAY reference

... should consist of a Getopt::Chain::v005 configuration

Getopt::Chain::v005->process( ... )

@ARGV will be used for <arguments>

... should consist of a Getopt::Chain::v005 configuration

SEE ALSO

Getopt::Chain::v005::Context

Getopt::Long

App::Cmd

MooseX::App::Cmd

AUTHOR

Robert Krimen, <rkrimen at cpan.org>

SOURCE

You can contribute or fork this project via GitHub:

http://github.com/robertkrimen/Getopt-Chain/tree/master


            

              
              
git clone git://github.com/robertkrimen/Getopt-Chain.git Getopt-Chain

BUGS

Please report any bugs or feature requests to bug-Getopt-Chain at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Getopt-Chain. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.


            

              
              
perldoc Getopt::Chain::v005

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2008 Robert Krimen, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.