NAME
Kernel::System::Console::BaseCommand – command base class
DESCRIPTION
Base class for console commands.
PUBLIC INTERFACE
new()
constructor for new objects. You should not need to reimplement this in your command, override "Configure()" instead if you need to.
Configure()
initializes this object. Override this method in your commands.
This method might throw exceptions.
Name()
get the Name of the current Command, e. g. 'Admin::User::SetPassword'.
Description()
get/set description for the current command. Call this in your Configure() method.
AdditionalHelp()
get/set additional help text for the current command. Call this in your Configure() method.
You can use color tags (see "Print()") in your help tags.
AddArgument()
adds an argument that can/must be specified on the command line. This function must be called during Configure() by the command to indicate which arguments it can process.
$CommandObject->AddArgument(
Name => 'filename',
Description => 'name of the file to be loaded',
Required => 1,
ValueRegex => qr{a-zA-Z0-9]\.txt},
);Please note that required arguments have to be specified before any optional ones.
The information about known arguments and options (see below) will be used to generate usage help and also to automatically verify the data provided by the user on the command line.
GetArgument()
fetch an argument value as provided by the user on the command line.
my $Filename = $CommandObject->GetArgument('filename');AddOption()
adds an option that can/must be specified on the command line. This function must be called during "Configure()" by the command to indicate which arguments it can process.
$CommandObject->AddOption(
Name => 'iterations',
Description => 'number of script iterations to perform',
Required => 1,
HasValue => 0,
ValueRegex => qr{\d+},
Multiple => 0, # optional, allow more than one occurrence (only possible if HasValue is true)
);Option Naming Conventions
If there is a source and a target involved in the command, the related options should start with --source and --target, for example --source-path.
For specifying filesystem locations, --*-path should be used for directory/filename combinations (e.g. mydirectory/myfile.pl), --*-filename for filenames without directories, and --*-directory for directories.
Example: --target-path /tmp/test.out --source-filename test.txt --source-directory /tmp
GetOption()
fetch an option as provided by the user on the command line.
my $Iterations = $CommandObject->GetOption('iterations');If the option was specified with HasValue => 1, the user provided value will be returned. Otherwise 1 will be returned if the option was present.
In case of an option with Multiple = 1>, an array reference will be returned if the option was specified, and undef otherwise.
PreRun()
perform additional validations/preparations before Run(). Override this method in your commands.
If this method returns, execution will be continued. If it throws an exception with die(), the program aborts at this point, and Run() will not be called.
Run()
runs the command. Override this method in your commands.
This method needs to return the exit code to be used for the whole program. For this, the convenience methods ExitCodeOk() and ExitCodeError() can be used.
In case of an exception, the error code will be set to 1 (error).
PostRun()
perform additional cleanups after Run(). Override this method in your commands.
The return value of this method will be ignored. It will be called after Run(), even if Run() caused an exception or returned an error exit code.
In case of an exception in this method, the exit code will be set to 1 (error) if Run() returned 0 (ok).
Execute()
this method will parse/validate the command line arguments supplied by the user. If that was ok, the Run() method of the command will be called.
ExitCodeError()
returns an exit code to signal something went wrong (mostly for better code readability).
return $CommandObject->ExitCodeError();You can also provide a custom error code for special use cases:
return $CommandObject->ExitCodeError(255);ExitCodeOk()
returns 0 as exit code to indicate everything went fine in the command (mostly for better code readability).
GetUsageHelp()
generates usage / help screen for this command.
my $UsageHelp = $CommandObject->GetUsageHelp();ANSI()
get/set support for colored text.
PrintError()
shorthand method to print an error message to STDERR.
It will be prefixed with 'Error: ' and colored in red, if the terminal supports it (see "ANSI()").
Print()
this method will print the given text to STDOUT.
You can add color tags (<green>...</green>, <yellow>...</yellow>, <red>...</red>) to your text, and they will be replaced with the corresponding terminal escape sequences if the terminal supports it (see "ANSI()").
TableOutput()
this method generates an ascii table of headers and column content
my $FormattedOutput = $Command->TableOutput(
TableData => {
Header => [
'First Header',
'Second Header',
'Third Header'
],
Body => [
[ 'FirstItem 1', 'SecondItem 1', 'ThirdItem 1' ],
[ 'FirstItem 2', 'SecondItem 2', 'ThirdItem 2' ],
[ 'FirstItem 3', 'SecondItem 3', 'ThirdItem 3' ],
[ 'FirstItem 4', 'SecondItem 4', 'ThirdItem 4' ],
],
},
Indention => 2, # Spaces to indent (ltr), default 0;
EvenOdd => 'yellow', # add even and odd line coloring (green|yellow|red)
# (overwrites existing coloring), # default 0
);
Returns:
+--------------+---------------+--------------+
| First Header | Second Header | Third Header |
+--------------+---------------+--------------+
| FirstItem 1 | SecondItem 1 | ThirdItem 1 |
| FirstItem 2 | SecondItem 2 | ThirdItem 1 |
| FirstItem 3 | SecondItem 3 | ThirdItem 1 |
| FirstItem 4 | SecondItem 4 | ThirdItem 1 |
+--------------+---------------+--------------+