Goals
-----

The trunk/Scripts/Functions directory exists to organize centos-art.sh specific functionalities.

Description
-----------

The specific functions of centos-art.sh script are designed with the ``Software Toolbox'' philosophy (see Toolbox introduction (coreutils.info)) in mind: each program ``should do one thing well''.  Inside centos-art.sh 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.

The specific functions of centos-art.sh script are organized inside specific directories under trunk/Scripts/Functions 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 render, the specific function directory for it would be trunk/Scripts/Functions/Render.

Creating the greet functionality
................................

To better understand how to design specific functions for centos-art.sh script, let's create the greet functionality which only goal is to print out different kind of greetings to your screen.  The greet functionality will be set using the follwiing directory structure:

trunk/Scripts/Functions/Greet   <-- The source location of greet function.
|-- greet_getOptions.sh         <-- Defines command-line interface.
|-- greet_sayGoodbye.sh         <-- Defines specific action.
|-- greet_sayHello.sh           <-- Defines specific action.
`-- greet.sh                    <-- Defines function initialization.

The greet.sh file contains the initialization script of greet functionality. It is the first file loaded from function source location by centos-art.sh script when it is executed using the greet functionality as first argument.

Inside centos-art.sh script, as convenction, each function script has one top commentary, followed by one blank line, and then one function defintion below it only.  The top commentary has the function description, one-line for copyright notice with your personal information,  the license under which the function source code is released ---the centos-art.sh script is released as GPL, so do all its functions--- and the $Id$ keyword of Subversion which is later expanded by svn propset command.  In our example, the top comment of greet.sh function script would look like the following:

#!/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) YEAR YOURFULLNAME
#
# 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., 675 Mass Ave, Cambridge, MA 02139, USA.
# ----------------------------------------------------------------------
# $Id$
# ----------------------------------------------------------------------

function greet {

    # Define command-line interface.
    greet_getOptions

    # Execute action name.
    if [[ $ACTIONNAM =~ "^${FUNCNAM}_[A-Za-z]+$" ]];then
        eval $ACTIONNAM
    else
        cli_printMessage "`gettext "A valid action is required."`" 'AsErrorLine'
        cli_printMessage "${FUNCDIRNAM}" 'AsToKnowMoreLine'
    fi

}

The first definition inside greet function is for variables that will be available along the whole execution environment of greet function. This time we didn't define any variable here so, we continued with definition of command-line interface, through greet_getOptions function.

The command-line interface of greet functionality defines how to interpret arguments passed from centos-art.sh script command-line.  Inside centos-art.sh script, the interpretation of arguments passed through its command-line takes place by mean of getopt command and is written as the following code example describes:

function greet_getOptions {

    # Define short options we want to support.
    local ARGSS=""

    # Define long options we want to support.
    local ARGSL="hello:,bye:,quiet"

    # Redefine ARGUMENTS variable using getopt output.
    cli_doParseArguments

    # Redefine positional parameters using ARGUMENTS variable.
    eval set -- "$ARGUMENTS"

    # Look for options passed through command-line.
    while true; do

        case "$1" in

            --hello )
                ACTIONNAM="${FUNCNAM}_sayHello"
                ACTIONVAL="$2"
                shift 2
                ;;

            --bye )
                ACTIONNAM="${FUNCNAM}_sayGoodbye"
                ACTIONVAL="$2"
                shift 2
                ;;

            --quiet )
                FLAG_QUIET='true'
                shift 1
                ;;

            -- )
                # Remove the `--' argument from the list of arguments
                # in order for processing non-option arguments
                # correctly. At this point all option arguments have
                # been processed already but the `--' argument still
                # remains to mark ending of option arguments and
                # begining of non-option arguments. The `--' argument
                # needs to be removed here in order to avoid
                # centos-art.sh script to process it as a path inside
                # the repository, which obviously is not.
                shift 1
                break
                ;;
        esac
    done

    # Redefine ARGUMENTS variable using current positional parameters.
    cli_doParseArgumentsReDef "$@"

}

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

function greet_sayHello {

    cli_printMessage "`gettext "Hello"`, $ACTIONVAL"

}

The greet_sayHello function definition is stored in greet_sayHello.sh function script.

function greet_sayGoodbye {

    cli_printMessage "`gettext "Goodbye"`, $ACTIONVAL"

}

The greet_sayGoodbye function definition is stored in the greet_sayGoodbye.sh function script.

Executing the greet functionality
.................................

To execute the greet specific functionality we've just created, pass the function name (i.e., greet) as first argument to centos-art.sh script and any of the valid options after it. Some examples are illustrated below:

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

The word World in the examples above can be anything. Likewise, if you need to change the way either the hello or goodbye messages are printed out, you can modifie the functions greet_sayHello and greet_sayGoodbye, respectively.

Documenting the greet functionality
...................................

Now that greet functionality works as we expect, it is time to document it.  To document functionalities inside centos-art.sh script we use the function directory path as argument to the help functionality (see Directories trunk Scripts Functions Help) of centos-art.sh script, just as the following command illustrates:

centos-art help --edit trunk/Scripts/Functions/Greet

The function documentation helps to understand how the function really works and how it should be used.  Also, when centos-art.sh script ends because an error, the documentation entry related to the functionality being currently executed is used as vehicle to communicate the user what is the correct way of using the functionality.

Localizing the greet functionality
..................................

Now that greet functionality has been documented, it is time to localize its output messages. Localizing specific functionalities of centos-art.sh script takes place as part of centos-art.sh script localization itself which is performed by applying the path trunk/Scripts to the locale functionality of centos-art.sh script.

As the greet functionality added new translatable strings to the centos-art.sh script, it is required to update the translation messages firstly, to add the new translatable strings from greet functionality to centos-art.sh script translation messages and then, edit the translation messages of centos-art.sh script to localize the new translatable strings that have been added. To achieve this, execute the following two commands:

centos-art locale --update trunk/Scripts

centos-art locale --edit trunk/Scripts

     Warning To translate output messages in different languages, your system locale information ---as in LANG environment variable--- must be set to that locale you want to produce translated messages for. For example, if you want to produce translated messages for Spanish language, your system locale information must be set to es_ES.UTF-8, or similar, before executing the locale functionality of centos-art.sh script.

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

Extending the greet functionality
.................................

In the greet functionality we've described so far, we only use cli_printMessage function in action specific function definitions in order to print messages, but more interesting things can be achieved inside action specific function definitions.  For example, if you pass a directory path as argument, you could use it to retrive a list of files from therein and process them. If the list of files turns too long or you just want to control which files to process, so you could add another argument in the form --filter='regex' and reduce the list of files to process using a regular expression pattern.

In case you consider to extend the greet functionality to do something different but print out grettings, consider changing the function name from greet to something more appropriate, as well. The name change must be coherent with the actions the new function is designed to perform.

If you doubt what name is better for your functionality, write to centos-devel@centos.org mailing list, explain what your functionality intends to do and request suggestion about what name would be more appropriate for it. That would be also very convenient for you, in order to evaluate the purposes of your function and what the community thinks about it. It is a way for you to gather ideas that help you to write using the community feeling as base.

If your function passes the community evaluation, that is a good sign for you to start/keep writing it. However, if it doesn't, it is time for you to rethink what you are doing and ask again until it passes the community evaluation. You can considered you've passed the community evaluation when after proposing your idea, you get a considerable amount of possitve responses for what you are doing, specially if those responses come from community leaders.

It is very hard to do something useful for a community of people without any point of contact with that community you are trying to do things for.  How could you know you are doing something that is needed if you don't know what the needs are?  So, explore the community needs first, define them, work them out and repeat the process time after time, even when you might think the need has been already satisfied. At that point, surely, you'll find smaller needs that need to be satisfied, as well.

Conclusions
...........

The greet functionality described in this section may serve as introduction for you to understand how specific functionalities are created inside centos-art.sh script. With some of luck this introduction will also serve you as motivation to create your own specific functionalities for centos-art.sh script.

By the way, the greet functionality doesn't exist inside centos-art.sh script yet. Would you like to create it?

Usage
-----

The following specific functions of centos-art.sh script, are available for you to use:

  * See Directories trunk Scripts Functions Help.

  * See Directories trunk Scripts Functions Locale.

  * See Directories trunk Scripts Functions Prepare.

  * See Directories trunk Scripts Functions Render.

  * See Directories trunk Scripts Functions Tuneup.

See also
--------

  * Directories trunk Scripts

  * Directories trunk