###########
BaseCommand
###########


****
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.


.. code-block:: perl

     $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.


.. code-block:: perl

     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.


.. code-block:: perl

     $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.


.. code-block:: perl

     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).


.. code-block:: perl

     return $CommandObject->ExitCodeError();


You can also provide a custom error code for special use cases:


.. code-block:: perl

     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.


.. code-block:: perl

     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


.. code-block:: perl

     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  |
     +--------------+---------------+--------------+



_ParseGlobalOptions()
=====================


parses any global options possibly provided by the user.

Returns a hash with the option values.


_ParseCommandlineArguments()
============================


parses and validates the command line arguments provided by the user according to
the configured arguments and options of the command.

Returns a hash with argument and option values if all needed values were supplied
and correct, or undef otherwise.


_Color()
========


this will color the given text (see Term::ANSIColor::color()) if
ANSI output is available and active, otherwise the text stays unchanged.


.. code-block:: perl

     my $PossiblyColoredText = $CommandObject->_Color('green', $Text);