.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "App::Cmd::Simple 3pm"
.TH App::Cmd::Simple 3pm "2016-07-18" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
App::Cmd::Simple \- a helper for building one\-command App::Cmd applications
.SH "VERSION"
.IX Header "VERSION"
version 0.331
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
in \fIsimplecmd\fR:
.PP
.Vb 2
\&  use YourApp::Cmd;
\&  Your::Cmd\->run;
.Ve
.PP
in \fIYourApp/Cmd.pm\fR:
.PP
.Vb 2
\&  package YourApp::Cmd;
\&  use base qw(App::Cmd::Simple);
\&
\&  sub opt_spec {
\&    return (
\&      [ "blortex|X",  "use the blortex algorithm" ],
\&      [ "recheck|r",  "recheck all results"       ],
\&    );
\&  }
\&
\&  sub validate_args {
\&    my ($self, $opt, $args) = @_;
\&
\&    # no args allowed but options!
\&    $self\->usage_error("No args allowed") if @$args;
\&  }
\&
\&  sub execute {
\&    my ($self, $opt, $args) = @_;
\&
\&    my $result = $opt\->{blortex} ? blortex() : blort();
\&
\&    recheck($result) if $opt\->{recheck};
\&
\&    print $result;
\&  }
.Ve
.PP
and, finally, at the command line:
.PP
.Vb 1
\&  knight!rjbs$ simplecmd \-\-recheck
\&
\&  All blorts successful.
.Ve
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
When writing a subclass of App::Cmd:Simple, there are only a few methods that
you might want to implement.  They behave just like the same-named methods in
App::Cmd.
.SS "opt_spec"
.IX Subsection "opt_spec"
This method should be overridden to provide option specifications.  (This is
list of arguments passed to \f(CW\*(C`describe_options\*(C'\fR from Getopt::Long::Descriptive,
after the first.)
.PP
If not overridden, it returns an empty list.
.SS "usage_desc"
.IX Subsection "usage_desc"
This method should be overridden to provide the top level usage line.
It's a one-line summary of how the command is to be invoked, and
should be given in the format used for the \f(CW$usage_desc\fR parameter to
\&\f(CW\*(C`describe_options\*(C'\fR in Getopt::Long::Descriptive.
.PP
If not overridden, it returns something that prints out like:
.PP
.Vb 1
\&  yourapp [\-?h] [long options...]
.Ve
.SS "validate_args"
.IX Subsection "validate_args"
.Vb 1
\&  $cmd\->validate_args(\e%opt, \e@args);
.Ve
.PP
This method is passed a hashref of command line options (as processed by
Getopt::Long::Descriptive) and an arrayref of leftover arguments.  It may throw
an exception (preferably by calling \f(CW\*(C`usage_error\*(C'\fR) if they are invalid, or it
may do nothing to allow processing to continue.
.SS "execute"
.IX Subsection "execute"
.Vb 1
\&  Your::App::Cmd::Simple\->execute(\e%opt, \e@args);
.Ve
.PP
This method does whatever it is the command should do!  It is passed a hash
reference of the parsed command-line options and an array reference of left
over arguments.
.SH "WARNINGS"
.IX Header "WARNINGS"
\&\fBThis should be considered experimental!\fR  Although it is probably not going
to change much, don't build your business model around it yet, okay?
.PP
App::Cmd::Simple is not rich in black magic, but it does do some somewhat
gnarly things to make an App::Cmd::Simple look as much like an
App::Cmd::Command as possible.  This means that you can't deviate too much from
the sort of thing shown in the synopsis as you might like.  If you're doing
something other than writing a fairly simple command, and you want to screw
around with the App::Cmd\-iness of your program, Simple might not be the best
choice.
.PP
\&\fBOne specific warning...\fR  if you are writing a program with the
App::Cmd::Simple class embedded in it, you \fBmust\fR call import on the class.
That's how things work.  You can just do this:
.PP
.Vb 1
\&  YourApp::Cmd\->import\->run;
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Ricardo Signes <rjbs@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2016 by Ricardo Signes.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.