Understanding Modules

=====================

Alain Reguera Delgado <al@centos.org.cu>

v0.1, Oct 2013

Overview

--------

From version 0.5, the *centos-art.sh* script introduces the idea of

modules to its base design. Modules are a collection of functions

written in Bash that can call one another to create individual

execution environments. They may be nested to achieve high levels of

maintainability and extensibility. This make possible for modules

writers to divide complicated tasks into smaller tasks that can be

easier to debug, maintain and share with other modules efficiently

(e.g., instead of loading modules all at once, they are only loaded at

demand and unset once they conclude their execution).

This article describes the modular design of *centos-art.sh* script.

It is a good place for you to start if you are planning to contribute

new module environments to *centos-art.sh* script or want to know more

about how it works. The next section delves into what a module

environment is, the three module types you can find in it and the

correct way of execute each one of them.

[[module-environment]]

Module Environment

------------------

When you execute the *centos-art.sh* script you create an execution

environment in which variables and functions are defined. The

execution environment is the higher environment inside *centos-art.sh*

script. It is considered to have a ``global'' scope, so variables and

functions defined in it are always available for any function

execution made from it. You can control the execution environment of

*centos-art.sh* script through files +centos-art.sh+ and

+centos-art.conf.sh+. These files don't provide too much functionality

so module environments are executed from +centos-art.sh+, to extend

its functionality.

Module environments are made of small functions that perform small

tasks and can be further executed in a specific order to produce the

desired result.  Module environments are executed and destroyed at

demand.  Inside *centos-art.sh*, module environments can be either

``parent modules,'' ``child modules,'' or ``sibling modules.''

[[module-environment-parent]]

Parent Modules

~~~~~~~~~~~~~~

Parent modules are initiated by executing the

*tcar_setModuleEnvironment* function with the *-t parent* option set

on it. Parent modules are very simple in design and you can use them

to implement simple solutions quickly. Normally, when you execute a

parent module, you initiate the highest module environment possible

inside *centos-art.sh* script.  Because of such high scope, parent

modules are frequently used to define module's global variables,

interpret module-specific options passed through the command-line and

execute the appropriate actions based on them.

In <<debug-parent-modules>>, we have executed the *hello* module with

the *--greeting=hi* and *--debug* options through the command-line. In

this example, *centos-art.sh* script executes a parent module named

*hello*, processes the module-specific options passed through the

command-line, prints a greeting message to standard output and exits

successfully.

[[debug-parent-modules]]

.Debugging execution of parent modules

======================================================================

----------------------------------------------------------------------

Thu 10 Oct 2013 11:53:28 PM CDT =========================>      [0] | main

Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules

Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_NAME                [0]=hello

Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_TYPE                parent

Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_ARGUMENT            --greeting=hi  

Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_LIST                hello|help|locale|prepare|render|tuneup|vcs

Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello

Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules

Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Manuals

Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Locales

Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Configs

Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/hello.sh

Thu 10 Oct 2013 11:53:28 PM CDT TEXTDOMAIN                      hello.sh

Thu 10 Oct 2013 11:53:28 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Locales

Thu 10 Oct 2013 11:53:28 PM CDT export -f                       hello

Thu 10 Oct 2013 11:53:28 PM CDT export -f                       hello_getOptions

Thu 10 Oct 2013 11:53:28 PM CDT ------------------------->      hello --greeting=hi  

hi             

Thu 10 Oct 2013 11:53:28 PM CDT <-------------------------      hello 

Thu 10 Oct 2013 11:53:28 PM CDT unset -f                        hello

Thu 10 Oct 2013 11:53:28 PM CDT unset -f                        hello_getOptions

Thu 10 Oct 2013 11:53:28 PM CDT <=========================      [0] | main

----------------------------------------------------------------------

======================================================================

<<debug-parent-modules>> describes an entire module environment in

action. With this information you can create your own module

environment, already. However, when your module is getting too much

complicated you probably want to divide it in smaller pieces that you

can execute accordingly, based on the purpose you defined for it. Such

kind of division can be implemented through ``modules' related

functions.''

Module's related functions are stored in the same directory of your

module's initialization file and they are very useful when you are

refactoring it.  Definitions of module's related functions are loaded

before the initialization file does, so it is a good practice to

create them only when you are absolutely sure they will be executed in

your module. Otherwise they may be loaded and never be used, which

make the script to waste memory unnecessarily. In these cases, when

you need to divide the logic of a module in smaller pieces where these

pieces may or may not be executed based on specific conditions, all

taking place in the same iteration, then using ``_child modules_'' is

a more suitable approach.

Child Modules

~~~~~~~~~~~~~

Child modules are initiated by executing the

*tcar_setModuleEnvironment* function with the *-t child* option set on

it.  Child modules have the characteristic of being nested modules.

They cannot be executed from the command-line. Normally, child modules

are executed from parent modules but they can be executed from other

child modules, too.  When several child modules are executed in one

single iteration of *centos-art.sh*, they create a chain of modules.

A chain of modules is very useful in situations where you want to

divide one large task into smaller tasks and also control which of

these smaller tasks is executed based on specific conditions (e.g.,

you may want to render images or documentation, but not both, in one

single iteration of *centos-art.sh* script).  In a chain of modules,

lower modules in the chain (those started last) have access to

information set by modules higher in the chain (those started first),

but not the opposite. When processing information this way, modules

aren't destroyed until the last module executed in the chain has

finished its work (e.g., all the commands inside it have been

executed). At that point, child modules are destroyed in the reverse

order they were executed.

For example, when you execute the *hello* module with both *--debug*

and *--upper* option, *centos-art.sh* script creates a chain of three

modules to produce the greeting message.  Firstly, it begins by

executing the parent module named *hello*, then it continues with the

child module named *output* which in turn executes the child module

name *lower* to finally print the expected greeting message.  In this

example, the module named *lower* is the last module in the chain of

executed modules. It has access to all information defined by earlier

modules (e.g., in *hello* and *output* modules) and none of its earlier

modules will be destroyed until it has finished its work. This process

becomes more visible when you take a look at <<debug-child-modules>>.

[[debug-child-modules]]

.Debugging execution of child modules

======================================================================

----------------------------------------------------------------------

Thu 10 Oct 2013 11:52:41 PM CDT =========================>      [0] | main

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_NAME                [0]=hello

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_TYPE                parent

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_ARGUMENT            --upper --greeting=hi  

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_LIST                hello|help|locale|prepare|render|tuneup|vcs

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Manuals

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Locales

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Configs

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/hello.sh

Thu 10 Oct 2013 11:52:41 PM CDT TEXTDOMAIN                      hello.sh

Thu 10 Oct 2013 11:52:41 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Locales

Thu 10 Oct 2013 11:52:41 PM CDT export -f                       hello

Thu 10 Oct 2013 11:52:41 PM CDT export -f                       hello_getOptions

Thu 10 Oct 2013 11:52:41 PM CDT ------------------------->      hello --upper --greeting=hi  

Thu 10 Oct 2013 11:52:41 PM CDT =========================>      [1] | hello

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_NAME                [1]=output

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_TYPE                child

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_ARGUMENT             

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_LIST                output

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Manuals

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Locales

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Configs

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/output.sh

Thu 10 Oct 2013 11:52:41 PM CDT TEXTDOMAIN                      output.sh

Thu 10 Oct 2013 11:52:41 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Locales

Thu 10 Oct 2013 11:52:41 PM CDT export -f                       output

Thu 10 Oct 2013 11:52:41 PM CDT ------------------------->      output  

Thu 10 Oct 2013 11:52:41 PM CDT =========================>      [2] | output

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules/Output/Modules

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_NAME                [2]=upper

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_TYPE                child

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_ARGUMENT             

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_LIST                camel|lower|random|upper

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output/Modules/Upper

Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules/Upper/Modules

Thu 10 Oct 2013 11:52:42 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Modules/Upper/Manuals

Thu 10 Oct 2013 11:52:42 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Modules/Upper/Locales

Thu 10 Oct 2013 11:52:42 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Modules/Upper/Configs

Thu 10 Oct 2013 11:52:42 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/Modules/Upper/upper.sh

Thu 10 Oct 2013 11:52:42 PM CDT TEXTDOMAIN                      upper.sh

Thu 10 Oct 2013 11:52:42 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Modules/Upper/Locales

Thu 10 Oct 2013 11:52:42 PM CDT export -f                       upper

Thu 10 Oct 2013 11:52:42 PM CDT ------------------------->      upper  

HI             

Thu 10 Oct 2013 11:52:42 PM CDT <-------------------------      upper  

Thu 10 Oct 2013 11:52:42 PM CDT unset -f                        upper

Thu 10 Oct 2013 11:52:42 PM CDT <=========================      [2] | output 

Thu 10 Oct 2013 11:52:42 PM CDT <-------------------------      output  

Thu 10 Oct 2013 11:52:42 PM CDT unset -f                        output

Thu 10 Oct 2013 11:52:42 PM CDT <=========================      [1] | hello 

Thu 10 Oct 2013 11:52:42 PM CDT <-------------------------      hello 

Thu 10 Oct 2013 11:52:42 PM CDT unset -f                        hello

Thu 10 Oct 2013 11:52:42 PM CDT unset -f                        hello_getOptions

Thu 10 Oct 2013 11:52:42 PM CDT <=========================      [0] | main 

----------------------------------------------------------------------

======================================================================

The module environment described in <<debug-child-modules>> shows the

child modules' ability of reducing scope as they get deeper in the

chain of executed modules. However, child modules lack the possibility

of nest modules that share the same scope. For example, in the *hello*

module described above, you cannot execute the modules *lower*  or

*upper* from *camel* module, as if they were child modules of it.

That is not possible because they all have the same scope, which is,

to print the greeting message to standard output. Child modules are

conceived to reduce the module scope as new child modules are

executed. When you need to execute new module environments and, also,

retain the last scope from which the new module is executed, you need

to use ``_sibling modules_,'' instead.

Sibling Modules

~~~~~~~~~~~~~~~

Sibling modules are initiated by executing the

*tcar_setModuleEnvironment* function with the *-t sibling* option set

on it.  Sibling modules are another type of nested modules but, in

contrast with child modules, sibling modules cannot be executed from

parent modules. Normally, sibling modules are executed from other

sibling modules but, considering the context, they can be executed

from child module too, to initiate sibling processing. When several

siblings modules are executed, they also build a chain of modules. In

contrast with the chain of child modules, the chain of sibling modules

destroys the last sibling module executed before executing the next

sibling module. This make the chain to stop its growing at sibling

module processing, unless you call a child module from a sibling

module. In this case, the chain expansion would continue as long as

the number of child modules you execute. This process becomes more

visible when you take a look at <<debug-sibling-modules>>.

In <<debug-sibling-modules>>, we've executed the *hello* module with

the *--greeting=hi*, *--camel*, and *--debug* options. In this

example, *centos-art.sh* script executes the *hello* module then the

*output* module which in turn executes the *camel* module. At this

point, can appreciate how the chain of modules stop growing. Observe

that *camel* module has gained the position 2 in the chain of modules

and executes the *upper* module which takes the position 3, as

expected. Now, when *upper* module finishes its work it is destroyed

and the module's counter is reset to its previous value which is 2

(the one set by *camel* module). Then, *camel* executes the *lower*

module which take position 3 at the chain of modules until it

finishes. When it finishes, the *camel* module finishes its work and

is destroyed, then *output*, then *hello*.

[[debug-sibling-modules]]

.Debugging execution of sibling modules

======================================================================

----------------------------------------------------------------------

Thu 10 Oct 2013 11:51:42 PM CDT =========================>      [0] | main

Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules

Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_NAME                [0]=hello

Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_TYPE                parent

Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_ARGUMENT            --camel --greeting=hi  

Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_LIST                hello|help|locale|prepare|render|tuneup|vcs

Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello

Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules

Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Manuals

Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Locales

Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Configs

Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/hello.sh

Thu 10 Oct 2013 11:51:42 PM CDT TEXTDOMAIN                      hello.sh

Thu 10 Oct 2013 11:51:42 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Locales

Thu 10 Oct 2013 11:51:43 PM CDT export -f                       hello

Thu 10 Oct 2013 11:51:43 PM CDT export -f                       hello_getOptions

Thu 10 Oct 2013 11:51:43 PM CDT ------------------------->      hello --camel --greeting=hi  

Thu 10 Oct 2013 11:51:43 PM CDT =========================>      [1] | hello

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_NAME                [1]=output

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_TYPE                child

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_ARGUMENT             

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_LIST                output

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Manuals

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Locales

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Configs

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/output.sh

Thu 10 Oct 2013 11:51:43 PM CDT TEXTDOMAIN                      output.sh

Thu 10 Oct 2013 11:51:43 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Locales

Thu 10 Oct 2013 11:51:43 PM CDT export -f                       output

Thu 10 Oct 2013 11:51:43 PM CDT ------------------------->      output  

Thu 10 Oct 2013 11:51:43 PM CDT =========================>      [2] | output

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules/Output/Modules

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_NAME                [2]=camel

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_TYPE                child

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_ARGUMENT             

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_LIST                camel|lower|random|upper

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output/Modules/Camel

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules/Camel/Modules

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Modules/Camel/Manuals

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Modules/Camel/Locales

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Modules/Camel/Configs

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/Modules/Camel/camel.sh

Thu 10 Oct 2013 11:51:43 PM CDT TEXTDOMAIN                      camel.sh

Thu 10 Oct 2013 11:51:43 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Modules/Camel/Locales

Thu 10 Oct 2013 11:51:43 PM CDT export -f                       camel

Thu 10 Oct 2013 11:51:43 PM CDT ------------------------->      camel  

Thu 10 Oct 2013 11:51:43 PM CDT =========================>      [3] | camel

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules/Output/Modules

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_NAME                [3]=upper

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_TYPE                sibling

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_ARGUMENT             

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_LIST                camel|lower|random|upper

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output/Modules/Upper

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules/Upper/Modules

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Modules/Upper/Manuals

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Modules/Upper/Locales

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Modules/Upper/Configs

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/Modules/Upper/upper.sh

Thu 10 Oct 2013 11:51:43 PM CDT TEXTDOMAIN                      upper.sh

Thu 10 Oct 2013 11:51:43 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Modules/Upper/Locales

Thu 10 Oct 2013 11:51:43 PM CDT export -f                       upper

Thu 10 Oct 2013 11:51:43 PM CDT ------------------------->      upper  

H              

Thu 10 Oct 2013 11:51:43 PM CDT <-------------------------      upper  

Thu 10 Oct 2013 11:51:43 PM CDT unset -f                        upper

Thu 10 Oct 2013 11:51:43 PM CDT <=========================      [3] | camel 

Thu 10 Oct 2013 11:51:43 PM CDT =========================>      [3] | camel

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules/Output/Modules

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_NAME                [3]=lower

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_TYPE                sibling

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_ARGUMENT             

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_LIST                camel|lower|random|upper

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output/Modules/Lower

Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules/Lower/Modules

Thu 10 Oct 2013 11:51:44 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Modules/Lower/Manuals

Thu 10 Oct 2013 11:51:44 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Modules/Lower/Locales

Thu 10 Oct 2013 11:51:44 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Modules/Lower/Configs

Thu 10 Oct 2013 11:51:44 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/Modules/Lower/lower.sh

Thu 10 Oct 2013 11:51:44 PM CDT TEXTDOMAIN                      lower.sh

Thu 10 Oct 2013 11:51:44 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Modules/Lower/Locales

Thu 10 Oct 2013 11:51:44 PM CDT export -f                       lower

Thu 10 Oct 2013 11:51:44 PM CDT ------------------------->      lower  

i              

Thu 10 Oct 2013 11:51:44 PM CDT <-------------------------      lower  

Thu 10 Oct 2013 11:51:44 PM CDT unset -f                        lower

Thu 10 Oct 2013 11:51:44 PM CDT <=========================      [3] | camel 

Thu 10 Oct 2013 11:51:44 PM CDT <-------------------------      camel  

Thu 10 Oct 2013 11:51:44 PM CDT unset -f                        camel

Thu 10 Oct 2013 11:51:44 PM CDT <=========================      [2] | output 

Thu 10 Oct 2013 11:51:44 PM CDT <-------------------------      output  

Thu 10 Oct 2013 11:51:44 PM CDT unset -f                        output

Thu 10 Oct 2013 11:51:44 PM CDT <=========================      [1] | hello 

Thu 10 Oct 2013 11:51:44 PM CDT <-------------------------      hello 

Thu 10 Oct 2013 11:51:44 PM CDT unset -f                        hello

Thu 10 Oct 2013 11:51:44 PM CDT unset -f                        hello_getOptions

Thu 10 Oct 2013 11:51:44 PM CDT <=========================      [0] | main

----------------------------------------------------------------------

======================================================================

<<debug-sibling-modules>> shows a single iteration of *centos-art.sh*

script executing different types of modules. Normally, one module is

executed at some point and destroyed at the same point when it has

finished its work, however, what if the next immediate module you are

about to execute is the same module you are about to destroyed? This

is, you need to execute the last module in the chain of executed

modules again, but, this time, from itself.  In cases like this, the

*centos-art.sh* script doesn't destroy the last module.  It cannot,

because you are certainly executing a new module from itself, so it

has to wait for this new call to finish in order to be destroyed. This

kind of processing is known as _processing modules recursively._

Recursive Modules

~~~~~~~~~~~~~~~~~

When one module environment executes itself we are in presence of a

recursive module execution. The execution of modules recursively

doesn't destroy the last module in the chain of executed modules and

doesn't increment or decrement the module counter either. The module

counter is somehow frozen until a different module environment is

executed. In this cases, the last module environment remains in memory

for the new module execution to make use of. This process becomes more visible

when you take a look at <<debug-recursive-modules>>.

[CAUTION]

When you execute modules recursively, you should be very careful not

to get trapped into an endless loop.

In <<debug-recursive-modules>>, we've executed the *hello* module with

the *--greeting=hello*, *--random*, and *--debug* options. In this

example, *centos-art.sh* script executes a parent module named *hello*

which in turn executes a child module named *output* which in turn

executes a child module named *random*. At this point, the *random*

modules executes itself five times (the number of characters passed as

value to greeting option) to print out random letters from the

greeting message. The output may have no much sense on itself but the

related debugging information helps to understand the execution of

modules recursively.

[[debug-recursive-modules]]

.Processing execution of modules recursively

======================================================================

----------------------------------------------------------------------

Thu 10 Oct 2013 11:50:03 PM CDT =========================>      [0] | main

Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules

Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_NAME                [0]=hello

Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_TYPE                parent

Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_ARGUMENT            --random --greeting=Hello  

Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_LIST                hello|help|locale|prepare|render|tuneup|vcs

Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello

Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules

Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Manuals

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Locales

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Configs

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/hello.sh

Thu 10 Oct 2013 11:50:04 PM CDT TEXTDOMAIN                      hello.sh

Thu 10 Oct 2013 11:50:04 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Locales

Thu 10 Oct 2013 11:50:04 PM CDT export -f                       hello

Thu 10 Oct 2013 11:50:04 PM CDT export -f                       hello_getOptions

Thu 10 Oct 2013 11:50:04 PM CDT ------------------------->      hello --random --greeting=Hello  

Thu 10 Oct 2013 11:50:04 PM CDT =========================>      [1] | hello

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_NAME                [1]=output

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_TYPE                child

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_ARGUMENT             

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_LIST                output

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Manuals

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Locales

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Configs

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/output.sh

Thu 10 Oct 2013 11:50:04 PM CDT TEXTDOMAIN                      output.sh

Thu 10 Oct 2013 11:50:04 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Locales

Thu 10 Oct 2013 11:50:04 PM CDT export -f                       output

Thu 10 Oct 2013 11:50:04 PM CDT ------------------------->      output  

Thu 10 Oct 2013 11:50:04 PM CDT =========================>      [2] | output

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules/Output/Modules

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_NAME                [2]=random

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_TYPE                child

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_ARGUMENT             

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_LIST                camel|lower|random|upper

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output/Modules/Random

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules/Random/Modules

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Modules/Random/Manuals

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Modules/Random/Locales

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Modules/Random/Configs

Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/Modules/Random/random.sh

Thu 10 Oct 2013 11:50:04 PM CDT TEXTDOMAIN                      random.sh

Thu 10 Oct 2013 11:50:04 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Modules/Random/Locales

Thu 10 Oct 2013 11:50:04 PM CDT export -f                       random

Thu 10 Oct 2013 11:50:04 PM CDT ------------------------->      random  

H              

Thu 10 Oct 2013 11:50:04 PM CDT ~~~~~~~~~~~~~~~~~~~~~~~~~>      random  

H              

Thu 10 Oct 2013 11:50:04 PM CDT ~~~~~~~~~~~~~~~~~~~~~~~~~>      random  

l              

Thu 10 Oct 2013 11:50:04 PM CDT ~~~~~~~~~~~~~~~~~~~~~~~~~>      random  

l              

Thu 10 Oct 2013 11:50:04 PM CDT ~~~~~~~~~~~~~~~~~~~~~~~~~>      random  

H              

Thu 10 Oct 2013 11:50:04 PM CDT <-------------------------      random  

Thu 10 Oct 2013 11:50:04 PM CDT unset -f                        random

Thu 10 Oct 2013 11:50:04 PM CDT <=========================      [2] | output 

Thu 10 Oct 2013 11:50:04 PM CDT <-------------------------      output  

Thu 10 Oct 2013 11:50:05 PM CDT unset -f                        output

Thu 10 Oct 2013 11:50:05 PM CDT <=========================      [1] | hello 

Thu 10 Oct 2013 11:50:05 PM CDT <-------------------------      hello 

Thu 10 Oct 2013 11:50:05 PM CDT unset -f                        hello

Thu 10 Oct 2013 11:50:05 PM CDT unset -f                        hello_getOptions

Thu 10 Oct 2013 11:50:05 PM CDT <=========================      [0] | main 

----------------------------------------------------------------------

======================================================================

Recursive execution of modules occurs only when the module you are

executing is considered sibling of the last module executed in the

chain of executed modules and they both have the same name. The fact

that no variable name is printed out in <<debug-recursive-modules>>

means that they were not created. The change in the arrows shown in

the example, from +->+ to +~>+, means that module's related functions

weren't exported for the new module execution either. It also means

that the initialization script is reusing both module's related

functions variables from the last module's environment in the chain of

executed modules. In this case *random* module itself.

Summary

~~~~~~~

This section has covered the module environment inside *centos-art.sh*

script, including module types and possible combinations of them. The

next section takes these concepts and focuses on the implementation of

them. Once you finish it, you should be able of writing your own

module environments from scratch inside *centos-art.sh* script.

[[module-implementation]]

Module Implementation

---------------------

The *centos-art.sh* script implements module environments inside the

``+Modules+'' directory. Inside this directory, each module

environment has its own directory.  Inside each module directory there

is one initialization file and, optionally, module-related stuff like

functions, locales, documentation, configuration and dependent

modules.  Inside the +Modules+ directory, module directories are

written capitalized while initialization files, inside them, are

written in lower case.  Even though module directories and

initialization files are written differently, they both make a single

module because they use the same single name.

[[module-implementation-parent]]

Parent Modules

~~~~~~~~~~~~~~

For example, consider the creation of a module named *hello*. The

purpose of this module is to print a greeting message to standard

output and then exit successfully. To create such a module, we need to

create a directory named ``Hello'' inside the ``Modules'' directory

and put an initialization file named ``hello.sh'' inside it.  Because

we want to execute the *hello* module from *centos-art.sh* script

command-line, we put it in the first level of directories of +Modules+

directory. See <<parent-module-layout>>.

[[parent-module-layout]]

.Directory layout used by parent modules

======================================================================

----------------------------------------------------------------------

.

|-- COPYING                     <1>

|-- Locales/                    <2>

|-- Manuals/                    <3>

|-- Modules/                    <4>

|   `-- Hello/                  <5>

|       |-- hello.sh            <6>

|       `-- hello_getOptions.sh <7>

|-- Scripts/                    <8>

|-- centos-art.conf.sh          <9>

`-- centos-art.sh               <10>

----------------------------------------------------------------------

<1> Script's copying conditions.

<2> Script's localization files.

<3> Script's documentation files.

<4> Script's modules. Here is where you store parent modules.

<5> Parent directory of module named hello.

<6> Initialization file of module named hello.

<7> Function related to module named hello.

<8> Script's global functions.

<9> Script's configuration file.

<10> Script's initialization file.

======================================================================

<<parent-module-layout>> presents a complete module layout you can use

as reference to create your own module implementations. However, it is

not complete yet.  At this point, when you execute *centos-art.sh*, it

is able to find out *hello* module's initialization file and execute

it but that prints an error message because the initialization file

doesn't have a function definition inside. It is completely empty.  In

order for *centos-art.sh* script to do something useful, you need to

write a function definition inside the initialization file, as

described in <<module-init-file>>.

[[module-init-file]]

The Initialization File

~~~~~~~~~~~~~~~~~~~~~~~

The module's initialization file contains the module's main function

definition and a comment describing what it does on top of it.  This

comment includes a small description about what the function does, a

written by section, the copyright note and the legal status of the

file. The function definition is set later and must be written using

the long definition format (i.e., it must begin with the word

``+function+,'' then the function name, and finally the ``+{+''

character).  The name of the function is exactly the same of the

initialization file but without the +.sh+ extension. These conditions

are required in order for *centos-art.sh* script to execute the

function definition and destroy it when it is no longer used.  See

<<initialization-file>>.

The function definition is where you write all the commands you want

the module runs, once executed.  The function definition can be as

simple as just one single line of code or as complex as you can

imagine. It is the place where you express your solutions. However,

when writing initialization files, it is considered a good practice to

avoid any sort of complexity.  Instead, try to write small and simple

initialization files.  In case you notice the initialization file is

growing up inevitably, you can reduce its code by refactoring it.  To

do this, you can use resources like module related functions and child

modules. These resources are described in

<<optimizing-module-implementation>>, and they help you to keep the

initialization file in a clean state, easy to understand, maintain and

debug.

[[initialization-file]]

.Initialization file used by hello module

======================================================================

----------------------------------------------------------------------

#!/bin/bash

######################################################################

#

#   hello.sh -- Print out greetings to standard output and exit

#   successfully.

#

#   Written by:

#   * Alain Reguera Delgado <al@centos.org.cu>, 2013

#

# Copyright (C) 2009-2013 The CentOS Artwork SIG

#

# 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.

#

######################################################################

function hello {

    tcar_printMessage "`gettext "Hello, World!"`" --as-stdout-line

}

----------------------------------------------------------------------

======================================================================

The function definition described in <<initialization-file>> uses the

*tcar_printMessage* global function to print localized versions of the

string ``Hello, World!'' to standard output. Because there isn't no

other command in the function definition, when the greeting message is

printed out, *centos-art.sh* destroys the *hello* module and exit

successfully. This process is more visible when also pass the

*--debug* option. See <<debug-parent-modules>>.

Summary

~~~~~~~

Congratulations! You've implemented a module environment inside

*centos-art.sh* script. With the information you have so far, you are

able to create your own module environment implementations. The next

section delves into available resources you can use to simplify module

environments when the initialization file starts growing inevitably

and complexity daemons begin hammering your head.

[[optimizing-module-implementation]]

Module Optimization

-------------------

The *centos-art.sh* script provides four resources you can use to

optimize your module implementations. These resources are ``related

functions,'' ``child modules,'' ``sibling modules'' and ``recursive

modules''.

[[module-related-functions]]

Related Functions

~~~~~~~~~~~~~~~~~

Related functions are very useful when you need to simplify the

function definition of one initialization file. Related functions are

stored in the same location of module initialization file, see

<<parent-module-layout>>.  Definition of related function are exported

to *centos-art.sh* execution environment before executing the function

definition set inside the initialization file, so related functions

are always available in the module environment.  As naming convention,

related functions are written using the module's name as suffix, then

an underscore (``_''), then a descriptive name which identifies the

function definition inside it. The *centos-art.sh* script relays in

these conventions to export and destroy related functions when new

module environments are created and destroyed.  If you create module

related functions with a different pattern from that described here,

they will not be executed nor available inside the initialization file

of the module environment being currently executed.

For example, consider extending the *hello* module so it is able to

interpret arguments passed through the command-line.  Now, inside the

initialization file, we have some variable definitions, one function

call to a module related function named *hello_getOptions*, and a

decision on how the greeting message must be printed out based on the

collected actions. See <<initialization-file-extended>>.

[[initialization-file-extended]]

.Initialization file used by hello module (extended)

======================================================================

----------------------------------------------------------------------

#!/bin/bash

######################################################################

#

#   hello.sh -- Print greeting messages and exit successfully.

#

#   Written by:

#   * Alain Reguera Delgado <al@centos.org.cu>, 2013

#

# Copyright (C) 2009-2013 The CentOS Artwork SIG

#

# 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.

#

######################################################################

function hello {

    # Define default greeting message.

    local HELLO_WORLD="`gettext "Hello, World!"`"

    # Define actions variable. Here is where actions related to

    # module-specific options are stored in for further processing.

    local ACTIONS=''

    # Interpret module-specific options and store related actions.

    hello_getOptions

    # Print greeting message

    if [[ -z ${ACTIONS} ]];then

        # Using parent module.

        tcar_printMessage "${HELLO_WORLD}" --as-stdout-line

    else

        # Using child module.

        tcar_setModuleEnvironment -m 'output' -t 'child'

    fi

}

----------------------------------------------------------------------

======================================================================

When you execute the command *centos-art.sh hello* with the

*--greeting=hi* argument, *centos-art.sh* stores module-specific

arguments inside the +TCAR_MODULE_ARGUMENT+ variable, creates a list

of all function definitions inside the module directory and exports

them.  This includes the function definition of the initialization

file itself.  Then *centos-art.sh* executes the function definition

set inside the initialization file and leaves all other function

definitions, already in memory, waiting for further execution. At this

point, the *hello* initialization function sets some default values

and execute the *hello_getOptions* function to parse all the arguments

passed through the command-line and redefines the +ACTIONS+ variable

based on them. Using the +ACTIONS+ variables it decides whether to

print the greeting message immediately or execute the child modules

named *output* so it decides what to do with the information collected

so far.

<<hello_getOptions-definition>> defines the options you can pass to

*hello* module and the associated actions they must perform for each

of them. Actions aren't immediately executed here. Instead, they are

stored in the +ACTIONS+ variable for further processing (e.g., we

store the names of the modules we want to execute later). The

+ACTIONS+ variable was defined in the initialization file so it has a

global scope inside the module environment and is reachable from any

related function executed inside it.  Storing the actions this way

lets the *hello* module to collect information about different actions

and execute them all in just one command.  When all options have been

parsed, only non-option arguments remain in the +TCAR_MODULE_ARGUMENT+

variable.

[[hello_getOptions-definition]]

.Related function definition (hello_getOptions)

======================================================================

----------------------------------------------------------------------

#!/bin/bash

######################################################################

#

#   hello_getOptions.sh -- Interpret module-specific options for hello.

#

#   Written by:

#   * Alain Reguera Delgado <al@centos.org.cu>, 2013

#

# Copyright (C) 2009-2013 The CentOS Artwork SIG

#

# 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.

#

######################################################################

function hello_getOptions {

    # Define short options we want to support.

    local ARGSS="h::,v,g:,l,u,c,r"

    # Define long options we want to support.

    local ARGSL="help::,version,greeting:,lower,upper,camel,random"

    # Redefine arguments using getopt(1) command parser.

    tcar_setModuleArguments

    # Reset positional parameters on this function, using output

    # produced from (getopt) arguments parser.

    eval set -- "${TCAR_MODULE_ARGUMENT}"

    # Look for options passed through command-line.

    while true; do

        case "${1}" in

            -h | --help )

                tcar_printHelp "${2}"

                ;;

            -v | --version )

                tcar_printVersion "${TCAR_MODULE_NAME}"

                ;;

            -g | --greeting )

                HELLO_WORLD="${2:-${HELLO_WORLD}}"

                shift 2

                ;;

            -l | --lower )

                ACTIONS="lower ${ACTIONS}"

                shift 1

                ;;

            -u | --upper )

                ACTIONS="upper ${ACTIONS}"

                shift 1

                ;;

            -c | --camel )

                ACTIONS="camel ${ACTIONS}"

                shift 1

                ;;

            -r | --random )

                ACTIONS="random ${ACTIONS}"

                shift 1

                ;;

            -- )

                shift 1

                break

                ;;

        esac

    done

    # Redefine arguments using current positional parameters. Only

    # paths should remain as arguments, at this point.

    TCAR_MODULE_ARGUMENT="${@}"

}

----------------------------------------------------------------------

======================================================================

[IMPORTANT]

<<hello_getOptions-definition>> presents the standard construction we

use inside *centos-art.sh* script for parsing arguments passed through