view release on metacpan or  search on metacpan

lib/App/Cmdline.pm  view on Meta::CPAN

    return [
        'no_bundling',
        'no_ignore_case',
        'auto_abbrev',
        ];
}

# ----------------------------------------------------------------
# Die with a given $error message and with the full Usage.
# ----------------------------------------------------------------
sub usage_error {
    my ( $self, $error ) = @_;
    die "Error: $error\nUsage: " . $self->usage->text;
}

1;


=pod

=head1 NAME

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

=head1 VERSION

version 0.1.2

=head1 SYNOPSIS

In your command-line script, e.g. in F<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
F<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);
       ...
   }

=head1 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 L<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
L<opt_spec|"opt_spec"> (optionally) and the method L<execute|"execute"> (mandatory).

=for :stopwords d'E<234>tre

=head1 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
I<raison d'E<234>tre> of this module) use the method
L<composed_of|"composed_of">. And to find out that various predefined
sets of options do not step on each other toes, use the method
L<check_for_duplicates|"check_for_duplicates">.

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

=head3 Summary of methods

=over

=item Methods that you must overwrite

   execute()

=item Methods that you should overwrite

   opt_spec()

=item Methods that you may overwrite

   usage_desc()
   validate_args()
   usage_error()
   getopt_conf()
   ...