Blame Manual/Filesystem/trunk/Scripts/Bash/Cli/Functions.texi

010b2d
@subsection Goals
010b2d
eb5b9c
The @file{trunk/Scripts/Bash/Functions} directory exists to organize
eb5b9c
@file{centos-art.sh} specific functionalities.
010b2d
010b2d
@subsection Description
010b2d
eb5b9c
The specific functions of @file{centos-art.sh} script are designed
eb5b9c
with ``Software Toolbox'' philosophy (@pxref{Toolbox
eb5b9c
introduction,,,coreutils.info}) in mind: each program ``should do one
eb5b9c
thing well''.  Inside @file{centos-art.sh} script, each specific
eb5b9c
functionality is considered a program that should do one thing well.
eb5b9c
Of course, if you find that they still don't do it, feel free to
eb5b9c
improve them in order for them to do so.
eb5b9c
eb5b9c
The specific functions of @file{centos-art.sh} script are organized
eb5b9c
inside specific directories under @file{trunk/Scripts/Bash/Functions}
eb5b9c
location. Each specific function directory should be named as the
eb5b9c
function it represents, with the first letter in uppercase. For
eb5b9c
example, if the function name is @code{render}, the specific function
eb5b9c
directory for it would be @samp{trunk/Scripts/Bash/Functions/Render}.
eb5b9c
eb5b9c
To better understand how specific functions of @file{centos-art.sh}
eb5b9c
script are designed, lets create one function which only goal is to
eb5b9c
output different kind of greetings to your screen.
eb5b9c
eb5b9c
When we create specific functions for @file{centos-art.sh} script it
eb5b9c
is crucial to know what these functions will do exactly and if there
eb5b9c
is any function that already does what we intend to do. If there is no
eb5b9c
one, it is good time to create them then. Otherwise, if
eb5b9c
functionalities already available don't do what you exactly expect,
eb5b9c
contact their authors and work together to improve them.
eb5b9c
eb5b9c
@quotation
eb5b9c
@strong{Tip} Join CentOS developers mailing list
eb5b9c
@email{centos-art@@centos.org} to share your ideas.
eb5b9c
@end quotation
eb5b9c
eb5b9c
It is also worth to know what global functions and variables do we
eb5b9c
have available inside @file{centos-art.sh} script, so advantage can be
eb5b9c
taken from them. Global variables are defined inside global function
eb5b9c
scripts. Global functions scripts are stored immediatly under
eb5b9c
@file{trunk/Scripts/Bash/Functions} directory, in files begining with
eb5b9c
@samp{cli} prefix.
eb5b9c
eb5b9c
OK, let's begin with our functionality example.
eb5b9c
eb5b9c
What function name do we use? Well, lets use @code{greet}. Note that
eb5b9c
@samp{hello} word is not a verb; but an expression, a kind of
eb5b9c
greeting, an interjection specifically. In contrast, @samp{greet} is a
eb5b9c
verb and describes what we do when we say @samp{Hello!}, @samp{Hi!},
eb5b9c
and similar expressions.
eb5b9c
eb5b9c
So far, we've gathered the following function information:
eb5b9c
eb5b9c
@verbatim
eb5b9c
Name: greet
eb5b9c
Path: trunk/Scripts/Bash/Functions/Greet
eb5b9c
File: trunk/Scripts/Bash/Functions/Greet/greet.sh
eb5b9c
@end verbatim
eb5b9c
eb5b9c
The @file{greet.sh} function script is the first file
eb5b9c
@file{centos-art.sh} script loads when the @samp{greet} functionality
eb5b9c
is called using commands like @samp{centos-art greet --hello='World'}.
eb5b9c
The @file{greet.sh} function script contains the @code{greet} function
eb5b9c
definition. 
eb5b9c
eb5b9c
Inside @file{centos-art.sh} script, as convenction, each function
eb5b9c
script has one top commentary, followed by one blank line, and then
eb5b9c
one function defintion below it only.
eb5b9c
eb5b9c
Inside @file{centos-art.sh} script functions, top commentaries have
eb5b9c
the following components: the functionality description, one-line for
eb5b9c
copyright note with your personal information,  the license under
eb5b9c
which the function source code is released ---the @file{centos-art.sh}
eb5b9c
script is released as GPL, so do all its functions---, the @code{$Id$}
eb5b9c
keyword of Subversion is later expanded by @command{svn propset}
eb5b9c
command.
eb5b9c
eb5b9c
In our @code{greet} function example, top commentary for
eb5b9c
@file{greet.sh} function script would look like the following:
eb5b9c
eb5b9c
@verbatim
eb5b9c
#!/bin/bash
eb5b9c
#
eb5b9c
# greet.sh -- This function outputs different kind of greetings to
eb5b9c
# your screen. Use this function to understand how centos-art.sh
eb5b9c
# script specific functionalities work.
eb5b9c
#
eb5b9c
# Copyright (C) YEAR YOURFULLNAME
eb5b9c
#
eb5b9c
# This program is free software; you can redistribute it and/or modify
eb5b9c
# it under the terms of the GNU General Public License as published by
eb5b9c
# the Free Software Foundation; either version 2 of the License, or
eb5b9c
# (at your option) any later version.
eb5b9c
# 
eb5b9c
# This program is distributed in the hope that it will be useful, but
eb5b9c
# WITHOUT ANY WARRANTY; without even the implied warranty of
eb5b9c
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
eb5b9c
# General Public License for more details.
eb5b9c
#
eb5b9c
# You should have received a copy of the GNU General Public License
eb5b9c
# along with this program; if not, write to the Free Software
eb5b9c
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
eb5b9c
# USA.
eb5b9c
# 
eb5b9c
# ----------------------------------------------------------------------
eb5b9c
# $Id$
eb5b9c
# ----------------------------------------------------------------------
eb5b9c
@end verbatim
eb5b9c
eb5b9c
After top commentary, separated by one blank line, the @code{greet}
eb5b9c
function definition would look like the following:
eb5b9c
eb5b9c
@verbatim
eb5b9c
function greet {
eb5b9c
eb5b9c
    # Define global variables.
eb5b9c
eb5b9c
    # Define command-line interface.
eb5b9c
    greet_getActions
eb5b9c
eb5b9c
}
eb5b9c
@end verbatim
eb5b9c
eb5b9c
The first definition inside @code{greet} function, are global
eb5b9c
variables that will be available along @code{greet} function execution
eb5b9c
environment. This time we didn't use global variable definitions for
eb5b9c
@code{greet} function execution environment, so we left that section
eb5b9c
empty.
eb5b9c
eb5b9c
Later, we call @code{greet_getActions} function to define the
eb5b9c
command-line interface of @code{greet} functionality. The command-line
eb5b9c
interface of @code{greet} functionality defines what and how actions
eb5b9c
are performed, based on arguments combination passed to
eb5b9c
@file{centos-art.sh} script.
eb5b9c
eb5b9c
@verbatim
eb5b9c
function greet_getActions {
eb5b9c
eb5b9c
    case "$ACTIONNAM" in
eb5b9c
eb5b9c
        --hello )
eb5b9c
            greet_doHello
eb5b9c
            ;;
eb5b9c
eb5b9c
        --bye )
eb5b9c
            greet_doBye
eb5b9c
            ;;
eb5b9c
eb5b9c
        * )
eb5b9c
            cli_printMessage "`gettext "The option provided is not valid."`"
eb5b9c
            cli_printMessage "$(caller)" 'AsToKnowMoreLine'
eb5b9c
eb5b9c
    esac
eb5b9c
eb5b9c
}
eb5b9c
@end verbatim
eb5b9c
eb5b9c
The @var{ACTIONNAM} global variable is defined in @file{cli.sh}
eb5b9c
function script and contains the value passed before the equal sign
eb5b9c
(i.e., @samp{=}) in the second command-line argument of
eb5b9c
@file{centos-art.sh} script. For example, if the second command-line
eb5b9c
argument is @option{--hello='World'}, the value of @var{ACTIONNAM}
eb5b9c
variable would be @samp{--hello}.  Using this configuration let us
eb5b9c
deside which action to perform based on the action name passed to
eb5b9c
@file{centos-art.sh} script as second argument. 
eb5b9c
eb5b9c
The @code{greet} function definition makes available two valid
eb5b9c
greetings through @option{--hello} and @option{--bye} options.  If no
eb5b9c
one of them is provided as second command-line argument, the @samp{*}
eb5b9c
case is evaluated instead. 
eb5b9c
eb5b9c
The @samp{*} case and its two lines further on should always be
eb5b9c
present in @file{_getActions.sh} function scripts, no matter what
eb5b9c
specific functionality you are creating. This convenction helps the
eb5b9c
user to find out documentation about current functionality in use,
eb5b9c
when no valid action is provided.
eb5b9c
eb5b9c
The @code{greet_doHello} and @code{greet_doBye} function definitions
eb5b9c
are the core of @code{greet} specific functionality.  In such function
eb5b9c
definitions we set what our @code{greet} function really does: to
eb5b9c
output different kinds of greetings.
eb5b9c
eb5b9c
@verbatim
eb5b9c
function greet_doHello {
eb5b9c
eb5b9c
    cli_printMessage "`gettext "Hello"` $ACTIONVAL"
eb5b9c
eb5b9c
}
eb5b9c
@end verbatim
eb5b9c
eb5b9c
The @code{greet_doHello} function definition is stored in
eb5b9c
@file{greet_doHello.sh} function script. 
eb5b9c
eb5b9c
@verbatim
eb5b9c
function greet_doBye {
eb5b9c
eb5b9c
    cli_printMessage "`gettext "Goodbye"` $ACTIONVAL"
eb5b9c
eb5b9c
}
eb5b9c
@end verbatim
eb5b9c
eb5b9c
The @code{greet_doBye} function definition is stored in the
eb5b9c
@file{greet_doBye.sh} function script. 
eb5b9c
eb5b9c
Both @file{greet_doHello.sh} and @file{greet_doBye.sh} function
eb5b9c
scripts are stored inside @code{greet} function directory path (i.e.
eb5b9c
@file{trunk/Scripts/Bash/Functions/Greet}).
eb5b9c
eb5b9c
The @var{ACTIONVAL} global variable is defined in @file{cli.sh}
eb5b9c
function script and contains the value passed after the equal sign
eb5b9c
(i.e., @samp{=}) in the second command-line argument of
eb5b9c
@file{centos-art.sh} script. For example, if the second command-line
eb5b9c
argument is @option{--hello='World'}, the value of @var{ACTIONVAL}
eb5b9c
variable would be @samp{World} without quotes.
eb5b9c
eb5b9c
Let's see how @code{greet} specific functionality files are organzied
eb5b9c
under @code{greet} function directory. To see file organization we use
eb5b9c
the @command{tree} command:
eb5b9c
eb5b9c
@verbatim
eb5b9c
trunk/Scripts/Bash/Functions/Greet
eb5b9c
|-- greet_doBye.sh
eb5b9c
|-- greet_doHello.sh
eb5b9c
|-- greet_getActions.sh
eb5b9c
`-- greet.sh
eb5b9c
@end verbatim
eb5b9c
eb5b9c
To try the @code{greet} specific functionality we've just created,
eb5b9c
pass the function name (i.e., @samp{greet}) as first argument to
eb5b9c
@file{centos-art.sh} script, and any of the valid options as second
eb5b9c
argument. Some examples are illustrated below:
eb5b9c
eb5b9c
@verbatim
eb5b9c
[centos@projects ~]$ centos-art greet --hello='World'
eb5b9c
Hello World
eb5b9c
[centos@projects ~]$ centos-art greet --bye='World'
eb5b9c
Goodbye World
eb5b9c
[centos@projects ~]$ 
eb5b9c
@end verbatim
eb5b9c
eb5b9c
The word @samp{World} in the examples above can be anything. In fact,
eb5b9c
change it to have a little fun.
eb5b9c
eb5b9c
Now that we have a specific function that works as we expect, it is
eb5b9c
time to document it.  To document @code{greet} specific functionality,
eb5b9c
we use its directory path and the @code{manual} functionality
65cd8a
(--- @strong{Removed}(pxref:trunk Scripts Bash Functions Manual) ---) of @file{centos-art.sh}
eb5b9c
script, just as the following command illustrates: 
eb5b9c
eb5b9c
@verbatim
eb5b9c
centos-art manual --edit=trunk/Scripts/Bash/Functions/Greet
eb5b9c
@end verbatim
eb5b9c
eb5b9c
To have a well documented function helps user to understand how your
eb5b9c
function really works, and how it should be used.  When no valid
eb5b9c
action is passed to a function, the @file{centos-art.sh} script uses
eb5b9c
the function documentation entry as vehicle to communicate which the
eb5b9c
valid functions are. When no documentation entry exists for a
eb5b9c
function, the @file{centos-art.sh} script informs that no
eb5b9c
documentation entry exists for such function and requests user to
eb5b9c
create it right at that time.
eb5b9c
eb5b9c
Now that we have documented our function, it is time to translate its
eb5b9c
output messages to different languages. To translate specific
eb5b9c
functionality output messages to different languages we use the
65cd8a
@code{locale} functionality (--- @strong{Removed}(pxref:trunk Scripts Bash Functions
65cd8a
Locale) ---) of @file{centos-art.sh} script, just as the following command
eb5b9c
illustrates:
eb5b9c
eb5b9c
@verbatim
eb5b9c
centos-art locale --edit
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@quotation
eb5b9c
@strong{Warning} To translate output messages in different languages,
eb5b9c
your system locale information ---as in @env{LANG} environment
eb5b9c
variable--- must be set to that locale you want to produce translated
eb5b9c
messages for. For example, if you want to produce translated messages
eb5b9c
for Spanish language, your system locale information must be set to
eb5b9c
@samp{es_ES.UTF-8}, or similar, first.
eb5b9c
@end quotation
eb5b9c
eb5b9c
Well, it seems that our example is rather complete by now. 
eb5b9c
eb5b9c
In @code{greet} function example we've described so far, we only use
eb5b9c
@command{cli_printMessage} global function in action specific function
eb5b9c
definitions in order to print messages, but more interesting things
eb5b9c
can be achieved inside action specific function definitions.  For
eb5b9c
example, if you pass a directory path as action value in second
eb5b9c
argument, you could retrive a list of files from therein, and process
eb5b9c
them. If the list of files turns too long or you just want to control
eb5b9c
which files to process, you could add the third argument in the form
eb5b9c
@option{--filter='regex'} and reduce the amount of files to process
eb5b9c
using a regular expression pattern.
eb5b9c
eb5b9c
The @code{greet} function described in this section may serve you as
eb5b9c
an introduction to understand how specific functionalities work inside
eb5b9c
@file{centos-art.sh} script. With some of luck this introduction will
eb5b9c
also serve you as motivation to create your own @file{centos-art.sh}
eb5b9c
script specific functionalities.
eb5b9c
eb5b9c
By the way, the @code{greet} functionality doesn't exist inside
eb5b9c
@file{centos-art.sh} script yet. Would you like to create it?
010b2d
010b2d
@subsection Usage
010b2d
eb5b9c
@subsubsection Global variables
eb5b9c
eb5b9c
The following global variables of @file{centos-art.sh} script, are
eb5b9c
available for you to use inside specific functions:
eb5b9c
eb5b9c
@defvar TEXTDOMAIN
eb5b9c
Default domain used to retrieve translated messages. This value is set
eb5b9c
in @file{initFunctions.sh} and shouldn't be changed.
eb5b9c
@end defvar
eb5b9c
eb5b9c
@defvar TEXTDOMAINDIR
eb5b9c
Default directory used to retrieve translated messages. This value is
eb5b9c
set in @file{initFunctions.sh} and shouldn't be changed.
eb5b9c
@end defvar
eb5b9c
eb5b9c
@defvar FUNCNAM
eb5b9c
Define function name.
eb5b9c
eb5b9c
Function names associate sets of actions. There is one set of actions
eb5b9c
for each unique function name inside @file{centos-art.sh} script.
eb5b9c
eb5b9c
Dunction names are passed as first argument in @file{centos-art.sh}
eb5b9c
command-line interface. For example, in the command @samp{centos-art
eb5b9c
render --entry=path/to/dir --filter=regex}, the @var{ACTION} passed to
eb5b9c
@file{centos-art.sh} script is @option{render}.
eb5b9c
eb5b9c
When first argument is not provided, the @file{centos-art.sh} script
eb5b9c
immediatly ends its execution.
eb5b9c
@end defvar
eb5b9c
eb5b9c
@defvar FUNCDIR
eb5b9c
@end defvar
eb5b9c
eb5b9c
@defvar FUNCDIRNAME
eb5b9c
@end defvar
eb5b9c
eb5b9c
@defvar FUNCSCRIPT
eb5b9c
@end defvar
eb5b9c
eb5b9c
@defvar FUNCCONFIG
eb5b9c
@end defvar
eb5b9c
eb5b9c
@defvar ACTIONNAM
eb5b9c
Define action name.
eb5b9c
eb5b9c
Each action name identifies an specific action to perform, inside an
eb5b9c
specific function.
eb5b9c
eb5b9c
Action name names aare passed as second argument in
eb5b9c
@file{centos-art.sh} command-line interface. For example, in the
eb5b9c
command @samp{centos-art render --entry=path/to/dir --filter=regex},
eb5b9c
the @var{ACTIONNAM} passed to @file{centos-art.sh} script is
eb5b9c
@option{--entry}.
eb5b9c
eb5b9c
When second argument is not provided, the @file{centos-art.sh} script
eb5b9c
immediatly ends its execution.
eb5b9c
@end defvar
eb5b9c
eb5b9c
@defvar ACTIONVAL
eb5b9c
Define action value.
eb5b9c
eb5b9c
Action values are associated to just one action name. Action values
eb5b9c
contain the working copy entry over which its associated action will be
eb5b9c
performed in.  Working copy entries can be files or directories inside
eb5b9c
the working copy.
eb5b9c
@end defvar
eb5b9c
eb5b9c
@defvar REGEX
eb5b9c
Define regular expression used as pattern to build the list of files
eb5b9c
to process.
eb5b9c
eb5b9c
By default, @var{REGEX} variable is set to @code{.+} to match all
eb5b9c
files.
eb5b9c
eb5b9c
Functions that need to build a list of files to process use the option
eb5b9c
@option{--filter} to redefine @var{REGEX} variable default value, and
eb5b9c
so, control the amount of files to process.
eb5b9c
@end defvar
eb5b9c
eb5b9c
@defvar ARGUMENTS 
eb5b9c
Define optional arguments. 
eb5b9c
eb5b9c
Optional arguments, inside @file{centos-art.sh} script, are considered
eb5b9c
as all command-line arguments passed to @file{centos-art.sh} script,
eb5b9c
from third argument position on. For example, in the command
eb5b9c
@samp{centos-art render --entry=path/to/dir --filter=regex} , the
eb5b9c
optional arguments are from @samp{--filter=regex} argument on.
eb5b9c
eb5b9c
Optional arguments are parsed using @command{getopt} command through
eb5b9c
the following base construction: 
eb5b9c
eb5b9c
@verbatim
eb5b9c
# Define short options we want to support.
eb5b9c
local ARGSS=""
eb5b9c
eb5b9c
# Define long options we want to support.
eb5b9c
local ARGSL="filter:,to:"
eb5b9c
eb5b9c
# Parse arguments using getopt(1) command parser.
eb5b9c
cli_doParseArguments
eb5b9c
eb5b9c
# Reset positional parameters using output from (getopt) argument
eb5b9c
# parser.
eb5b9c
eval set -- "$ARGUMENTS"
eb5b9c
eb5b9c
# Define action to take for each option passed.
eb5b9c
while true; do
eb5b9c
    case "$1" in
eb5b9c
        --filter )
eb5b9c
            REGEX="$2" 
eb5b9c
            shift 2
eb5b9c
            ;;
eb5b9c
        --to )
eb5b9c
            TARGET="$2" 
eb5b9c
            shift 2
eb5b9c
            ;;
eb5b9c
        * )
eb5b9c
            break
eb5b9c
    esac
eb5b9c
done
eb5b9c
@end verbatim
eb5b9c
eb5b9c
Optional arguments provide support to command options inside
eb5b9c
@file{centos-art.sh} script. For instance, consider the Subversion
eb5b9c
(@command{svn}) command, where there are many options (e.g.,
eb5b9c
@option{copy}, @option{delete}, @option{move}, etc), and inside each
eb5b9c
option there are several modifiers (e.g., @samp{--revision},
eb5b9c
@samp{--message}, @samp{--username}, etc.) that can be combined one
eb5b9c
another in their short or long variants. 
eb5b9c
eb5b9c
The @var{ARGUMENTS} variable is used to store arguments passed from
eb5b9c
command-line for later use inside @file{centos-art.sh} script. Storing
eb5b9c
arguments is specially useful when we want to run a command with some
eb5b9c
specific options from them. Consider the following command:
eb5b9c
eb5b9c
@verbatim
eb5b9c
centos-art path --copy=SOURCE --to=TARGET --message="The commit message goes here." --username='johndoe'
eb5b9c
@end verbatim
eb5b9c
eb5b9c
In the above command, the @option{--message}, and @option{--username}
eb5b9c
options are specific to @command{svn copy} command. In such cases,
eb5b9c
options are not interpreted by @file{centos-art.sh} script itself.
eb5b9c
Instead, the @file{centos-art.sh} script uses @command{getopt} to
eb5b9c
retrive them and store them in the @var{ARGUMENTS} variable for later
eb5b9c
use, as described in the following command:
eb5b9c
eb5b9c
@verbatim
eb5b9c
# Build subversion command to duplicate locations inside the
eb5b9c
# workstation.
eb5b9c
eval svn copy $SOURCE $TARGET --quiet $ARGUMENTS
eb5b9c
@end verbatim
eb5b9c
eb5b9c
When @command{getopt} parses @var{ARGUMENTS}, we may use short options
eb5b9c
(e.g., @option{-m}) or long options (e.g., @option{--message}). When
eb5b9c
we use short options, arguments are separated by one space from the
eb5b9c
option (e.g., @option{-m 'This is a commit message.'}).  When we use
eb5b9c
long options arguments are separated by an equal sign (@samp{=})
eb5b9c
(e.g., @option{--message='This is a commit message'}).
eb5b9c
eb5b9c
In order for @command{getopt} to parse @var{ARGUMENTS} correctly, it
eb5b9c
is required to provide the short and long definition of options that
eb5b9c
will be passed or at least supported by the command performing the
eb5b9c
final action the function script exists for.
eb5b9c
eb5b9c
As convenction, inside @file{centos-art.sh} script, short option
eb5b9c
definitions are set in the @var{ARGSS} variable; and long option
eb5b9c
definitions are set in the @var{ARGSL} variable.
eb5b9c
eb5b9c
When you define short and long options, it may be needed to define
eb5b9c
which of these option arguments are required and which not. To define
eb5b9c
an option argument as required, you need to set one colon @samp{:}
eb5b9c
after the option definition (e.g., @option{-o m: -l message:}).  On
eb5b9c
the other hand, to define an option argument as not required, you need
eb5b9c
to set two colons @samp{::} after the option definition (e.g.,
eb5b9c
@option{-o m:: -l message::}).
eb5b9c
@end defvar
eb5b9c
eb5b9c
@defvar EDITOR 
eb5b9c
Default text editor. 
eb5b9c
eb5b9c
The @file{centos-art.sh} script uses default text @env{EDITOR} to edit
eb5b9c
pre-commit subversion messages, translation files, configuration
eb5b9c
files, script files, and similar text-based files.
eb5b9c
eb5b9c
If @env{EDITOR} environment variable is not set, @file{centos-art.sh}
eb5b9c
script uses @file{/usr/bin/vim} as default text editor. Otherwise, the
eb5b9c
following values are recognized by @file{centos-art.sh} script:
eb5b9c
010b2d
@itemize
eb5b9c
@item @file{/usr/bin/vim}
eb5b9c
@item @file{/usr/bin/emacs}
eb5b9c
@item @file{/usr/bin/nano}
010b2d
@end itemize
010b2d
eb5b9c
If no one of these values is set in @env{EDITOR} environment variable,
eb5b9c
@file{centos-art.sh} uses @file{/usr/bin/vim} text editor by default. 
eb5b9c
@end defvar
eb5b9c
eb5b9c
@subsubsection Global functions
eb5b9c
eb5b9c
Function scripts stored directly under
eb5b9c
@file{trunk/Scripts/Bash/Functions/} directory are used to define
eb5b9c
global functions.  Global functions can be used inside action specific
eb5b9c
functionalities and or even be reused inside themselves. This section
eb5b9c
provides introductory information to global functions you can use
eb5b9c
inside @file{centos-art.sh} script.
eb5b9c
eb5b9c
@defun cli_checkActionArguments
eb5b9c
Validate action value (@var{ACTIONVAL}) variable.
eb5b9c
eb5b9c
The action value variable can take one of the following values:
eb5b9c
eb5b9c
@enumerate
eb5b9c
@item Path to one directory inside the local working copy,
eb5b9c
@item Path to one file inside the local working copy,
eb5b9c
@end enumerate
eb5b9c
eb5b9c
If another value different from that specified above is passed to
eb5b9c
action value variable, the @file{centos-art.sh} script prints an error
eb5b9c
message and ends script execution.
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_checkFiles FILE [TYPE]
eb5b9c
Verify file existence.
eb5b9c
eb5b9c
@code{cli_checkFiles} receives a @var{FILE} absolute path and performs
eb5b9c
file verification as specified in @var{TYPE}.  When @var{TYPE} is not
eb5b9c
specified, @code{cli_checkFiles} verifies @var{FILE} existence, no
eb5b9c
matter what kind of file it be.  If @var{TYPE} is specified, use one
eb5b9c
of the following values:
eb5b9c
eb5b9c
@table @option
eb5b9c
@item d
eb5b9c
@itemx directory
eb5b9c
Ends script execution if @var{FILE} is not a directory.
eb5b9c
eb5b9c
When you verify directories with cli_checkFiles, if directory doesn't
eb5b9c
exist, @file{centos-art.sh} script asks you for confirmation in order
eb5b9c
to create that directory. If you answer positively,
eb5b9c
@file{centos-art.sh} script creates that directory and continues
eb5b9c
script flows normally. Otherwise, if you answer negatively,
eb5b9c
@file{centos-art.sh} ends script execution with an error and
eb5b9c
documentation message.
eb5b9c
eb5b9c
@item f
eb5b9c
@item regular-file
eb5b9c
Ends script execution if @var{FILE} is not a regular file.
eb5b9c
@item h
eb5b9c
@itemx symbolic-link
eb5b9c
Ends script execution if @var{FILE} is not a symbolic link.
eb5b9c
@item x
eb5b9c
@itemx execution
eb5b9c
Ends script execution if @var{FILE} is not executable.
eb5b9c
@item fh
eb5b9c
Ends script execution if @var{FILE} is neither a regular file nor a
eb5b9c
symbolic link.
eb5b9c
@item fd
eb5b9c
Ends script execution if @var{FILE} is neither a regular file nor a
eb5b9c
directory.
eb5b9c
@item isInWorkingCopy
eb5b9c
Ends script execution if @var{FILE} is not inside the working copy.
eb5b9c
@end table
eb5b9c
eb5b9c
As default behaviour, if @var{FILE} passes all verifications,
eb5b9c
@file{centos-art.sh} script continues with its normal flow. 
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_commitRepoChanges [LOCATION]
eb5b9c
eb5b9c
Syncronize changes between repository and working copy.
eb5b9c
eb5b9c
The @code{cli_commitRepoChanges} function brings changes from the
eb5b9c
central repository down to the working copy---using @command{svn
eb5b9c
update}---, checks the working copy changes---using @command{svn
eb5b9c
status} command---, prints status report---using both @command{svn
eb5b9c
update} and @command{svn status} commands output, and finally, commits
eb5b9c
recent changes from the working copy up to the repository---using
eb5b9c
@command{svn commit} command---.
eb5b9c
eb5b9c
Previous to commit the working copy changes up to the central
eb5b9c
repository, the @code{cli_commitRepoChanges} function asks you to
eb5b9c
verify changes---using @command{svn diff} command---, and later,
eb5b9c
another confirmation question is shown to be sure you really want to
eb5b9c
commit changes up to central repository.
eb5b9c
eb5b9c
If @var{LOCATION} argument is not specified, the value of
eb5b9c
@var{ACTIONVAL} variable is used as reference instead.
eb5b9c
eb5b9c
@float Figure, trunk/Scripts/Bash/Functions/cli_commitRepoChanges
eb5b9c
@verbatim
eb5b9c
----------------------------------------------------------------------
eb5b9c
--> Bringing changes from the repository into the working copy
eb5b9c
--> Checking changes in the working copy
eb5b9c
----------------------------------------------------------------------
eb5b9c
Added           0 file from the repository.
eb5b9c
Deleted         0 file from the repository.
eb5b9c
Updated         0 file from the repository.
eb5b9c
Conflicted      0 file from the repository.
eb5b9c
Merged          0 file from the repository.
eb5b9c
Modified        4 files from the working copy.
eb5b9c
Unversioned     0 file from the working copy.
eb5b9c
Deleted         0 file from the working copy.
eb5b9c
Added           0 file from the working copy.
eb5b9c
----------------------------------------------------------------------
eb5b9c
@end verbatim
eb5b9c
@caption{The @code{cli_commitRepoChanges} function output.}
eb5b9c
@end float
eb5b9c
eb5b9c
Call the @code{cli_commitRepoChanges} function before or/and after
eb5b9c
calling functions that modify files or directories inside the working
eb5b9c
copy as you may need to.  
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_doParseArguments
eb5b9c
Redefine arguments (@var{ARGUMENTS}) global variable using
eb5b9c
@command{getopt} command output. For more information about how to use
eb5b9c
@code{cli_doParseArguments} function, see @var{ARGUMENTS} variable
eb5b9c
description above.
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_doParseArgumentsReDef $@@
eb5b9c
Initialize/reset arguments (@var{ARGUMENTS}) global variable using
eb5b9c
positional parameters variable (@var{$@@}) as reference.
eb5b9c
eb5b9c
When we work inside function definitions, positional parameters are
eb5b9c
reset to the last function definition positional parameters.  If you
eb5b9c
need to redefine positional parameters from one specific function, you
eb5b9c
need to call @code{cli_doParseArgumentsReDef} with the positional
eb5b9c
parameters variable (@var{$@@}), set as first argument, to that
eb5b9c
specific function you want to redefine positional parameters at.
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_getArguments
eb5b9c
eb5b9c
Initialize function name (@var{FUNCNAM}), action name
eb5b9c
(@var{ACTIONNAM}), and action value (@var{ACTIONVAL}) global
eb5b9c
variables, using positional parameters passed in @var{$@@} variable.
eb5b9c
eb5b9c
The @code{cli_getArguments} function is called from @code{cli.sh}
eb5b9c
function script, using @code{cli} function positional parameters
eb5b9c
(i.e., the positional parameters passed as arguments in the
eb5b9c
command-line) as first function argument. 
eb5b9c
eb5b9c
Once command-line positional parameters are accesible to
eb5b9c
@file{centos-art.sh} script execution evironment,
eb5b9c
@code{cli_getArguments} uses regular expression to retrive
eb5b9c
action variables from first and second argument. The first argument
eb5b9c
defines the value used as function name (@var{FUNCNAM}), and the
eb5b9c
second argument defines both values used as action name
eb5b9c
(@var{ACTIONNAM}) and action value (@var{ACTIONVAL}), respectively.
eb5b9c
eb5b9c
The first argument is a word in lower case. This word specifies the
eb5b9c
name of the functionality you want to use (e.g., @samp{render} to
eb5b9c
render images, @samp{manual} to work on documentation, and so on.)
eb5b9c
eb5b9c
The second argument has a long option style (e.g.,
eb5b9c
@samp{--option=value}). The @samp{--option} represents the action name
eb5b9c
(@var{ACTIONNAM}), and the characters inbetween the equal sign
eb5b9c
(@samp{=}) and the first space character, are considered as the action
eb5b9c
value (@var{ACTIONVAL}). In order to provide action values with space
eb5b9c
characters inbetween you need to enclose action value with quotes like
eb5b9c
in @samp{--option='This is long value with spaces inbetween'}.
eb5b9c
Generally, action values are used to specify paths over which the
eb5b9c
action name acts on.
eb5b9c
eb5b9c
Once action related variables (i.e., @var{FUNCNAM}, @var{ACTIONNAM},
eb5b9c
and @var{ACTIONVAL}) are defined and validated,
eb5b9c
@code{cli_getArguments} shifts the positional arguments to remove the
eb5b9c
first two arguments passed (i.e., those used to retrive action related
eb5b9c
variables) and redefine the arguments (@var{ARGUMENTS}) global
eb5b9c
variable with the new positional parameters information.
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_getFunctions
eb5b9c
Initialize funtionalities supported by @file{centos-art.sh} script.
eb5b9c
eb5b9c
Functionalities supported by @file{centos-art.sh} script are organized
eb5b9c
in functionality directories under
eb5b9c
@file{trunk/Scripts/Bash/Functions/} directory. Each functionality
eb5b9c
directory stores function scripts to the functionality such directory
eb5b9c
was created for. Function scripts contain function definitions.
eb5b9c
Function definitions contain several commands focused on achieving one
eb5b9c
specific task only (i.e., the one such functionality was created for).
eb5b9c
eb5b9c
In order for @file{centos-art.sh} script to recognize a functionality,
eb5b9c
such functionality needs to be stored under
eb5b9c
@file{trunk/Scripts/Bash/Functions/} in a directory written
eb5b9c
capitalized (i.e., the whole name is written in lowercase except the
eb5b9c
first character which is in uppercase). The directory where one
eb5b9c
specific functionality is stored is known as the @samp{functionality
eb5b9c
directory}. 
eb5b9c
eb5b9c
Inside each functionality directory, the functionalty itself is
eb5b9c
implemented through function scripts. Function scripts are organized
eb5b9c
in files independently one another and written in @samp{camelCase}
eb5b9c
format with the function name as prefix.  Separation between prefix
eb5b9c
and description is done using underscore (@samp{_}) character.
eb5b9c
eb5b9c
In order for @file{centos-art.sh} script to load functionalities
eb5b9c
correctly, function definition inside function scripts should be set
eb5b9c
using the @samp{function} reserved word, just as in the following
eb5b9c
example:
eb5b9c
eb5b9c
@verbatim
eb5b9c
function prefix_doSomething {
eb5b9c
eb5b9c
    # Do something here...
eb5b9c
eb5b9c
}
eb5b9c
@end verbatim
eb5b9c
eb5b9c
The above function definition is just a convenction we use, in order
eb5b9c
to make identification of function names easier read and automate by
eb5b9c
@file{centos-art.sh} script initialization commands, once
eb5b9c
@file{centos-art.sh} script determines which functionality directory
eb5b9c
to use.  Specifically, in order to initialize and export functions,
eb5b9c
@file{centos-art.sh} script executes all function scripts inside the
eb5b9c
functionality directory, and later @command{grep} on them using a
eb5b9c
regular expression pattern, where the @samp{function} reserved word is
eb5b9c
used as reference to retrive the function names and export them to
eb5b9c
@file{centos-art.sh} script execution environment, and so, make
eb5b9c
function definitions ---from function scripts inside the functionality
eb5b9c
directory--- available for further calls.
eb5b9c
eb5b9c
If the functionality specified in the command-line first argument
eb5b9c
doesn't have a functionality directory, @file{centos-art.sh} script
eb5b9c
considers the functionality provided in the command-line as invalid
eb5b9c
functionality and immediatly stops script execution with an error
eb5b9c
message.
eb5b9c
eb5b9c
In order to keep visual consistency among function scripts, please
eb5b9c
consider using the following function script design model as template
eb5b9c
for your own function scripts:
eb5b9c
eb5b9c
@verbatim
eb5b9c
#!/bin/bash
eb5b9c
#
eb5b9c
# prefix_doSomething.sh -- This function illustrates function scripts
eb5b9c
# design model you can use to create your own function scripts inside
eb5b9c
# centos-art.sh script.
eb5b9c
#
eb5b9c
# Copyright (C) YEAR YOURFULLNAME
eb5b9c
#
eb5b9c
# This program is free software; you can redistribute it and/or modify
eb5b9c
# it under the terms of the GNU General Public License as published by
eb5b9c
# the Free Software Foundation; either version 2 of the License, or
eb5b9c
# (at your option) any later version.
eb5b9c
# 
eb5b9c
# This program is distributed in the hope that it will be useful, but
eb5b9c
# WITHOUT ANY WARRANTY; without even the implied warranty of
eb5b9c
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
eb5b9c
# General Public License for more details.
eb5b9c
#
eb5b9c
# You should have received a copy of the GNU General Public License
eb5b9c
# along with this program; if not, write to the Free Software
eb5b9c
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
eb5b9c
# USA.
eb5b9c
# 
eb5b9c
# ----------------------------------------------------------------------
eb5b9c
# $Id$
eb5b9c
# ----------------------------------------------------------------------
eb5b9c
eb5b9c
function prefix_doSomething {
eb5b9c
eb5b9c
    # Do something here...
eb5b9c
eb5b9c
}
eb5b9c
@end verbatim
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_getCountryCodes [FILTER]
eb5b9c
Output country codes supported by @file{centos-art.sh} script. 
eb5b9c
eb5b9c
The @code{cli_getCountryCodes} function outputs a list with country
eb5b9c
codes as defined in ISO3166 standard. When @var{FILTER} is provided,
eb5b9c
@code{cli_getCountryCodes} outputs country codes that match
eb5b9c
@var{FILTER} regular expression pattern.
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_getCountryName [FILTER]
eb5b9c
Outputs country name supported by @file{centos-art.sh} script.
eb5b9c
eb5b9c
The @code{cli_getCountryName} function reads one language locale code
eb5b9c
in the format LL_CC and outputs the name of its related country as in
eb5b9c
ISO3166. If filter is specified, @code{cli_getCountryName} returns the
eb5b9c
country name that matches the locale code specified in @var{FILTER},
eb5b9c
exactly.
eb5b9c
@end defun
eb5b9c
 
eb5b9c
@defun cli_getCurrentLocale
eb5b9c
Output current locale used by @file{centos-art.sh} script. 
eb5b9c
eb5b9c
The @code{cli_getCurrentLocale} function uses @env{LANG} environment
eb5b9c
variable to build a locale pattern that is later applied to
eb5b9c
@code{cli_getLocales} function output in order to return the current
eb5b9c
locale that @file{centos-art.sh} script works with. 
eb5b9c
eb5b9c
The current locale information, returned by
eb5b9c
@code{cli_getCurrentLocale}, is output from more specific to less
eb5b9c
specific. For example, if @samp{en_GB} locale exists in
eb5b9c
@code{cli_getLocales} function output, the @samp{en_GB} locale would
eb5b9c
take precedence before @samp{en} locale.
eb5b9c
eb5b9c
Locale precedence selection is quite important in order to define the
eb5b9c
locale type we use for message translations. For example, if
eb5b9c
@samp{en_GB} is used, we are also saying that the common language
eb5b9c
specification for English language (i.e., @samp{en}) is no longer
eb5b9c
used. Instead, we are using English non-common country-specific
eb5b9c
language specifications like @samp{en_AU}, @samp{en_BW}, @samp{en_GB},
eb5b9c
@samp{en_US}, etc., for message translations.  
eb5b9c
eb5b9c
Use @code{cli_getCurrentLocale} function to know what current locale
eb5b9c
information to use inside @file{centos-art.sh} script.
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_getFilesList [LOCATION]
eb5b9c
Output list of files to process.
eb5b9c
eb5b9c
The @code{cli_getFilesList} function uses @var{LOCATION} variable as
eb5b9c
source location to build a list of files just as specified by regular
eb5b9c
expression (@var{REGEX}) global variable. Essentially, what the
eb5b9c
@code{cli_getFilesList} function does is using @command{find} command
eb5b9c
to look for files in the location (@var{LOCATION}) just as posix-egrep
eb5b9c
regular expression (@var{REGEX}) specifies. 
eb5b9c
eb5b9c
If @var{LOCATION} is not specified when @code{cli_getFilesList}
eb5b9c
function is called, the action value (@var{ACTIONVAL}) global variable
eb5b9c
is used as location value instead.
eb5b9c
eb5b9c
By default, if the regular expression (@var{REGEX}) global variable is
eb5b9c
not redefined after its first definition in the @code{cli} function,
eb5b9c
all files that match default regular expression value (i.e.,
eb5b9c
@samp{.+}) will be added to the list of files to process. Otherwise,
eb5b9c
if you redefine the regular expression global variable after its first
eb5b9c
definition in the @code{cli} function and before calling
eb5b9c
@code{cli_getFilesList} function, the last value you specifed is used
eb5b9c
instead.
eb5b9c
eb5b9c
When you need to customize the regular expression (@var{REGEX}) global
eb5b9c
variable value inside a function, do not redefine the global variable
eb5b9c
(at least you be absolutly convinced you need to).  Instead, set the
eb5b9c
regular expression global variable as @samp{local} to the function you
eb5b9c
need a customized regular expression value for.  If we don't redefine
eb5b9c
the regular expression global variable as local to the function, or
eb5b9c
use another name for the regular expression variable (which is not
eb5b9c
very convenient in order to keep the amount of names to remember low),
eb5b9c
you may experiment undesired concantenation issues that make your
eb5b9c
regular expression to be something different from that you expect them
eb5b9c
to be, specially if the function where you are doing the variable
eb5b9c
redefinition is called several times during the same script execution.
eb5b9c
eb5b9c
As result, the @code{cli_getFilesList} re-defines the value of
eb5b9c
@var{FILES} variable with the list of files the @command{find} command
eb5b9c
returned. As example, consider the following construction:
eb5b9c
eb5b9c
@verbatim
eb5b9c
function prefix_doSomething {
eb5b9c
eb5b9c
    # Initialize the list of files to process.
eb5b9c
    local FILES=''
eb5b9c
eb5b9c
    # Initialize location.
eb5b9c
    local LOCATION=/home/centos/artwork/trunk/Identity/Themes/Models/Default
eb5b9c
eb5b9c
    # Re-define regular expression to match scalable vector graphic
eb5b9c
    # files only. Note how we use the global value of REGEX to build a
eb5b9c
    # new local REGEX value here.
eb5b9c
    local REGEX="${REGEX}.*\.(svgz|svg)"
eb5b9c
eb5b9c
    # Redefine list of files to process.
eb5b9c
    cli_getFilesList $LOCATION
eb5b9c
eb5b9c
    # Process list of files.
eb5b9c
    for FILE in $FILES;do
eb5b9c
        cli_printMessages "$FILE" 'AsResponseLine'
eb5b9c
        # Do something else here on...
eb5b9c
    done
eb5b9c
eb5b9c
}
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_getLangCodes [FILTER]
eb5b9c
Outputs language codes supported by @file{centos-art.sh} script.
eb5b9c
eb5b9c
@code{cli_getLangCodes} function outputs a list of language codes as
eb5b9c
defined in ISO639 standard. When @var{FILTER} is provided,
eb5b9c
@code{cli_getLangCodes} outputs language codes that match @var{FILTER}
eb5b9c
regular expression pattern.
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_getLangName [FILTER]
eb5b9c
Outputs language names supported by @file{centos-art.sh} script.
eb5b9c
eb5b9c
@code{cli_getLangName} function reads one language locale code in the
eb5b9c
format LL_CC and outputs the language related name as in ISO639. If
eb5b9c
filter is specified, @code{cli_getLangName} returns the language name
eb5b9c
that matches the locale code specified in @var{FILTER}, exactly.
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_getLocales
eb5b9c
Output locale codes supported by @file{centos-art.sh} script.
eb5b9c
eb5b9c
Occasionally, you use @code{cli_getLocales} function to add locale
eb5b9c
information in non-common country-specific language (@samp{LL_CC})
eb5b9c
format for those languages (e.g., @samp{bn_IN}, @samp{pt_BR}, etc.)
eb5b9c
which locale differences cannot be solved using common language
eb5b9c
specifications (@samp{LL}) into one unique common locale specification
eb5b9c
(e.g., @samp{bn}, @samp{pt}, etc.).  
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_getRepoName NAME TYPE
eb5b9c
Sanitate file names.
eb5b9c
eb5b9c
Inside @file{centos-art.sh} script, specific functionalities rely both
eb5b9c
in @code{cli_getRepoName} and repository file system organization to
eb5b9c
achieve their goals.  Consider @code{cli_getRepoName} function as
eb5b9c
central place to manage file name convenctions for other functions
eb5b9c
inside @file{centos-art.sh} script.
eb5b9c
eb5b9c
@quotation
eb5b9c
@strong{Important} @code{cli_getRepoName} function doesn't verify file
eb5b9c
or directory existence, for that purpose use @code{cli_checkFiles}
eb5b9c
function instead.
eb5b9c
@end quotation
eb5b9c
eb5b9c
The @var{NAME} variable contains the file name or directory name you
eb5b9c
want to sanitate.
eb5b9c
eb5b9c
The @var{TYPE} variable specifies what type of sanitation you want to
eb5b9c
perform on @var{NAME}. The @var{TYPE} can be one of the following
eb5b9c
values:
eb5b9c
eb5b9c
@table @option
eb5b9c
@item d
eb5b9c
@itemx directory
eb5b9c
Sanitate directory @var{NAME}s.
eb5b9c
@item f
eb5b9c
@item regular-file
eb5b9c
Sanitate regular file @var{NAME}s.
eb5b9c
@end table
eb5b9c
eb5b9c
Use @code{cli_getRepoName} function to sanitate file names and
eb5b9c
directory names before their utilization. 
eb5b9c
eb5b9c
Use @code{cli_getRepoName} when you need to change file name
eb5b9c
convenctions inside @file{centos-art.sh} script. 
eb5b9c
eb5b9c
When we change file name convenctions inside @code{cli_getRepoName}
eb5b9c
what we are really changing is the way functions interpret repository
eb5b9c
file system organization. Notice that when we change a file name
eb5b9c
(e.g., a function name), it is necessary to update all files where
eb5b9c
such file name is placed on. This may require a massive substitution
eb5b9c
inside the repository, each time we change name convenctions in the
65cd8a
repository (--- @strong{Removed}(pxref:trunk Scripts Bash Functions Path) ---, for more
eb5b9c
information).
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_getRepoStatus [LOCATION]
eb5b9c
Request repository status.
eb5b9c
eb5b9c
This function requests the status of a @var{LOCATION} inside the
eb5b9c
working copy using the @command{svn status} command and returns the
eb5b9c
first character in the output line, just as described in @command{svn
eb5b9c
help status}. If @var{LOCATION} is not a regular file or a directory,
eb5b9c
inside the working copy, the @file{centos-art.sh} script prints a
eb5b9c
message and ends its execution.
eb5b9c
eb5b9c
Use this function to perform verifications based a repository
eb5b9c
@var{LOCATION} status.
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_getTemporalFile @var{NAME}
eb5b9c
Output absolute path to temporal file @var{NAME}.
eb5b9c
eb5b9c
The @code{cli_getTemporalFile} function uses @file{/tmp} directory as
eb5b9c
source location to store temporal files, the @file{centos-art.sh}
eb5b9c
script name, and a random identification string to let you run more
eb5b9c
than one @file{centos-art.sh} script simultaneously on the same user
eb5b9c
session.  For example, due the following temporal file defintion:
eb5b9c
eb5b9c
@verbatim
eb5b9c
cli_getTemporalFile $FILE
eb5b9c
@end verbatim
eb5b9c
eb5b9c
If @var{FILE} name is @file{instance.svg} and the unique random string
eb5b9c
is @samp{f16f7b51-ac12-4b7f-9e66-72df847f12de}, the final temporal
eb5b9c
file, built from previous temporal file definition, would be:
eb5b9c
eb5b9c
@verbatim
eb5b9c
/tmp/centos-art.sh-f16f7b51-ac12-4b7f-9e66-72df847f12de-instance.svg
eb5b9c
@end verbatim
eb5b9c
eb5b9c
When you use the @code{cli_getTemporalFile} function to create
eb5b9c
temporal files, be sure to remove temporal files created once you've
eb5b9c
ended up with them.  For example, consider the following construction:
eb5b9c
eb5b9c
@verbatim
eb5b9c
for FILE in $FILES;do
eb5b9c
eb5b9c
    # Initialize temporal instance of file.
eb5b9c
    INSTANCE=$(cli_getTemporalFile $FILE)
eb5b9c
eb5b9c
    # Do something ... 
eb5b9c
eb5b9c
    # Remove temporal instance of file.
eb5b9c
    if [[ -f $INSTANCE ]];then
eb5b9c
        rm $INSTANCE
eb5b9c
    fi
eb5b9c
eb5b9c
done
eb5b9c
@end verbatim
eb5b9c
eb5b9c
Use the @code{cli_getTemporalFile} function whenever you need to
eb5b9c
create temporal files inside @file{centos-art.sh} script.
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_getThemeName
eb5b9c
Output theme name.
eb5b9c
eb5b9c
In order for @code{cli_getThemeName} function to extract theme name
eb5b9c
correctly, the @var{ACTIONVAL} variable must contain a directory path
eb5b9c
under @file{trunk/Identity/Themes/Motifs/} directory structure.
eb5b9c
Otherwise, @code{cli_getThemeName} returns an empty string.  
eb5b9c
@end defun
eb5b9c
eb5b9c
@defun cli_printMessage MESSAGE [FORMAT]
eb5b9c
Define standard output message definition supported by
eb5b9c
@file{centos-art.sh} script.
eb5b9c
eb5b9c
When @var{FORMAT} is not specified, @code{cli_printMessage} outputs
eb5b9c
information just as it was passed in @var{MESSAGE} variable.
eb5b9c
Otherwise, @var{FORMAT} can take one of the following values:
eb5b9c
eb5b9c
@table @option
eb5b9c
@item AsHeadingLine
eb5b9c
To print heading messages.
eb5b9c
@verbatim
eb5b9c
----------------------------------------------------------------------
eb5b9c
$MESSAGE
eb5b9c
----------------------------------------------------------------------
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsWarningLine
eb5b9c
To print warning messages.
eb5b9c
@verbatim
eb5b9c
----------------------------------------------------------------------
eb5b9c
WARNING: $MESSAGE
eb5b9c
----------------------------------------------------------------------
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsNoteLine
eb5b9c
To print note messages.
eb5b9c
@verbatim
eb5b9c
----------------------------------------------------------------------
eb5b9c
NOTE: $MESSAGE
eb5b9c
----------------------------------------------------------------------
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsUpdatingLine
eb5b9c
To print @samp{Updating} messages on two-columns format.
eb5b9c
@verbatim
eb5b9c
Updating        $MESSAGE
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsRemovingLine
eb5b9c
To print @samp{Removing} messages on two-columns format.
eb5b9c
@verbatim
eb5b9c
Removing        $MESSAGE
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsCheckingLine
eb5b9c
To print @samp{Checking} messages on two-columns format.
eb5b9c
@verbatim
eb5b9c
Checking        $MESSAGE
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsCreatingLine
eb5b9c
To print @samp{Creating} messages on two-columns format.
eb5b9c
@verbatim
eb5b9c
Creating        $MESSAGE
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsSavedAsLine
eb5b9c
To print @samp{Saved as} messages on two-columns format.
eb5b9c
@verbatim
eb5b9c
Saved as        $MESSAGE
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsLinkToLine
eb5b9c
To print @samp{Linked to} messages on two-columns format.
eb5b9c
@verbatim
eb5b9c
Linked to       $MESSAGE
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsMovedToLine
eb5b9c
To print @samp{Moved to} messages on two-columns format.
eb5b9c
@verbatim
eb5b9c
Moved to        $MESSAGE
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsTranslationLine
eb5b9c
To print @samp{Translation} messages on two-columns format.
eb5b9c
@verbatim
eb5b9c
Translation     $MESSAGE
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsConfigurationLine
eb5b9c
To print @samp{Configuration} messages on two-columns format.
eb5b9c
@verbatim
eb5b9c
Configuration   $MESSAGE
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsResponseLine
eb5b9c
To print response messages on one-column format.
eb5b9c
@verbatim
eb5b9c
--> $MESSAGE
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsRequestLine
eb5b9c
To print request messages on one-column format. Request messages
eb5b9c
output messages with one colon (@samp{:}) and without trailing newline
eb5b9c
(@samp{\n}) at message end.
eb5b9c
@verbatim
eb5b9c
$MESSAGE:
eb5b9c
@end verbatim
eb5b9c
eb5b9c
@item AsYesOrNoRequestLine
eb5b9c
To print @samp{yes or no} request messages on one-column format. If
eb5b9c
something different from @samp{y} is answered (when using
eb5b9c
@code{en_US.UTF-8} locale), script execution ends immediatly.  
eb5b9c
eb5b9c
@verbatim
eb5b9c
$MESSAGE [y/N]:
eb5b9c
@end verbatim
eb5b9c
eb5b9c
When we use @file{centos-art.sh} script in a locale different from
eb5b9c
@code{en_US.UTF-8}, confirmation answer may be different from
eb5b9c
@samp{y}. For example, if you use @code{es_ES.UTF-8} locale, the
eb5b9c
confirmation question would look like:
eb5b9c
eb5b9c
@verbatim
eb5b9c
$MESSAGE [s/N]:
eb5b9c
@end verbatim
eb5b9c
eb5b9c
and the confirmation answer would be @samp{s}, as it is on Spanish
eb5b9c
@samp{sí} word.
eb5b9c
eb5b9c
Definition of which confirmation word to use is set on translation
65cd8a
messages for your specific locale information. --- @strong{Removed}(xref:trunk Scripts
65cd8a
Bash Functions Locale) ---, for more information about locale-specific
eb5b9c
translation messages.
eb5b9c
eb5b9c
@item AsToKnowMoreLine
eb5b9c
To standardize @samp{to know more, run the following command:}
eb5b9c
messages. When the @option{AsToKnowMoreLine} option is used, the
eb5b9c
@var{MESSAGE} value should be set to @code{"$(caller)"}. @code{caller}
eb5b9c
is a Bash builtin that returns the context of the current subroutine
eb5b9c
call. @option{AsToKnowMoreLine} option uses @code{caller} builtin
eb5b9c
output to build documentation entries dynamically.
eb5b9c
eb5b9c
@verbatim
eb5b9c
----------------------------------------------------------------------
eb5b9c
To know more, run the following command:
eb5b9c
centos-art manual --read='path/to/dir'
eb5b9c
----------------------------------------------------------------------
eb5b9c
@end verbatim
eb5b9c
eb5b9c
Use @option{AsToKnowMoreLine} option after errors and for intentional
eb5b9c
script termination. 
eb5b9c
eb5b9c
@item AsRegularLine
eb5b9c
To standardize regular messages on one-column format. 
eb5b9c
eb5b9c
When @var{MESSAGE} contains a colon inside (e.g., @samp{description:
eb5b9c
message}), the @code{cli_printMessage} function outputs @var{MESSAGE}
eb5b9c
on two-columns format. 
eb5b9c
@end table
eb5b9c
eb5b9c
Use @code{cli_printMessage} function whenever you need to output
eb5b9c
information from @file{centos-art.sh} script.
eb5b9c
eb5b9c
@quotation
eb5b9c
@strong{Tip} To improve two-columns format, change the following file:
eb5b9c
@verbatim
eb5b9c
trunk/Scripts/Bash/Styles/output_forTwoColumns.awk
eb5b9c
@end verbatim
eb5b9c
@end quotation
eb5b9c
@end defun
eb5b9c
eb5b9c
@subsubsection Specific functions
eb5b9c
eb5b9c
The following specific functions of @file{centos-art.sh} script, are
eb5b9c
available for you to use:
eb5b9c
eb5b9c
@menu
7c36fe
@comment --- Removed(* Filesystem trunk Scripts Bash Functions Html::) ---
7c36fe
@comment --- Removed(* Filesystem trunk Scripts Bash Functions Locale::) ---
7c36fe
@comment --- Removed(* Filesystem trunk Scripts Bash Functions Manual::) ---
7c36fe
@comment --- Removed(* Filesystem trunk Scripts Bash Functions Path::) ---
7c36fe
@comment --- Removed(* Filesystem trunk Scripts Bash Functions Render::) ---
7c36fe
@comment --- Removed(* Filesystem trunk Scripts Bash Functions Render Config::) ---
7c36fe
@comment --- Removed(* Filesystem trunk Scripts Bash Functions Shell::) ---
7c36fe
@comment --- Removed(* Filesystem trunk Scripts Bash Functions Svg::) ---
7c36fe
@comment --- Removed(* Filesystem trunk Scripts Bash Functions Verify::) ---
eb5b9c
@end menu
eb5b9c
010b2d
@subsection See also
010b2d
010b2d
@menu
7c36fe
* Filesystem trunk Scripts Bash::
7c36fe
@comment --- Removed(* Filesystem trunk Scripts Bash Locale::) ---
010b2d
@end menu