Blame Manual/centos-art.sh-html/centos-art.sh_71.html

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

2.64 The <tt>`trunk/Scripts/Bash/Cli/Functions'</tt> Directory

632e8b
632e8b
52772c
52772c

2.64.1 Goals

632e8b
52772c

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

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

632e8b
52772c
52772c

2.64.2 Description

632e8b
52772c

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

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

52772c

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

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

52772c

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

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

52772c

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

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

52772c
Info

Tip

Join CentOS developers mailing list

52772c
centos-art@centos.org to share your ideas.
52772c

9bfd15
52772c

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

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

52772c

OK, let's begin with our functionality example.

52772c

52772c

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

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

52772c

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

52772c

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

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

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

52772c

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

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

52772c

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

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

52772c

In our greet function example, top commentary for

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

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

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

52772c
function definition would look like the following:
52772c

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

The first definition inside greet function, are global

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

52772c

Later, we call greet_getActions function to define the

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

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

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

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

52772c

The greet function definition makes available two valid

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

52772c

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

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

52772c

The greet_doHello and greet_doBye function definitions

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

52772c
function greet_doHello {
52772c
52772c
    cli_printMessage "`gettext "Hello"` $ACTIONVAL"
52772c
52772c
}
52772c
52772c

The greet_doHello function definition is stored in

52772c
<tt>`greet_doHello.sh'</tt> function script. 
52772c

52772c
function greet_doBye {
52772c
52772c
    cli_printMessage "`gettext "Goodbye"` $ACTIONVAL"
52772c
52772c
}
52772c
52772c

The greet_doBye function definition is stored in the

52772c
<tt>`greet_doBye.sh'</tt> function script. 
52772c

52772c

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

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

52772c

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

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

52772c

Let's see how greet specific functionality files are organzied

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

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

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

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

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

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

52772c
change it to have a little fun.
52772c

52772c

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

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

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

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

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

52772c

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

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

52772c
centos-art locale --edit
52772c
52772c
Warning

Warning

To translate output messages in different languages,

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

52772c
52772c

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

52772c

52772c

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

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

52772c

The greet function described in this section may serve you as

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

52772c

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

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

52772c
52772c
52772c

2.64.3 Usage

52772c
52772c
52772c
52772c

2.64.3.1 Global variables

52772c
52772c

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

52772c
available for you to use inside specific functions:
52772c

52772c
52772c
<u>Variable:</u> TEXTDOMAIN
52772c
52772c
52772c

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

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

52772c
52772c
52772c
<u>Variable:</u> TEXTDOMAINDIR
52772c
52772c
52772c

Default directory used to retrieve translated messages. This value is

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

52772c
52772c
52772c
<u>Variable:</u> FUNCNAM
52772c
52772c
52772c

Define function name.

52772c

52772c

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

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

52772c

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

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

52772c

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

52772c
immediatly ends its execution.
52772c

52772c
52772c
52772c
<u>Variable:</u> FUNCDIR
52772c
52772c
52772c
52772c
52772c
52772c
<u>Variable:</u> FUNCDIRNAME
52772c
52772c
52772c
52772c
52772c
52772c
<u>Variable:</u> FUNCSCRIPT
52772c
52772c
52772c
52772c
52772c
52772c
<u>Variable:</u> FUNCCONFIG
52772c
52772c
52772c
52772c
52772c
52772c
<u>Variable:</u> ACTIONNAM
52772c
52772c
52772c

Define action name.

52772c

52772c

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

52772c
specific function.
52772c

52772c

Action name names aare passed as second argument in

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

52772c

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

52772c
immediatly ends its execution.
52772c

52772c
52772c
52772c
<u>Variable:</u> ACTIONVAL
52772c
52772c
52772c

Define action value.

52772c

52772c

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

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

52772c
52772c
52772c
<u>Variable:</u> REGEX
52772c
52772c
52772c

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

52772c
to process.
52772c

52772c

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

52772c
files.
52772c

52772c

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

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

632e8b
52772c
52772c
<u>Variable:</u> ARGUMENTS
52772c
52772c
52772c

Define optional arguments.

52772c

52772c

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

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

52772c

Optional arguments are parsed using getopt command through

52772c
the following base construction: 
52772c

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

Optional arguments provide support to command options inside

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

52772c

The ARGUMENTS variable is used to store arguments passed from

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

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

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

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

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

When getopt parses ARGUMENTS, we may use short options

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

52772c

In order for getopt to parse ARGUMENTS correctly, it

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

52772c

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

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

52772c

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

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

52772c
52772c
52772c
<u>Variable:</u> EDITOR
52772c
52772c
52772c

Default text editor.

52772c

52772c

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

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

52772c

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

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

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

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

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

    52772c
    52772c
    52772c
    52772c

    2.64.3.2 Global functions

    52772c
    52772c

    Function scripts stored directly under

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

    52772c
    52772c
    <u>Function:</u> cli_checkActionArguments
    52772c
    52772c
    52772c

    Validate action value (ACTIONVAL) variable.

    52772c

    52772c

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

    52772c

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

      If another value different from that specified above is passed to

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_checkFiles FILE [TYPE]
      52772c
      52772c
      52772c

      Verify file existence.

      52772c

      52772c

      cli_checkFiles receives a FILE absolute path and performs

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

      52772c
      52772c
      <samp>`d'</samp>
      52772c
      <samp>`directory'</samp>
      52772c

      Ends script execution if FILE is not a directory.

      52772c

      52772c

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

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

      52772c
      52772c
      <samp>`f'</samp>
      52772c
      <samp>`regular-file'</samp>
      52772c

      Ends script execution if FILE is not a regular file.

      52772c

      52772c
      <samp>`h'</samp>
      52772c
      <samp>`symbolic-link'</samp>
      52772c

      Ends script execution if FILE is not a symbolic link.

      52772c

      52772c
      <samp>`x'</samp>
      52772c
      <samp>`execution'</samp>
      52772c

      Ends script execution if FILE is not executable.

      52772c

      52772c
      <samp>`fh'</samp>
      52772c

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

      52772c
      symbolic link.
      52772c

      52772c
      <samp>`fd'</samp>
      52772c

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

      52772c
      directory.
      52772c

      52772c
      <samp>`isInWorkingCopy'</samp>
      52772c

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

      52772c

      52772c
      52772c
      52772c

      As default behaviour, if FILE passes all verifications,

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_commitRepoChanges [LOCATION]
      52772c
      52772c
      52772c

      Syncronize changes between repository and working copy.

      52772c

      52772c

      The cli_commitRepoChanges function brings changes from the

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

      52772c

      Previous to commit the working copy changes up to the central

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

      52772c

      If LOCATION argument is not specified, the value of

      52772c
      ACTIONVAL variable is used as reference instead.
      52772c

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

      Figure 2.3: The cli_commitRepoChanges function output.

      52772c
      52772c

      52772c

      Call the cli_commitRepoChanges function before or/and after

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_doParseArguments
      52772c
      52772c
      52772c

      Redefine arguments (ARGUMENTS) global variable using

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_doParseArgumentsReDef $@
      52772c
      52772c
      52772c

      Initialize/reset arguments (ARGUMENTS) global variable using

      52772c
      positional parameters variable ($@) as reference.
      52772c

      52772c

      When we work inside function definitions, positional parameters are

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_getArguments
      52772c
      52772c
      52772c

      Initialize function name (FUNCNAM), action name

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

      52772c

      The cli_getArguments function is called from cli.sh

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

      52772c

      Once command-line positional parameters are accesible to

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

      52772c

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

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

      52772c

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

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

      52772c

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

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_getFunctions
      52772c
      52772c
      52772c

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

      52772c

      52772c

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

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

      52772c

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

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

      52772c

      Inside each functionality directory, the functionalty itself is

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

      52772c

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

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

      52772c
      function prefix_doSomething {
      52772c
      52772c
          # Do something here...
      52772c
      52772c
      }
      52772c
      52772c

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

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

      52772c

      If the functionality specified in the command-line first argument

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

      52772c

      In order to keep visual consistency among function scripts, please

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

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

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

      52772c

      52772c

      The cli_getCountryCodes function outputs a list with country

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_getCountryName [FILTER]
      52772c
      52772c
      52772c

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

      52772c

      52772c

      The cli_getCountryName function reads one language locale code

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

      52772c
       
      52772c
      52772c
      <u>Function:</u> cli_getCurrentLocale
      52772c
      52772c
      52772c

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

      52772c

      52772c

      The cli_getCurrentLocale function uses LANG environment

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

      52772c

      The current locale information, returned by

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

      52772c

      Locale precedence selection is quite important in order to define the

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

      52772c

      Use cli_getCurrentLocale function to know what current locale

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_getFilesList [LOCATION]
      52772c
      52772c
      52772c

      Output list of files to process.

      52772c

      52772c

      The cli_getFilesList function uses LOCATION variable as

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

      52772c

      If LOCATION is not specified when cli_getFilesList

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

      52772c

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

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

      52772c

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

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

      52772c

      As result, the cli_getFilesList re-defines the value of

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

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

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

      52772c

      52772c

      cli_getLangCodes function outputs a list of language codes as

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_getLangName [FILTER]
      52772c
      52772c
      52772c

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

      52772c

      52772c

      cli_getLangName function reads one language locale code in the

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_getLocales
      52772c
      52772c
      52772c

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

      52772c

      52772c

      Occasionally, you use cli_getLocales function to add locale

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_getRepoName NAME TYPE
      52772c
      52772c
      52772c

      Sanitate file names.

      52772c

      52772c

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

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

      52772c
      Important

      Important

      cli_getRepoName function doesn't verify file

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

      52772c
      52772c

      The NAME variable contains the file name or directory name you

      52772c
      want to sanitate.
      52772c

      52772c

      The TYPE variable specifies what type of sanitation you want to

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

      52772c
      52772c
      <samp>`d'</samp>
      52772c
      <samp>`directory'</samp>
      52772c

      Sanitate directory NAMEs.

      52772c

      52772c
      <samp>`f'</samp>
      52772c
      <samp>`regular-file'</samp>
      52772c

      Sanitate regular file NAMEs.

      52772c

      52772c
      52772c
      52772c

      Use cli_getRepoName function to sanitate file names and

      52772c
      directory names before their utilization. 
      52772c

      52772c

      Use cli_getRepoName when you need to change file name

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

      52772c

      When we change file name convenctions inside cli_getRepoName

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_getRepoStatus [LOCATION]
      52772c
      52772c
      52772c

      Request repository status.

      52772c

      52772c

      This function requests the status of a LOCATION inside the

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

      52772c

      Use this function to perform verifications based a repository

      52772c
      LOCATION status.
      52772c

      52772c
      52772c
      52772c
      <u>Function:</u> cli_getTemporalFile NAME
      52772c
      52772c
      52772c

      Output absolute path to temporal file NAME.

      52772c

      52772c

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

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

      52772c
      cli_getTemporalFile $FILE
      52772c
      52772c

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

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

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

      When you use the cli_getTemporalFile function to create

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

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

      Use the cli_getTemporalFile function whenever you need to

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_getThemeName
      52772c
      52772c
      52772c

      Output theme name.

      52772c

      52772c

      In order for cli_getThemeName function to extract theme name

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

      52772c
      52772c
      52772c
      <u>Function:</u> cli_printMessage MESSAGE [FORMAT]
      52772c
      52772c
      52772c

      Define standard output message definition supported by

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

      52772c

      When FORMAT is not specified, cli_printMessage outputs

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

      52772c
      52772c
      <samp>`AsHeadingLine'</samp>
      52772c

      To print heading messages.

      52772c

      ----------------------------------------------------------------------
      52772c
      $MESSAGE
      52772c
      ----------------------------------------------------------------------
      52772c
      52772c
      52772c
      <samp>`AsWarningLine'</samp>
      52772c

      To print warning messages.

      52772c

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

      To print note messages.

      52772c

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

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

      52772c

      Updating        $MESSAGE
      52772c
      52772c
      52772c
      <samp>`AsRemovingLine'</samp>
      52772c

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

      52772c

      Removing        $MESSAGE
      52772c
      52772c
      52772c
      <samp>`AsCheckingLine'</samp>
      52772c

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

      52772c

      Checking        $MESSAGE
      52772c
      52772c
      52772c
      <samp>`AsCreatingLine'</samp>
      52772c

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

      52772c

      Creating        $MESSAGE
      52772c
      52772c
      52772c
      <samp>`AsSavedAsLine'</samp>
      52772c

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

      52772c

      Saved as        $MESSAGE
      52772c
      52772c
      52772c
      <samp>`AsLinkToLine'</samp>
      52772c

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

      52772c

      Linked to       $MESSAGE
      52772c
      52772c
      52772c
      <samp>`AsMovedToLine'</samp>
      52772c

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

      52772c

      Moved to        $MESSAGE
      52772c
      52772c
      52772c
      <samp>`AsTranslationLine'</samp>
      52772c

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

      52772c

      Translation     $MESSAGE
      52772c
      52772c
      52772c
      <samp>`AsConfigurationLine'</samp>
      52772c

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

      52772c

      Configuration   $MESSAGE
      52772c
      52772c
      52772c
      <samp>`AsResponseLine'</samp>
      52772c

      To print response messages on one-column format.

      52772c

      --> $MESSAGE
      52772c
      52772c
      52772c
      <samp>`AsRequestLine'</samp>
      52772c

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

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

      $MESSAGE:
      52772c
      52772c
      52772c
      <samp>`AsYesOrNoRequestLine'</samp>
      52772c

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

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

      52772c
      $MESSAGE [y/N]:
      52772c
      52772c

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

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

      52772c
      $MESSAGE [s/N]:
      52772c
      52772c

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

      52772c
      <samp>`sí'</samp> word.
      52772c

      52772c

      Definition of which confirmation word to use is set on translation

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

      52772c
      52772c
      <samp>`AsToKnowMoreLine'</samp>
      52772c

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

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

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

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

      52772c
      script termination. 
      52772c

      52772c
      52772c
      <samp>`AsRegularLine'</samp>
      52772c

      To standardize regular messages on one-column format.

      52772c

      52772c

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

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

      52772c
      52772c
      52772c

      Use cli_printMessage function whenever you need to output

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

      52772c
      Info

      Tip

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

      52772c

      trunk/Scripts/Bash/Styles/output_forTwoColumns.awk
      52772c
      52772c
      52772c
      52772c
      52772c
      52772c

      2.64.3.3 Specific functions

      52772c
      52772c

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

      52772c
      available for you to use:
      52772c

      52772c
      632e8b
      52772c
      52772c

      2.64.4 See also

      632e8b
      52772c
      1856b7
      2.62 The <tt>`trunk/Scripts/Bash'</tt> Directory  
      52772c
      52772c
      632e8b
      632e8b
      632e8b
      52772c
      [ < ]
      1856b7
      [ > ]
      632e8b
         
      1856b7
      [ << ]
      52772c
      [ Up ]
      1856b7
      [ >> ]
      632e8b
      632e8b

      632e8b
       <font size="-1">
      52772c
        This document was generated on March, 22 2011 using texi2html 1.76.
      632e8b
       </font>
      632e8b
       
      632e8b
      632e8b

      632e8b
      </body>
      632e8b
      </html>