|
|
b32b45 |
@subheading Goals
|
|
|
b32b45 |
|
|
|
b32b45 |
The @file{trunk/Scripts/Functions} directory exists to organize
|
|
|
b32b45 |
@file{centos-art.sh} specific functionalities.
|
|
|
b32b45 |
|
|
|
b32b45 |
@subheading Description
|
|
|
b32b45 |
|
|
|
b32b45 |
The specific functions of @file{centos-art.sh} script are designed
|
|
|
b32b45 |
with the ``Software Toolbox'' philosophy (@inforef{Toolbox
|
|
|
b32b45 |
introduction,,coreutils.info}) in mind: each program ``should do one
|
|
|
b32b45 |
thing well''. Inside @file{centos-art.sh} script, each specific
|
|
|
b32b45 |
functionality is considered a program that should do one thing well.
|
|
|
b32b45 |
Of course, if you find that they still don't do it, feel free to
|
|
|
b32b45 |
improve them in order for them to do so.
|
|
|
b32b45 |
|
|
|
b32b45 |
The specific functions of @file{centos-art.sh} script are organized
|
|
|
b32b45 |
inside specific directories under @file{trunk/Scripts/Functions}
|
|
|
b32b45 |
location. Each specific function directory should be named as the
|
|
|
b32b45 |
function it represents, with the first letter in uppercase. For
|
|
|
b32b45 |
example, if the function name is @code{render}, the specific function
|
|
|
b32b45 |
directory for it would be @samp{trunk/Scripts/Functions/Render}.
|
|
|
b32b45 |
|
|
|
b32b45 |
@subsubheading Creating the @code{greet} functionality
|
|
|
b32b45 |
|
|
|
b32b45 |
To better understand how to design specific functions for
|
|
|
b32b45 |
@file{centos-art.sh} script, let's create the @code{greet}
|
|
|
b32b45 |
functionality which only goal is to print out different kind of
|
|
|
b32b45 |
greetings to your screen. The @code{greet} functionality will be set
|
|
|
b32b45 |
using the follwiing directory structure:
|
|
|
b32b45 |
|
|
|
b32b45 |
@verbatim
|
|
|
b32b45 |
trunk/Scripts/Functions/Greet <-- The source location of greet function.
|
|
|
b32b45 |
|-- greet_getOptions.sh <-- Defines command-line interface.
|
|
|
b32b45 |
|-- greet_sayGoodbye.sh <-- Defines specific action.
|
|
|
b32b45 |
|-- greet_sayHello.sh <-- Defines specific action.
|
|
|
b32b45 |
`-- greet.sh <-- Defines function initialization.
|
|
|
b32b45 |
@end verbatim
|
|
|
b32b45 |
|
|
|
b32b45 |
The @file{greet.sh} file contains the initialization script of
|
|
|
b32b45 |
@code{greet} functionality. It is the first file loaded from function
|
|
|
b32b45 |
source location by @command{centos-art.sh} script when it is executed
|
|
|
b32b45 |
using the @code{greet} functionality as first argument.
|
|
|
b32b45 |
|
|
|
b32b45 |
Inside @file{centos-art.sh} script, as convenction, each function
|
|
|
b32b45 |
script has one top commentary, followed by one blank line, and then
|
|
|
b32b45 |
one function defintion below it only. The top commentary has the
|
|
|
b32b45 |
function description, one-line for copyright notice with your personal
|
|
|
b32b45 |
information, the license under which the function source code is
|
|
|
b32b45 |
released ---the @file{centos-art.sh} script is released as GPL, so do
|
|
|
b32b45 |
all its functions--- and the @code{$Id$} keyword of Subversion which
|
|
|
b32b45 |
is later expanded by @command{svn propset} command. In our example,
|
|
|
b32b45 |
the top comment of @code{greet.sh} function script would look like the
|
|
|
b32b45 |
following:
|
|
|
b32b45 |
|
|
|
b32b45 |
@verbatim
|
|
|
b32b45 |
#!/bin/bash
|
|
|
b32b45 |
#
|
|
|
b32b45 |
# greet.sh -- This function outputs different kind of greetings to
|
|
|
b32b45 |
# your screen. Use this function to understand how centos-art.sh
|
|
|
b32b45 |
# script specific functionalities work.
|
|
|
b32b45 |
#
|
|
|
b32b45 |
# Copyright (C) YEAR YOURFULLNAME
|
|
|
b32b45 |
#
|
|
|
b32b45 |
# This program is free software; you can redistribute it and/or modify
|
|
|
b32b45 |
# it under the terms of the GNU General Public License as published by
|
|
|
b32b45 |
# the Free Software Foundation; either version 2 of the License, or (at
|
|
|
b32b45 |
# your option) any later version.
|
|
|
b32b45 |
#
|
|
|
b32b45 |
# This program is distributed in the hope that it will be useful, but
|
|
|
b32b45 |
# WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
b32b45 |
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
|
b32b45 |
# General Public License for more details.
|
|
|
b32b45 |
#
|
|
|
b32b45 |
# You should have received a copy of the GNU General Public License
|
|
|
b32b45 |
# along with this program; if not, write to the Free Software
|
|
|
b32b45 |
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
|
b32b45 |
# ----------------------------------------------------------------------
|
|
|
b32b45 |
# $Id$
|
|
|
b32b45 |
# ----------------------------------------------------------------------
|
|
|
b32b45 |
|
|
|
b32b45 |
function greet {
|
|
|
b32b45 |
|
|
|
b32b45 |
# Define command-line interface.
|
|
|
b32b45 |
greet_getOptions
|
|
|
b32b45 |
|
|
|
b32b45 |
# Execute action name.
|
|
|
b32b45 |
if [[ $ACTIONNAM =~ "^${FUNCNAM}_[A-Za-z]+$" ]];then
|
|
|
b32b45 |
eval $ACTIONNAM
|
|
|
b32b45 |
else
|
|
|
b32b45 |
cli_printMessage "`gettext "A valid action is required."`" 'AsErrorLine'
|
|
|
b32b45 |
cli_printMessage "${FUNCDIRNAM}" 'AsToKnowMoreLine'
|
|
|
b32b45 |
fi
|
|
|
b32b45 |
|
|
|
b32b45 |
}
|
|
|
b32b45 |
@end verbatim
|
|
|
b32b45 |
|
|
|
b32b45 |
The first definition inside @code{greet} function is for variables
|
|
|
b32b45 |
that will be available along the whole execution environment of
|
|
|
b32b45 |
@code{greet} function. This time we didn't define any variable here
|
|
|
b32b45 |
so, we continued with definition of command-line interface, through
|
|
|
b32b45 |
@code{greet_getOptions} function.
|
|
|
b32b45 |
|
|
|
b32b45 |
The command-line interface of @code{greet} functionality defines how
|
|
|
b32b45 |
to interpret arguments passed from @command{centos-art.sh} script
|
|
|
b32b45 |
command-line. Inside @command{centos-art.sh} script, the
|
|
|
b32b45 |
interpretation of arguments passed through its command-line takes
|
|
|
b32b45 |
place by mean of @command{getopt} command and is written as the
|
|
|
b32b45 |
following code example describes:
|
|
|
b32b45 |
|
|
|
b32b45 |
@verbatim
|
|
|
b32b45 |
function greet_getOptions {
|
|
|
b32b45 |
|
|
|
b32b45 |
# Define short options we want to support.
|
|
|
b32b45 |
local ARGSS=""
|
|
|
b32b45 |
|
|
|
b32b45 |
# Define long options we want to support.
|
|
|
b32b45 |
local ARGSL="hello:,bye:,quiet"
|
|
|
b32b45 |
|
|
|
b32b45 |
# Redefine ARGUMENTS variable using getopt output.
|
|
|
b32b45 |
cli_doParseArguments
|
|
|
b32b45 |
|
|
|
b32b45 |
# Redefine positional parameters using ARGUMENTS variable.
|
|
|
b32b45 |
eval set -- "$ARGUMENTS"
|
|
|
b32b45 |
|
|
|
b32b45 |
# Look for options passed through command-line.
|
|
|
b32b45 |
while true; do
|
|
|
b32b45 |
|
|
|
b32b45 |
case "$1" in
|
|
|
b32b45 |
|
|
|
b32b45 |
--hello )
|
|
|
b32b45 |
ACTIONNAM="${FUNCNAM}_sayHello"
|
|
|
b32b45 |
ACTIONVAL="$2"
|
|
|
b32b45 |
shift 2
|
|
|
b32b45 |
;;
|
|
|
b32b45 |
|
|
|
b32b45 |
--bye )
|
|
|
b32b45 |
ACTIONNAM="${FUNCNAM}_sayGoodbye"
|
|
|
b32b45 |
ACTIONVAL="$2"
|
|
|
b32b45 |
shift 2
|
|
|
b32b45 |
;;
|
|
|
b32b45 |
|
|
|
b32b45 |
--quiet )
|
|
|
b32b45 |
FLAG_QUIET='true'
|
|
|
b32b45 |
shift 1
|
|
|
b32b45 |
;;
|
|
|
b32b45 |
|
|
|
b32b45 |
-- )
|
|
|
b32b45 |
# Remove the `--' argument from the list of arguments
|
|
|
b32b45 |
# in order for processing non-option arguments
|
|
|
b32b45 |
# correctly. At this point all option arguments have
|
|
|
b32b45 |
# been processed already but the `--' argument still
|
|
|
b32b45 |
# remains to mark ending of option arguments and
|
|
|
b32b45 |
# begining of non-option arguments. The `--' argument
|
|
|
b32b45 |
# needs to be removed here in order to avoid
|
|
|
b32b45 |
# centos-art.sh script to process it as a path inside
|
|
|
b32b45 |
# the repository, which obviously is not.
|
|
|
b32b45 |
shift 1
|
|
|
b32b45 |
break
|
|
|
b32b45 |
;;
|
|
|
b32b45 |
esac
|
|
|
b32b45 |
done
|
|
|
b32b45 |
|
|
|
b32b45 |
# Redefine ARGUMENTS variable using current positional parameters.
|
|
|
b32b45 |
cli_doParseArgumentsReDef "$@"
|
|
|
b32b45 |
|
|
|
b32b45 |
}
|
|
|
b32b45 |
@end verbatim
|
|
|
b32b45 |
|
|
|
b32b45 |
The @code{greet_sayHello} and @code{greet_sayGoodbye} function definitions
|
|
|
b32b45 |
are the core of @code{greet} specific functionality. In such function
|
|
|
b32b45 |
definitions we set what our @code{greet} function really does: to
|
|
|
b32b45 |
output different kinds of greetings.
|
|
|
b32b45 |
|
|
|
b32b45 |
@verbatim
|
|
|
b32b45 |
function greet_sayHello {
|
|
|
b32b45 |
|
|
|
b32b45 |
cli_printMessage "`gettext "Hello"`, $ACTIONVAL"
|
|
|
b32b45 |
|
|
|
b32b45 |
}
|
|
|
b32b45 |
@end verbatim
|
|
|
b32b45 |
|
|
|
b32b45 |
The @code{greet_sayHello} function definition is stored in
|
|
|
b32b45 |
@file{greet_sayHello.sh} function script.
|
|
|
b32b45 |
|
|
|
b32b45 |
@verbatim
|
|
|
b32b45 |
function greet_sayGoodbye {
|
|
|
b32b45 |
|
|
|
b32b45 |
cli_printMessage "`gettext "Goodbye"`, $ACTIONVAL"
|
|
|
b32b45 |
|
|
|
b32b45 |
}
|
|
|
b32b45 |
@end verbatim
|
|
|
b32b45 |
|
|
|
b32b45 |
The @code{greet_sayGoodbye} function definition is stored in the
|
|
|
b32b45 |
@file{greet_sayGoodbye.sh} function script.
|
|
|
b32b45 |
|
|
|
b32b45 |
@subsubheading Executing the @code{greet} functionality
|
|
|
b32b45 |
|
|
|
b32b45 |
To execute the @code{greet} specific functionality we've just created,
|
|
|
b32b45 |
pass the function name (i.e., @code{greet}) as first argument to
|
|
|
b32b45 |
@file{centos-art.sh} script and any of the valid options after it.
|
|
|
b32b45 |
Some examples are illustrated below:
|
|
|
b32b45 |
|
|
|
b32b45 |
@verbatim
|
|
|
b32b45 |
[centos@projects ~]$ centos-art greet --hello='World'
|
|
|
b32b45 |
Hello, World
|
|
|
b32b45 |
[centos@projects ~]$ centos-art greet --bye='World'
|
|
|
b32b45 |
Goodbye, World
|
|
|
b32b45 |
[centos@projects ~]$ centos-art greet --bye='World' --quiet
|
|
|
b32b45 |
[centos@projects ~]$
|
|
|
b32b45 |
@end verbatim
|
|
|
b32b45 |
|
|
|
b32b45 |
The word @samp{World} in the examples above can be anything. Likewise,
|
|
|
b32b45 |
if you need to change the way either the hello or goodbye messages are
|
|
|
b32b45 |
printed out, you can modifie the functions @code{greet_sayHello} and
|
|
|
b32b45 |
@code{greet_sayGoodbye}, respectively.
|
|
|
b32b45 |
|
|
|
b32b45 |
@subsubheading Documenting the @command{greet} functionality
|
|
|
b32b45 |
|
|
|
b32b45 |
Now that @code{greet} functionality works as we expect, it is time to
|
|
|
b32b45 |
document it. To document functionalities inside
|
|
|
b32b45 |
@command{centos-art.sh} script we use the function directory path as
|
|
|
b32b45 |
argument to the @code{help} functionality (@pxref{Directories trunk
|
|
|
b32b45 |
Scripts Functions Help}) of @file{centos-art.sh} script, just as the
|
|
|
b32b45 |
following command illustrates:
|
|
|
b32b45 |
|
|
|
b32b45 |
@verbatim
|
|
|
b32b45 |
centos-art help --edit trunk/Scripts/Functions/Greet
|
|
|
b32b45 |
@end verbatim
|
|
|
b32b45 |
|
|
|
b32b45 |
The function documentation helps to understand how the function really
|
|
|
b32b45 |
works and how it should be used. Also, when @command{centos-art.sh}
|
|
|
b32b45 |
script ends because an error, the documentation entry related to the
|
|
|
b32b45 |
functionality being currently executed is used as vehicle to
|
|
|
b32b45 |
communicate the user what is the correct way of using the
|
|
|
b32b45 |
functionality.
|
|
|
b32b45 |
|
|
|
b32b45 |
@subsubheading Localizing the @command{greet} functionality
|
|
|
b32b45 |
|
|
|
b32b45 |
Now that @code{greet} functionality has been documented, it is time to
|
|
|
b32b45 |
localize its output messages. Localizing specific functionalities of
|
|
|
b32b45 |
@command{centos-art.sh} script takes place as part of
|
|
|
b32b45 |
@command{centos-art.sh} script localization itself which is performed
|
|
|
b32b45 |
by applying the path @file{trunk/Scripts} to the @code{locale}
|
|
|
b32b45 |
functionality of @command{centos-art.sh} script.
|
|
|
b32b45 |
|
|
|
b32b45 |
As the @code{greet} functionality added new translatable strings to
|
|
|
b32b45 |
the @command{centos-art.sh} script, it is required to update the
|
|
|
b32b45 |
translation messages firstly, to add the new translatable strings from
|
|
|
b32b45 |
@code{greet} functionality to @command{centos-art.sh} script
|
|
|
b32b45 |
translation messages and then, edit the translation messages of
|
|
|
b32b45 |
@command{centos-art.sh} script to localize the new translatable
|
|
|
b32b45 |
strings that have been added. To achieve this, execute the following
|
|
|
b32b45 |
two commands:
|
|
|
b32b45 |
|
|
|
b32b45 |
@verbatim
|
|
|
b32b45 |
centos-art locale --update trunk/Scripts
|
|
|
b32b45 |
@end verbatim
|
|
|
b32b45 |
|
|
|
b32b45 |
@verbatim
|
|
|
b32b45 |
centos-art locale --edit trunk/Scripts
|
|
|
b32b45 |
@end verbatim
|
|
|
b32b45 |
|
|
|
b32b45 |
@quotation
|
|
|
b32b45 |
@strong{Warning} To translate output messages in different languages,
|
|
|
b32b45 |
your system locale information ---as in @env{LANG} environment
|
|
|
b32b45 |
variable--- must be set to that locale you want to produce translated
|
|
|
b32b45 |
messages for. For example, if you want to produce translated messages
|
|
|
b32b45 |
for Spanish language, your system locale information must be set to
|
|
|
b32b45 |
@samp{es_ES.UTF-8}, or similar, before executing the @code{locale}
|
|
|
b32b45 |
functionality of @command{centos-art.sh} script.
|
|
|
b32b45 |
@end quotation
|
|
|
b32b45 |
|
|
|
b32b45 |
Well, it seems that our example is rather complete by now.
|
|
|
b32b45 |
|
|
|
b32b45 |
@subsubheading Extending the @code{greet} functionality
|
|
|
b32b45 |
|
|
|
b32b45 |
In the @code{greet} functionality we've described so far, we only use
|
|
|
b32b45 |
@code{cli_printMessage} function in action specific function
|
|
|
b32b45 |
definitions in order to print messages, but more interesting things
|
|
|
b32b45 |
can be achieved inside action specific function definitions. For
|
|
|
b32b45 |
example, if you pass a directory path as argument, you could use it to
|
|
|
b32b45 |
retrive a list of files from therein and process them. If the list of
|
|
|
b32b45 |
files turns too long or you just want to control which files to
|
|
|
b32b45 |
process, so you could add another argument in the form
|
|
|
b32b45 |
@option{--filter='regex'} and reduce the list of files to process
|
|
|
b32b45 |
using a regular expression pattern.
|
|
|
b32b45 |
|
|
|
b32b45 |
In case you consider to extend the @code{greet} functionality to do
|
|
|
b32b45 |
something different but print out grettings, consider changing the
|
|
|
b32b45 |
function name from @code{greet} to something more appropriate, as
|
|
|
b32b45 |
well. The name change must be coherent with the actions the new
|
|
|
b32b45 |
function is designed to perform.
|
|
|
b32b45 |
|
|
|
b32b45 |
If you doubt what name is better for your functionality, write to
|
|
|
b32b45 |
@email{centos-devel@@centos.org} mailing list, explain what your
|
|
|
b32b45 |
functionality intends to do and request suggestion about what name
|
|
|
b32b45 |
would be more appropriate for it. That would be also very convenient
|
|
|
b32b45 |
for you, in order to evaluate the purposes of your function and what
|
|
|
b32b45 |
the community thinks about it. It is a way for you to gather ideas
|
|
|
b32b45 |
that help you to write using the community feeling as base.
|
|
|
b32b45 |
|
|
|
b32b45 |
If your function passes the community evaluation, that is a good sign
|
|
|
b32b45 |
for you to start/keep writing it. However, if it doesn't, it is time
|
|
|
b32b45 |
for you to rethink what you are doing and ask again until it passes
|
|
|
b32b45 |
the community evaluation. You can considered you've passed the
|
|
|
b32b45 |
community evaluation when after proposing your idea, you get a
|
|
|
b32b45 |
considerable amount of possitve responses for what you are doing,
|
|
|
b32b45 |
specially if those responses come from community leaders.
|
|
|
b32b45 |
|
|
|
b32b45 |
It is very hard to do something useful for a community of people
|
|
|
b32b45 |
without any point of contact with that community you are trying to do
|
|
|
b32b45 |
things for. How could you know you are doing something that is needed
|
|
|
b32b45 |
if you don't know what the needs are? So, explore the community needs
|
|
|
b32b45 |
first, define them, work them out and repeat the process time after
|
|
|
b32b45 |
time, even when you might think the need has been already satisfied.
|
|
|
b32b45 |
At that point, surely, you'll find smaller needs that need to be
|
|
|
b32b45 |
satisfied, as well.
|
|
|
b32b45 |
|
|
|
b32b45 |
@subsubheading Conclusions
|
|
|
b32b45 |
|
|
|
b32b45 |
The @code{greet} functionality described in this section may serve as
|
|
|
b32b45 |
introduction for you to understand how specific functionalities are
|
|
|
b32b45 |
created inside @file{centos-art.sh} script. With some of luck this
|
|
|
b32b45 |
introduction will also serve you as motivation to create your own
|
|
|
b32b45 |
specific functionalities for @file{centos-art.sh} script.
|
|
|
b32b45 |
|
|
|
b32b45 |
By the way, the @code{greet} functionality doesn't exist inside
|
|
|
b32b45 |
@file{centos-art.sh} script yet. Would you like to create it?
|
|
|
b32b45 |
|
|
|
b32b45 |
@subheading Usage
|
|
|
b32b45 |
|
|
|
b32b45 |
The following specific functions of @file{centos-art.sh} script, are
|
|
|
b32b45 |
available for you to use:
|
|
|
b32b45 |
|
|
|
b32b45 |
@itemize
|
|
|
b32b45 |
@item @xref{Directories trunk Scripts Functions Help}.
|
|
|
b32b45 |
@item @xref{Directories trunk Scripts Functions Locale}.
|
|
|
b32b45 |
@item @xref{Directories trunk Scripts Functions Prepare}.
|
|
|
b32b45 |
@item @xref{Directories trunk Scripts Functions Render}.
|
|
|
b32b45 |
@item @xref{Directories trunk Scripts Functions Tuneup}.
|
|
|
b32b45 |
@end itemize
|
|
|
b32b45 |
|
|
|
b32b45 |
@subheading See also
|
|
|
b32b45 |
|
|
|
b32b45 |
@itemize
|
|
|
b32b45 |
@item @ref{Directories trunk Scripts}
|
|
|
b32b45 |
@item @ref{Directories trunk}
|
|
|
b32b45 |
@end itemize
|