Goals
-----

The trunk/Scripts/Bash/Functions directory exists to organize centos-art.sh specific functionalities.

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

The specific functions of centos-art.sh script are designed with ``Software Toolbox'' philosophy (see Toolbox introduction (coreutils.info)) in mind: each program ``should do one thing well''.  Inside centos-art.sh script, each specific functionality is considered a program that should do one thing well. Of course, if you find that they still don't do it, feel free to improve them in order for them to do so.

The specific functions of centos-art.sh script are organized inside specific directories under trunk/Scripts/Bash/Functions location. Each specific function directory should be named as the function it represents, with the first letter in uppercase. For example, if the function name is render, the specific function directory for it would be trunk/Scripts/Bash/Functions/Render.

To better understand how specific functions of centos-art.sh script are designed, lets create one function which only goal is to output different kind of greetings to your screen.

When we create specific functions for centos-art.sh script it is crucial to know what these functions will do exactly and if there is any function that already does what we intend to do. If there is no one, it is good time to create them then. Otherwise, if functionalities already available don't do what you exactly expect, contact their authors and work together to improve them.

     Tip Join CentOS developers mailing list centos-art@centos.org to share your ideas.

It is also worth to know what global functions and variables do we have available inside centos-art.sh script, so advantage can be taken from them. Global variables are defined inside global function scripts. Global functions scripts are stored immediatly under trunk/Scripts/Bash/Functions directory, in files begining with cli prefix.

OK, let's begin with our functionality example.

What function name do we use? Well, lets use greet. Note that hello word is not a verb; but an expression, a kind of greeting, an interjection specifically. In contrast, greet is a verb and describes what we do when we say Hello!, Hi!, and similar expressions.

So far, we've gathered the following function information:

Name: greet
Path: trunk/Scripts/Bash/Functions/Greet
File: trunk/Scripts/Bash/Functions/Greet/greet.sh

The greet.sh function script is the first file centos-art.sh script loads when the greet functionality is called using commands like centos-art greet --hello='World'. The greet.sh function script contains the greet function definition.

Inside centos-art.sh script, as convenction, each function script has one top commentary, followed by one blank line, and then one function defintion below it only.

Inside centos-art.sh script functions, top commentaries have the following components: the functionality description, one-line for copyright note with your personal information,  the license under which the function source code is released ---the centos-art.sh script is released as GPL, so do all its functions---, subversion's $Id$ keyword which is later expanded by svn propset command.

In our greet function example, top commentary for greet.sh function script would look like the following:

#!/bin/bash
#
# greet.sh -- This function outputs different kind of greetings to
# your screen. Use this function to understand how centos-art.sh
# script specific functionalities work.
#
# Copyright (C) YEAR YOURFULLNAME
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
# USA.
#
# ----------------------------------------------------------------------
# $Id$
# ----------------------------------------------------------------------

After top commentary, separated by one blank line, the greet function definition would look like the following:

function greet {

    # Define global variables.

    # Define command-line interface.
    greet_getActions

}

The first definition inside greet function, are global variables that will be available along greet function execution environment. This time we didn't use global variable definitions for greet function execution environment, so we left that section empty.

Later, we call greet_getActions function to define the command-line interface of greet functionality. The greet functionality command-line interface defines what and how actions are performed, based on arguments combination passed to centos-art.sh script.

function greet_getActions {

    case "$ACTIONNAM" in

        --hello )
            greet_doHello
            ;;

        --bye )
            greet_doBye
            ;;

        * )
            cli_printMessage "`gettext "The option provided is not valid."`"
            cli_printMessage "$(caller)" 'AsToKnowMoreLine'

    esac

}

The ACTIONNAM global variable is defined in cli.sh function script and contains the value passed before the equal sign (i.e., =) in the second command-line argument of centos-art.sh script. For example, if the second command-line argument is --hello='World', the value of ACTIONNAM variable would be --hello.  Using this configuration let us deside which action to perform based on the action name passed to centos-art.sh script as second argument.

The greet function definition makes available two valid greetings through --hello and --bye options.  If no one of them is provided as second command-line argument, the * case is evaluated instead.

The * case and its two lines further on should always be present in _getActions.sh function scripts, no matter what specific functionality you are creating. This convenction helps the user to find out documentation about current functionality in use.

The greet_doHello and greet_doBye function definitions are the core of greet specific functionality.  In such function definitions we set what our greet function really does: to output different kinds of greetings.

function greet_doHello {

    cli_printMessage "`gettext "Hello"` $ACTIONVAL"

}

The greet_doHello function definition is stored in greet_doHello.sh function script.

function greet_doBye {

    cli_printMessage "`gettext "Goodbye"` $ACTIONVAL"

}

The greet_doBye function definition is stored in the greet_doBye.sh function script.

Both greet_doHello.sh and greet_doBye.sh function scripts are stored inside greet's function directory path (i.e. trunk/Scripts/Bash/Functions/Greet).

The ACTIONVAL global variable is defined in cli.sh function script and contains the value passed after the equal sign (i.e., =) in the second command-line argument of centos-art.sh script. For example, if the second command-line argument is --hello='World', the value of ACTIONVAL variable would be World without quotes.

Let's see how greet specific functionality files are organzied under greet's function directory. To see file organization we use the tree command:

trunk/Scripts/Bash/Functions/Greet
|-- greet_doBye.sh
|-- greet_doHello.sh
|-- greet_getActions.sh
`-- greet.sh

To try the greet specific functionality we've just created, pass the function name (i.e., greet) as first argument to centos-art.sh script, and any of the valid options as second argument. Some examples are illustrated below:

[centos@projects ~]$ centos-art greet --hello='World'
Hello World
[centos@projects ~]$ centos-art greet --bye='World'
Goodbye World
[centos@projects ~]$

The word World in the examples above can be anything. In fact, change it to have a little fun.

Now that we have a specific function that works as we expect, it is time to document it. To document greet specific functionality, we use its directory path and the manual functionality (see trunk Scripts Bash Functions Manual) of centos-art.sh script, just as the following command illustrates:

centos-art manual --edit=trunk/Scripts/Bash/Functions/Greet

Now that we have documented our function, it is time to translate its output messages to different languages. To translate specific functionality output messages to different languages we use the locale functionality (see trunk Scripts Bash Functions Locale) of centos-art.sh script, just as the following command illustrates:

--- Removed(xref:trunk Scripts Bash Functions Chino) ---, for testing.

centos-art locale --edit

     Warning To translate output messages in different languages, your system locale information ---as in LANG environment variable--- must be set to that locale you want to produce translated messages for. For example, if you want to produce translated messages for Spanish language, your system locale information must be set to es_ES.UTF-8 or similar.

Well, it seems that our example is rather complete by now.

In greet function example we've described so far, we only use cli_printMessage global function in action specific function definitions in order to print a message simply, but more interesting things can be achieved inside action specific function definitions. For example, if you pass a directory path as second argument option value, you could retrive a list of files from therein, and process them. If the list of files turns too long or you just want to control which files to process, you could add the third argument in the form --filter='regex' and reduce the amount of files to process using a regular expression pattern.

The greet function described in this section may serve you as an introduction to understand how specific functionalities work inside centos-art.sh script. With some of luck this introduction will also serve you as motivation to create your own centos-art.sh script specific functionalities.

By the way, the greet functionality doesn't exist inside centos-art.sh script yet. Would you like to create it?

Usage
-----

Global variables
................

The following global variables of centos-art.sh script, are available for you to use inside specific functions:

 -- Variable: TEXTDOMAIN
     Default domain used to retrieve translated messages. This value is set in initFunctions.sh and shouldn't be changed.

 -- Variable: TEXTDOMAINDIR
     Default directory used to retrieve translated messages. This value is set in initFunctions.sh and shouldn't be changed.

 -- Variable: FUNCNAM
     Define function name.

     Function names associate sets of actions. There is one set of actions for each unique function name inside centos-art.sh script.

     Dunction names are passed as first argument in centos-art.sh command-line interface. For example, in the command centos-art render --entry=path/to/dir --filter=regex, the ACTION passed to centos-art.sh script is render.

     When first argument is not provided, the centos-art.sh script immediatly ends its execution.

 -- Variable: ACTIONNAM
     Define action name.

     Each action name identifies an specific action to perform, inside an specific function.

     Action name names aare passed as second argument in centos-art.sh command-line interface. For example, in the command centos-art render --entry=path/to/dir --filter=regex, the ACTIONNAM passed to centos-art.sh script is --entry.

     When second argument is not provided, the centos-art.sh script immediatly ends its execution.

 -- Variable: ACTIONVAL
     Define action value.

     Action values are associated to just one action name. Action values contain the repository entry over which its associated action will be performed in.  Repository entries can be directories, files, or URLs refering the repository structure.

     When action value is not specified as repository entry, the centos-art.sh script evaluates the current directory it was executed from. If such directory is under the repository structure (i.e., /home/centos/artwork/), the centos-art.sh script uses that directory as value to ACTIONVAL variable. Otherwise, if outside the repository structure, the centos-art.sh script prints the message The path provided can't be processed. and, after it, immediatly ends script execution.

     Default action value is passed as second argument in centos-art.sh command-line interface. For example, in the command centos-art render --entry=path/to/dir --filter=regex, the ACTIONVAL passed to centos-art.sh script is path/to/dir.

 -- Variable: REGEX
     Define regular expression used as pattern to build the list of files to process.

     By default, REGEX variable is set to .+ to match all files.

     Functions that need to build a list of files to process use the option --filter to redefine REGEX variable default value, and so, control the amount of files to process.

 -- Variable: ARGUMENTS
     Define optional arguments.

     Optional arguments, inside centos-art.sh script, are considered as all command-line arguments passed to centos-art.sh script, from third argument position on. For example, in the command centos-art render --entry=path/to/dir --filter=regex , the optional arguments are from --filter=regex argument on.

     Optional arguments are parsed using getopt command through the following base construction:

     # Define short options we want to support.
     local ARGSS=""

     # Define long options we want to support.
     local ARGSL="filter:,to:"

     # Parse arguments using getopt(1) command parser.
     cli_doParseArguments

     # Reset positional parameters using output from (getopt) argument
     # parser.
     eval set -- "$ARGUMENTS"

     # Define action to take for each option passed.
     while true; do
         case "$1" in
             --filter )
                 REGEX="$2"
                 shift 2
                 ;;
             --to )
                 TARGET="$2"
                 shift 2
                 ;;
             * )
                 break
         esac
     done

     Optional arguments provide support to command options inside centos-art.sh script. For instance, consider the Subversion (svn) command, where there are many options (e.g., copy, delete, move, etc), and inside each option there are several modifiers (e.g., --revision, --message, --username, etc.) that can be combined one another in their short or long variants.

     The ARGUMENTS variable is used to store arguments passed from command-line for later use inside centos-art.sh script. Storing arguments is specially useful when we want to run a command with some specific options from them. Consider the following command:

     centos-art path --copy=SOURCE --to=TARGET --message="The commit message goes here." --username='johndoe'

     In the above command, the --message, and --username options are specific to svn copy command. In such cases, options are not interpreted by centos-art.sh script itself. Instead, the centos-art.sh script uses getopt to retrive them and stores them in the ARGUMENT variable for later use, as described in the following command:

     # Build subversion command to duplicate locations inside the
     # workstation.
     eval svn copy $SOURCE $TARGET --quiet $ARGUMENTS

     When getopt parses ARGUMENTS, we may use short options (e.g., -m) or long options (e.g., --message). When we use short options, arguments are separated by one space from the option (e.g., -m 'This is a commit message.').  When we use long options arguments are separated by an equal sign (=) (e.g., --message='This is a commit message').

     In order for getopt to parse ARGUMENTS correctly, it is required to provide the short and long definition of options that will be passed or at least supported by the command performing the final action the function script exists for.

     As convenction, inside centos-art.sh script, short option definitions are set in the ARGSS variable; and long option definitions are set in the ARGSL variable.

     When you define short and long options, it may be needed to define which of these option arguments are required and which not. To define an option argument as required, you need to set one colon : after the option definition (e.g., -o m: -l message:).  On the other hand, to define an option argument as not required, you need to set two colons :: after the option definition (e.g., -o m:: -l message::).

 -- Variable: EDITOR
     Default text editor.

     The centos-art.sh script uses default text EDITOR to edit pre-commit subversion messages, translation files, configuration files, script files, and similar text-based files.

     If EDITOR environment variable is not set, centos-art.sh script uses /usr/bin/vim as default text editor. Otherwise, the following values are recognized by centos-art.sh script:

       * /usr/bin/vim

       * /usr/bin/emacs

       * /usr/bin/nano

     If no one of these values is set in EDITOR environment variable, centos-art.sh uses /usr/bin/vim text editor by default.

Global functions
................

Functions defined under trunk/Scripts/Bash/Functions/ directory are considered global. Global function can be used inside action specific functionalities and reused inside themselves. This section provides introductory information to global functions you can use inside centos-art.sh script.

 -- Function: cli_checkActionArguments
     Validate action value (ACTIONVAL) variable.

     cli_checkActionArguments is called from cli_getActionArguments function. Probably, there is not other use for cli_checkActionArguments but to be called from cli_getActionArguments function.

 -- Function: cli_checkFiles FILE [TYPE]
     Verify file existence.

     cli_checkFiles receives a FILE absolute path and performs file verification as specified in TYPE.  When TYPE is not specified, cli_checkFiles verifies FILE existence, no matter what kind of file it be.  If TYPE is specified, use one of the following values:

     d
     directory
          Ends script execution if FILE is not a directory.

          When you verify directories with cli_checkFiles, if directory doesn't exist, centos-art.sh script asks you for confirmation in order to create that directory. If you answer positively, centos-art.sh script creates that directory and continues script flows normally. Otherwise, if you answer negatively, centos-art.sh ends script execution with an error and documentation message.

     f

     regular-file
          Ends script execution if FILE is not a regular file.

     h
     symbolic-link
          Ends script execution if FILE is not a symbolic link.

     x
     execution
          Ends script execution if FILE is not executable.

     fh
          Ends script execution if FILE is neither a regular file nor a symbolic link.

     fd
          Ends script execution if FILE is neither a regular file nor a directory.

     As default behaviour, if FILE passes all verifications, centos-art.sh script continues with its normal flow.

 -- Function: cli_commitRepoChanges [LOCATION]

     Syncronize changes between repository and working copy.

     The cli_commitRepoChanges function brings changes from the central repository down to the working copy---using svn update---, checks the working copy changes---using svn status command---, prints status report---using both svn update and svn status commands output, and finally, commits recent changes from the working copy up to the repository---using svn commit command---.

     Previous to commit the working copy changes up to the central repository, the cli_commitRepoChanges function asks you to verify changes---using svn diff command---, and later, another confirmation question is shown to be sure you really want to commit changes up to central repository.

     If LOCATION argument is not specified, the value of ACTIONVAL variable is used as reference instead.

     ----------------------------------------------------------------------
     --> Bringing changes from the repository into the working copy
     --> Checking changes in the working copy
     ----------------------------------------------------------------------
     Added           0 file from the repository.
     Deleted         0 file from the repository.
     Updated         0 file from the repository.
     Conflicted      0 file from the repository.
     Merged          0 file from the repository.
     Modified        4 files from the working copy.
     Unversioned     0 file from the working copy.
     Deleted         0 file from the working copy.
     Added           0 file from the working copy.
     ----------------------------------------------------------------------
     Figure: The cli_commitRepoChanges function output.

     Call the cli_commitRepoChanges function before or/and after calling functions that modify files or directories inside the working copy as you may need to.

 -- Function: cli_doParseArguments
     Redefines arguments (ARGUMENTS) global variable using getopt command output. For more information about how to use cli_doParseArguments function, see ARGUMENTS variable description above.

 -- Function: cli_doParseArgumentsReDef [$@]
     Initialize/reset arguments (ARGUMENTS) global variable using positional parameters variable ($@) as reference.

     When you use cli_doParseArgumentsReDef inside some function, the positional parameters variable ($@) is automatically reset to that function positional parameters, not the command-line positional parameters.

     If you need to redefine specific positional parameters from one specific function, you need to call cli_doParseArgumentsReDef with the positional parameters variable ($@), set as first argument, to that specific function you want to redefine positional parameters on.

     In order to use positional paramenters passed as command-line, we use the ARGUMENTS global variable which is defined at cli function, and occasionally, farther redefined (by cli_doParseArgumentsReDef) as far as it may be convenient.

 -- Function: cli_getActionArguments [$@]

     Initialize function name (FUNCNAM), action name (ACTIONNAM), and action value (ACTIONVAL) global variables, using positional parameters passed in $@ variable.

     The cli_getActionsArguments function is called from cli.sh function script. The cli_getActionsArguments function is call from cli.sh function script using cli function positional parameters (i.e., the positional parameters passed as arguments in the command-line) as first function argument.

     Once command-line positional parameters are accesible, cli-getActionsArguments uses regular expression to retrive action variables from first and second argument. The first argument defines the value use as function name (FUNCNAM), and the second argument defines the value used as action name (ACTIONNAM) and action value (ACTIONVAL), respectively.

     The first argument is a word in lower case. This word specifies the name of the functionality you want to use (e.g., render to rener images, manual to work on documentation, and so on.)

     The second argument has a long option style (e.g., --option=value). The --option represents the action name (ACTIONNAM), and the characters after the equal sign (=), and before the first space character, are considered as the action value (ACTIONVAL). In order to provide action values with space characters you need to enclose it with quotes like in --option='This is long value'. Generally, action values are used to specify paths over which the action name acts on.

     Once action related variables (i.e., FUNCNAM, ACTIONNAM, and ACTIONVAL) are defined and validated, cli_getActionsArguments shifts the positional arguments to remove the first two arguments passed (i.e., those one used to retrive action related variables) and redefine the arguments (ARGUMENTS) global variable with the new positional parameters information.

 -- Function: cli_getActions
     Initialize funtionalities supported by centos-art.sh script.

     Functionalities supported by centos-art.sh script are organized in functionality directories under trunk/Scripts/Bash/Functions/ directory. Each functionality directory stores function scripts to the functionality such directory was created for. Function scripts contain function definitions. Function definitions contain several commands focused on achieving one specific task only.

     Functionalities supported by centos-art.sh script are initialized and executed using the centos-art.sh script functionality name convenction as reference.

     In order to for centos-art.sh script to recognize a functionality, such functionality needs to be stored under trunk/Scripts/Bash/Functions/ in a directory written capitalized (i.e., the whole name is written in lowercase except the first character which is in uppercase). The directory where one specific functionality is stored is known as the functionality directory.

     Inside each functionality directory, the functionalty itself is implemented through function scripts. Function scripts are organized in independent files written in camelCase format with the function name as prefix.  Separation between prefix and description is done using underscore (_) character.

     In order for centos-art.sh script to load functionalities correctly, function definition inside function scripts should be set using the function reserved word, just as in the following example:

     function prefix_doSomething {

         # Do something here...

     }

     In order to keep visual consistency among function scripts, use the following function script design model as template to create your own function scripts:

     #!/bin/bash
     #
     # prefix_doSomething.sh -- This function illustrates function scripts
     # design model you can use to create your own function scripts inside
     # centos-art.sh script.
     #
     # Copyright (C) YEAR YOURFULLNAME
     #
     # This program is free software; you can redistribute it and/or modify
     # it under the terms of the GNU General Public License as published by
     # the Free Software Foundation; either version 2 of the License, or
     # (at your option) any later version.
     #
     # This program is distributed in the hope that it will be useful, but
     # WITHOUT ANY WARRANTY; without even the implied warranty of
     # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     # General Public License for more details.
     #
     # You should have received a copy of the GNU General Public License
     # along with this program; if not, write to the Free Software
     # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
     # USA.
     #
     # ----------------------------------------------------------------------
     # $Id$
     # ----------------------------------------------------------------------

     function prefix_doSomething {

         # Do something here...

     }

     Once centos-art.sh script determines which functionality directory to use, function scripts are executed and function definitinos exported. This way, function definitions are made available inside centos-art.sh script execution evironment for further calls.  If the functionality specified in the command-line first argument doesn't have a functionality directory, centos-art.sh script considers the functionality provided in the command-line as invalid functionality and immediatly stops script execution with an informative message.

 -- Function: cli_getCountryCodes [FILTER]
     Output country codes supported by centos-art.sh script.

     The cli_getCountryCodes function outputs a list with country codes as defined in ISO3166 standard. When FILTER is provided, cli_getCountryCodes outputs country codes that match FILTER regular expression pattern.

 -- Function: cli_getCountryName [FILTER]
     Outputs country name supported by centos-art.sh script.

     The cli_getCountryName function reads one language locale code in the format LL_CC and outputs the name of its related country as in ISO3166. If filter is specified, cli_getCountryName returns the country name that matches the locale code specified in FILTER, exactly.

 -- Function: cli_getCurrentLocale
     Output current locale used by centos-art.sh script.

     The cli_getCurrentLocale function uses LANG environment variable to build a locale pattern that is later applied to cli_getLocales function output in order to return the current locale that centos-art.sh script works with.

     The current locale information, returned by cli_getCurrentLocale, is output from more specific to less specific. For example, if en_GB locale exists in cli_getLocales function output, the en_GB locale would take precedence before en locale.

     Locale precedence selection is quite important in order to define the locale type we use for message translations. For example, if en_GB is used, we are also saying that the common language specification for English language (i.e., en) is no longer used. Instead, we are using English non-common country-specific language specifications like en_AU, en_BW, en_GB, en_US, etc., for message translations.

     Use cli_getCurrentLocale function to know what current locale information to use inside centos-art.sh script.

 -- Function: cli_getFilesList

 -- Function: cli_getLangCodes [FILTER]
     Outputs language codes supported by centos-art.sh script.

     cli_getLangCodes function outputs a list of language codes as defined in ISO639 standard. When FILTER is provided, cli_getLangCodes outputs language codes that match FILTER regular expression pattern.

 -- Function: cli_getLangName [FILTER]
     Outputs language names supported by centos-art.sh script.

     cli_getLangName function reads one language locale code in the format LL_CC and outputs the language related name as in ISO639. If filter is specified, cli_getLangName returns the language name that matches the locale code specified in FILTER, exactly.

 -- Function: cli_getLocales
     Output locale codes supported by centos-art.sh script.

     Occasionally, you use cli_getLocales function to add locale information in non-common country-specific language (LL_CC) format for those languages (e.g., bn_IN, pt_BR, etc.) which locale differences cannot be solved using common language specifications (LL) into one unique common locale specification (e.g., bn, pt, etc.).

 -- Function: cli_getRepoName NAME TYPE
     Sanitate file names.

     Inside centos-art.sh script, specific functionalities rely both in cli_getRepoName and repository file system organization to achieve their goals.  Consider cli_getRepoName function as central place to manage file name convenctions for other functions inside centos-art.sh script.

          Important cli_getRepoName function doesn't verify file or directory existence, for that purpose use cli_checkFiles function instead.

     The NAME variable contains the file name or directory name you want to sanitate.

     The TYPE variable specifies what type of sanitation you want to perform on NAME. The TYPE can be one of the following values:

     d
     directory
          Sanitate directory NAMEs.

     f

     regular-file
          Sanitate regular file NAMEs.

     Use cli_getRepoName function to sanitate file names and directory names before their utilization.

     Use cli_getRepoName when you need to change file name convenctions inside centos-art.sh script.

     When we change file name convenctions inside cli_getRepoName what we are really changing is the way functions interpret repository file system organization. Notice that when we change a file name (e.g., a function name), it is necessary to update all files where such file name is placed on. This may require a massive substitution, each time we change name convenctions in the repository (see trunk Scripts Bash Functions Path, for more information).

 -- Function: cli_getRepoStatus

 -- Function: cli_getTemporalFile NAME
     Output absolute path to temporal file NAME.

     cli_getTemporalFile uses /tmp directory as source location to store temporal files, the centos-art.sh script name, and a random identification string to let you run more than one centos-art.sh script simultaneously on the same user session. For example, due the following temporal file defintion:

     cli_getTemporalFile $FILE

     If FILE name is instance.svg and unique random string is f16f7b51-ac12-4b7f-9e66-72df847f12de, the final temporal file, built from previous temporal file definition, would be:

     /tmp/centos-art.sh-f16f7b51-ac12-4b7f-9e66-72df847f12de-instance.svg

     When you use cli_getTemporalFile function to create temporal files, be sure to remove temporal files created once you've ended up with them.  For example, consider the following construction:

     for FILE in $FILES;do

         # Initialize temporal instance of file.
         INSTANCE=$(cli_getTemporalFile $FILE)

         # Do something ...

         # Remove temporal instance of file.
         if [[ -f $INSTANCE ]];then
             rm $INSTANCE
         fi

     done

     Use cli_getTemporalFile function whenever you need to create temporal files inside centos-art.sh script.

 -- Function: cli_getThemeName
     Output theme name.

     In order for cli_getThemeName function to extract theme name correctly, the ACTIONVAL variable must contain a directory path under trunk/Identity/Themes/Motifs/ directory structure. Otherwise, cli_getThemeName returns an empty string.

 -- Function: cli_printMessage MESSAGE [FORMAT]
     Define standard output message definition supported by centos-art.sh script.

     When FORMAT is not specified, cli_printMessage outputs information just as it was passed in MESSAGE variable. Otherwise, FORMAT can take one of the following values:

     AsHeadingLine
          To print heading messages.
          ----------------------------------------------------------------------
          $MESSAGE
          ----------------------------------------------------------------------

     AsWarningLine
          To print warning messages.
          ----------------------------------------------------------------------
          WARNING: $MESSAGE
          ----------------------------------------------------------------------

     AsNoteLine
          To print note messages.
          ----------------------------------------------------------------------
          NOTE: $MESSAGE
          ----------------------------------------------------------------------

     AsUpdatingLine
          To print Updating messages on two-columns format.
          Updating        $MESSAGE

     AsRemovingLine
          To print Removing messages on two-columns format.
          Removing        $MESSAGE

     AsCheckingLine
          To print Checking messages on two-columns format.
          Checking        $MESSAGE

     AsCreatingLine
          To print Creating messages on two-columns format.
          Creating        $MESSAGE

     AsSavedAsLine
          To print Saved as messages on two-columns format.
          Saved as        $MESSAGE

     AsLinkToLine
          To print Linked to messages on two-columns format.
          Linked to       $MESSAGE

     AsMovedToLine
          To print Moved to messages on two-columns format.
          Moved to        $MESSAGE

     AsTranslationLine
          To print Translation messages on two-columns format.
          Translation     $MESSAGE

     AsConfigurationLine
          To print Configuration messages on two-columns format.
          Configuration   $MESSAGE

     AsResponseLine
          To print response messages on one-column format.
          --> $MESSAGE

     AsRequestLine
          To print request messages on one-column format. Request messages output messages with one colon (:) and without trailing newline (\n) at message end.
          $MESSAGE:

     AsYesOrNoRequestLine
          To print yes or no request messages on one-column format. If something different from y is answered (when using en_US.UTF-8 locale), script execution ends immediatly.

          $MESSAGE [y/N]:

          When we use centos-art.sh script in a locale different from en_US.UTF-8, confirmation answer may be different from y. For example, if you use es_ES.UTF-8 locale, the confirmation question would look like:

          $MESSAGE [s/N]:

          and the confirmation answer would be s, as it is on Spanish sí word.

          Definition of which confirmation word to use is set on translation messages for your specific locale information. See trunk Scripts Bash Functions Locale, for more information about locale-specific translation messages.

     AsToKnowMoreLine
          To standardize to know more, run the following command: messages. When the AsToKnowMoreLine option is used, the MESSAGE value should be set to "$(caller)". caller is a Bash builtin that returns the context of the current subroutine call. AsToKnowMoreLine option uses caller builtin output to build documentation entries dynamically.

          ----------------------------------------------------------------------
          To know more, run the following command:
          centos-art manual --read='path/to/dir'
          ----------------------------------------------------------------------

          Use AsToKnowMoreLine option after errors and for intentional script termination.

     AsRegularLine
          To standardize regular messages on one-column format.

          When MESSAGE contains a colon inside (e.g., description: message), the cli_printMessage function outputs MESSAGE on two-columns format.

     Use cli_printMessage function whenever you need to output information from centos-art.sh script.

          Tip To improve two-columns format, change the following file:
          trunk/Scripts/Bash/Styles/output_forTwoColumns.awk

Specific functions
..................

The following specific functions of centos-art.sh script, are available for you to use:

See also
--------