There are a few no-cost BSD shell providers around, which has allowed me to develop and test directly on that platform. However I haven't found anything similar for Win32. I vaguely remember some offering from Microsoft for CPAN developers, but can no longer find any reference to it. Can someone jog my memory, or give me a pointer to an alternative service?

If I install dependencies for a particular project using "cpanm -l extlib $MODULE" in the top level directory, the function below will automatically setup local::lib for that location when I change into that directory, and unset it when I change out. I use a test for the existence of a "extlib" directory and a Makefile.PL file because that is what I consistently have.

# Automatic local::lib setup based on extlib directory

set_local_lib() {

    if [[ $PWD != $MYOLDPWD ]]; then

        MYOLDPWD="$PWD";

        OLDPERL5LIB=$PERL5LIB


        unset PERL5LIB

        unset PERL_MB_OPT

        unset PERL_MM_OPT

        unset PERL_LOCAL_LIB_ROOT

        if [[ -n $VERY_LOCAL_LIB_PATH ]]; then

            export PATH=`echo $PATH | sed -e "s|$VERY_LOCAL_LIB_PATH:||g"`

            unset VERY_LOCAL_LIB_PATH

        fi

        if [[ -e Makefile.PL && -d extlib ]]; then

            eval `perl -Mlocal::lib=extlib`

            VERY_LOCAL_LIB_PATH=$PWD/extlib/bin

            echo "[Using local::lib with $PWD/extlib]";

        fi

        if [[ -n $OLDPERL5LIB ]]; then

            unset OLDPERL5LIB

            echo "[local::lib turned off]";

        fi

    fi

}

export PROMPT_COMMAND=set_local_lib

Can this be improved? Is there are better way of achieving location dependent local::lib without resorting to FindBin/local::lib trickery in test scripts? It has also been mentioned that perlbrew and local::lib don't work together. If "extlib" was a perl-version-dependent location this could also be overcome.

I also uploaded a distribution (App-githook-perltidy) to CPAN however I'm not sure yet if it is installable as it doesn't contain any Perl module files, and cpanm at least doesn't seem to install based on distribution name only. Anyone have thoughts on if it makes sense to have a single-script CPAN distribution?

But it doesn't necessarily have to be that way. App::Dispatcher is a tool for constructing command line applications written in Perl. It is specifically designed to handle applications with multiple sub-commands and will generate code to display usage text, validate options and arguments, and dispatch commands. Its main strength is that the usage and validation does not load any command classes with their possibly heavy startup dependencies.

• Command Classes

  These classes are written by the application author to do the actual work. They have special methods which App::Dispatcher uses to build the Dispatcher class.

• Dispatcher Class

  The Dispatcher class is generated when the application author runs the app-dispatcher(1) command. The dispatcher class is called by the Application Script at runtime. After performing option and argument processing the dispatcher class calls the appropriate Command Class.

  The only runtime dependency that the Dispatcher Class needs to run is Getopt::Long::Descriptive(3p), which the application author should add to their Makefile.PL and/or Build.PL scripts.

  Note that App::Dispatcher is a code generation tool. This means that option and argument processing will not change when command classes are modified, until app-dispatcher is re-run.

• Application Script

  The application script is what the user runs, and does nothing more than call the Dispatcher Class:

  #!/usr/bin/perl
  use Your::Command::Dispatcher;
  Your::Command::Dispatcher->run;
  

  All the examples below assume the existence of this application script.

The rest of this tutorial is all about how to write Command Classes. Let's start with a simple command that has two options, one optional argument, and no sub-commands:

package Your::Command;

sub opt_spec {(
    [ "dry-run|n",     "print out SQL instead of running it" ],
    [ "drop-tables|D", "DROP TABLEs before deploying" ],
)};

sub arg_spec {(
    [ "database=s",   "which database to deploy to",
        { default => 'development' } 
    ],
)};

sub run {
    my ($class,$opt) = @_;

    if ( $opt->dry_run ) {
        print "Not ";
    }
    print "Deploying to ". $opt->database ."\n";
}

1;

With the above code in 'lib/Your/Command.pm' we can run app-dispatcher and then our script:

ex1$ app-dispatcher --add-help Your::Command
Writing lib/Your/Command/Dispatcher.pm

ex1$ ./ex --help
usage: ex [options] [<database>]
    --help             print usage message and exit
    -n --dry-run       print out SQL instead of running it
    -D --drop-tables   DROP TABLEs before deploying

ex1$ ./ex
Deploying to development

ex1$ ./ex -n production
Not Deploying to production

There are several things to note here. The first is the definition of the opt_spec() and arg_spec() methods. The values returned from these methods are passed more or less untouched to Getopt::Long::Descriptive's describe_options() routine.

Obvious should be the fact that the '-add-help' option to app-dispatcher has added a '--help' option to our command.

What is more interesting is that arguments specification has the same format as the options specification. An argument could actually be considered the same as an un-named option with a fixed position. So App::Dispatcher actually folds arguments into the option object passed to the command class. The added benefit is that the parameter validation of Getopt::Long is now also run against arguments.

Let's make the argument mandatory by adding a "required" key to the arg_spec definition:

{ default => 'development', required => 1 }

ex2$ ./ex
usage: ex [options] <database>
    --help             print usage message and exit
    -n --dry-run       print out SQL instead of running it
    -D --drop-tables   DROP TABLEs before deploying

You can see that the that the argument is now mandatory, and the usage message no longer has the '[]' brackets. If the automatically generated usage message is not to your liking, you can write a usage_desc() method to specify your own, but that is not really recommended as you'll have to keep it up to date manually when your code changes:

sub usage_desc {
    return '%c %o <DATABASE>'
}

Now imagine that the application should have more functions, for example 'test', and 'undeploy', and that they should be run as sub-commands. We will rewrite 'Your::Command' as follows:

package Your::Command;


sub opt_spec {(
    [ "dry-run|n",     "print out SQL instead of running it" ],
)};


sub arg_spec {(
    [ "command=s",   "what to do", { required => 1 } ],
)};

What we now have is a global option 'dry-run', that applies to all commands, accessed through the third argument to the run() method (see below). Because the 'Your::Command' arg_spec defines a mandatory argument, our usage message is still displayed when we run our command with no arguments. If we wanted an action to take place when no arguments are given, we would make the Your::Command argument optional, and reinstate the run() method in that package.

Now we write a new command class 'Your::Command::deploy' as follows ( 'test' and 'undeploy' are similarly written):

package Your::Command::deploy;


sub arg_spec {(
    [ "database=s",   "production|development",
        { default => 'development', required => 1 } 
    ],
)};


sub run {
    my ($self,$opt,$gopt) = @_;


    if ( $gopt->dry_run ) {
        print "Not ";
    } 
    print "Deploying to ". $opt->database ."\n";
}

1;
__END__


=head1 NAME


Your::Command::deploy - deploy to a database

Lets build the dispatcher class again:

ex3$ app-dispatcher --add-help Your::Command
Found lib/Your/Command/test.pm
Found lib/Your/Command/undeploy.pm
Found lib/Your/Command/deploy.pm
Writing lib/Your/Command/Dispatcher.pm

Notice that the dispatcher has found our new command classes, and the usage message now shows more information about our subcommands:

ex3$ ./ex
usage: ex [options] <command>
    --help         print usage message and exit
    -n --dry-run   print out SQL instead of running it

Commands:
    test         test a database
    deploy       deploy to a database
    undeploy     undeploy a database

The informational text for sub-commands has been taken from the POD documentation in the class file. You can override this by specifying an 'abstract()' method.

Also displayed contextually correctly are usage messages for our sub commands:

ex3$ ./ex deploy 
usage: ex deploy [options] <database>
    --help    print usage message and exit

You can write sub-sub-commands as far down as you want to go. There is however only ever one global option as specified in the Your::Command class.

ex3$ ./ex -n deploy backup
Not Deploying to backup

By default, commands are listed in a semi-random order. If you want to list them in an order that makes more sense (for example in the order they would typicaly be run) you can add an order() method to each class which returns an integer.

package Your::Command::deploy;

sub order {1};

package Your::Command::test;

sub order {2};

package Your::Command::undeploy;

sub order {3};

And now we have:

ex4$ ./ex 
usage: ex [options] <command>
    --help         print usage message and exit
    -n --dry-run   print out SQL instead of running it

Commands:
    deploy       deploy to a database
    test         test a database
    undeploy     undeploy a database

App::Dispatcher is brand new and has just been uploaded to CPAN. Feedback, bug reports, patches etc are very welcome.

Alternatives

It seems the current state of the art for command line applications is App::Cmd. I wrote App::Dispatcher out of the frustration with the time that it takes App::Cmd to simply generate a usage message, since App::Cmd loads every command class in an app dynamically.