@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 and variables do we

have available inside @file{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

@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 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 @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 fixed to

@option{--filter} for whatever value it passes 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} global variable may serve to.

@end defvar

@defvar ARGUMENTS 

Define optional arguments. 

Inside @file{centos-art.sh} script, specifically inside @command{path}

functionality, we consider optional arguments as all command-line

arguments passed to @file{centos-art.sh} script, from third argument

position on.  

Optional arguments are appended to commands in order for

@file{centos-art.sh} script to support them.  Such commands are

executed inside @file{centos-art.sh} script using Bash's

@command{eval} built-in.  

If you provide unrecognized options to such commands, they will

complain just as they would do from the command-line.  Or what is the

same, final verification of which options are valid or not is done

inside the command options wered appended to, not by

@file{centos-art.sh} script.  

When parsing @var{ARGUMENTS}, we may find short options (e.g.,

@option{-m}) or long options (e.g., @option{--message}). When using

short options, arguments are separated by one space from the option

(e.g., @option{-m 'This is a commit message.'}).  When using long

options arguments are separated by an equal sign (@samp{=}) (e.g.,

@option{--message='This is a commit message'}). To know which option

have required arguments let @file{centos-art.sh} script to know how to

build the optional argument string by quoting the option's argument.  

Note that if we don't use @command{getopt} to parse the command-line

arguments it would complicate to determine when an argument is an

option argument and when it is not; when options' argument are

optional and where they are not. Inside getopt, required option

arguments are defined using the colon (@samp{:}) symbol after the

option (e.g., @option{-o m: -l message:}).

As convenction we use long options as reference. We take the value of

@var{ARGSLONG} and split it using the comma (@samp{,}) character as

separator and check if the last character of the option is a colon

like in the regular expression @code{[[:alpha:]]+:,}.

Take care not to match two colons like in the regular expression

@code{[[:alpha:]]+::,}, this construction is used to specify that

option can receive and argument but it is not required.

@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 [LOCATION]

Commit changes from the working copy up to the repository.

The @code{cli_commitRepoChanges} function uses the value of

@var{OPTIONVAL} variable as reference to perform change verifications

inside the working copy.

The @code{cli_commitRepoChanges} function brings changes from the

repository to the working copy---using @command{svn update}---, check

the working copy changes---using @command{svn status} command---,

print status report---using both @command{svn update} and @command{svn

status} commands output, and finally, commit recent changes from the

working copy up to the repository---using @command{svn commit}

command---.

Previous to commit the working copy changes up to the repository, the

@code{cli_commitRepoChanges} function asks you to verify changes, and

later, another confirmation question is shown to be sure you really

want to commit changes up to central repository.

Call the @code{cli_commitRepoChanges} function after functions that

modify files or directories inside the working copy.  

@end defun

@defun cli_checkFiles FILE [TYPE]

Verify files existence.

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

@item fd

Ends script execution if @var{FILE} is neither a regular file or a

directory.

@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{Important} @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_getTemporalFile @var{NAME}

Output absolute path to temporal file @var{NAME}.

@code{cli_getTemporalFile} uses @file{/tmp} directory as source

location to store temporal files, the @file{centos-art.sh} script

name, and a random identification string 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

cli_getTemporalFile $FILE

@end verbatim

If @var{FILE} name is @file{instance.svg} and unique random string is

@samp{f16f7b51-ac12-4b7f-9e66-72df847f12de}, the final temporal file,

built from previous temporal file definition, would be:

@verbatim

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

@end verbatim

When you use @code{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:

@verbatim

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

@end verbatim

Use @code{cli_getTemporalFile} function whenever you need to create

temporal files inside @file{centos-art.sh} script.

@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