| @subheading Goals |
| |
| The @file{trunk/Scripts/Functions} directory exists to organize |
| @file{centos-art.sh} specific functionalities. |
| |
| @subheading Description |
| |
| The specific functions of @file{centos-art.sh} script are designed |
| with the ``Software Toolbox'' philosophy (@inforef{Toolbox |
| introduction,,coreutils.info}) in mind: each program ``should do one |
| thing well''. Inside @file{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 @file{centos-art.sh} script are organized |
| inside specific directories under @file{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 @code{render}, the specific function |
| directory for it would be @samp{trunk/Scripts/Functions/Render}. |
| |
| @subsubheading Creating the @code{greet} functionality |
| |
| To better understand how to design specific functions for |
| @file{centos-art.sh} script, let's create the @code{greet} |
| functionality which only goal is to print out different kind of |
| greetings to your screen. The @code{greet} functionality will be set |
| using the follwiing directory structure: |
| |
| @verbatim |
| trunk/Scripts/Functions/Greet <-- The source location of greet function. |
| |-- greet_getArguments.sh <-- Defines command-line interface. |
| |-- greet_sayGoodbye.sh <-- Defines specific action. |
| |-- greet_sayHello.sh <-- Defines specific action. |
| `-- greet.sh <-- Defines function initialization. |
| @end verbatim |
| |
| The @file{greet.sh} file contains the initialization script of |
| @code{greet} functionality. It is the first file loaded from function |
| source location by @command{centos-art.sh} script when it is executed |
| using the @code{greet} functionality as first argument. |
| |
| Inside @file{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 @file{centos-art.sh} script is released as GPL, so do |
| all its functions--- and the @code{$Id$} keyword of Subversion which |
| is later expanded by @command{svn propset} command. In our example, |
| the top comment of @code{greet.sh} function script would look like the |
| following: |
| |
| @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) 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_getArguments |
| |
| # 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 |
| |
| } |
| @end verbatim |
| |
| The first definition inside @code{greet} function is for variables |
| that will be available along the whole execution environment of |
| @code{greet} function. This time we didn't define any variable here |
| so, we continued with definition of command-line interface, through |
| @code{greet_getArguments} function. |
| |
| The command-line interface of @code{greet} functionality defines how |
| to interpret arguments passed from @command{centos-art.sh} script |
| command-line. Inside @command{centos-art.sh} script, the |
| interpretation of arguments passed through its command-line takes |
| place by mean of @command{getopt} command and is written as the |
| following code example describes: |
| |
| @verbatim |
| function greet_getArguments { |
| |
| # 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 |
| ;; |
| |
| -- ) |
| # 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 |
| |
| |
| |
| |
| |
| shift 1 |
| break |
| ;; |
| esac |
| done |
| |
| |
| cli_doParseArgumentsReDef "$@" |
| |
| } |
| @end verbatim |
| |
| The @code{greet_sayHello} and @code{greet_sayGoodbye} function definitions |
| are the core of @code{greet} specific functionality. In such function |
| definitions we set what our @code{greet} function really does: to |
| output different kinds of greetings. |
| |
| @verbatim |
| function greet_sayHello { |
| |
| cli_printMessage "`gettext "Hello"`, $ACTIONVAL" |
| |
| } |
| @end verbatim |
| |
| The @code{greet_sayHello} function definition is stored in |
| @file{greet_sayHello.sh} function script. |
| |
| @verbatim |
| function greet_sayGoodbye { |
| |
| cli_printMessage "`gettext "Goodbye"`, $ACTIONVAL" |
| |
| } |
| @end verbatim |
| |
| The @code{greet_sayGoodbye} function definition is stored in the |
| @file{greet_sayGoodbye.sh} function script. |
| |
| @subsubheading Executing the @code{greet} functionality |
| |
| To execute the @code{greet} specific functionality we've just created, |
| pass the function name (i.e., @code{greet}) as first argument to |
| @file{centos-art.sh} script and any of the valid options after it. |
| Some examples are illustrated below: |
| |
| @verbatim |
| [centos@projects ~]$ centos-art greet --hello='World' |
| Hello, World |
| [centos@projects ~]$ centos-art greet --bye='World' |
| Goodbye, World |
| [centos@projects ~]$ |
| @end verbatim |
| |
| The word @samp{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 @code{greet_sayHello} and |
| @code{greet_sayGoodbye}, respectively. |
| |
| @subsubheading Documenting the @command{greet} functionality |
| |
| Now that @code{greet} functionality works as we expect, it is time to |
| document it. To document functionalities inside |
| @command{centos-art.sh} script we use the function directory path as |
| argument to the @code{help} functionality (@pxref{Directories trunk |
| Scripts Functions Help}) of @file{centos-art.sh} script, just as the |
| following command illustrates: |
| |
| @verbatim |
| centos-art help --edit trunk/Scripts/Functions/Greet |
| @end verbatim |
| |
| The function documentation helps to understand how the function really |
| works and how it should be used. Also, when @command{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. |
| |
| @subsubheading Localizing the @command{greet} functionality |
| |
| Now that @code{greet} functionality has been documented, it is time to |
| localize its output messages. Localizing specific functionalities of |
| @command{centos-art.sh} script takes place as part of |
| @command{centos-art.sh} script localization itself which is performed |
| by applying the path @file{trunk/Scripts} to the @code{locale} |
| functionality of @command{centos-art.sh} script. |
| |
| As the @code{greet} functionality added new translatable strings to |
| the @command{centos-art.sh} script, it is required to update the |
| translation messages firstly, to add the new translatable strings from |
| @code{greet} functionality to @command{centos-art.sh} script |
| translation messages and then, edit the translation messages of |
| @command{centos-art.sh} script to localize the new translatable |
| strings that have been added. To achieve this, execute the following |
| two commands: |
| |
| @verbatim |
| centos-art locale --update trunk/Scripts |
| centos-art locale --edit trunk/Scripts |
| @end verbatim |
| |
| @quotation |
| @strong{Warning} To translate output messages in different languages, |
| your system locale information ---as in @env{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 |
| @samp{es_ES.UTF-8}, or similar, before executing the @code{locale} |
| functionality of @command{centos-art.sh} script. |
| @end quotation |
| |
| Well, it seems that our example is rather complete by now. |
| |
| @subsubheading Extending the @code{greet} functionality |
| |
| In the @code{greet} functionality we've described so far, we only use |
| @code{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 |
| @option{--filter='regex'} and reduce the list of files to process |
| using a regular expression pattern. |
| |
| In case you consider to extend the @code{greet} functionality to do |
| something different but print out grettings, consider changing the |
| function name from @code{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 |
| @email{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. |
| |
| @subsubheading Conclusions |
| |
| The @code{greet} functionality described in this section may serve as |
| introduction for you to understand how specific functionalities are |
| created inside @file{centos-art.sh} script. With some of luck this |
| introduction will also serve you as motivation to create your own |
| specific functionalities for @file{centos-art.sh} script. |
| |
| By the way, the @code{greet} functionality doesn't exist inside |
| @file{centos-art.sh} script yet. Would you like to create it? |
| |
| @subheading Usage |
| |
| The following specific functions of @file{centos-art.sh} script, are |
| available for you to use: |
| |
| @itemize |
| @item @xref{Directories trunk Scripts Functions Help}. |
| @item @xref{Directories trunk Scripts Functions Locale}. |
| @item @xref{Directories trunk Scripts Functions Prepare}. |
| @item @xref{Directories trunk Scripts Functions Render}. |
| @item @xref{Directories trunk Scripts Functions Tuneup}. |
| @end itemize |
| |
| @subheading See also |
| |
| @itemize |
| @item @ref{Directories trunk Scripts} |
| @item @ref{Directories trunk} |
| @end itemize |
| |