.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.48)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "App::Cmd::Simple 3"
.TH App::Cmd::Simple 3 2026-10-25 "perl v5.44.0" "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 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 0.01;
\&  use parent 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\*(Aqs 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\*(Aqt 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\*(Aqt deviate too much from
the sort of thing shown in the synopsis as you might like.  If you\*(Aqre 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\*(Aqs how things work.  You can just do this:
.PP
.Vb 1
\&  YourApp::Cmd\->import\->run;
.Ve