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.