<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!--This manual describes what the CentOS Artwork Repository is and what
can you do inside it.
Copyright C 2009, 2010 Alain Reguera Delgado. All rights
reserved.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled GNU Free
Documentation License.
-->
<!-- Created on November, 2 2010 by texi2html 1.76 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people <dev@texi2html.cvshome.org>
Send bugs and suggestions to <users@texi2html.cvshome.org>
-->
<head>
<title>CentOS Artwork Repository: 3.35 trunk/Scripts/Bash/Functions</title>
<meta name="description" content="CentOS Artwork Repository: 3.35 trunk/Scripts/Bash/Functions">
<meta name="keywords" content="CentOS Artwork Repository: 3.35 trunk/Scripts/Bash/Functions">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.76">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<style type="text/css">
<!--
@import "/home/centos/artwork/trunk/Identity/Models/Css/Texi2html/common.css";
a.summary-letter {text-decoration: none}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="repository_37.html#SEC199" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC201" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="repository_3.html#SEC3" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="repository_3.html#SEC3" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="repository_62.html#SEC343" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="repository.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="repository_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="repository_62.html#SEC343" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="repository_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="trunk-Scripts-Bash-Functions"></a>
<a name="SEC200"></a>
<h2 class="section"> 3.35 trunk/Scripts/Bash/Functions </h2>
<a name="SEC201"></a>
<h3 class="subsection"> 3.35.1 Goals </h3>
<p>The <tt>`trunk/Scripts/Bash/Functions'</tt> directory exists to organize
<tt>`centos-art.sh'</tt> specific functionalities.
</p>
<a name="SEC202"></a>
<h3 class="subsection"> 3.35.2 Description </h3>
<p>The specific functions of <tt>`centos-art.sh'</tt> script are designed
with "Software Toolbox" philosophy (see <a href="../coreutils/Toolbox-introduction.html#Toolbox-introduction">(coreutils.info)Toolbox introduction</a>) in mind: each program "should do one
thing well". Inside <tt>`centos-art.sh'</tt> script, each specific
functionality is considered a program that should do one thing well.
Of course, if you find that they still don't do it, feel free to
improve them in order for them to do so.
</p>
<p>The specific functions of <tt>`centos-art.sh'</tt> script are organized
inside specific directories under <tt>`trunk/Scripts/Bash/Functions'</tt>
location. Each specific function directory should be named as the
function it represents, with the first letter in uppercase. For
example, if the function name is <samp>`render'</samp>, the specific function
directory for it would be <samp>`trunk/Scripts/Bash/Functions/Render'</samp>.
</p>
<p>To better understand how specific functions of <tt>`centos-art.sh'</tt>
script are designed, lets create one function which only goal is to
output different kind of greetings to your screen.
</p>
<p>When creating specific functions for <tt>`centos-art.sh'</tt> script it is
crucial to know what these function will do exactly and if there is
any function that already does what we intend to do. If there is no
one, it is good time to create them then. Otherwise, if
functionalities already available don't do what you exactly expect,
contact their authors and work together to improve them.
</p>
<blockquote class="orange"><img src="/home/centos/artwork/trunk/Identity/Widgets/Img/icon-admonition-idea.png" alt="Info"><h3>Tip</h3><p> Most debates about CentOS Artwork Repository take place
in the CentOS art works (<a href="mailto:centos-art@centos.org">centos-art@centos.org</a>) mailing list.
</p></blockquote>
<p>It is also worth to know what global functions we have available, so
advantage can be taken from them. Global functions are stored
immediatly under <tt>`trunk/Scripts/Bash/Functions'</tt> directory in
files begining with <samp>`cli'</samp> prefix.
</p>
<a name="SEC203"></a>
<h4 class="subsubsection"> 3.35.2.1 Creating new specific functionalities </h4>
<p>OK, let's begin with our specific functionality example.
</p>
<p>What function name do we use? Well, lets use <samp>`greet'</samp>. Note that
<samp>`hello'</samp> is not a verb, but an expression, a kind of greeting, an
interjection specifically. In contrast, <samp>`greet'</samp> is a verb and
describes what we do when we say <samp>`Hello!'</samp>, <samp>`Hi!'</samp>, and so on.
So far, we've gathered the following function information:
</p>
<pre class="verbatim">Name: greet
Path: trunk/Scripts/Bash/Functions/Greet
File: trunk/Scripts/Bash/Functions/Greet/greet.sh
</pre>
<blockquote class="blue"><img src="/home/centos/artwork/trunk/Identity/Widgets/Img/icon-admonition-info.png" alt="info"><h3>Note</h3><p> Note how function name is used as reference to define
function path, function script, and function definition inside
function script.
</p></blockquote>
<p>As consistency convenction, files related to <samp>`greet'</samp>
functionality are stored under its own function path. The
<tt>`greet.sh'</tt> function script is the first file <tt>`centos-art.sh'</tt>
script loads when the <samp>`greet'</samp> functionality is called using
commands like <samp>`centos-art greet --hello='World''</samp>.
</p>
<p>The <tt>`greet.sh'</tt> function script contains the <code>greet</code>
function definition. Inside <tt>`centos-art.sh'</tt> script, each function
definition has its own top commentary, followed by one blank line, and
then one function defintion below it.
</p>
<p>The function top commentary contains a brief description about what
the function does, one-line for copyright note --with your personal
information--, the license under which the function source code is
released --the <tt>`centos-art.sh'</tt> script is released as GPL, so do
all its functions--, and the subversion <samp>`$Id$'</samp> keyword. In our
function example, the <tt>`greet.sh'</tt> top commentary would look like
the following:
</p>
<pre class="verbatim">#!/bin/bash
#
# greet.sh -- This function outputs different kind of greetings to
# your screen. Use this function to understand how centos-art.sh
# script specific functionalities work.
#
# Copyright (C) 2010 Alain Reguera Delgado
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
# USA.
#
# ----------------------------------------------------------------------
# $Id: greet.sh 520 2010-11-02 09:44:26Z al $
# ----------------------------------------------------------------------
</pre>
<p>The <samp>`greet'</samp> function defines variables that will be available
along <samp>`greet'</samp> function execution environment. Later, as final
definition, the <samp>`greet'</samp> function calls the
<tt>`greet_getActions'</tt> function defined inside
<tt>`greet_getActions.sh'</tt> function script.
</p>
<p>In our example, the <samp>`greet'</samp> function definition would look as
follows:
</p>
<pre class="verbatim">function greet {
# Define global variables.
# Define command-line interface.
greet_getActions
}
</pre>
<p>This time we didn't use global variables for <samp>`greet'</samp>
functionality, so we left section for global variables definition
empty.
</p>
<p>The <code>greet_getActions</code> function defines the command-line
interface of <samp>`greet'</samp> functionality. The command-line interface
defines what to do with arguments passed to <tt>`centos-art.sh'</tt>
script once <samp>`greet'</samp> has been specified as second argument.
</p>
<p>In our function example, the <code>greet_getActions</code> function
definition would look like the following:
</p>
<pre class="verbatim">function greet_getActions {
case "$OPTIONNAM" in
--hello )
greet_doHello
;;
--bye )
greet_doBye
;;
* )
cli_printMessage "`gettext "The option provided is not valid."`"
cli_printMessage "$(caller)" 'AsToKnowMoreLine'
esac
}
</pre>
<p>In the above example, we've defined a selection case based on second
argument's option name (<var>OPTIONNAM</var>). In our selection case, we
defined the <samp>`--hello'</samp> and <samp>`--bye'</samp> options as valid
options. If no one of them is provided as second command-line
argument, the <samp>`*'</samp> option is evaluated instead.
</p>
<p>The <samp>`*'</samp> option and the two following lines, should always be
present in <tt>`*_getActions.sh'</tt> function scripts, no matter what
specific functionality you are creating. This convenction helps the
user to find out documentation about the current functionality in use.
Of course, function documentation needs to be created first
(see section <a href="repository_39.html#SEC209">trunk/Scripts/Bash/Functions/Help</a>, to know how), and that
task is something you --as author of specific functions-- probably
want to do personally.
</p>
<p>Following with our example, the <code>greet_doHello</code>, and
<code>greet_doBye</code> functions are the core of <samp>`greet'</samp>
specific functionality. In such functions is where we define what our
function realy does --output different kinds of greetings, in the
sake of our example--.
</p>
<pre class="verbatim">function greet_doHello {
cli_printMessage "`gettext "Hello"` $OPTIONVAL"
}
</pre>
<pre class="verbatim">function greet_doBye {
cli_printMessage "`gettext "Goodbye"` $OPTIONVAL"
}
</pre>
<p>In both <code>greet_doHello</code> and <code>gree_doBye</code> function
definitions, we used the <var>OPTIONVAL</var> variable. This variable is
defined in <tt>`cli.sh'</tt> function script and contains the value passed
after the equal sign (i.e., <samp>`='</samp>) inside second command-line
argument. For example, if the second command-line argument is
<samp>`--hello='World''</samp>, the value of <var>OPTIONVAL</var> variable is
<samp>`World'</samp> without quotes.
</p>
<p>Well, it seems that our example is rather complete by now. Let's see
how its files are organized. For this, we use the <code>tree</code>
command:
</p>
<pre class="verbatim">trunk/Scripts/Bash/Functions/Greet
|-- greet_doBye.sh
|-- greet_doHello.sh
|-- greet_getActions.sh
`-- greet.sh
</pre>
<p>To try the <samp>`greet'</samp> specific functionality, you need to pass the
<samp>`greet'</samp> as first argument to <tt>`centos-art.sh'</tt> script, and
any of the valid options as second argument. Some examples are
illustrated below:
</p>
<pre class="verbatim">[centos@projects ~]$ centos-art greet --hello='World'
Hello World
[centos@projects ~]$ centos-art greet --bye='World'
Goodbye World
[centos@projects ~]$
</pre>
<p>The word <samp>`World'</samp> in the examples above, can be anything. In fact,
change it to have a little fun :).
</p>
<p>In <samp>`greet'</samp> example we've described so far, we only use the
<code>cli_printMessage</code> global function in action specific
functions, but more interesting things can be achieved inside them.
For example, if you pass a directory path as second argument option
value, you could retrive a list of files from therein, and process
them. If the list of files turns too long, you could add the third
argument in the form <samp>`--filter='regex''</samp> and reduce the amount
of files to process using a regular expression pattern.
</p>
<p>This description may serve you as an introduction to understand how
specific functionalities work inside <tt>`centos-art.sh'</tt> script. With
some of luck this introduction will also serve you as motivation to
create your own specific functionalities.
</p>
<p>By the way, the <samp>`greet'</samp> functionality doesn't exist inside
<tt>`centos-art.sh'</tt> script. Would you like to create it?
</p>
<a name="SEC204"></a>
<h3 class="subsection"> 3.35.3 Usage </h3>
<a name="SEC205"></a>
<h4 class="subsubsection"> 3.35.3.1 Global variables </h4>
<p>The following global variables of <tt>`centos-art.sh'</tt> script, are
available for you to use inside specific functions:
</p>
<dl compact="compact">
<dt> <var>TEXTDOMAIN</var></dt>
<dd><p>Default domain used to retrieve translated messages. This value is set
in `initFunctions.sh' and shouldn't be changed.
</p>
</dd>
<dt> <var>TEXTDOMAINDIR</var></dt>
<dd><p>Default directory used to retrieve translated messages. This value is
set in `initFunctions.sh' and shouldn't be changed.
</p>
</dd>
<dt> <var>ACTION</var></dt>
<dd><p>Default action passed to <code>centos-art</code> command as first
argument. For example, in the command <samp>`centos-art render
--entry=path/to/dir --filter=regex'</samp>, the action passed to
<code>centos-art</code> is <samp>`render'</samp>.
</p>
</dd>
<dt> <var>OPTIONNAM</var></dt>
<dd><p>Default option name passed to <code>centos-art</code> command as second
argument. For example, in the command <samp>`centos-art render
--entry=path/to/dir --filter=regex'</samp>, the option name passed to
<code>centos-art</code> as second argument is <samp>`--entry'</samp>.
</p>
</dd>
<dt> <var>OPTIONVAL</var></dt>
<dd><p>Default option value passed to <code>centos-art</code> command as second
argument. For example, in the command <samp>`centos-art render
--entry=path/to/dir --filter=regex'</samp>, the option value passed to
<code>centos-art</code> as second argument is <samp>`path/to/dir'</samp>.
</p>
</dd>
<dt> <var>REGEX</var></dt>
<dd><p>Default option value passed to <code>centos-art</code> command as third
argument. For example, in the command <samp>`centos-art render
--entry=path/to/dir --filter=regex'</samp>, the option value passed to
<code>centos-art</code> as second argument is <samp>`regex'</samp>.
</p>
<p>At present time, the option name passed as third argument is not
variable, as second argument option name is. The third argument option
name is stocked to <samp>`--filter'</samp> for whatever value it passed at
the right side of its equal sign. Generally, third argument option
value is used to pass regular expression patterns that modify the list
of files to process but this is not the only feature it may serve to.
</p>
</dd>
<dt> <var>ANSWER</var></dt>
<dd><p>Default answer for questions. As most questions are to request
confirmation about some specific action, default answer to this
variable is negative (i.e., <samp>`No'</samp>). Default answer value takes
place when no value is entered as response to confirmation questions
before pressing <kbd>RET</kbd> key.
</p>
</dd>
<dt> <var>TMPFILE</var></dt>
<dd><p>Default location to store temporal files. This variable contains a
value with the format <samp>`/tmp/centos-art-$$'</samp>. The <samp>`$$'</samp> expands
to the process id of <code>centos-art</code> current execution.
</p>
</dd>
<dt> <var>EDITOR</var> </dt>
<dd><p>Default text editor. This variable contains the absolute path to
<tt>`centos-art.sh'</tt> script default text editor (i.e.,
<tt>`/usr/bin/vim'</tt>). If you want to use a different text editor set,
and export this variable in your <tt>`~/.bash_profile'</tt> file. The
<tt>`centos-art.sh'</tt> script recognizes one of the following text
editors only:
</p>
<ul class="toc">
<li> /usr/bin/vim
</li><li> /usr/bin/emacs
</li><li> /usr/bin/nano
</li></ul>
</dd>
</dl>
<a name="SEC206"></a>
<h4 class="subsubsection"> 3.35.3.2 Global functions </h4>
<p>The following global functions of <tt>`centos-art.sh'</tt> script, are
available for you to use inside specific functions:
</p>
<dl compact="compact">
<dt> <code>cli_checkFiles</code></dt>
<dd><p>This function checks files (e.g., regular files, regular directories,
symbolic links, etc.) existence.
</p>
</dd>
<dt> <code>cli_getCountryCodes</code></dt>
<dd><p>This function outputs a list with country codes as defined in ISO3166
standard.
</p>
</dd>
<dt> <code>cli_getCountryNames</code></dt>
<dd><p>This function reads one language locale code in the format LL_CC and
outputs the name of its related country.
</p>
</dd>
<dt> <code>cli_getCurrentLocale</code></dt>
<dd><p>This function checks <var>LANG</var> environment variable and returns the
current locale from more specific to less specific. For example, if
the locale <samp>`en_GB'</samp> is the current one, it should be used instead
of just <samp>`en'</samp>.
</p>
</dd>
<dt> <code>cli_getLangCodes</code></dt>
<dd><p>This function outputs a list of language codes as defined in ISO639
standard.
</p>
</dd>
<dt> <code>cli_getLangNames</code></dt>
<dd><p>This function reads one language locale code in the format LL_CC and
outputs its language name as defined in ISO639 standard.
</p>
</dd>
<dt> <code>cli_getLocales</code></dt>
<dd><p>This function outputs locale codes in LL and LL_CC format. Combine
both ISO639 and ISO3166 specification in order to build the final
locale list. This function defines which translation locales are
supported inside CentOS Artwork Repository.
</p>
</dd>
<dt> <code>cli_getRepoNames</code></dt>
<dd><p>This function sets naming convenction. Inside CentOS Artowrk
Repository, regular files are written in lower case and directories
are written in lower case but with the first letter in upper case. Use
this function to sanitate the name of regular files and directories
you work with.
</p>
</dd>
<dt> <code>cli_getThemeName</code></dt>
<dd><p>This function manipulates the current absolute path to extract the
theme name from it. If there is no theme in the path, this function
returns an empty string.
</p>
</dd>
<dt> <code>cli_printMessage</code></dt>
<dd><p>This function outputs information in predifined formats. This function
(cli_printMessage) is the standard way to output information inside
<tt>`centos-art.sh'</tt> script. Use this function whenever you need to
output information from <tt>`centos-art.sh'</tt>.
</p></dd>
</dl>
<a name="SEC207"></a>
<h4 class="subsubsection"> 3.35.3.3 Specific functions </h4>
<p>The following specific functions of <tt>`centos-art.sh'</tt> script, are
available for you to use:
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="repository_39.html#SEC209">3.36 trunk/Scripts/Bash/Functions/Help</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="repository_40.html#SEC214">3.37 trunk/Scripts/Bash/Functions/Html</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="repository_41.html#SEC219">3.38 trunk/Scripts/Bash/Functions/Locale</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="repository_42.html#SEC224">3.39 trunk/Scripts/Bash/Functions/Path</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="repository_43.html#SEC229">3.40 trunk/Scripts/Bash/Functions/Render</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="repository_44.html#SEC234">3.41 trunk/Scripts/Bash/Functions/Render/Config</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="repository_45.html#SEC242">3.42 trunk/Scripts/Bash/Functions/Shell</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="repository_46.html#SEC247">3.43 trunk/Scripts/Bash/Functions/Svg</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="repository_47.html#SEC252">3.44 trunk/Scripts/Bash/Functions/Verify</a></td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<a name="SEC208"></a>
<h3 class="subsection"> 3.35.4 See also </h3>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="repository_37.html#SEC195">3.34 trunk/Scripts/Bash</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="repository_48.html#SEC260">3.45 trunk/Scripts/Bash/Locale</a></td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC207" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="repository_39.html#SEC209" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="repository_3.html#SEC3" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC200" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="repository_62.html#SEC343" title="Next chapter"> >> </a>]</td>
</tr></table>
<p>
<font size="-1">
This document was generated on <i>November, 2 2010</i> using <a href="http://texi2html.cvshome.org/"><i>texi2html 1.76</i></a>.
</font>
<br>
</p>
</body>
</html>