NAME

CLI::Dispatch - simple CLI dispatcher

SYNOPSIS

  * Basic usage

  In your script file (e.g. script.pl):

    #!/usr/bin/perl
    use strict;
    use lib 'lib';
    use CLI::Dispatch;
    CLI::Dispatch->run('MyScript');

  And in your "command" file (e.g. lib/MyScript/DumpMe.pm):

    package MyScript::DumpMe;
    use strict;
    use base 'CLI::Dispatch::Command';
    use Data::Dump;

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

      @args = $self unless @args;

      # do something
      print $self->{verbose} ? Data::Dump::dump(@args) : @args;
    }
    1;

  From the shell:

    > perl script.pl dump_me "some args" --verbose

    # will dump "some args"

  * Advanced usage

  In your script file (e.g. script.pl):

    #!/usr/bin/perl
    use strict;
    use lib 'lib';
    use MyScript;
    MyScript->run;

  And in your "dispatcher" file (e.g. lib/MyScript.pm):

    package MyScript;
    use strict;
    use base 'CLI::Dispatch';

    sub options {qw( help|h|? verbose|v stderr )}
    sub get_command { shift @ARGV || 'Help' }  # no camelization

    1;

  And in your "command" file (e.g. lib/MyScript/escape.pm):

    package MyScript::escape;
    use strict;
    use base 'CLI::Dispatch::Command';

    sub options {qw( uri )}

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

      if ( $self->{uri} ) {
        require URI::Escape;
        print URI::Escape::uri_escape($args[0]);
      }
      else {
        require HTML::Entities;
        print HTML::Entities::encode_entities($args[0]);
      }
    }
    1;

  From the shell:

    > perl script.pl escape "query=some string!?" --uri

    # will print a uri-escaped string

  * Lazy way

  In your script file (e.g. inline.pl):

    use strict;
    MyScript::Inline->run_directly;

    package MyScript::Inline;
    use base 'CLI::Dispatch::Command';
    sub run {
      my ($self, @args) = @_;

      # do something...
    }

  From the shell:

    > perl inline.pl -v

  * Using subcommands

  In your script file (e.g. script.pl):

    #!/usr/bin/perl
    use strict;
    use lib 'lib';
    use CLI::Dispatch;
    CLI::Dispatch->run('MyScript');

  And in your "command" file (e.g. lib/MyScript/Command.pm):

    package MyScript::Command;
    use strict;
    use CLI::Dispatch;
    use base 'CLI::Dispatch::Command';

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

      # create a dispatcher object configured with the same options
      # as this command
      my $dispatcher = CLI::Dispatch->new(%$self);

      $dispatcher->run('MyScript::Command');
    }

    1;

  And in your "subcommand" file (e.g. lib/MyScript/Command/Subcommand'):

    package MyScript::Command::Subcommand;
    use strict;
    use base 'CLI::Dispatch::Command';

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

      # do something useful
    }

    1;

  From the shell:

    > perl script.pl command subcommand "some args" --verbose

    # will do something useful

DESCRIPTION

CLI::Dispatch is a simple CLI dispatcher. Basic usage is almost the same as the one of App::CLI, but you can omit a dispatcher class if you don't need to customize. Command/class mapping is slightly different, too (ucfirst for App::CLI, and camelize for CLI::Dispatch). And unlike App::Cmd, CLI::Dispatch dispatcher works even when some of the subordinate commands are broken for various reasons (unsupported OS, lack of dependencies, etc). Those are the main reasons why I reinvent the wheel.

See CLI::Dispatch::Command to know how to write an actual command class.

METHODS

run

takes optional namespaces, and parses @ARGV to load an appropriate command class, and runs it with options that are also parsed from @ARGV. As shown in the SYNOPSIS, you don't need to pass anything when you create a dispatcher subclass, and vice versa.

options

specifies an array of global options every command should have. By default, help and verbose (and their short forms) are registered. Command-specific options should be placed in each command class.

default_command

specifies a default command that will run when you don't specify any command (when you run a script without any arguments). help by default.

get_command

usually looks for a command from @ARGV (after global options are parsed), transforms it if necessary (camelize by default), and returns the result.

If you have only one command, and you don't want to specify it every time when you run a script, let this just return the command:

  sub get_command { 'JustDoThis' }

Then, when you run the script, YourScript::JustDoThis command will always be executed (and the first argument won't be considered as a command).

convert_command

takes a command name, transforms it if necessary (camelize by default), and returns the result. You may also want to override this to convert short aliases for long command names.

  sub convert_command {
    my $command = shift->SUPER::convert_command(@_);
    return ($command eq 'Fcgi') ? 'FastCGI' : $command;
  }

get_options

takes an array of option specifications and returns a hash of parsed options. See Getopt::Long for option specifications.

load_command

takes a namespace, and a flag to tell if the help option is set or not, and loads an appropriate command class to return its instance.

run_directly

takes a fully qualified package name, and loads it if necessary, and run it with options parsed from @ARGV. This is mainly used to run a command directly (without configuring a dispatcher), which makes writing a simple command easier. You usually don't need to use this directly. This is called internally when you run a command (based on CLI::Dispatch::Command) directly, without instantiation.

new (since 0.17)

creates a dispatcher object. You usually don't need to use this (because CLI::Dispatch creates this internally). If you need to copy options from a command to its subcommand, this may help.

SEE ALSO

App::CLI, App::Cmd, Getopt::Long

AUTHOR

Kenichi Ishigaki, <ishigaki@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Kenichi Ishigaki.

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

cpanm CLI::Dispatch

perl -MCPAN -e shell
install CLI::Dispatch