Blame Identity/Manual/repository-html/repository_68.html

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

2.61 The <tt>`trunk/Scripts/Functions'</tt> Directory

06d106
06d106
52772c
52772c

2.61.1 Goals

06d106
ed9de5

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

ed9de5
<tt>`centos-art.sh'</tt> specific functionalities.
06d106

06d106
52772c
52772c

2.61.2 Description

06d106
ed9de5

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

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

ed9de5

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

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

ed9de5

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

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

ed9de5

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

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

f456e5
Info

Tip

Join CentOS developers mailing list

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

ed9de5
ed9de5

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

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

ed9de5

OK, let's begin with our functionality example.

ed9de5

ed9de5

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

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

ed9de5

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

ed9de5

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

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

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

ed9de5

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

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

ed9de5

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

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

ed9de5

In our greet function example, top commentary for

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

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

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

ed9de5
function definition would look like the following:
ed9de5

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

The first definition inside greet function, are global

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

ed9de5

Later, we call greet_getActions function to define the

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

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

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

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

ed9de5

The greet function definition makes available two valid

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

ed9de5

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

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

ed9de5

The greet_doHello and greet_doBye function definitions

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

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

The greet_doHello function definition is stored in

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

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

The greet_doBye function definition is stored in the

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

ed9de5

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

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

ed9de5

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

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

ed9de5

Let's see how greet specific functionality files are organzied

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

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

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

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

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

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

ed9de5
change it to have a little fun.
ed9de5

ed9de5

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

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

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

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

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

ed9de5

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

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

ed9de5
centos-art locale --edit
ed9de5
f456e5
Warning

Warning

To translate output messages in different languages,

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

ed9de5
ed9de5

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

ed9de5

ed9de5

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

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

ed9de5

The greet function described in this section may serve you as

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

ed9de5

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

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

632e8b
52772c
52772c

2.61.3 Usage

632e8b
ed9de5
ed9de5
ed9de5

2.61.3.1 Global variables

ed9de5
ed9de5

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

ed9de5
available for you to use inside specific functions:
ed9de5

ed9de5
ed9de5
<u>Variable:</u> TEXTDOMAIN
ed9de5
ed9de5
ed9de5

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

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

ed9de5
ed9de5
ed9de5
<u>Variable:</u> TEXTDOMAINDIR
ed9de5
ed9de5
ed9de5

Default directory used to retrieve translated messages. This value is

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

ed9de5
ed9de5
ed9de5
<u>Variable:</u> FUNCNAM
ed9de5
ed9de5
ed9de5

Define function name.

ed9de5

ed9de5

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

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

ed9de5

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

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

ed9de5

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

ed9de5
immediatly ends its execution.
ed9de5

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

Define action name.

ed9de5

ed9de5

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

ed9de5
specific function.
ed9de5

ed9de5

Action name names aare passed as second argument in

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

ed9de5

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

ed9de5
immediatly ends its execution.
ed9de5

ed9de5
ed9de5
ed9de5
<u>Variable:</u> ACTIONVAL
ed9de5
ed9de5
ed9de5

Define action value.

ed9de5

ed9de5

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

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

ed9de5
ed9de5
ed9de5
<u>Variable:</u> REGEX
ed9de5
ed9de5
ed9de5

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

ed9de5
to process.
ed9de5

ed9de5

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

ed9de5
files.
ed9de5

ed9de5

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

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

ed9de5
ed9de5
ed9de5
<u>Variable:</u> ARGUMENTS
ed9de5
ed9de5
ed9de5

Define optional arguments.

ed9de5

ed9de5

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

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

ed9de5

Optional arguments are parsed using getopt command through

ed9de5
the following base construction: 
ed9de5

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

Optional arguments provide support to command options inside

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

ed9de5

The ARGUMENTS variable is used to store arguments passed from

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

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

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

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

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

When getopt parses ARGUMENTS, we may use short options

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

ed9de5

In order for getopt to parse ARGUMENTS correctly, it

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

ed9de5

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

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

ed9de5

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

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

ed9de5
ed9de5
ed9de5
<u>Variable:</u> EDITOR
ed9de5
ed9de5
ed9de5

Default text editor.

ed9de5

ed9de5

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

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

ed9de5

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

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

52772c
    ed9de5
  • <tt>`/usr/bin/vim'</tt>
  • ed9de5
  • <tt>`/usr/bin/emacs'</tt>
  • ed9de5
  • <tt>`/usr/bin/nano'</tt>
  • 52772c
    632e8b
    ed9de5

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

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

    632e8b
    ed9de5
    ed9de5
    ed9de5

    2.61.3.2 Global functions

    ed9de5
    ed9de5

    Function scripts stored directly under

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

    ed9de5
    ed9de5
    <u>Function:</u> cli_checkActionArguments
    ed9de5
    ed9de5
    ed9de5

    Validate action value (ACTIONVAL) variable.

    ed9de5

    ed9de5

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

    ed9de5

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

      If another value different from that specified above is passed to

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

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

      Verify file existence.

      ed9de5

      ed9de5

      cli_checkFiles receives a FILE absolute path and performs

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

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

      Ends script execution if FILE is not a directory.

      ed9de5

      ed9de5

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

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

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

      Ends script execution if FILE is not a regular file.

      ed9de5

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

      Ends script execution if FILE is not a symbolic link.

      ed9de5

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

      Ends script execution if FILE is not executable.

      ed9de5

      ed9de5
      <samp>`fh'</samp>
      ed9de5

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

      ed9de5
      symbolic link.
      ed9de5

      ed9de5
      <samp>`fd'</samp>
      ed9de5

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

      ed9de5
      directory.
      ed9de5

      ed9de5
      <samp>`isInWorkingCopy'</samp>
      ed9de5

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

      ed9de5

      ed9de5
      ed9de5
      ed9de5

      As default behaviour, if FILE passes all verifications,

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

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

      Syncronize changes between repository and working copy.

      ed9de5

      ed9de5

      The cli_commitRepoChanges function brings changes from the

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

      ed9de5

      Previous to commit the working copy changes up to the central

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

      ed9de5

      If LOCATION argument is not specified, the value of

      ed9de5
      ACTIONVAL variable is used as reference instead.
      ed9de5

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

      Figure 2.3: The cli_commitRepoChanges function output.

      ed9de5
      ed9de5

      ed9de5

      Call the cli_commitRepoChanges function before or/and after

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

      ed9de5
      ed9de5
      ed9de5
      <u>Function:</u> cli_doParseArguments
      ed9de5
      ed9de5
      ed9de5

      Redefine arguments (ARGUMENTS) global variable using

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

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

      Initialize/reset arguments (ARGUMENTS) global variable using

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

      ed9de5

      When we work inside function definitions, positional parameters are

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

      ed9de5
      ed9de5
      ed9de5
      <u>Function:</u> cli_getArguments
      ed9de5
      ed9de5
      ed9de5

      Initialize function name (FUNCNAM), action name

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

      ed9de5

      The cli_getArguments function is called from cli.sh

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

      ed9de5

      Once command-line positional parameters are accesible to

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

      ed9de5

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

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

      ed9de5

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

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

      ed9de5

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

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

      ed9de5
      ed9de5
      ed9de5
      <u>Function:</u> cli_getFunctions
      ed9de5
      ed9de5
      ed9de5

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

      ed9de5

      ed9de5

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

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

      ed9de5

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

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

      ed9de5

      Inside each functionality directory, the functionalty itself is

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

      ed9de5

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

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

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

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

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

      ed9de5

      If the functionality specified in the command-line first argument

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

      ed9de5

      In order to keep visual consistency among function scripts, please

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

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

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

      ed9de5

      ed9de5

      The cli_getCountryCodes function outputs a list with country

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

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

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

      ed9de5

      ed9de5

      The cli_getCountryName function reads one language locale code

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

      ed9de5
       
      ed9de5
      ed9de5
      <u>Function:</u> cli_getCurrentLocale
      ed9de5
      ed9de5
      ed9de5

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

      ed9de5

      ed9de5

      The cli_getCurrentLocale function uses LANG environment

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

      ed9de5

      The current locale information, returned by

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

      ed9de5

      Locale precedence selection is quite important in order to define the

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

      ed9de5

      Use cli_getCurrentLocale function to know what current locale

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

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

      Output list of files to process.

      ed9de5

      ed9de5

      The cli_getFilesList function uses LOCATION variable as

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

      ed9de5

      If LOCATION is not specified when cli_getFilesList

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

      ed9de5

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

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

      ed9de5

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

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

      ed9de5

      As result, the cli_getFilesList re-defines the value of

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

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

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

      ed9de5

      ed9de5

      cli_getLangCodes function outputs a list of language codes as

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

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

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

      ed9de5

      ed9de5

      cli_getLangName function reads one language locale code in the

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

      ed9de5
      ed9de5
      ed9de5
      <u>Function:</u> cli_getLocales
      ed9de5
      ed9de5
      ed9de5

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

      ed9de5

      ed9de5

      Occasionally, you use cli_getLocales function to add locale

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

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

      Sanitate file names.

      ed9de5

      ed9de5

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

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

      f456e5
      Important

      Important

      cli_getRepoName function doesn't verify file

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

      ed9de5
      ed9de5

      The NAME variable contains the file name or directory name you

      ed9de5
      want to sanitate.
      ed9de5

      ed9de5

      The TYPE variable specifies what type of sanitation you want to

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

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

      Sanitate directory NAMEs.

      ed9de5

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

      Sanitate regular file NAMEs.

      ed9de5

      ed9de5
      ed9de5
      ed9de5

      Use cli_getRepoName function to sanitate file names and

      ed9de5
      directory names before their utilization. 
      ed9de5

      ed9de5

      Use cli_getRepoName when you need to change file name

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

      ed9de5

      When we change file name convenctions inside cli_getRepoName

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

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

      Request repository status.

      ed9de5

      ed9de5

      This function requests the status of a LOCATION inside the

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

      ed9de5

      Use this function to perform verifications based a repository

      ed9de5
      LOCATION status.
      ed9de5

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

      Output absolute path to temporal file NAME.

      ed9de5

      ed9de5

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

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

      ed9de5
      cli_getTemporalFile $FILE
      ed9de5
      ed9de5

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

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

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

      When you use the cli_getTemporalFile function to create

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

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

      Use the cli_getTemporalFile function whenever you need to

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

      ed9de5
      ed9de5
      ed9de5
      <u>Function:</u> cli_getThemeName
      ed9de5
      ed9de5
      ed9de5

      Output theme name.

      ed9de5

      ed9de5

      In order for cli_getThemeName function to extract theme name

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

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

      Define standard output message definition supported by

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

      ed9de5

      When FORMAT is not specified, cli_printMessage outputs

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

      ed9de5
      ed9de5
      <samp>`AsHeadingLine'</samp>
      ed9de5

      To print heading messages.

      ed9de5

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

      To print warning messages.

      ed9de5

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

      To print note messages.

      ed9de5

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

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

      ed9de5

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

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

      ed9de5

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

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

      ed9de5

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

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

      ed9de5

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

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

      ed9de5

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

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

      ed9de5

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

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

      ed9de5

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

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

      ed9de5

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

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

      ed9de5

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

      To print response messages on one-column format.

      ed9de5

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

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

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

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

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

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

      ed9de5
      $MESSAGE [y/N]:
      ed9de5
      ed9de5

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

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

      ed9de5
      $MESSAGE [s/N]:
      ed9de5
      ed9de5

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

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

      ed9de5

      Definition of which confirmation word to use is set on translation

      ed9de5
      messages for your specific locale information. -- Removed(xref:trunk Scripts
      ed9de5
      Bash Functions Locale) --, for more information about locale-specific
      ed9de5
      translation messages.
      ed9de5

      ed9de5
      ed9de5
      <samp>`AsToKnowMoreLine'</samp>
      ed9de5

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

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

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

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

      ed9de5
      script termination. 
      ed9de5

      ed9de5
      ed9de5
      <samp>`AsRegularLine'</samp>
      ed9de5

      To standardize regular messages on one-column format.

      ed9de5

      ed9de5

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

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

      ed9de5
      ed9de5
      ed9de5

      Use cli_printMessage function whenever you need to output

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

      f456e5
      Info

      Tip

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

      ed9de5

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

      2.61.3.3 Specific functions

      ed9de5
      ed9de5

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

      ed9de5
      available for you to use:
      ed9de5

      ed9de5
      ed9de5
      ed9de5
      52772c

      2.61.4 See also

      632e8b
      ed9de5
      ed9de5
      2.60 The <tt>`trunk/Scripts'</tt> Directory  
      ed9de5
      ed9de5
      34051a
      34051a
      34051a
      ed9de5
      [ < ]
      ed9de5
      [ > ]
      34051a
         
      1075b9
      [ << ]
      52772c
      [ Up ]
      ed9de5
      [ >> ]
      34051a
      34051a

      34051a
       <font size="-1">
      f456e5
        This document was generated on March, 24 2011 using texi2html 1.76.
      34051a
       </font>
      34051a
       
      34051a
      34051a

      34051a
      </body>
      34051a
      </html>