1App::Yath::Command(3) User Contributed Perl DocumentationApp::Yath::Command(3)
2
3
4
6 App::Yath::Command - Base class for yath commands
7
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
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
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
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
142 The source code repository for Test2-Harness can be found at
143 http://github.com/Test-More/Test2-Harness/.
144
146 Chad Granum <exodist@cpan.org>
147
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.36.0 2022-09-08 App::Yath::Command(3)