Blame Manual/Directories/trunk/Scripts/Functions.texi

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