view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    App::Cmdline - helper for writing command-line applications

VERSION
    version 0.1.2

SYNOPSIS
    In your command-line script, e.g. in myapp:

       use App::myapp;
       App::myapp->run;

    Such command-line script will be executed, for example, by:

      senger@ShereKhan$ myapp --version
      senger@ShereKhan$ myapp --check
      senger@ShereKhan$ myapp -c

    In your module that does the full job you are implementing, e.g. in
    App/myapp.pm:

       package App::myapp;
       use parent 'App::Cmdline';

       # Define your own options, and/or add some predefined sets.
       sub opt_spec {
           my $self = shift;
           return $self->check_for_duplicates (
               [ 'check|c' => "only check the configuration"  ],
               $self->composed_of (
                   'App::Cmdline::Options::Basic',
                   'App::Cmdline::Options::DB',
               )
           );
       }

       # The main job is implemented here
       use Data::Dumper;
       sub execute {
           my ($self, $opt, $args) = @_;

           print STDERR "Started...\n" unless $opt->quiet;
           print STDOUT 'Options ($opt):    ' . Dumper ($opt);
           print STDOUT 'Arguments ($args): ' . Dumper ($args);
           ...
       }

DESCRIPTION
    This module helps to write command-line applications, especially if they
    need to be fed by some command-line options and arguments. It extends
    the App::Cmd::Simple module by adding the ability to use several
    predefined sets of options that many real command-line applications use
    and need anyway. For example, in most applications you need a way how to
    print its version or how to provide a decent help text. Once (or if) you
    agree with the way how it is done here, you can spend much less time
    with the almost-always-repeating options.

    Your module (representing the application you are writing) should
    inherit from this module and implement, at least, the method opt_spec
    (optionally) and the method execute (mandatory).

METHODS
    In order to use the ability of composing list of options from the
    existing sets of predefined options (which is, after all, the main
    *raison d'être* of this module) use the method composed_of. And to find
    out that various predefined sets of options do not step on each other
    toes, use the method check_for_duplicates.

    When writing a subclass of App::Cmdline, there are only a few methods
    that you might want to overwrite (except for execute that you must
    overwrite). Below are those that may be of your interest, or those that
    are implemented here slightly differently from the App::Cmd::Simple.

   Summary of methods
    Methods that you must overwrite
           execute()

    Methods that you should overwrite
           opt_spec()

    Methods that you may overwrite
           usage_desc()
           validate_args()
           usage_error()
           getopt_conf()
           ...

    Methods that you just call
           composed_of()
           check_for_duplicates()
           usage_error()

  opt_spec
    This method returns a list with option definitions, each element being
    an arrayref. This returned list is passed (starting as its second
    argument) to "describe_options" from Getopt::Long::Descriptive. You need
    to check the documentation on how to specify options, but mainly each
    element is a pair of *option specification* and the *help text for this