Blame Manuals/Repository/en/Html/repository_40.html

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

3.37 trunk/Scripts/Bash/Functions

4c79b5
4c79b5
5cee2c
6ba043

3.37.1 Goals

6ba043
ec5f63

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

ec5f63
<tt>`centos-art.sh'</tt> specific functionalities.
54b5a5

6ba043
5cee2c
6ba043

3.37.2 Description

6ba043
ec5f63

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

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

ec5f63

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

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

ec5f63

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

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

ec5f63

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

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

ec5f63
Info

Tip

Join CentOS developers mailing list

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

ec5f63
ec5f63

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

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

ec5f63

OK, let's begin with our functionality example.

ec5f63

ec5f63

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

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

ec5f63

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

ec5f63

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

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

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

ec5f63

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

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

ec5f63

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

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

ec5f63

In our greet function example, top commentary for

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

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

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

ec5f63
function definition would look like the following:
ec5f63

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

The first definition inside greet function, are global

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

ec5f63

Later, we call greet_getActions function to define the

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

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

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

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

ec5f63

The greet function definition makes available two valid

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

ec5f63

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

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

ec5f63

The greet_doHello and greet_doBye function definitions

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

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

The greet_doHello function definition is stored in

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

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

The greet_doBye function definition is stored in the

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

ec5f63

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

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

ec5f63

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

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

ec5f63

Let's see how greet specific functionality files are organzied

8e85aa
under greet function directory. To see file organization we use
8e85aa
the tree command:
ec5f63

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

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

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

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

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

ec5f63
change it to have a little fun.
ec5f63

ec5f63

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

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

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

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

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

ec5f63

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

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

ec5f63
centos-art locale --edit
ec5f63
ec5f63
Warning

Warning

To translate output messages in different languages,

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

ec5f63
ec5f63

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

ec5f63

ec5f63

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

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

ec5f63

The greet function described in this section may serve you as

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

ec5f63

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

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

6ba043
5cee2c
6ba043

3.37.3 Usage

6ba043
1d1bf4
5cee2c
ec5f63

3.37.3.1 Global variables

ec5f63
ec5f63

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

ec5f63
available for you to use inside specific functions:
ec5f63

ec5f63
ec5f63
<u>Variable:</u> TEXTDOMAIN
ec5f63
ec5f63
ec5f63

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

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

ec5f63
ec5f63
ec5f63
<u>Variable:</u> TEXTDOMAINDIR
ec5f63
ec5f63
ec5f63

Default directory used to retrieve translated messages. This value is

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

1d1bf4
ec5f63
ec5f63
<u>Variable:</u> FUNCNAM
ec5f63
ec5f63
ec5f63

Define function name.

ec5f63

ec5f63

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

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

ec5f63

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

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

ec5f63

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

ec5f63
immediatly ends its execution.
ec5f63

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

Define action name.

ec5f63

ec5f63

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

ec5f63
specific function.
ec5f63

ec5f63

Action name names aare passed as second argument in

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

ec5f63

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

ec5f63
immediatly ends its execution.
ec5f63

ec5f63
ec5f63
ec5f63
<u>Variable:</u> ACTIONVAL
ec5f63
ec5f63
ec5f63

Define action value.

ec5f63

ec5f63

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

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

ec5f63
ec5f63
ec5f63
<u>Variable:</u> REGEX
ec5f63
ec5f63
ec5f63

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

ec5f63
to process.
ec5f63

ec5f63

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

ec5f63
files.
ec5f63

ec5f63

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

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

ec5f63
ec5f63
ec5f63
<u>Variable:</u> ARGUMENTS
ec5f63
ec5f63
ec5f63

Define optional arguments.

ec5f63

ec5f63

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

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

ec5f63

Optional arguments are parsed using getopt command through

ec5f63
the following base construction: 
ec5f63

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

Optional arguments provide support to command options inside

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

ec5f63

The ARGUMENTS variable is used to store arguments passed from

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

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

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

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

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

When getopt parses ARGUMENTS, we may use short options

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

ec5f63

In order for getopt to parse ARGUMENTS correctly, it

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

ec5f63

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

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

ec5f63

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

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

ec5f63
ec5f63
ec5f63
<u>Variable:</u> EDITOR
ec5f63
ec5f63
ec5f63

Default text editor.

ec5f63

ec5f63

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

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

ec5f63

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

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

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

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

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

    ec5f63
    ec5f63
    5cee2c
    ec5f63

    3.37.3.2 Global functions

    ec5f63
    ec5f63

    Function scripts stored directly under

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

    ec5f63
    ec5f63
    <u>Function:</u> cli_checkActionArguments
    ec5f63
    ec5f63
    ec5f63

    Validate action value (ACTIONVAL) variable.

    ec5f63

    ec5f63

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

    ec5f63

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

      If another value different from that specified above is passed to

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

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

      Verify file existence.

      ec5f63

      ec5f63

      cli_checkFiles receives a FILE absolute path and performs

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

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

      Ends script execution if FILE is not a directory.

      ec5f63

      ec5f63

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

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

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

      Ends script execution if FILE is not a regular file.

      ec5f63

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

      Ends script execution if FILE is not a symbolic link.

      ec5f63

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

      Ends script execution if FILE is not executable.

      ec5f63

      ec5f63
      <samp>`fh'</samp>
      ec5f63

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

      ec5f63
      symbolic link.
      ec5f63

      ec5f63
      <samp>`fd'</samp>
      ec5f63

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

      ec5f63
      directory.
      ec5f63

      ec5f63
      <samp>`isInWorkingCopy'</samp>
      ec5f63

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

      ec5f63

      ec5f63
      ec5f63
      ec5f63

      As default behaviour, if FILE passes all verifications,

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

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

      Syncronize changes between repository and working copy.

      ec5f63

      ec5f63

      The cli_commitRepoChanges function brings changes from the

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

      ec5f63

      Previous to commit the working copy changes up to the central

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

      ec5f63

      If LOCATION argument is not specified, the value of

      ec5f63
      ACTIONVAL variable is used as reference instead.
      ec5f63

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

      Figure 3.14: The cli_commitRepoChanges function output.

      ec5f63
      ec5f63

      ec5f63

      Call the cli_commitRepoChanges function before or/and after

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

      ec5f63
      ec5f63
      ec5f63
      <u>Function:</u> cli_doParseArguments
      ec5f63
      ec5f63
      ec5f63

      Redefine arguments (ARGUMENTS) global variable using

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

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

      Initialize/reset arguments (ARGUMENTS) global variable using

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

      ec5f63

      When we work inside function definitions, positional parameters are

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

      ec5f63
      ec5f63
      ec5f63
      <u>Function:</u> cli_getArguments
      ec5f63
      ec5f63
      ec5f63

      Initialize function name (FUNCNAM), action name

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

      ec5f63

      The cli_getArguments function is called from cli.sh

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

      ec5f63

      Once command-line positional parameters are accesible to

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

      ec5f63

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

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

      ec5f63

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

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

      ec5f63

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

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

      ec5f63
      ec5f63
      ec5f63
      <u>Function:</u> cli_getFunctions
      ec5f63
      ec5f63
      ec5f63

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

      ec5f63

      ec5f63

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

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

      ec5f63

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

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

      ec5f63

      Inside each functionality directory, the functionalty itself is

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

      ec5f63

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

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

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

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

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

      ec5f63

      If the functionality specified in the command-line first argument

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

      ec5f63

      In order to keep visual consistency among function scripts, please

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

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

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

      ec5f63

      ec5f63

      The cli_getCountryCodes function outputs a list with country

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

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

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

      ec5f63

      ec5f63

      The cli_getCountryName function reads one language locale code

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

      ec5f63
       
      ec5f63
      ec5f63
      <u>Function:</u> cli_getCurrentLocale
      ec5f63
      ec5f63
      ec5f63

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

      ec5f63

      ec5f63

      The cli_getCurrentLocale function uses LANG environment

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

      ec5f63

      The current locale information, returned by

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

      ec5f63

      Locale precedence selection is quite important in order to define the

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

      ec5f63

      Use cli_getCurrentLocale function to know what current locale

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

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

      Output list of files to process.

      ec5f63

      ec5f63

      The cli_getFilesList function uses LOCATION variable as

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

      ec5f63

      If LOCATION is not specified when cli_getFilesList

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

      ec5f63

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

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

      ec5f63

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

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

      ec5f63

      As result, the cli_getFilesList re-defines the value of

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

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

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

      ec5f63

      ec5f63

      cli_getLangCodes function outputs a list of language codes as

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

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

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

      ec5f63

      ec5f63

      cli_getLangName function reads one language locale code in the

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

      ec5f63
      ec5f63
      ec5f63
      <u>Function:</u> cli_getLocales
      ec5f63
      ec5f63
      ec5f63

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

      ec5f63

      ec5f63

      Occasionally, you use cli_getLocales function to add locale

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

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

      Sanitate file names.

      ec5f63

      ec5f63

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

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

      ec5f63
      Important

      Important

      cli_getRepoName function doesn't verify file

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

      ec5f63
      ec5f63

      The NAME variable contains the file name or directory name you

      ec5f63
      want to sanitate.
      ec5f63

      ec5f63

      The TYPE variable specifies what type of sanitation you want to

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

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

      Sanitate directory NAMEs.

      ec5f63

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

      Sanitate regular file NAMEs.

      ec5f63

      ec5f63
      ec5f63
      ec5f63

      Use cli_getRepoName function to sanitate file names and

      ec5f63
      directory names before their utilization. 
      ec5f63

      ec5f63

      Use cli_getRepoName when you need to change file name

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

      ec5f63

      When we change file name convenctions inside cli_getRepoName

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

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

      Request repository status.

      ec5f63

      ec5f63

      This function requests the status of a LOCATION inside the

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

      ec5f63

      Use this function to perform verifications based a repository

      ec5f63
      LOCATION status.
      ec5f63

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

      Output absolute path to temporal file NAME.

      ec5f63

      ec5f63

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

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

      ec5f63
      cli_getTemporalFile $FILE
      ec5f63
      ec5f63

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

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

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

      When you use the cli_getTemporalFile function to create

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

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

      Use the cli_getTemporalFile function whenever you need to

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

      ec5f63
      ec5f63
      ec5f63
      <u>Function:</u> cli_getThemeName
      ec5f63
      ec5f63
      ec5f63

      Output theme name.

      ec5f63

      ec5f63

      In order for cli_getThemeName function to extract theme name

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

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

      Define standard output message definition supported by

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

      ec5f63

      When FORMAT is not specified, cli_printMessage outputs

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

      ec5f63
      ec5f63
      <samp>`AsHeadingLine'</samp>
      ec5f63

      To print heading messages.

      ec5f63

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

      To print warning messages.

      ec5f63

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

      To print note messages.

      ec5f63

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

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

      ec5f63

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

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

      ec5f63

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

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

      ec5f63

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

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

      ec5f63

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

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

      ec5f63

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

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

      ec5f63

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

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

      ec5f63

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

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

      ec5f63

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

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

      ec5f63

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

      To print response messages on one-column format.

      ec5f63

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

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

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

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

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

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

      ec5f63
      $MESSAGE [y/N]:
      ec5f63
      ec5f63

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

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

      ec5f63
      $MESSAGE [s/N]:
      ec5f63
      ec5f63

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

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

      ec5f63

      Definition of which confirmation word to use is set on translation

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

      ec5f63
      ec5f63
      <samp>`AsToKnowMoreLine'</samp>
      ec5f63

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

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

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

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

      ec5f63
      script termination. 
      ec5f63

      ec5f63
      ec5f63
      <samp>`AsRegularLine'</samp>
      ec5f63

      To standardize regular messages on one-column format.

      ec5f63

      ec5f63

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

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

      ec5f63
      ec5f63
      ec5f63

      Use cli_printMessage function whenever you need to output

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

      ec5f63
      Info

      Tip

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

      ec5f63

      trunk/Scripts/Bash/Styles/output_forTwoColumns.awk
      ec5f63
      ec5f63
      ec5f63
      ec5f63
      5cee2c
      ec5f63

      3.37.3.3 Specific functions

      ec5f63
      ec5f63

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

      ec5f63
      available for you to use:
      ec5f63

      1d1bf4
      5cee2c
      3.38 trunk/Scripts/Bash/Functions/Html  
      ec5f63
      5cee2c
      3.39 trunk/Scripts/Bash/Functions/Locale  
      ec5f63
      5cee2c
      3.40 trunk/Scripts/Bash/Functions/Manual  
      ec5f63
      5cee2c
      3.41 trunk/Scripts/Bash/Functions/Path  
      ec5f63
      5cee2c
      3.42 trunk/Scripts/Bash/Functions/Render  
      ec5f63
      13b177
      3.43 trunk/Scripts/Bash/Functions/Render/Config  
      ec5f63
      13b177
      3.44 trunk/Scripts/Bash/Functions/Shell  
      ec5f63
      13b177
      3.45 trunk/Scripts/Bash/Functions/Svg  
      3f9ae1
      13b177
      3.46 trunk/Scripts/Bash/Functions/Verify  
      ec5f63
      ec5f63
      ec5f63
      ec5f63
      5cee2c
      ec5f63

      3.37.4 See also

      ec5f63
      ec5f63
      5cee2c
      3.36 trunk/Scripts/Bash  
      63f275
      13b177
      3.47 trunk/Scripts/Bash/Locale  
      63f275
      63f275
      4c79b5
      5fb024
      4c79b5
      5cee2c
      [ < ]
      5cee2c
      [ > ]
      4c79b5
         
      4c79b5
      [ << ]
      5cee2c
      [ Up ]
      13b177
      [ >> ]
      4c79b5
      4c79b5

      4c79b5
       <font size="-1">
      139290
        This document was generated on January, 14 2011 using texi2html 1.76.
      4c79b5
       </font>
      4c79b5
       
      4c79b5
      4c79b5

      4c79b5
      </body>
      4c79b5
      </html>