.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 >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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Command::V2 3pm"
.TH Command::V2 3pm "2019-01-02" "perl v5.28.1" "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"
Command \- base class for modules implementing the command pattern
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use TopLevelNamespace;
\&
\&  class TopLevelNamespace::SomeObj::Command {
\&    is => \*(AqCommand\*(Aq,
\&    has => [
\&        someobj => { is => \*(AqTopLevelNamespace::SomeObj\*(Aq, id_by => \*(Aqsome_obj_id\*(Aq },
\&        verbose => { is => \*(AqBoolean\*(Aq, is_optional => 1 },
\&    ],
\&  };
\&
\&  sub execute {
\&      my $self = shift;
\&      if ($self\->verbose) {
\&          print "Working on id ",$self\->some_obj_id,"\en";
\&      }
\&      my $result = $someobj\->do_something();
\&      if ($self\->verbose) {
\&          print "Result was $result\en";
\&      }
\&      return $result;
\&  }
\&
\&  sub help_brief {
\&      return \*(AqCall do_something on a SomeObj instance\*(Aq;
\&  }
\&  sub help_synopsis {
\&      return \*(Aqcmd \-\-some_obj_id 123 \-\-verbose\*(Aq;
\&  }
\&  sub help_detail {
\&      return \*(AqThis command performs a FooBarBaz transform on a SomObj object instance by calling its do_something method.\*(Aq;
\&  }
\&
\&  # Another part of the code
\& 
\&  my $cmd = TopLevelNamespace::SomeObj::Command\->create(some_obj_id => $some_obj\->id);
\&  $cmd\->execute();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Command module is a base class for creating other command modules
implementing the Command Pattern.  These modules can be easily reused in
applications or loaded and executed dynamicaly in a command-line program.
.PP
Each Command subclass represents a reusable work unit.  The bulk of the
module's code will likely be in the \fBexecute()\fR method.  \fBexecute()\fR will
usually take only a single argument, an instance of the Command subclass.
.SH "Command-line use"
.IX Header "Command-line use"
Creating a top-level Command module called, say TopLevelNamespace::Command,
and a script called tln_cmd that looks like:
.PP
.Vb 3
\&  #!/usr/bin/perl
\&  use TopLevelNamespace;
\&  TopLevelNamespace::Command\->execute_with_shell_params_and_exit();
.Ve
.PP
gives you an instant command-line tool as an interface to the hierarchy of
command modules at TopLevelNamespace::Command.
.PP
For example:
.PP
.Vb 1
\&  > tln_cmd foo bar \-\-baz 1 \-\-qux
.Ve
.PP
will create an instance of TopLevelNamespace::Command::Foo::Bar (if that
class exists) with params baz => 1 and qux => 1, assumming qux is a boolean
property, call \fBexecute()\fR on it, and translate the return value from \fBexecute()\fR
into the appropriate notion of a shell return value, meaning that if
\&\fBexecute()\fR returns true in the Perl sense, then the script returns 0 \- true in
the shell sense.
.PP
The infrastructure takes care of turning the command line parameters into
parameters for \fBcreate()\fR.  Params designated as is_optional are, of course,
optional and non-optional parameters that are missing will generate an error.
.PP
\&\-\-help is an implicit param applicable to all Command modules.  It generates 
some hopefully useful text based on the documentation in the class definition
(the 'doc' attributes you can attach to a class and properties), and the
strings returned by \fBhelp_detail()\fR, \fBhelp_brief()\fR and \fBhelp_synopsis()\fR.
.SH "TODO"
.IX Header "TODO"
This documentation needs to be fleshed out more.  There's a lot of special 
things you can do with Command modules that isn't mentioned here yet.