@subsection Goals

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

@subsection Description

The specific functions of @file{centos-art.sh} script are designed
with ``Software Toolbox'' philosophy (@pxref{Toolbox
introduction,,,coreutils.info}) in mind: each program ``should do one
thing well''.  Inside @file{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 @file{centos-art.sh} script are organized
inside specific directories under @file{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 @code{render}, the specific function
directory for it would be @samp{trunk/Scripts/Bash/Functions/Render}.

To better understand how specific functions of @file{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 @file{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.

@quotation
@strong{Tip} Join CentOS developers mailing list
@email{centos-art@@centos.org} to share your ideas.
@end quotation

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

OK, let's begin with our functionality example.

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

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

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

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

Inside @file{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 @file{centos-art.sh} script functions, top commentaries
describe function definition in the following five components:
one-line for copyright note with your personal information,  the
license under which the function source code is released ---the
@file{centos-art.sh} script is released as GPL, so do all its
functions---, subversion's @code{$Id$} keyword which is later expanded
by @command{svn propset} command.

In our @code{greet} function example, top commentary for
@file{greet.sh} function script would look like the following:

@verbatim
#!/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$
# ----------------------------------------------------------------------
@end verbatim

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

@verbatim
function greet {

    # Define global variables.

    # Define command-line interface.
    greet_getActions

}
@end verbatim

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

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

@verbatim
function greet_getActions {

    case "$OPTIONNAM" in

        --hello )
            greet_doHello
            ;;

        --bye )
            greet_doBye
            ;;

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

    esac

}
@end verbatim

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

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

The @samp{*} case and its two further lines should always be present
in @file{_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 @code{greet_doHello} and @code{greet_doBye} function definitions
are the core of @code{greet} specific functionality.  In such function
definitions we set what our @code{greet} function really does: to
output different kinds of greetings.

@verbatim
function greet_doHello {

    cli_printMessage "`gettext "Hello"` $OPTIONVAL"

}
@end verbatim

The @code{greet_doHello} function definition is stored in
@file{greet_doHello.sh} function script. 

@verbatim
function greet_doBye {

    cli_printMessage "`gettext "Goodbye"` $OPTIONVAL"

}
@end verbatim

The @code{greet_doBye} function definition is stored in the
@file{greet_doBye.sh} function script. 

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

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

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

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

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

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

The word @samp{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 @code{greet} specific functionality,
we use its directory path and the @code{help} functionality
(@pxref{trunk Scripts Bash Functions Help}) of @file{centos-art.sh}
script, just as the following command illustrates: 

@verbatim
centos-art help --edit=trunk/Scripts/Bash/Functions/Greet
@end verbatim

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
@code{locale} functionality (@pxref{trunk Scripts Bash Functions
Locale}) of @file{centos-art.sh} script, just as the following command
illustrates:

@verbatim
centos-art locale --edit
@end verbatim

@quotation
@strong{Warning} To translate output messages in different languages,
your system locale information ---as in @env{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
@samp{es_ES.UTF-8} or similar.  
@end quotation

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

In @code{greet} function example we've described so far, we only use
@command{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
@option{--filter='regex'} and reduce the amount of files to process
using a regular expression pattern.

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

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

@subsection Usage

@subsubsection Global variables

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

@defvar TEXTDOMAIN
Default domain used to retrieve translated messages. This value is set
in @file{initFunctions.sh} and shouldn't be changed.
@end defvar

@defvar TEXTDOMAINDIR
Default directory used to retrieve translated messages. This value is
set in @file{initFunctions.sh} and shouldn't be changed.
@end defvar

@defvar ACTION
Default action passed as first argument in @file{centos-art.sh}
command-line interface. For example, in the command @samp{centos-art
render --entry=path/to/dir --filter=regex}, the @var{ACTION} passed to
@file{centos-art.sh} script is @option{render}.
@end defvar

@defvar OPTIONNAM
Default option name passed as second argument in @file{centos-art.sh}
command-line interface. For example, in the command @samp{centos-art
render --entry=path/to/dir --filter=regex}, the @var{OPTIONNAM} passed
to @file{centos-art.sh} script is @option{--entry}.
@end defvar

@defvar OPTIONVAL
Default option value passed as second argument in @file{centos-art.sh}
command-line interface. For example, in the command @samp{centos-art
render --entry=path/to/dir --filter=regex}, the @var{OPTIONVAL} passed
to @file{centos-art.sh} script is @option{path/to/dir}.
@end defvar

@defvar REGEX
Default option value passed as third argument in @file{centos-art.sh}
command-line interface. For example, in the command @samp{centos-art
render --entry=path/to/dir --filter=regex}, the @var{REGEX} passed to
@file{centos-art.sh} is @option{regex}. 

The third argument option name is not variable as second argument
option name is. The third argument option name is stocked to
@option{--filter} for whatever value it passed at the right side of
its equal sign. 

Generally, third argument option value is used to pass regular
expression patterns that modify the list of files to process, but this
is not the only feature @var{REGEX} may serve to.
@end defvar

@defvar ANSWER
Default answer to confirmation questions. 

As most questions request confirmation to perform some action, default
answer to @var{ANSWER} variable is negative (i.e., @samp{No}).
Default answer value takes place when no value is entered as response
to confirmation questions before pressing @key{RET} key.
@end defvar

@defvar TMPFILE
Default location to store temporal files. 

The @var{TMPFILE} uses @file{/tmp} directory as source location to
store temporal files, the @file{centos-art.sh} script name, and the
process id of @file{centos-art.sh} script execution to let you run
more than one @file{centos-art.sh} script simultaneously on the same
user session.  For example, due the following temporal file defintion:

@verbatim
${TMPFILE}-${FILE}
@end verbatim

If @var{FILE} name is @file{instance.svg} and process id is
@samp{3761}, the final temporal file built from previous temporal file
definition would be:

@verbatim
/tmp/centos-art.sh-3761-instance.svg
@end verbatim

When you use @var{TMPFILE} global variable to create temporal files,
be sure to remove temporal files created once you've ended up with
them.  For example, consider the following construction:

@verbatim
for FILE in $FILES;do

    # Initialize temporal instance of file.
    INSTANCE=${TMPFILE}-${FILE}

    # Do something ... 

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

done
@end verbatim
@end defvar

@defvar EDITOR 
Default text editor. 

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

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

@itemize
@item @file{/usr/bin/vim}
@item @file{/usr/bin/emacs}
@item @file{/usr/bin/nano}
@end itemize

If no one of these values is set in @env{EDITOR} environment variable,
@file{centos-art.sh} uses @file{/usr/bin/vim} text editor by default. 
@end defvar

@subsubsection Global functions

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

@defun cli_commitRepoChanges
Commit recent changes up to central repository.

The @code{cli_commitRepoChanges} function uses the list of files
stored in the @var{FILES} variable and verifies changes inside your
repository working copy, using subversion commands.  If
@code{cli_commitRepoChanges} finds changes inside your working copy,
it asks you for confirmation to commit them up to central repository.

Call @code{cli_commitRepoChanges} function after functions that modify
files inside your repository working copy.
@end defun

@defun cli_checkFiles FILE [TYPE]
Verify files.

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

@table @option
@item d
@itemx directory
Ends script execution if @var{FILE} is not a directory.

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

@item f
@item regular-file
Ends script execution if @var{FILE} is not a regular file.
@item h
@itemx symbolic-link
Ends script execution if @var{FILE} is not a symbolic link.
@item x
@itemx execution
Ends script execution if @var{FILE} is not executable.
@item fh
Ends script execution if @var{FILE} is neither a regular file or a
symbolic link.
@end table

As default behaviour, if @var{FILE} passes all verifications,
@file{centos-art.sh} script continues with its normal flow. 
@end defun

@defun cli_getCountryCodes [FILTER]
Output country codes.

The @code{cli_getCountryCodes} function outputs a list with country
codes as defined in ISO3166 standard. When @var{FILTER} is provided,
@code{cli_getCountryCodes} outputs country codes that match
@var{FILTER} regular expression pattern.
@end defun

@defun cli_getCountryName [FILTER]
Output country names.

The @code{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, @code{cli_getCountryName} returns the
country name that matches the locale code specified in @var{FILTER},
exactly.

The @code{cli_getCountryName} function outputs country name supported
by @file{centos-art.sh} script.
@end defun
 
@defun cli_getCurrentLocale
Output current locale used by @file{centos-art.sh} script. 

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

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

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

Use @code{cli_getCurrentLocale} function to know what current locale
information to use inside @file{centos-art.sh} script.

The @code{cli_getCurrentLocale} function outputs current locale used
by @file{centos-art.sh} script.
@end defun

@defun cli_getLangCodes [FILTER]
Output language codes.

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

The @code{cli_getLangCodes} function outputs language codes supported
by @file{centos-art.sh} script.
@end defun

@defun cli_getLangName [FILTER]
Output language names.

@code{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, @code{cli_getLangName} returns the language name
that matches the locale code specified in @var{FILTER}, exactly.

The @code{cli_getLangName} function outputs language names supported
by @file{centos-art.sh} script.
@end defun

@defun cli_getLocales
Output locale codes supported by @file{centos-art.sh} script.

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

@defun cli_getRepoName NAME TYPE
Sanitate file names.

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

@quotation
@strong{Warning} @code{cli_getRepoName} function doesn't verify file
or directory existence, for that purpose use @code{cli_checkFiles}
function instead.
@end quotation

The @var{NAME} variable contains the file name or directory name you
want to sanitate.

The @var{TYPE} variable can be one of the following values:
@table @option
@item d
@itemx directory
Sanitate directory @var{NAME}s.
@item f
@item regular-file
Sanitate regular file @var{NAME}s.
@end table

Use @code{cli_getRepoName} function to sanitate file names and
directory names before their utilization. 

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

When changing file name convenctions inside @code{cli_getRepoName}
what you are really changing is the way functions interpret repository
file system organization. In order to a complete file name convenction
change, you also need to change file names and directory names inside
repository file system organization, just as you did in
@code{cli_getRepoName} function. 

@quotation
@strong{Note} @xref{trunk Scripts Bash Functions Path}, for more
information on how to rename files and directories massively inside
repository file system organization.
@end quotation
@end defun

@defun cli_getThemeName
Output theme name.

In order for @code{cli_getThemeName} function to extract theme name
correctly, the @var{OPTIONVAL} variable must contain a directory path
under @file{trunk/Identity/Themes/Motifs/} directory structure.
Otherwise, @code{cli_getThemeName} returns an empty string.  
@end defun

@defun cli_printMessage MESSAGE [FORMAT]
Give format to output messages.

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

@table @option
@item AsHeadingLine
To print heading messages.
@verbatim
----------------------------------------------------------------------
$MESSAGE
----------------------------------------------------------------------
@end verbatim

@item AsWarningLine
To print warning messages.
@verbatim
----------------------------------------------------------------------
WARNING: $MESSAGE
----------------------------------------------------------------------
@end verbatim

@item AsNoteLine
To print note messages.
@verbatim
----------------------------------------------------------------------
NOTE: $MESSAGE
----------------------------------------------------------------------
@end verbatim

@item AsUpdatingLine
To print @samp{Updating} messages using two-columns format.
@verbatim
Updating        $MESSAGE
@end verbatim

@item AsRemovingLine
To print @samp{Removing} messages using two-columns format.
@verbatim
Removing        $MESSAGE
@end verbatim

@item AsCheckingLine
To print @samp{Checking} messages using two-columns format.
@verbatim
Checking        $MESSAGE
@end verbatim

@item AsCreatingLine
To print @samp{Creating} messages using two-columns format.
@verbatim
Creating        $MESSAGE
@end verbatim

@item AsSavedAsLine
To print @samp{Saved as} messages using two-columns format.
@verbatim
Saved as        $MESSAGE
@end verbatim

@item AsLinkToLine
To print @samp{Linked to} messages using two-columns format.
@verbatim
Linked to       $MESSAGE
@end verbatim

@item AsMovedToLine
To print @samp{Moved to} messages using two-columns format.
@verbatim
Moved to        $MESSAGE
@end verbatim

@item AsTranslationLine
To print @samp{Translation} messages using two-columns format.
@verbatim
Translation     $MESSAGE
@end verbatim

@item AsConfigurationLine
To print @samp{Configuration} messages using two-columns format.
@verbatim
Configuration   $MESSAGE
@end verbatim

@item AsResponseLine
To print response messages using one-column format.
@verbatim
--> $MESSAGE
@end verbatim

@item AsRequestLine
To print request messages using one-column format. Request messages
supress the trailing newline character from final output.
@verbatim
$MESSAGE
@end verbatim

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

@verbatim
$MESSAGE [y/N]:
@end verbatim

When you are using @file{centos-art.sh} script in a locale different
from @code{en_US.UTF-8}, confirmation answer may be different from
@samp{y}. For example, if you are using @code{es_ES.UTF-8} locale, the
confirmation question would look like:

@verbatim
$MESSAGE [s/N]:
@end verbatim

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

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

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

@verbatim
----------------------------------------------------------------------
To know more, run the following command:
centos-art help --read='path/to/dir'
----------------------------------------------------------------------
@end verbatim

Use @option{AsToKnowMoreLine} option after errors and for intentional
script termination. 

@item AsRegularLine
To standardize regular messages using one-column format. 

When @var{MESSAGE} contains a colon inside (e.g., @samp{description:
message}), the @code{cli_printMessage} function outputs @var{MESSAGE}
using two-columns format. 
@end table

@quotation
@strong{Tip} To improve two-columns format, change the following file:
@verbatim
trunk/Scripts/Bash/Styles/output_forTwoColumns.awk
@end verbatim
@end quotation

Use @code{cli_printMessage} function whenever you need to output
information from @file{centos-art.sh} script.
@end defun

@subsubsection Specific functions

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

@menu
* trunk Scripts Bash Functions Help::
* trunk Scripts Bash Functions Html::
* trunk Scripts Bash Functions Locale::
* trunk Scripts Bash Functions Path::
* trunk Scripts Bash Functions Render::
* trunk Scripts Bash Functions Render Config::
* trunk Scripts Bash Functions Shell::
* trunk Scripts Bash Functions Svg::
* trunk Scripts Bash Functions Verify::
@end menu

@subsection See also

@menu
* trunk Scripts Bash::
* trunk Scripts Bash Locale::
@end menu