Blame Manuals/Filesystem/filesystem-html/filesystem_51.html

ee1f37
ee1f37
<html>
ee1f37
ee1f37
ee1f37
Permission is granted to copy, distribute and/or modify this document
ee1f37
under the terms of the GNU Free Documentation License, Version 1.2 or
ee1f37
any later version published by the Free Software Foundation; with no
ee1f37
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
ee1f37
copy of the license is included in the section entitled GNU Free
ee1f37
Documentation License.  
ee1f37
-->
ee1f37
ee1f37
ee1f37
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
ee1f37
            Karl Berry  <karl@freefriends.org>
ee1f37
            Olaf Bachmann <obachman@mathematik.uni-kl.de>
ee1f37
            and many others.
ee1f37
Maintained by: Many creative people <dev@texi2html.cvshome.org>
ee1f37
Send bugs and suggestions to <users@texi2html.cvshome.org>
ee1f37
ee1f37
-->
ee1f37
<head>
d05905
<title>CentOS Artwork Repository - Filesystem: 3.48 trunk/Scripts/Bash/Functions</title>
ee1f37
d05905
<meta name="description" content="CentOS Artwork Repository - Filesystem: 3.48 trunk/Scripts/Bash/Functions">
d05905
<meta name="keywords" content="CentOS Artwork Repository - Filesystem: 3.48 trunk/Scripts/Bash/Functions">
ee1f37
<meta name="resource-type" content="document">
ee1f37
<meta name="distribution" content="global">
ee1f37
<meta name="Generator" content="texi2html 1.76">
ee1f37
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
ee1f37
<style type="text/css">
ee1f37
ee1f37
@import "/home/centos/artwork/trunk/Identity/Models/Css/Texi2html/common.css";
ee1f37
ee1f37
a.summary-letter {text-decoration: none}
ee1f37
pre.display {font-family: serif}
ee1f37
pre.format {font-family: serif}
ee1f37
pre.menu-comment {font-family: serif}
ee1f37
pre.menu-preformatted {font-family: serif}
ee1f37
pre.smalldisplay {font-family: serif; font-size: smaller}
ee1f37
pre.smallexample {font-size: smaller}
ee1f37
pre.smallformat {font-family: serif; font-size: smaller}
ee1f37
pre.smalllisp {font-size: smaller}
ee1f37
span.sansserif {font-family:sans-serif; font-weight:normal;}
ee1f37
ul.toc {list-style: none}
ee1f37
-->
ee1f37
</style>
ee1f37
ee1f37
ee1f37
</head>
ee1f37
ee1f37
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
ee1f37
ee1f37
db14a4
[ < ]
ee1f37
[ > ]
ee1f37
   
db14a4
[ << ]
db14a4
[ Up ]
db14a4
[ >> ]
ee1f37
   
ee1f37
   
ee1f37
   
ee1f37
   
db14a4
[Top]
db14a4
[Contents]
db14a4
[Index]
db14a4
[ ? ]
ee1f37
ee1f37
ee1f37
ee1f37

3.48 trunk/Scripts/Bash/Functions

ee1f37
ee1f37
ee1f37
ee1f37

3.48.1 Goals

ee1f37
ee1f37

The <tt>`trunk/Scripts/Bash/Functions'</tt> directory exists to organize

ee1f37
<tt>`centos-art.sh'</tt> specific functionalities.
ee1f37

ee1f37
ee1f37
ee1f37

3.48.2 Description

ee1f37
ee1f37

The specific functions of <tt>`centos-art.sh'</tt> script are designed

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

ee1f37

The specific functions of <tt>`centos-art.sh'</tt> script are organized

ee1f37
inside specific directories under <tt>`trunk/Scripts/Bash/Functions'</tt>
ee1f37
location. Each specific function directory should be named as the
ee1f37
function it represents, with the first letter in uppercase. For
ee1f37
example, if the function name is render, the specific function
ee1f37
directory for it would be <samp>`trunk/Scripts/Bash/Functions/Render'</samp>.
ee1f37

ee1f37

To better understand how specific functions of <tt>`centos-art.sh'</tt>

ee1f37
script are designed, lets create one function which only goal is to
ee1f37
output different kind of greetings to your screen.
ee1f37

ee1f37

When we create specific functions for <tt>`centos-art.sh'</tt> script it

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

ee1f37
Info

Tip

Join CentOS developers mailing list

ee1f37
centos-art@centos.org to share your ideas.
ee1f37

ee1f37
ee1f37

It is also worth to know what global functions and variables do we

ee1f37
have available inside <tt>`centos-art.sh'</tt> script, so advantage can be
ee1f37
taken from them. Global variables are defined inside global function
ee1f37
scripts. Global functions scripts are stored immediatly under
ee1f37
<tt>`trunk/Scripts/Bash/Functions'</tt> directory, in files begining with
ee1f37
<samp>`cli'</samp> prefix.
ee1f37

ee1f37

OK, let's begin with our functionality example.

ee1f37

ee1f37

What function name do we use? Well, lets use greet. Note that

ee1f37
<samp>`hello'</samp> word is not a verb; but an expression, a kind of
ee1f37
greeting, an interjection specifically. In contrast, <samp>`greet'</samp> is a
ee1f37
verb and describes what we do when we say <samp>`Hello!'</samp>, <samp>`Hi!'</samp>,
ee1f37
and similar expressions.
ee1f37

ee1f37

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

ee1f37

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

The <tt>`greet.sh'</tt> function script is the first file

ee1f37
<tt>`centos-art.sh'</tt> script loads when the <samp>`greet'</samp> functionality
ee1f37
is called using commands like <samp>`centos-art greet --hello='World''</samp>.
ee1f37
The <tt>`greet.sh'</tt> function script contains the greet function
ee1f37
definition. 
ee1f37

ee1f37

Inside <tt>`centos-art.sh'</tt> script, as convenction, each function

ee1f37
script has one top commentary, followed by one blank line, and then
ee1f37
one function defintion below it only.
ee1f37

ee1f37

Inside <tt>`centos-art.sh'</tt> script functions, top commentaries have

ee1f37
the following components: the functionality description, one-line for
ee1f37
copyright note with your personal information,  the license under
ee1f37
which the function source code is released --the <tt>`centos-art.sh'</tt>
ee1f37
script is released as GPL, so do all its functions--, the $Id$
ee1f37
keyword of Subversion is later expanded by svn propset
ee1f37
command.
ee1f37

ee1f37

In our greet function example, top commentary for

ee1f37
<tt>`greet.sh'</tt> function script would look like the following:
ee1f37

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

After top commentary, separated by one blank line, the greet

ee1f37
function definition would look like the following:
ee1f37

ee1f37
function greet {
ee1f37
ee1f37
    # Define global variables.
ee1f37
ee1f37
    # Define command-line interface.
ee1f37
    greet_getActions
ee1f37
ee1f37
}
ee1f37
ee1f37

The first definition inside greet function, are global

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

ee1f37

Later, we call greet_getActions function to define the

ee1f37
command-line interface of greet functionality. The command-line
ee1f37
interface of greet functionality defines what and how actions
ee1f37
are performed, based on arguments combination passed to
ee1f37
<tt>`centos-art.sh'</tt> script.
ee1f37

ee1f37
function greet_getActions {
ee1f37
ee1f37
    case "$ACTIONNAM" in
ee1f37
ee1f37
        --hello )
ee1f37
            greet_doHello
ee1f37
            ;;
ee1f37
ee1f37
        --bye )
ee1f37
            greet_doBye
ee1f37
            ;;
ee1f37
ee1f37
        * )
ee1f37
            cli_printMessage "`gettext "The option provided is not valid."`"
ee1f37
            cli_printMessage "$(caller)" 'AsToKnowMoreLine'
ee1f37
ee1f37
    esac
ee1f37
ee1f37
}
ee1f37
ee1f37

The ACTIONNAM global variable is defined in <tt>`cli.sh'</tt>

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

ee1f37

The greet function definition makes available two valid

ee1f37
greetings through <samp>`--hello'</samp> and <samp>`--bye'</samp> options.  If no
ee1f37
one of them is provided as second command-line argument, the <samp>`*'</samp>
ee1f37
case is evaluated instead. 
ee1f37

ee1f37

The <samp>`*'</samp> case and its two lines further on should always be

ee1f37
present in <tt>`_getActions.sh'</tt> function scripts, no matter what
ee1f37
specific functionality you are creating. This convenction helps the
ee1f37
user to find out documentation about current functionality in use,
ee1f37
when no valid action is provided.
ee1f37

ee1f37

The greet_doHello and greet_doBye function definitions

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

ee1f37
function greet_doHello {
ee1f37
ee1f37
    cli_printMessage "`gettext "Hello"` $ACTIONVAL"
ee1f37
ee1f37
}
ee1f37
ee1f37

The greet_doHello function definition is stored in

ee1f37
<tt>`greet_doHello.sh'</tt> function script. 
ee1f37

ee1f37
function greet_doBye {
ee1f37
ee1f37
    cli_printMessage "`gettext "Goodbye"` $ACTIONVAL"
ee1f37
ee1f37
}
ee1f37
ee1f37

The greet_doBye function definition is stored in the

ee1f37
<tt>`greet_doBye.sh'</tt> function script. 
ee1f37

ee1f37

Both <tt>`greet_doHello.sh'</tt> and <tt>`greet_doBye.sh'</tt> function

ee1f37
scripts are stored inside greet function directory path (i.e.
ee1f37
<tt>`trunk/Scripts/Bash/Functions/Greet'</tt>).
ee1f37

ee1f37

The ACTIONVAL global variable is defined in <tt>`cli.sh'</tt>

ee1f37
function script and contains the value passed after the equal sign
ee1f37
(i.e., <samp>`='</samp>) in the second command-line argument of
ee1f37
<tt>`centos-art.sh'</tt> script. For example, if the second command-line
ee1f37
argument is <samp>`--hello='World''</samp>, the value of ACTIONVAL
ee1f37
variable would be <samp>`World'</samp> without quotes.
ee1f37

ee1f37

Let's see how greet specific functionality files are organzied

ee1f37
under greet function directory. To see file organization we use
ee1f37
the tree command:
ee1f37

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

To try the greet specific functionality we've just created,

ee1f37
pass the function name (i.e., <samp>`greet'</samp>) as first argument to
ee1f37
<tt>`centos-art.sh'</tt> script, and any of the valid options as second
ee1f37
argument. Some examples are illustrated below:
ee1f37

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

The word <samp>`World'</samp> in the examples above can be anything. In fact,

ee1f37
change it to have a little fun.
ee1f37

ee1f37

Now that we have a specific function that works as we expect, it is

ee1f37
time to document it.  To document greet specific functionality,
ee1f37
we use its directory path and the manual functionality
db14a4
(see section trunk/Scripts/Bash/Functions/Manual) of <tt>`centos-art.sh'</tt>
ee1f37
script, just as the following command illustrates: 
ee1f37

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

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

ee1f37
function really works, and how it should be used.  When no valid
ee1f37
action is passed to a function, the <tt>`centos-art.sh'</tt> script uses
ee1f37
the function documentation entry as vehicle to communicate which the
ee1f37
valid functions are. When no documentation entry exists for a
ee1f37
function, the <tt>`centos-art.sh'</tt> script informs that no
ee1f37
documentation entry exists for such function and requests user to
ee1f37
create it right at that time.
ee1f37

ee1f37

Now that we have documented our function, it is time to translate its

ee1f37
output messages to different languages. To translate specific
ee1f37
functionality output messages to different languages we use the
db14a4
locale functionality (see section trunk/Scripts/Bash/Functions/Locale) of <tt>`centos-art.sh'</tt> script, just as the following command
ee1f37
illustrates:
ee1f37

ee1f37
centos-art locale --edit
ee1f37
ee1f37
Warning

Warning

To translate output messages in different languages,

ee1f37
your system locale information --as in LANG environment
ee1f37
variable-- must be set to that locale you want to produce translated
ee1f37
messages for. For example, if you want to produce translated messages
ee1f37
for Spanish language, your system locale information must be set to
ee1f37
<samp>`es_ES.UTF-8'</samp>, or similar, first.
ee1f37

ee1f37
ee1f37

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

ee1f37

ee1f37

In greet function example we've described so far, we only use

ee1f37
cli_printMessage global function in action specific function
ee1f37
definitions in order to print messages, but more interesting things
ee1f37
can be achieved inside action specific function definitions.  For
ee1f37
example, if you pass a directory path as action value in second
ee1f37
argument, you could retrive a list of files from therein, and process
ee1f37
them. If the list of files turns too long or you just want to control
ee1f37
which files to process, you could add the third argument in the form
ee1f37
<samp>`--filter='regex''</samp> and reduce the amount of files to process
ee1f37
using a regular expression pattern.
ee1f37

ee1f37

The greet function described in this section may serve you as

ee1f37
an introduction to understand how specific functionalities work inside
ee1f37
<tt>`centos-art.sh'</tt> script. With some of luck this introduction will
ee1f37
also serve you as motivation to create your own <tt>`centos-art.sh'</tt>
ee1f37
script specific functionalities.
ee1f37

ee1f37

By the way, the greet functionality doesn't exist inside

ee1f37
<tt>`centos-art.sh'</tt> script yet. Would you like to create it?
ee1f37

ee1f37
ee1f37
ee1f37

3.48.3 Usage

ee1f37
ee1f37
ee1f37
ee1f37

3.48.3.1 Global variables

ee1f37
ee1f37

The following global variables of <tt>`centos-art.sh'</tt> script, are

ee1f37
available for you to use inside specific functions:
ee1f37

ee1f37
ee1f37
<u>Variable:</u> TEXTDOMAIN
ee1f37
ee1f37
ee1f37

Default domain used to retrieve translated messages. This value is set

ee1f37
in <tt>`initFunctions.sh'</tt> and shouldn't be changed.
ee1f37

ee1f37
ee1f37
ee1f37
<u>Variable:</u> TEXTDOMAINDIR
ee1f37
ee1f37
ee1f37

Default directory used to retrieve translated messages. This value is

ee1f37
set in <tt>`initFunctions.sh'</tt> and shouldn't be changed.
ee1f37

ee1f37
ee1f37
ee1f37
<u>Variable:</u> FUNCNAM
ee1f37
ee1f37
ee1f37

Define function name.

ee1f37

ee1f37

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

ee1f37
for each unique function name inside <tt>`centos-art.sh'</tt> script.
ee1f37

ee1f37

Dunction names are passed as first argument in <tt>`centos-art.sh'</tt>

ee1f37
command-line interface. For example, in the command <samp>`centos-art
ee1f37
render --entry=path/to/dir --filter=regex'</samp>, the ACTION passed to
ee1f37
<tt>`centos-art.sh'</tt> script is <samp>`render'</samp>.
ee1f37

ee1f37

When first argument is not provided, the <tt>`centos-art.sh'</tt> script

ee1f37
immediatly ends its execution.
ee1f37

ee1f37
ee1f37
ee1f37
<u>Variable:</u> FUNCDIR
ee1f37
ee1f37
ee1f37
ee1f37
ee1f37
ee1f37
<u>Variable:</u> FUNCDIRNAME
ee1f37
ee1f37
ee1f37
ee1f37
ee1f37
ee1f37
<u>Variable:</u> FUNCSCRIPT
ee1f37
ee1f37
ee1f37
ee1f37
ee1f37
ee1f37
<u>Variable:</u> FUNCCONFIG
ee1f37
ee1f37
ee1f37
ee1f37
ee1f37
ee1f37
<u>Variable:</u> ACTIONNAM
ee1f37
ee1f37
ee1f37

Define action name.

ee1f37

ee1f37

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

ee1f37
specific function.
ee1f37

ee1f37

Action name names aare passed as second argument in

ee1f37
<tt>`centos-art.sh'</tt> command-line interface. For example, in the
ee1f37
command <samp>`centos-art render --entry=path/to/dir --filter=regex'</samp>,
ee1f37
the ACTIONNAM passed to <tt>`centos-art.sh'</tt> script is
ee1f37
<samp>`--entry'</samp>.
ee1f37

ee1f37

When second argument is not provided, the <tt>`centos-art.sh'</tt> script

ee1f37
immediatly ends its execution.
ee1f37

ee1f37
ee1f37
ee1f37
<u>Variable:</u> ACTIONVAL
ee1f37
ee1f37
ee1f37

Define action value.

ee1f37

ee1f37

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

ee1f37
contain the working copy entry over which its associated action will be
ee1f37
performed in.  Working copy entries can be files or directories inside
ee1f37
the working copy.
ee1f37

ee1f37
ee1f37
ee1f37
<u>Variable:</u> REGEX
ee1f37
ee1f37
ee1f37

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

ee1f37
to process.
ee1f37

ee1f37

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

ee1f37
files.
ee1f37

ee1f37

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

ee1f37
<samp>`--filter'</samp> to redefine REGEX variable default value, and
ee1f37
so, control the amount of files to process.
ee1f37

ee1f37
ee1f37
ee1f37
<u>Variable:</u> ARGUMENTS
ee1f37
ee1f37
ee1f37

Define optional arguments.

ee1f37

ee1f37

Optional arguments, inside <tt>`centos-art.sh'</tt> script, are considered

ee1f37
as all command-line arguments passed to <tt>`centos-art.sh'</tt> script,
ee1f37
from third argument position on. For example, in the command
ee1f37
<samp>`centos-art render --entry=path/to/dir --filter=regex'</samp> , the
ee1f37
optional arguments are from <samp>`--filter=regex'</samp> argument on.
ee1f37

ee1f37

Optional arguments are parsed using getopt command through

ee1f37
the following base construction: 
ee1f37

ee1f37
# Define short options we want to support.
ee1f37
local ARGSS=""
ee1f37
ee1f37
# Define long options we want to support.
ee1f37
local ARGSL="filter:,to:"
ee1f37
ee1f37
# Parse arguments using getopt(1) command parser.
ee1f37
cli_doParseArguments
ee1f37
ee1f37
# Reset positional parameters using output from (getopt) argument
ee1f37
# parser.
ee1f37
eval set -- "$ARGUMENTS"
ee1f37
ee1f37
# Define action to take for each option passed.
ee1f37
while true; do
ee1f37
    case "$1" in
ee1f37
        --filter )
ee1f37
            REGEX="$2" 
ee1f37
            shift 2
ee1f37
            ;;
ee1f37
        --to )
ee1f37
            TARGET="$2" 
ee1f37
            shift 2
ee1f37
            ;;
ee1f37
        * )
ee1f37
            break
ee1f37
    esac
ee1f37
done
ee1f37
ee1f37

Optional arguments provide support to command options inside

ee1f37
<tt>`centos-art.sh'</tt> script. For instance, consider the Subversion
ee1f37
(svn) command, where there are many options (e.g.,
ee1f37
<samp>`copy'</samp>, <samp>`delete'</samp>, <samp>`move'</samp>, etc), and inside each
ee1f37
option there are several modifiers (e.g., <samp>`--revision'</samp>,
ee1f37
<samp>`--message'</samp>, <samp>`--username'</samp>, etc.) that can be combined one
ee1f37
another in their short or long variants. 
ee1f37

ee1f37

The ARGUMENTS variable is used to store arguments passed from

ee1f37
command-line for later use inside <tt>`centos-art.sh'</tt> script. Storing
ee1f37
arguments is specially useful when we want to run a command with some
ee1f37
specific options from them. Consider the following command:
ee1f37

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

In the above command, the <samp>`--message'</samp>, and <samp>`--username'</samp>

ee1f37
options are specific to svn copy command. In such cases,
ee1f37
options are not interpreted by <tt>`centos-art.sh'</tt> script itself.
ee1f37
Instead, the <tt>`centos-art.sh'</tt> script uses getopt to
ee1f37
retrive them and store them in the ARGUMENTS variable for later
ee1f37
use, as described in the following command:
ee1f37

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

When getopt parses ARGUMENTS, we may use short options

ee1f37
(e.g., <samp>`-m'</samp>) or long options (e.g., <samp>`--message'</samp>). When
ee1f37
we use short options, arguments are separated by one space from the
ee1f37
option (e.g., <samp>`-m 'This is a commit message.''</samp>).  When we use
ee1f37
long options arguments are separated by an equal sign (<samp>`='</samp>)
ee1f37
(e.g., <samp>`--message='This is a commit message''</samp>).
ee1f37

ee1f37

In order for getopt to parse ARGUMENTS correctly, it

ee1f37
is required to provide the short and long definition of options that
ee1f37
will be passed or at least supported by the command performing the
ee1f37
final action the function script exists for.
ee1f37

ee1f37

As convenction, inside <tt>`centos-art.sh'</tt> script, short option

ee1f37
definitions are set in the ARGSS variable; and long option
ee1f37
definitions are set in the ARGSL variable.
ee1f37

ee1f37

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

ee1f37
which of these option arguments are required and which not. To define
ee1f37
an option argument as required, you need to set one colon <samp>`:'</samp>
ee1f37
after the option definition (e.g., <samp>`-o m: -l message:'</samp>).  On
ee1f37
the other hand, to define an option argument as not required, you need
ee1f37
to set two colons <samp>`::'</samp> after the option definition (e.g.,
ee1f37
<samp>`-o m:: -l message::'</samp>).
ee1f37

ee1f37
ee1f37
ee1f37
<u>Variable:</u> EDITOR
ee1f37
ee1f37
ee1f37

Default text editor.

ee1f37

ee1f37

The <tt>`centos-art.sh'</tt> script uses default text EDITOR to edit

ee1f37
pre-commit subversion messages, translation files, configuration
ee1f37
files, script files, and similar text-based files.
ee1f37

ee1f37

If EDITOR environment variable is not set, <tt>`centos-art.sh'</tt>

ee1f37
script uses <tt>`/usr/bin/vim'</tt> as default text editor. Otherwise, the
ee1f37
following values are recognized by <tt>`centos-art.sh'</tt> script:
ee1f37

ee1f37
    ee1f37
  • <tt>`/usr/bin/vim'</tt>
  • ee1f37
  • <tt>`/usr/bin/emacs'</tt>
  • ee1f37
  • <tt>`/usr/bin/nano'</tt>
  • ee1f37
    ee1f37
    ee1f37

    If no one of these values is set in EDITOR environment variable,

    ee1f37
    <tt>`centos-art.sh'</tt> uses <tt>`/usr/bin/vim'</tt> text editor by default. 
    ee1f37

    ee1f37
    ee1f37
    ee1f37
    ee1f37

    3.48.3.2 Global functions

    ee1f37
    ee1f37

    Function scripts stored directly under

    ee1f37
    <tt>`trunk/Scripts/Bash/Functions/'</tt> directory are used to define
    ee1f37
    global functions.  Global functions can be used inside action specific
    ee1f37
    functionalities and or even be reused inside themselves. This section
    ee1f37
    provides introductory information to global functions you can use
    ee1f37
    inside <tt>`centos-art.sh'</tt> script.
    ee1f37

    ee1f37
    ee1f37
    <u>Function:</u> cli_checkActionArguments
    ee1f37
    ee1f37
    ee1f37

    Validate action value (ACTIONVAL) variable.

    ee1f37

    ee1f37

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

    ee1f37

    ee1f37
      ee1f37
    1. Path to one directory inside the local working copy,
    2. ee1f37
    3. Path to one file inside the local working copy,
    4. ee1f37
      ee1f37
      ee1f37

      If another value different from that specified above is passed to

      ee1f37
      action value variable, the <tt>`centos-art.sh'</tt> script prints an error
      ee1f37
      message and ends script execution.
      ee1f37

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_checkFiles FILE [TYPE]
      ee1f37
      ee1f37
      ee1f37

      Verify file existence.

      ee1f37

      ee1f37

      cli_checkFiles receives a FILE absolute path and performs

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

      ee1f37
      ee1f37
      <samp>`d'</samp>
      ee1f37
      <samp>`directory'</samp>
      ee1f37

      Ends script execution if FILE is not a directory.

      ee1f37

      ee1f37

      When you verify directories with cli_checkFiles, if directory doesn't

      ee1f37
      exist, <tt>`centos-art.sh'</tt> script asks you for confirmation in order
      ee1f37
      to create that directory. If you answer positively,
      ee1f37
      <tt>`centos-art.sh'</tt> script creates that directory and continues
      ee1f37
      script flows normally. Otherwise, if you answer negatively,
      ee1f37
      <tt>`centos-art.sh'</tt> ends script execution with an error and
      ee1f37
      documentation message.
      ee1f37

      ee1f37
      ee1f37
      <samp>`f'</samp>
      ee1f37
      <samp>`regular-file'</samp>
      ee1f37

      Ends script execution if FILE is not a regular file.

      ee1f37

      ee1f37
      <samp>`h'</samp>
      ee1f37
      <samp>`symbolic-link'</samp>
      ee1f37

      Ends script execution if FILE is not a symbolic link.

      ee1f37

      ee1f37
      <samp>`x'</samp>
      ee1f37
      <samp>`execution'</samp>
      ee1f37

      Ends script execution if FILE is not executable.

      ee1f37

      ee1f37
      <samp>`fh'</samp>
      ee1f37

      Ends script execution if FILE is neither a regular file nor a

      ee1f37
      symbolic link.
      ee1f37

      ee1f37
      <samp>`fd'</samp>
      ee1f37

      Ends script execution if FILE is neither a regular file nor a

      ee1f37
      directory.
      ee1f37

      ee1f37
      <samp>`isInWorkingCopy'</samp>
      ee1f37

      Ends script execution if FILE is not inside the working copy.

      ee1f37

      ee1f37
      ee1f37
      ee1f37

      As default behaviour, if FILE passes all verifications,

      ee1f37
      <tt>`centos-art.sh'</tt> script continues with its normal flow. 
      ee1f37

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_commitRepoChanges [LOCATION]
      ee1f37
      ee1f37
      ee1f37

      Syncronize changes between repository and working copy.

      ee1f37

      ee1f37

      The cli_commitRepoChanges function brings changes from the

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

      ee1f37

      Previous to commit the working copy changes up to the central

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

      ee1f37

      If LOCATION argument is not specified, the value of

      ee1f37
      ACTIONVAL variable is used as reference instead.
      ee1f37

      ee1f37
      ee1f37
      ----------------------------------------------------------------------
      ee1f37
      --> Bringing changes from the repository into the working copy
      ee1f37
      --> Checking changes in the working copy
      ee1f37
      ----------------------------------------------------------------------
      ee1f37
      Added           0 file from the repository.
      ee1f37
      Deleted         0 file from the repository.
      ee1f37
      Updated         0 file from the repository.
      ee1f37
      Conflicted      0 file from the repository.
      ee1f37
      Merged          0 file from the repository.
      ee1f37
      Modified        4 files from the working copy.
      ee1f37
      Unversioned     0 file from the working copy.
      ee1f37
      Deleted         0 file from the working copy.
      ee1f37
      Added           0 file from the working copy.
      ee1f37
      ----------------------------------------------------------------------
      ee1f37
      ee1f37

      Figure 3.3: The cli_commitRepoChanges function output.

      ee1f37
      ee1f37

      ee1f37

      Call the cli_commitRepoChanges function before or/and after

      ee1f37
      calling functions that modify files or directories inside the working
      ee1f37
      copy as you may need to.  
      ee1f37

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_doParseArguments
      ee1f37
      ee1f37
      ee1f37

      Redefine arguments (ARGUMENTS) global variable using

      ee1f37
      getopt command output. For more information about how to use
      ee1f37
      cli_doParseArguments function, see ARGUMENTS variable
      ee1f37
      description above.
      ee1f37

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_doParseArgumentsReDef $@
      ee1f37
      ee1f37
      ee1f37

      Initialize/reset arguments (ARGUMENTS) global variable using

      ee1f37
      positional parameters variable ($@) as reference.
      ee1f37

      ee1f37

      When we work inside function definitions, positional parameters are

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

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_getArguments
      ee1f37
      ee1f37
      ee1f37

      Initialize function name (FUNCNAM), action name

      ee1f37
      (ACTIONNAM), and action value (ACTIONVAL) global
      ee1f37
      variables, using positional parameters passed in $@ variable.
      ee1f37

      ee1f37

      The cli_getArguments function is called from cli.sh

      ee1f37
      function script, using cli function positional parameters
      ee1f37
      (i.e., the positional parameters passed as arguments in the
      ee1f37
      command-line) as first function argument. 
      ee1f37

      ee1f37

      Once command-line positional parameters are accesible to

      ee1f37
      <tt>`centos-art.sh'</tt> script execution evironment,
      ee1f37
      cli_getArguments uses regular expression to retrive
      ee1f37
      action variables from first and second argument. The first argument
      ee1f37
      defines the value used as function name (FUNCNAM), and the
      ee1f37
      second argument defines both values used as action name
      ee1f37
      (ACTIONNAM) and action value (ACTIONVAL), respectively.
      ee1f37

      ee1f37

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

      ee1f37
      name of the functionality you want to use (e.g., <samp>`render'</samp> to
      ee1f37
      render images, <samp>`manual'</samp> to work on documentation, and so on.)
      ee1f37

      ee1f37

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

      ee1f37
      <samp>`--option=value'</samp>). The <samp>`--option'</samp> represents the action name
      ee1f37
      (ACTIONNAM), and the characters inbetween the equal sign
      ee1f37
      (<samp>`='</samp>) and the first space character, are considered as the action
      ee1f37
      value (ACTIONVAL). In order to provide action values with space
      ee1f37
      characters inbetween you need to enclose action value with quotes like
      ee1f37
      in <samp>`--option='This is long value with spaces inbetween''</samp>.
      ee1f37
      Generally, action values are used to specify paths over which the
      ee1f37
      action name acts on.
      ee1f37

      ee1f37

      Once action related variables (i.e., FUNCNAM, ACTIONNAM,

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

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_getFunctions
      ee1f37
      ee1f37
      ee1f37

      Initialize funtionalities supported by <tt>`centos-art.sh'</tt> script.

      ee1f37

      ee1f37

      Functionalities supported by <tt>`centos-art.sh'</tt> script are organized

      ee1f37
      in functionality directories under
      ee1f37
      <tt>`trunk/Scripts/Bash/Functions/'</tt> directory. Each functionality
      ee1f37
      directory stores function scripts to the functionality such directory
      ee1f37
      was created for. Function scripts contain function definitions.
      ee1f37
      Function definitions contain several commands focused on achieving one
      ee1f37
      specific task only (i.e., the one such functionality was created for).
      ee1f37

      ee1f37

      In order for <tt>`centos-art.sh'</tt> script to recognize a functionality,

      ee1f37
      such functionality needs to be stored under
      ee1f37
      <tt>`trunk/Scripts/Bash/Functions/'</tt> in a directory written
      ee1f37
      capitalized (i.e., the whole name is written in lowercase except the
      ee1f37
      first character which is in uppercase). The directory where one
      ee1f37
      specific functionality is stored is known as the <samp>`functionality
      ee1f37
      directory'</samp>. 
      ee1f37

      ee1f37

      Inside each functionality directory, the functionalty itself is

      ee1f37
      implemented through function scripts. Function scripts are organized
      ee1f37
      in files independently one another and written in <samp>`camelCase'</samp>
      ee1f37
      format with the function name as prefix.  Separation between prefix
      ee1f37
      and description is done using underscore (<samp>`_'</samp>) character.
      ee1f37

      ee1f37

      In order for <tt>`centos-art.sh'</tt> script to load functionalities

      ee1f37
      correctly, function definition inside function scripts should be set
      ee1f37
      using the <samp>`function'</samp> reserved word, just as in the following
      ee1f37
      example:
      ee1f37

      ee1f37
      function prefix_doSomething {
      ee1f37
      ee1f37
          # Do something here...
      ee1f37
      ee1f37
      }
      ee1f37
      ee1f37

      The above function definition is just a convenction we use, in order

      ee1f37
      to make identification of function names easier read and automate by
      ee1f37
      <tt>`centos-art.sh'</tt> script initialization commands, once
      ee1f37
      <tt>`centos-art.sh'</tt> script determines which functionality directory
      ee1f37
      to use.  Specifically, in order to initialize and export functions,
      ee1f37
      <tt>`centos-art.sh'</tt> script executes all function scripts inside the
      ee1f37
      functionality directory, and later grep on them using a
      ee1f37
      regular expression pattern, where the <samp>`function'</samp> reserved word is
      ee1f37
      used as reference to retrive the function names and export them to
      ee1f37
      <tt>`centos-art.sh'</tt> script execution environment, and so, make
      ee1f37
      function definitions --from function scripts inside the functionality
      ee1f37
      directory-- available for further calls.
      ee1f37

      ee1f37

      If the functionality specified in the command-line first argument

      ee1f37
      doesn't have a functionality directory, <tt>`centos-art.sh'</tt> script
      ee1f37
      considers the functionality provided in the command-line as invalid
      ee1f37
      functionality and immediatly stops script execution with an error
      ee1f37
      message.
      ee1f37

      ee1f37

      In order to keep visual consistency among function scripts, please

      ee1f37
      consider using the following function script design model as template
      ee1f37
      for your own function scripts:
      ee1f37

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

      Output country codes supported by <tt>`centos-art.sh'</tt> script.

      ee1f37

      ee1f37

      The cli_getCountryCodes function outputs a list with country

      ee1f37
      codes as defined in ISO3166 standard. When FILTER is provided,
      ee1f37
      cli_getCountryCodes outputs country codes that match
      ee1f37
      FILTER regular expression pattern.
      ee1f37

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_getCountryName [FILTER]
      ee1f37
      ee1f37
      ee1f37

      Outputs country name supported by <tt>`centos-art.sh'</tt> script.

      ee1f37

      ee1f37

      The cli_getCountryName function reads one language locale code

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

      ee1f37
       
      ee1f37
      ee1f37
      <u>Function:</u> cli_getCurrentLocale
      ee1f37
      ee1f37
      ee1f37

      Output current locale used by <tt>`centos-art.sh'</tt> script.

      ee1f37

      ee1f37

      The cli_getCurrentLocale function uses LANG environment

      ee1f37
      variable to build a locale pattern that is later applied to
      ee1f37
      cli_getLocales function output in order to return the current
      ee1f37
      locale that <tt>`centos-art.sh'</tt> script works with. 
      ee1f37

      ee1f37

      The current locale information, returned by

      ee1f37
      cli_getCurrentLocale, is output from more specific to less
      ee1f37
      specific. For example, if <samp>`en_GB'</samp> locale exists in
      ee1f37
      cli_getLocales function output, the <samp>`en_GB'</samp> locale would
      ee1f37
      take precedence before <samp>`en'</samp> locale.
      ee1f37

      ee1f37

      Locale precedence selection is quite important in order to define the

      ee1f37
      locale type we use for message translations. For example, if
      ee1f37
      <samp>`en_GB'</samp> is used, we are also saying that the common language
      ee1f37
      specification for English language (i.e., <samp>`en'</samp>) is no longer
      ee1f37
      used. Instead, we are using English non-common country-specific
      ee1f37
      language specifications like <samp>`en_AU'</samp>, <samp>`en_BW'</samp>, <samp>`en_GB'</samp>,
      ee1f37
      <samp>`en_US'</samp>, etc., for message translations.  
      ee1f37

      ee1f37

      Use cli_getCurrentLocale function to know what current locale

      ee1f37
      information to use inside <tt>`centos-art.sh'</tt> script.
      ee1f37

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_getFilesList [LOCATION]
      ee1f37
      ee1f37
      ee1f37

      Output list of files to process.

      ee1f37

      ee1f37

      The cli_getFilesList function uses LOCATION variable as

      ee1f37
      source location to build a list of files just as specified by regular
      ee1f37
      expression (REGEX) global variable. Essentially, what the
      ee1f37
      cli_getFilesList function does is using find command
      ee1f37
      to look for files in the location (LOCATION) just as posix-egrep
      ee1f37
      regular expression (REGEX) specifies. 
      ee1f37

      ee1f37

      If LOCATION is not specified when cli_getFilesList

      ee1f37
      function is called, the action value (ACTIONVAL) global variable
      ee1f37
      is used as location value instead.
      ee1f37

      ee1f37

      By default, if the regular expression (REGEX) global variable is

      ee1f37
      not redefined after its first definition in the cli function,
      ee1f37
      all files that match default regular expression value (i.e.,
      ee1f37
      <samp>`.+'</samp>) will be added to the list of files to process. Otherwise,
      ee1f37
      if you redefine the regular expression global variable after its first
      ee1f37
      definition in the cli function and before calling
      ee1f37
      cli_getFilesList function, the last value you specifed is used
      ee1f37
      instead.
      ee1f37

      ee1f37

      When you need to customize the regular expression (REGEX) global

      ee1f37
      variable value inside a function, do not redefine the global variable
      ee1f37
      (at least you be absolutly convinced you need to).  Instead, set the
      ee1f37
      regular expression global variable as <samp>`local'</samp> to the function you
      ee1f37
      need a customized regular expression value for.  If we don't redefine
      ee1f37
      the regular expression global variable as local to the function, or
      ee1f37
      use another name for the regular expression variable (which is not
      ee1f37
      very convenient in order to keep the amount of names to remember low),
      ee1f37
      you may experiment undesired concantenation issues that make your
      ee1f37
      regular expression to be something different from that you expect them
      ee1f37
      to be, specially if the function where you are doing the variable
      ee1f37
      redefinition is called several times during the same script execution.
      ee1f37

      ee1f37

      As result, the cli_getFilesList re-defines the value of

      ee1f37
      FILES variable with the list of files the find command
      ee1f37
      returned. As example, consider the following construction:
      ee1f37

      ee1f37
      function prefix_doSomething {
      ee1f37
      ee1f37
          # Initialize the list of files to process.
      ee1f37
          local FILES=''
      ee1f37
      ee1f37
          # Initialize location.
      ee1f37
          local LOCATION=/home/centos/artwork/trunk/Identity/Themes/Models/Default
      ee1f37
      ee1f37
          # Re-define regular expression to match scalable vector graphic
      ee1f37
          # files only. Note how we use the global value of REGEX to build a
      ee1f37
          # new local REGEX value here.
      ee1f37
          local REGEX="${REGEX}.*\.(svgz|svg)"
      ee1f37
      ee1f37
          # Redefine list of files to process.
      ee1f37
          cli_getFilesList $LOCATION
      ee1f37
      ee1f37
          # Process list of files.
      ee1f37
          for FILE in $FILES;do
      ee1f37
              cli_printMessages "$FILE" 'AsResponseLine'
      ee1f37
              # Do something else here on...
      ee1f37
          done
      ee1f37
      ee1f37
      }
      ee1f37
      ee1f37
      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_getLangCodes [FILTER]
      ee1f37
      ee1f37
      ee1f37

      Outputs language codes supported by <tt>`centos-art.sh'</tt> script.

      ee1f37

      ee1f37

      cli_getLangCodes function outputs a list of language codes as

      ee1f37
      defined in ISO639 standard. When FILTER is provided,
      ee1f37
      cli_getLangCodes outputs language codes that match FILTER
      ee1f37
      regular expression pattern.
      ee1f37

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_getLangName [FILTER]
      ee1f37
      ee1f37
      ee1f37

      Outputs language names supported by <tt>`centos-art.sh'</tt> script.

      ee1f37

      ee1f37

      cli_getLangName function reads one language locale code in the

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

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_getLocales
      ee1f37
      ee1f37
      ee1f37

      Output locale codes supported by <tt>`centos-art.sh'</tt> script.

      ee1f37

      ee1f37

      Occasionally, you use cli_getLocales function to add locale

      ee1f37
      information in non-common country-specific language (<samp>`LL_CC'</samp>)
      ee1f37
      format for those languages (e.g., <samp>`bn_IN'</samp>, <samp>`pt_BR'</samp>, etc.)
      ee1f37
      which locale differences cannot be solved using common language
      ee1f37
      specifications (<samp>`LL'</samp>) into one unique common locale specification
      ee1f37
      (e.g., <samp>`bn'</samp>, <samp>`pt'</samp>, etc.).  
      ee1f37

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_getRepoName NAME TYPE
      ee1f37
      ee1f37
      ee1f37

      Sanitate file names.

      ee1f37

      ee1f37

      Inside <tt>`centos-art.sh'</tt> script, specific functionalities rely both

      ee1f37
      in cli_getRepoName and repository file system organization to
      ee1f37
      achieve their goals.  Consider cli_getRepoName function as
      ee1f37
      central place to manage file name convenctions for other functions
      ee1f37
      inside <tt>`centos-art.sh'</tt> script.
      ee1f37

      ee1f37
      Important

      Important

      cli_getRepoName function doesn't verify file

      ee1f37
      or directory existence, for that purpose use cli_checkFiles
      ee1f37
      function instead.
      ee1f37

      ee1f37
      ee1f37

      The NAME variable contains the file name or directory name you

      ee1f37
      want to sanitate.
      ee1f37

      ee1f37

      The TYPE variable specifies what type of sanitation you want to

      ee1f37
      perform on NAME. The TYPE can be one of the following
      ee1f37
      values:
      ee1f37

      ee1f37
      ee1f37
      <samp>`d'</samp>
      ee1f37
      <samp>`directory'</samp>
      ee1f37

      Sanitate directory NAMEs.

      ee1f37

      ee1f37
      <samp>`f'</samp>
      ee1f37
      <samp>`regular-file'</samp>
      ee1f37

      Sanitate regular file NAMEs.

      ee1f37

      ee1f37
      ee1f37
      ee1f37

      Use cli_getRepoName function to sanitate file names and

      ee1f37
      directory names before their utilization. 
      ee1f37

      ee1f37

      Use cli_getRepoName when you need to change file name

      ee1f37
      convenctions inside <tt>`centos-art.sh'</tt> script. 
      ee1f37

      ee1f37

      When we change file name convenctions inside cli_getRepoName

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

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_getRepoStatus [LOCATION]
      ee1f37
      ee1f37
      ee1f37

      Request repository status.

      ee1f37

      ee1f37

      This function requests the status of a LOCATION inside the

      ee1f37
      working copy using the svn status command and returns the
      ee1f37
      first character in the output line, just as described in svn
      ee1f37
      help status. If LOCATION is not a regular file or a directory,
      ee1f37
      inside the working copy, the <tt>`centos-art.sh'</tt> script prints a
      ee1f37
      message and ends its execution.
      ee1f37

      ee1f37

      Use this function to perform verifications based a repository

      ee1f37
      LOCATION status.
      ee1f37

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_getTemporalFile NAME
      ee1f37
      ee1f37
      ee1f37

      Output absolute path to temporal file NAME.

      ee1f37

      ee1f37

      The cli_getTemporalFile function uses <tt>`/tmp'</tt> directory as

      ee1f37
      source location to store temporal files, the <tt>`centos-art.sh'</tt>
      ee1f37
      script name, and a random identification string to let you run more
      ee1f37
      than one <tt>`centos-art.sh'</tt> script simultaneously on the same user
      ee1f37
      session.  For example, due the following temporal file defintion:
      ee1f37

      ee1f37
      cli_getTemporalFile $FILE
      ee1f37
      ee1f37

      If FILE name is <tt>`instance.svg'</tt> and the unique random string

      ee1f37
      is <samp>`f16f7b51-ac12-4b7f-9e66-72df847f12de'</samp>, the final temporal
      ee1f37
      file, built from previous temporal file definition, would be:
      ee1f37

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

      When you use the cli_getTemporalFile function to create

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

      ee1f37
      for FILE in $FILES;do
      ee1f37
      ee1f37
          # Initialize temporal instance of file.
      ee1f37
          INSTANCE=$(cli_getTemporalFile $FILE)
      ee1f37
      ee1f37
          # Do something ... 
      ee1f37
      ee1f37
          # Remove temporal instance of file.
      ee1f37
          if [[ -f $INSTANCE ]];then
      ee1f37
              rm $INSTANCE
      ee1f37
          fi
      ee1f37
      ee1f37
      done
      ee1f37
      ee1f37

      Use the cli_getTemporalFile function whenever you need to

      ee1f37
      create temporal files inside <tt>`centos-art.sh'</tt> script.
      ee1f37

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_getThemeName
      ee1f37
      ee1f37
      ee1f37

      Output theme name.

      ee1f37

      ee1f37

      In order for cli_getThemeName function to extract theme name

      ee1f37
      correctly, the ACTIONVAL variable must contain a directory path
      ee1f37
      under <tt>`trunk/Identity/Themes/Motifs/'</tt> directory structure.
      ee1f37
      Otherwise, cli_getThemeName returns an empty string.  
      ee1f37

      ee1f37
      ee1f37
      ee1f37
      <u>Function:</u> cli_printMessage MESSAGE [FORMAT]
      ee1f37
      ee1f37
      ee1f37

      Define standard output message definition supported by

      ee1f37
      <tt>`centos-art.sh'</tt> script.
      ee1f37

      ee1f37

      When FORMAT is not specified, cli_printMessage outputs

      ee1f37
      information just as it was passed in MESSAGE variable.
      ee1f37
      Otherwise, FORMAT can take one of the following values:
      ee1f37

      ee1f37
      ee1f37
      <samp>`AsHeadingLine'</samp>
      ee1f37

      To print heading messages.

      ee1f37

      ----------------------------------------------------------------------
      ee1f37
      $MESSAGE
      ee1f37
      ----------------------------------------------------------------------
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsWarningLine'</samp>
      ee1f37

      To print warning messages.

      ee1f37

      ----------------------------------------------------------------------
      ee1f37
      WARNING: $MESSAGE
      ee1f37
      ----------------------------------------------------------------------
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsNoteLine'</samp>
      ee1f37

      To print note messages.

      ee1f37

      ----------------------------------------------------------------------
      ee1f37
      NOTE: $MESSAGE
      ee1f37
      ----------------------------------------------------------------------
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsUpdatingLine'</samp>
      ee1f37

      To print <samp>`Updating'</samp> messages on two-columns format.

      ee1f37

      Updating        $MESSAGE
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsRemovingLine'</samp>
      ee1f37

      To print <samp>`Removing'</samp> messages on two-columns format.

      ee1f37

      Removing        $MESSAGE
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsCheckingLine'</samp>
      ee1f37

      To print <samp>`Checking'</samp> messages on two-columns format.

      ee1f37

      Checking        $MESSAGE
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsCreatingLine'</samp>
      ee1f37

      To print <samp>`Creating'</samp> messages on two-columns format.

      ee1f37

      Creating        $MESSAGE
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsSavedAsLine'</samp>
      ee1f37

      To print <samp>`Saved as'</samp> messages on two-columns format.

      ee1f37

      Saved as        $MESSAGE
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsLinkToLine'</samp>
      ee1f37

      To print <samp>`Linked to'</samp> messages on two-columns format.

      ee1f37

      Linked to       $MESSAGE
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsMovedToLine'</samp>
      ee1f37

      To print <samp>`Moved to'</samp> messages on two-columns format.

      ee1f37

      Moved to        $MESSAGE
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsTranslationLine'</samp>
      ee1f37

      To print <samp>`Translation'</samp> messages on two-columns format.

      ee1f37

      Translation     $MESSAGE
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsConfigurationLine'</samp>
      ee1f37

      To print <samp>`Configuration'</samp> messages on two-columns format.

      ee1f37

      Configuration   $MESSAGE
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsResponseLine'</samp>
      ee1f37

      To print response messages on one-column format.

      ee1f37

      --> $MESSAGE
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsRequestLine'</samp>
      ee1f37

      To print request messages on one-column format. Request messages

      ee1f37
      output messages with one colon (<samp>`:'</samp>) and without trailing newline
      ee1f37
      (<samp>`\n'</samp>) at message end.
      ee1f37

      $MESSAGE:
      ee1f37
      ee1f37
      ee1f37
      <samp>`AsYesOrNoRequestLine'</samp>
      ee1f37

      To print <samp>`yes or no'</samp> request messages on one-column format. If

      ee1f37
      something different from <samp>`y'</samp> is answered (when using
      ee1f37
      en_US.UTF-8 locale), script execution ends immediatly.  
      ee1f37

      ee1f37
      $MESSAGE [y/N]:
      ee1f37
      ee1f37

      When we use <tt>`centos-art.sh'</tt> script in a locale different from

      ee1f37
      en_US.UTF-8, confirmation answer may be different from
      ee1f37
      <samp>`y'</samp>. For example, if you use es_ES.UTF-8 locale, the
      ee1f37
      confirmation question would look like:
      ee1f37

      ee1f37
      $MESSAGE [s/N]:
      ee1f37
      ee1f37

      and the confirmation answer would be <samp>`s'</samp>, as it is on Spanish

      ee1f37
      <samp>`sí'</samp> word.
      ee1f37

      ee1f37

      Definition of which confirmation word to use is set on translation

      db14a4
      messages for your specific locale information. See section trunk/Scripts/Bash/Functions/Locale, for more information about locale-specific
      ee1f37
      translation messages.
      ee1f37

      ee1f37
      ee1f37
      <samp>`AsToKnowMoreLine'</samp>
      ee1f37

      To standardize <samp>`to know more, run the following command:'</samp>

      ee1f37
      messages. When the <samp>`AsToKnowMoreLine'</samp> option is used, the
      ee1f37
      MESSAGE value should be set to "$(caller)". caller
      ee1f37
      is a Bash builtin that returns the context of the current subroutine
      ee1f37
      call. <samp>`AsToKnowMoreLine'</samp> option uses caller builtin
      ee1f37
      output to build documentation entries dynamically.
      ee1f37

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

      Use <samp>`AsToKnowMoreLine'</samp> option after errors and for intentional

      ee1f37
      script termination. 
      ee1f37

      ee1f37
      ee1f37
      <samp>`AsRegularLine'</samp>
      ee1f37

      To standardize regular messages on one-column format.

      ee1f37

      ee1f37

      When MESSAGE contains a colon inside (e.g., <samp>`description:

      ee1f37
      message'</samp>), the cli_printMessage function outputs MESSAGE
      ee1f37
      on two-columns format. 
      ee1f37

      ee1f37
      ee1f37
      ee1f37

      Use cli_printMessage function whenever you need to output

      ee1f37
      information from <tt>`centos-art.sh'</tt> script.
      ee1f37

      ee1f37
      Info

      Tip

      To improve two-columns format, change the following file:

      ee1f37

      trunk/Scripts/Bash/Styles/output_forTwoColumns.awk
      ee1f37
      ee1f37
      ee1f37
      ee1f37
      ee1f37
      ee1f37

      3.48.3.3 Specific functions

      ee1f37
      ee1f37

      The following specific functions of <tt>`centos-art.sh'</tt> script, are

      ee1f37
      available for you to use:
      ee1f37

      ee1f37
      db14a4
      3.49 trunk/Scripts/Bash/Functions/Html  
      ee1f37
      db14a4
      3.50 trunk/Scripts/Bash/Functions/Locale  
      ee1f37
      db14a4
      3.51 trunk/Scripts/Bash/Functions/Manual  
      ee1f37
      db14a4
      3.52 trunk/Scripts/Bash/Functions/Path  
      ee1f37
      db14a4
      3.53 trunk/Scripts/Bash/Functions/Render  
      ee1f37
      db14a4
      3.54 trunk/Scripts/Bash/Functions/Render/Config  
      ee1f37
      db14a4
      3.55 trunk/Scripts/Bash/Functions/Shell  
      ee1f37
      db14a4
      3.56 trunk/Scripts/Bash/Functions/Svg  
      ee1f37
      db14a4
      3.57 trunk/Scripts/Bash/Functions/Verify  
      ee1f37
      ee1f37
      ee1f37
      ee1f37
      ee1f37
      ee1f37

      3.48.4 See also

      ee1f37
      ee1f37
      db14a4
      3.47 trunk/Scripts/Bash  
      ee1f37
      db14a4
      3.58 trunk/Scripts/Bash/Locale  
      ee1f37
      ee1f37
      ee1f37
      ee1f37
      ee1f37
      ee1f37
      [ < ]
      db14a4
      [ > ]
      ee1f37
         
      db14a4
      [ << ]
      ee1f37
      [ Up ]
      db14a4
      [ >> ]
      ee1f37
      ee1f37

      ee1f37
       <font size="-1">
      ee1f37
        This document was generated on February, 27 2011 using texi2html 1.76.
      ee1f37
       </font>
      ee1f37
       
      ee1f37
      ee1f37

      ee1f37
      </body>
      ee1f37
      </html>