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