.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "App::Yath::Command 3pm"
.TH App::Yath::Command 3pm "2023-03-12" "perl v5.36.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 "NAME"
App::Yath::Command \- Base class for yath commands
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the base class for any/all yath commands. If you wish to add a new yath
command you should subclass this package.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    package App::Yath::Command::mycommand;
\&    use strict;
\&    use warnings;
\&
\&    use App::Yath::Options();
\&    use parent \*(AqApp::Yath::Command\*(Aq;
\&
\&    # Include existing option sets
\&    include_options(
\&        \*(AqApp::Yath::Options::Debug\*(Aq,
\&        \*(AqApp::Yath::Options::PreCommand\*(Aq,
\&        ...,
\&    );
\&
\&    # Add some custom options
\&    option_group {prefix => \*(Aqmycommand\*(Aq, category => \*(Aqmycommand options\*(Aq} => sub {
\&        option foo => (
\&            description => "the foo option",
\&            default     => 0,
\&        );
\&    };
\&
\&    # This is used to sort/group commands in the "yath help" output
\&    sub group { \*(Aqthirdparty\*(Aq }
\&
\&    # Brief 1\-line summary
\&    sub summary { "This is a third party command, it does stuff..." }
\&
\&    # Longer description of the command (used in yath help mycommand)
\&    sub description {
\&        return <<"    EOT";
\&    This command does:
\&    This
\&    That
\&    Those
\&        EOT
\&    }
\&
\&    # Entrypoint
\&    sub run {
\&        my $self = shift;
\&
\&        my $settings = $self\->settings;
\&        my $args     = $self\->args;
\&
\&        print "Hello Third Party!\en"
\&
\&        # Return an exit value.
\&        return 0;
\&    }
.Ve
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.ie n .IP "$string = $cmd_class\->cli_help(settings => $settings, options => $options)" 4
.el .IP "\f(CW$string\fR = \f(CW$cmd_class\fR\->cli_help(settings => \f(CW$settings\fR, options => \f(CW$options\fR)" 4
.IX Item "$string = $cmd_class->cli_help(settings => $settings, options => $options)"
This method generates the command line help for any given command. In general
you will \s-1NOT\s0 want to override this.
.Sp
\&\f(CW$settings\fR should be an instance of Test2::Harness::Settings.
.Sp
\&\f(CW$options\fR should be an instance of App::Yath::Options if provided. This
method is usually capable of filling in the details when this is omitted.
.ie n .IP "$multi_line_string = $cmd_class\->\fBdescription()\fR" 4
.el .IP "\f(CW$multi_line_string\fR = \f(CW$cmd_class\fR\->\fBdescription()\fR" 4
.IX Item "$multi_line_string = $cmd_class->description()"
Long-form description of the command. Used in \f(CW\*(C`cli_help()\*(C'\fR.
.ie n .IP "@list = $cmd_class\->\fBdoc_args()\fR" 4
.el .IP "\f(CW@list\fR = \f(CW$cmd_class\fR\->\fBdoc_args()\fR" 4
.IX Item "@list = $cmd_class->doc_args()"
A list of argument names to the command, used to generate documentation.
.ie n .IP "$string = $cmd_class\->\fBgenerate_pod()\fR" 4
.el .IP "\f(CW$string\fR = \f(CW$cmd_class\fR\->\fBgenerate_pod()\fR" 4
.IX Item "$string = $cmd_class->generate_pod()"
This can be used to generate \s-1POD\s0 documentation from the command itself using
the other fields listed in this section, as well as all applicable command
lines options specified in the command.
.ie n .IP "$string = $cmd_class\->\fBgroup()\fR" 4
.el .IP "\f(CW$string\fR = \f(CW$cmd_class\fR\->\fBgroup()\fR" 4
.IX Item "$string = $cmd_class->group()"
Used for sorting/grouping commands in the \f(CW\*(C`yath help\*(C'\fR output.
.Sp
Existing groups:
.Sp
.Vb 4
\&    \*(Aq test\*(Aq     # Space in front to make sure test related command float up
\&    \*(Aqlog\*(Aq       # Log processing commands
\&    \*(Aqpersist\*(Aq   # Commands related to the persistent runner
\&    \*(Aqzinit\*(Aq     # The init command and related command sink to the bottom.
.Ve
.Sp
Unless your command \s-1OBVIOUSLY\s0 and \s-1CLEARLY\s0 belongs in one of the above groups
you should probably create your own. Please do not prefix it with a space to
make it float, \f(CW\*(Aq test\*(Aq\fR is a special case, you are not that special.
.ie n .IP "$string = $cmd_class\->\fBname()\fR" 4
.el .IP "\f(CW$string\fR = \f(CW$cmd_class\fR\->\fBname()\fR" 4
.IX Item "$string = $cmd_class->name()"
Name of the command. By default this is the last part of the package name. You
will probably never want to override this.
.ie n .IP "$short_string = $cmd_class\->\fBsummary()\fR" 4
.el .IP "\f(CW$short_string\fR = \f(CW$cmd_class\fR\->\fBsummary()\fR" 4
.IX Item "$short_string = $cmd_class->summary()"
A short summary of what this command is.
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
.ie n .IP "$bool = $cmd\->\fBalways_keep_dir()\fR" 4
.el .IP "\f(CW$bool\fR = \f(CW$cmd\fR\->\fBalways_keep_dir()\fR" 4
.IX Item "$bool = $cmd->always_keep_dir()"
By default the working directory is deleted when yath exits. Some commands such
as App::Yath::Command::start need to keep the directory. Override this
method to return true if your command uses the workdir and needs to keep it.
.ie n .IP "$arrayref = $cmd\->\fBargs()\fR" 4
.el .IP "\f(CW$arrayref\fR = \f(CW$cmd\fR\->\fBargs()\fR" 4
.IX Item "$arrayref = $cmd->args()"
Get an arrayref of command line arguments \fB\s-1AFTER\s0\fR options have been
process/removed.
.ie n .IP "$bool = $cmd\->\fBinternal_only()\fR" 4
.el .IP "\f(CW$bool\fR = \f(CW$cmd\fR\->\fBinternal_only()\fR" 4
.IX Item "$bool = $cmd->internal_only()"
Set this to true if you do not want your command to show up in the help output.
.ie n .IP "$exit_code = $cmd\->\fBrun()\fR" 4
.el .IP "\f(CW$exit_code\fR = \f(CW$cmd\fR\->\fBrun()\fR" 4
.IX Item "$exit_code = $cmd->run()"
This is the main entrypoint for the command. You \fB\s-1MUST\s0\fR override this. This
method should return an exit code.
.ie n .IP "$settings = $cmd\->\fBsettings()\fR" 4
.el .IP "\f(CW$settings\fR = \f(CW$cmd\fR\->\fBsettings()\fR" 4
.IX Item "$settings = $cmd->settings()"
Get the settings as populated by the command line options.
.ie n .IP "$cmd\->write_settings_to($directory, $filename)" 4
.el .IP "\f(CW$cmd\fR\->write_settings_to($directory, \f(CW$filename\fR)" 4
.IX Item "$cmd->write_settings_to($directory, $filename)"
A helper method to write the settings to a specified directory and filename.
File is written as \s-1JSON.\s0
.Sp
If you are subclassing another command such as App::Yath::Command::test you
may want to override this to a no-op to prevent the settings file from being
written, the App::Yath::Command:run command does this.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Test2\-Harness can be found at
\&\fIhttp://github.com/Test\-More/Test2\-Harness/\fR.
.SH "MAINTAINERS"
.IX Header "MAINTAINERS"
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.SH "AUTHORS"
.IX Header "AUTHORS"
.PD 0
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.PD
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2020 Chad Granum <exodist7@gmail.com>.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.PP
See \fIhttp://dev.perl.org/licenses/\fR