Robert Krimen > Getopt-Chain > Getopt::Chain::v005



Annotate this POD


New  3
Open  0
View/Report Bugs
Module Version: 0.005   Source  


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


Version 0.005


    #!/usr/bin/perl -w

    use strict;
    use Getopt::Chain::v005;

    # A partial, pseudo-reimplementation of git(1):

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


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


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







Robert Krimen, <rkrimen at>


You can contribute or fork this project via GitHub:

    git clone git:// Getopt-Chain


Please report any bugs or feature requests to bug-Getopt-Chain at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


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

    perldoc Getopt::Chain::v005

You can also look for information at:



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.

syntax highlighting: