1App::Yath::Command(3) User Contributed Perl DocumentationApp::Yath::Command(3)
2
3
4

NAME

6       App::Yath::Command - Base class for yath commands
7

DESCRIPTION

9       This is the base class for any/all yath commands. If you wish to add a
10       new yath command you should subclass this package.
11

SYNOPSIS

13           package App::Yath::Command::mycommand;
14           use strict;
15           use warnings;
16
17           use App::Yath::Options();
18           use parent 'App::Yath::Command';
19
20           # Include existing option sets
21           include_options(
22               'App::Yath::Options::Debug',
23               'App::Yath::Options::PreCommand',
24               ...,
25           );
26
27           # Add some custom options
28           option_group {prefix => 'mycommand', category => 'mycommand options'} => sub {
29               option foo => (
30                   description => "the foo option",
31                   default     => 0,
32               );
33           };
34
35           # This is used to sort/group commands in the "yath help" output
36           sub group { 'thirdparty' }
37
38           # Brief 1-line summary
39           sub summary { "This is a third party command, it does stuff..." }
40
41           # Longer description of the command (used in yath help mycommand)
42           sub description {
43               return <<"    EOT";
44           This command does:
45           This
46           That
47           Those
48               EOT
49           }
50
51           # Entrypoint
52           sub run {
53               my $self = shift;
54
55               my $settings = $self->settings;
56               my $args     = $self->args;
57
58               print "Hello Third Party!\n"
59
60               # Return an exit value.
61               return 0;
62           }
63

CLASS METHODS

65       $string = $cmd_class->cli_help(settings => $settings, options =>
66       $options)
67           This method generates the command line help for any given command.
68           In general you will NOT want to override this.
69
70           $settings should be an instance of Test2::Harness::Settings.
71
72           $options should be an instance of App::Yath::Options if provided.
73           This method is usually capable of filling in the details when this
74           is omitted.
75
76       $multi_line_string = $cmd_class->description()
77           Long-form description of the command. Used in cli_help().
78
79       @list = $cmd_class->doc_args()
80           A list of argument names to the command, used to generate
81           documentation.
82
83       $string = $cmd_class->generate_pod()
84           This can be used to generate POD documentation from the command
85           itself using the other fields listed in this section, as well as
86           all applicable command lines options specified in the command.
87
88       $string = $cmd_class->group()
89           Used for sorting/grouping commands in the "yath help" output.
90
91           Existing groups:
92
93               ' test'     # Space in front to make sure test related command float up
94               'log'       # Log processing commands
95               'persist'   # Commands related to the persistent runner
96               'zinit'     # The init command and related command sink to the bottom.
97
98           Unless your command OBVIOUSLY and CLEARLY belongs in one of the
99           above groups you should probably create your own. Please do not
100           prefix it with a space to make it float, ' test' is a special case,
101           you are not that special.
102
103       $string = $cmd_class->name()
104           Name of the command. By default this is the last part of the
105           package name. You will probably never want to override this.
106
107       $short_string = $cmd_class->summary()
108           A short summary of what this command is.
109

OBJECT METHODS

111       $bool = $cmd->always_keep_dir()
112           By default the working directory is deleted when yath exits. Some
113           commands such as App::Yath::Command::start need to keep the
114           directory. Override this method to return true if your command uses
115           the workdir and needs to keep it.
116
117       $arrayref = $cmd->args()
118           Get an arrayref of command line arguments AFTER options have been
119           process/removed.
120
121       $bool = $cmd->internal_only()
122           Set this to true if you do not want your command to show up in the
123           help output.
124
125       $exit_code = $cmd->run()
126           This is the main entrypoint for the command. You MUST override
127           this. This method should return an exit code.
128
129       $settings = $cmd->settings()
130           Get the settings as populated by the command line options.
131
132       $cmd->write_settings_to($directory, $filename)
133           A helper method to write the settings to a specified directory and
134           filename.  File is written as JSON.
135
136           If you are subclassing another command such as
137           App::Yath::Command::test you may want to override this to a no-op
138           to prevent the settings file from being written, the
139           App::Yath::Command:run command does this.
140

SOURCE

142       The source code repository for Test2-Harness can be found at
143       http://github.com/Test-More/Test2-Harness/.
144

MAINTAINERS

146       Chad Granum <exodist@cpan.org>
147

AUTHORS

149       Chad Granum <exodist@cpan.org>
150
152       Copyright 2020 Chad Granum <exodist7@gmail.com>.
153
154       This program is free software; you can redistribute it and/or modify it
155       under the same terms as Perl itself.
156
157       See http://dev.perl.org/licenses/
158
159
160
161perl v5.38.0                      2023-10-04             App::Yath::Command(3)
Impressum