@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---, the @code{$Id$}

keyword of Subversion 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 command-line

interface of @code{greet} functionality defines what and how actions

are performed, based on arguments combination passed to

@file{centos-art.sh} script.

@verbatim

function greet_getActions {

    case "$ACTIONNAM" in

        --hello )

            greet_doHello

            ;;

        --bye )

            greet_doBye

            ;;

        * )

            cli_printMessage "`gettext "The option provided is not valid."`"

            cli_printMessage "$(caller)" 'AsToKnowMoreLine'

    esac

}

@end verbatim

The @var{ACTIONNAM} 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{ACTIONNAM}

variable would be @samp{--hello}.  Using this configuration let us

deside which action to perform based on the action 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 lines further on 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,

when no valid action is provided.

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"` $ACTIONVAL"

}

@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"` $ACTIONVAL"

}

@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} function directory path (i.e.

@file{trunk/Scripts/Bash/Functions/Greet}).

The @var{ACTIONVAL} 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{ACTIONVAL}

variable would be @samp{World} without quotes.

Let's see how @code{greet} specific functionality files are organzied

under @code{greet} 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{manual} functionality

(@pxref{trunk Scripts Bash Functions Manual}) of @file{centos-art.sh}

script, just as the following command illustrates: 

@verbatim

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

@end verbatim

To have a well documented function helps user to understand how your

function really works, and how it should be used.  When no valid

action is passed to a function, the @file{centos-art.sh} script uses

the function documentation entry as vehicle to communicate which the

valid functions are. When no documentation entry exists for a

function, the @file{centos-art.sh} script informs that no

documentation entry exists for such function and requests user to

create it right at that time.

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, first.

@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 messages, but more interesting things

can be achieved inside action specific function definitions.  For

example, if you pass a directory path as action value in second

argument, 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 FUNCNAM

Define function name.

Function names associate sets of actions. There is one set of actions

for each unique function name inside @file{centos-art.sh} script.

Dunction names are 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}.

When first argument is not provided, the @file{centos-art.sh} script

immediatly ends its execution.

@end defvar

@defvar FUNCDIR

@end defvar

@defvar FUNCDIRNAME

@end defvar

@defvar FUNCSCRIPT

@end defvar

@defvar FUNCCONFIG

@end defvar

@defvar ACTIONNAM

Define action name.

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

specific function.

Action name names aare passed as second argument in

@file{centos-art.sh} command-line interface. For example, in the

command @samp{centos-art render --entry=path/to/dir --filter=regex},

the @var{ACTIONNAM} passed to @file{centos-art.sh} script is

@option{--entry}.

When second argument is not provided, the @file{centos-art.sh} script

immediatly ends its execution.

@end defvar

@defvar ACTIONVAL

Define action value.

Action values are associated to just one action name. Action values

contain the working copy entry over which its associated action will be

performed in.  Working copy entries can be files or directories inside

the working copy.

@end defvar

@defvar REGEX

Define regular expression used as pattern to build the list of files

to process.

By default, @var{REGEX} variable is set to @code{.+} to match all

files.

Functions that need to build a list of files to process use the option

@option{--filter} to redefine @var{REGEX} variable default value, and

so, control the amount of files to process.

@end defvar

@defvar ARGUMENTS 

Define optional arguments. 

Optional arguments, inside @file{centos-art.sh} script, are considered

as all command-line arguments passed to @file{centos-art.sh} script,

from third argument position on. For example, in the command

@samp{centos-art render --entry=path/to/dir --filter=regex} , the

optional arguments are from @samp{--filter=regex} argument on.

Optional arguments are parsed using @command{getopt} command through

the following base construction: 

@verbatim

# Define short options we want to support.

local ARGSS=""

# Define long options we want to support.

local ARGSL="filter:,to:"

# Parse arguments using getopt(1) command parser.

cli_doParseArguments

# Reset positional parameters using output from (getopt) argument

# parser.

eval set -- "$ARGUMENTS"

# Define action to take for each option passed.

while true; do

    case "$1" in

        --filter )

            REGEX="$2" 

            shift 2

            ;;

        --to )

            TARGET="$2" 

            shift 2

            ;;

        * )

            break

    esac

done

@end verbatim

Optional arguments provide support to command options inside

@file{centos-art.sh} script. For instance, consider the Subversion

(@command{svn}) command, where there are many options (e.g.,

@option{copy}, @option{delete}, @option{move}, etc), and inside each

option there are several modifiers (e.g., @samp{--revision},

@samp{--message}, @samp{--username}, etc.) that can be combined one

another in their short or long variants. 

The @var{ARGUMENTS} variable is used to store arguments passed from

command-line for later use inside @file{centos-art.sh} script. Storing

arguments is specially useful when we want to run a command with some

specific options from them. Consider the following command:

@verbatim

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

@end verbatim

In the above command, the @option{--message}, and @option{--username}

options are specific to @command{svn copy} command. In such cases,

options are not interpreted by @file{centos-art.sh} script itself.

Instead, the @file{centos-art.sh} script uses @command{getopt} to

retrive them and store them in the @var{ARGUMENTS} variable for later

use, as described in the following command:

@verbatim

# Build subversion command to duplicate locations inside the

# workstation.

eval svn copy $SOURCE $TARGET --quiet $ARGUMENTS

@end verbatim

When @command{getopt} parses @var{ARGUMENTS}, we may use short options

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

we use short options, arguments are separated by one space from the

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

long options arguments are separated by an equal sign (@samp{=})

(e.g., @option{--message='This is a commit message'}).

In order for @command{getopt} to parse @var{ARGUMENTS} correctly, it

is required to provide the short and long definition of options that

will be passed or at least supported by the command performing the

final action the function script exists for.

As convenction, inside @file{centos-art.sh} script, short option

definitions are set in the @var{ARGSS} variable; and long option

definitions are set in the @var{ARGSL} variable.

When you define short and long options, it may be needed to define

which of these option arguments are required and which not. To define

an option argument as required, you need to set one colon @samp{:}

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

the other hand, to define an option argument as not required, you need

to set two colons @samp{::} after the option definition (e.g.,

@option{-o m:: -l message::}).

@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

Function scripts stored directly under

@file{trunk/Scripts/Bash/Functions/} directory are used to define

global functions.  Global functions can be used inside action specific

functionalities and or even be reused inside themselves. This section

provides introductory information to global functions you can use

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

@defun cli_checkActionArguments

Validate action value (@var{ACTIONVAL}) variable.

The action value variable can take one of the following values:

@enumerate

@item Path to one directory inside the local working copy,

@item Path to one file inside the local working copy,

@end enumerate

If another value different from that specified above is passed to

action value variable, the @file{centos-art.sh} script prints an error

message and ends script execution.

@end defun

@defun cli_checkFiles FILE [TYPE]

Verify file 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 nor a

symbolic link.

@item fd

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

directory.

@item isInWorkingCopy

Ends script execution if @var{FILE} is not inside the working copy.

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

Syncronize changes between repository and working copy.

The @code{cli_commitRepoChanges} function brings changes from the

central repository down to the working copy---using @command{svn

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

status} command---, prints status report---using both @command{svn

update} and @command{svn status} commands output, and finally, commits

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 central

repository, the @code{cli_commitRepoChanges} function asks you to

verify changes---using @command{svn diff} command---, and later,

another confirmation question is shown to be sure you really want to

commit changes up to central repository.

If @var{LOCATION} argument is not specified, the value of

@var{ACTIONVAL} variable is used as reference instead.

@float Figure, trunk/Scripts/Bash/Functions/cli_commitRepoChanges

@verbatim

----------------------------------------------------------------------

--> Bringing changes from the repository into the working copy

--> Checking changes in the working copy

----------------------------------------------------------------------

Added           0 file from the repository.

Deleted         0 file from the repository.

Updated         0 file from the repository.

Conflicted      0 file from the repository.

Merged          0 file from the repository.

Modified        4 files from the working copy.

Unversioned     0 file from the working copy.

Deleted         0 file from the working copy.

Added           0 file from the working copy.

----------------------------------------------------------------------

@end verbatim

@caption{The @code{cli_commitRepoChanges} function output.}

@end float

Call the @code{cli_commitRepoChanges} function before or/and after

calling functions that modify files or directories inside the working

copy as you may need to.  

@end defun

@defun cli_doParseArguments

Redefine arguments (@var{ARGUMENTS}) global variable using

@command{getopt} command output. For more information about how to use

@code{cli_doParseArguments} function, see @var{ARGUMENTS} variable

description above.

@end defun

@defun cli_doParseArgumentsReDef $@@

Initialize/reset arguments (@var{ARGUMENTS}) global variable using

positional parameters variable (@var{$@@}) as reference.

When we work inside function definitions, positional parameters are

reset to the last function definition positional parameters.  If you

need to redefine positional parameters from one specific function, you

need to call @code{cli_doParseArgumentsReDef} with the positional

parameters variable (@var{$@@}), set as first argument, to that

specific function you want to redefine positional parameters at.

@end defun

@defun cli_getArguments

Initialize function name (@var{FUNCNAM}), action name

(@var{ACTIONNAM}), and action value (@var{ACTIONVAL}) global

variables, using positional parameters passed in @var{$@@} variable.

The @code{cli_getArguments} function is called from @code{cli.sh}

function script, using @code{cli} function positional parameters

(i.e., the positional parameters passed as arguments in the

command-line) as first function argument. 

Once command-line positional parameters are accesible to

@file{centos-art.sh} script execution evironment,

@code{cli_getArguments} uses regular expression to retrive

action variables from first and second argument. The first argument

defines the value used as function name (@var{FUNCNAM}), and the

second argument defines both values used as action name

(@var{ACTIONNAM}) and action value (@var{ACTIONVAL}), respectively.

The first argument is a word in lower case. This word specifies the

name of the functionality you want to use (e.g., @samp{render} to

render images, @samp{manual} to work on documentation, and so on.)

The second argument has a long option style (e.g.,

@samp{--option=value}). The @samp{--option} represents the action name

(@var{ACTIONNAM}), and the characters inbetween the equal sign

(@samp{=}) and the first space character, are considered as the action

value (@var{ACTIONVAL}). In order to provide action values with space

characters inbetween you need to enclose action value with quotes like

in @samp{--option='This is long value with spaces inbetween'}.

Generally, action values are used to specify paths over which the

action name acts on.

Once action related variables (i.e., @var{FUNCNAM}, @var{ACTIONNAM},

and @var{ACTIONVAL}) are defined and validated,

@code{cli_getArguments} shifts the positional arguments to remove the

first two arguments passed (i.e., those used to retrive action related

variables) and redefine the arguments (@var{ARGUMENTS}) global

variable with the new positional parameters information.

@end defun

@defun cli_getFunctions

Initialize funtionalities supported by @file{centos-art.sh} script.

Functionalities supported by @file{centos-art.sh} script are organized

in functionality directories under

@file{trunk/Scripts/Bash/Functions/} directory. Each functionality

directory stores function scripts to the functionality such directory

was created for. Function scripts contain function definitions.

Function definitions contain several commands focused on achieving one

specific task only (i.e., the one such functionality was created for).

In order for @file{centos-art.sh} script to recognize a functionality,

such functionality needs to be stored under

@file{trunk/Scripts/Bash/Functions/} in a directory written

capitalized (i.e., the whole name is written in lowercase except the

first character which is in uppercase). The directory where one

specific functionality is stored is known as the @samp{functionality

directory}. 

Inside each functionality directory, the functionalty itself is

implemented through function scripts. Function scripts are organized

in files independently one another and written in @samp{camelCase}

format with the function name as prefix.  Separation between prefix

and description is done using underscore (@samp{_}) character.

In order for @file{centos-art.sh} script to load functionalities

correctly, function definition inside function scripts should be set

using the @samp{function} reserved word, just as in the following

example:

@verbatim

function prefix_doSomething {

    # Do something here...

}

@end verbatim