Goals
-----

This section provides the automation work line. The automation work line exists to standardize content production in CentOS Artwork Repository.  There is no need to type several tasks, time after time, if they can be programmed into just one executable script.

In this section you'll find how to organize and extend the centos-art.sh script, a bash scripts specially designed to automate most frequent tasks in the repository (e.g., image rendition, documenting directory structures, translating content, etc.).  If you can't resist the idea of automating repeatable tasks, then take a look here.

Description
-----------

The best way to understand the centos-art.sh script is studying and improving its source code.  However, as start point, you may prefer to read an introductory resume before diving into the source code details. In this section we identify the different parts the centos-art.sh script is made of and how these parts interact one another.

Execution environments
......................

The centos-art.sh script is basically made of four execution environments which are named script, global, specific and action. These execution environments are nested one into another and provide different definition levels for variables and functions.  In this design, variables and functions defined in higher execution environments are available on lower execution environments, but variables and functions defined in lower execution environments are not available for higher execution enviroments.

+----------------------------------------------------------------------+
| [centos@host]$ centos-art function path/to/dir --option='value'      |
+----------------------------------------------------------------------+
| ~/bin/centos-art --> ~/artwork/trunk/Scripts/centos-art.sh           |
+---v--------------------------------------------------------------v---+
    | centos-art.sh                                                |
    +---v------------------------------------------------------v---+
    .   | cli $@                                               |   .
    .   +---v----------------------------------------------v---+   .
    .   .   | cli_getFunctions                             |   .   .
    .   .   +---v--------------------------------------v---+   .   .
    .   .   .   | function                             |   .   .   .
    .   .   .   +---v------------------------------v---+   .   .   .
    .   .   .   .   | function_getArguments        |   .   .   .   .
    .   .   .   .   | function_doSomething         |   .   .   .   .
    .   .   .   .   +------------------------------+   .   .   .   .
    .   .   .   .                                      .   .   .   .
    .   .   .   .   Execution environment (action)     .   .   .   .
    .   .   .   ........................................   .   .   .
    .   .   .                                              .   .   .
    .   .   .   Execution environment (specific)           .   .   .
    .   .   ................................................   .   .
    .   .                                                      .   .
    .   .   Execution environment (global)                     .   .
    .   ........................................................   .
    .                                                              .
    .   Execution environment (script)                             .
    ................................................................

The script execution environment exists to provide script definitions that can't be set anywhere else inside the script. Example of such definitions include initialization of internationalization through gettext program, script personal information and initialization of global functionalities.

The global execution environment exists to provide definitions that can't be set anywhere else inside the script. Example of such definitions include initialization of functionalities (e.g., cli_printMessage, cli_getCurrentLocale, cli_checkFiles, etc.) and variables (e.g., FUNCNAM, FUNCDIR, FUNCDIRNAM, ARGUMENTS, etc.) that can be both used on specific and action execution environments, only.

The specific execution environment exists to provide definitions that can't be set anywhere else inside the script. Example of such definitions include initialization of specifc functionalities (e.g., render, help, locale, etc.) and specific variables (ACTIONNAM, ACTIONVAL, etc.) that can be used on action execution environment only.

The action execution environment exists to perform the script actions themselves. It is here where we perform content rendition, content documentation, content localization and whatever action you plan for the centos-art.sh script to perform. For example, if you passed the render value as first argument to centos-art.sh command-line, the script performs the content rendition action through the render function which is defined in the render.sh file under trunk/Scripts/Functions/Render directory. Is there, inside render functionality were the action execution environment takes place exactly.

Command-line interface
......................

When the centos-art command is executed in a bash terminal, the bash interpreter uses the PATH environment variable to find where such command is. In order to run the centos-art, it must exist either as a link to an executable file or an executable file by its own, in any of the paths provided by PATH environment variable.  Otherwise, the bash interpreter will print an error message and prompt you back to type a valid command.

By default, after installing The CentOS Distribution, there is no centos-art command available in the PATH environment variable for you to execute.  The centos-art command is made available in your workstation as result of executing the prepare functionality of centos-art.sh script (see Directories trunk Scripts Functions Prepare) which requires you had previously downloaded a working copy of CentOS Artwork Repository in your workstation.

When the centos-art is executed, the first positional parameter passed is required and represents the name of the function you want to perform (e.g., render for content rendition, locale for content localization, etc.).  Beyond the first positional parameter you can provide either option or non-option parameters in no specific order. There are also, option parameters with arguments and without arguments. Frequently, non-option paramters are used to specify the path location inside the repository where the function will be performed in (e.g., the directory structure do you want to produce content for) and option parameters to specify how such functionality is performed (e.g., do you want to go quietly?  do you want to do filtering?  etc.).

    A         B         C              D           E
---------- ------- ----------- ---------------- -------
centos-art funcnam path/to/dir --filter='regex' --quiet
---------- ------- ----------- ---------------- -------

    A = The centos-art.sh script command-line.
    B = The centos-art.sh function name.
    C = Non-option parameter.
    D = Option parameter (with argument).
    E = Option parameter (without argument).

Parsing command-line options
............................

The action of parsing options is performed through getopt and results particularly interesting. getopt breaks up (parse) options in command lines and checks for legal options using the GNU getopt routines to do this. One important consideration on centos-art.sh script design is that positional parameters are retrived in the cli function but parsed on each specific function, individually. There isn't a big parsing definition to cover all specific functions, but one parsing definitions for each specific functions.

Usage
-----

  * See Directories trunk Scripts Functions.

See also
--------

  * Directories trunk