tcar_setModuleEnvironment.sh(1)

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

Name

----

tcar_setModuleEnvironment.sh - Initiate module environments.

Synopsis

--------

*tcar_setModuleEnvironment [-m "MODULE_NAME"] [-t "MODULE_TYPE"] [-g MODULE_ARGUMENT] ...*

Description

-----------

From version 0.5 of The CentOS Artwork Repository on, the

*centos-art.sh* script was redesigned to introduce 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 efficiently 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).

Inside the *centos-art.sh* script there are two kinds of functions,

which are "global functions" and "module-specific functions." The

global functions are loaded in the very beginning of *centos-art.sh*

script and remain in memory for you to use whenever you need it, using

a regular function call syntax. The module-specific functions, on the

other hand, are only loaded when they are needed and they are removed

from memory once the task they were created for is done.  To load

module-specific functions inside the *centos-art.sh* script, you use

the *tcar_setModuleEnvironment* global function as described in the

synopsis section above.

Module Execution Environment

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

Each time you execute the *tcar_setModuleEnvironment* function, it

creates a new ``Module Environment.'' A module environment is a

logical space where you can deploy solutions for specific problems.

The implementation of these solutions take place in the Modules

directory of *centos-art.sh* script, as described in

<<module-implementation>>.

Module environments all begin with a ``top-module.'' These modules are

stored at the first level of Modules directory inside the

*centos-art.sh* script tree. These modules are small and their goal

main goal it to define global variables for task-specific actions,

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

execute the appropriate sub-module based on it.

Sub-modules are module environments that nest one inside another

creating a chain of module environments. A chain of module

environments is very useful in situations where you want to divide one

large task into smaller tasks and also control which of those smaller

tasks are loaded based on specific conditions (e.g., you want to

render both images and documentation).  In a chain of modules, module

environments at a lower level in the chain (those started last) have

access to higher module environments (those started first), but not

the opposite. When processing information this way, module

environments aren't destroyed until the last module environment loaded

is done. At that point, module environments are destroyed in the

reverse order they were loaded (e.g., if the chain of module was

executed as ``render->images->svg'', then, when ``svg'' module

environment is done, the chain of modules will be destroy ``images''

and finally ``render'').

Module environments can also share one common module environment on

top of them to create sibling processing (sib-module). Sibling

processing is very useful in situations where you start processing

information in a way and then need to jump to another kind of

processing (e.g., when you are rendering documentation you first start

rendering it as html and then jump into manpage). In this situation,

you open a module environment that contains information useful for two

or more different kind of information processing and jump from one

processing to another without destroying the common information.

However, when one of the specific way or processing information is

done, it is destroyed. This, before opening a new way of processing

(e.g., once html processing is done, the html module is destroyed and,

then, the manpage module is loaded). So, only the required modules are

active while processing information.

[[module-implementation]]

Module Implementation

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

The implementation of *tcar_setModuleEnvironment* function uses global

array variables to store information about the modules and (non-array)

local variables to handle the information stored about modules in each

call of the function. Each time you call the

*tcar_setModuleEnvironment* function, it increments the array

variables counter, stores module-specific information in the array

variables, reset (non-array) local variables using the current

module's information stored in the array variables and executes the

module's initialization script from (non-array) local variables.  When

the module's environment finishes its execution, the array counter

decrements and the module's environment is unset, to free the memory

it was using.  This process repeats continually, each time you call

the *tcar_setModuleEnvironment* function.

[TIP]

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

In case you want to see how modules are created and destroyed inside,

pass the *--debug* option to *centos-art.sh* script. It will activate

the script internal debugger for you to see the whole process.

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

When we say that a module environment is destroyed it means that all

the related variables and functions which make that module environment

useful are removed from *centos-art.sh* script execution environment,

which make the module environment inoperable to all effects, indeed.

However, the global array variables used by

*tcar_setModuleEnvironment* function to store module-specific

information remain active until the last module environment is

destroyed.  This make possible for *centos-art.sh* script to remember

information about the module environments required for a specific

tasks.  It is also very useful when it is necessary to jump from one

module environment to another under the same parent module environment.

Each module environment you want to execute needs a module directory

in the *centos-art.sh* script tree. In this directory you organize the

functions that make your module environment useful. The directory

structure of your module directory is important because

*tcar_setModuleEnvironment* makes use of it to know module-specific

information.

To illustrate how modules need to be implemented inside

*centos-art.sh* script in order for *tcar_setModuleEnvironment* to

execute them, we are using an example module named ``greet''. The

purpose of greet module is instructive only. Because, greet has a

module directory structure for its own, its documentation is not in

this documentation page but in greet module own documentation page. To

read greet module's documentation page, run the following command:

*centos-art greet --help*.

[[options]]

Options

-------

The *tcar_setModuleEnvironment* function accepts the following

options:

-m ::

    This option specifies the name of the module you want to load.

-t::

    This option specifies the type of the module you want to load.

    Modules can be one of the following types:

+

top-module;;

    This modules are stored in the first level of Modules directory.

    This type of modules initiate module environments for specific

    tasks so it can be called from anywhere inside *centos-art.sh*

    script.

sub-module;;

    This modules are stored from the second-level of Modules directory

    on. This type of modules can be executed from top-modules,

    sub-modules, or sib-modules but never the *centos-art.sh* file

    itself.

sib-module;;

    This modules are stored from the second-level of Modules directory

    on. This type of modules can be executed from sub-modules or

    sib-modules, but never top-modules or the *centos-art.sh* file

    itself.

-g::

    This option specifies the module-specific option you want to pass

    for processing in the module environment you are about to execute.

    Generally, module-specific options are passed through

    *centos-art.sh* command-line but you may need to pass them

    internally in some cases (e.g., you are executing a top-module

    from a sub-module). If you need to pass more than one option, then

    you need to put the -g option before each option you want to pass.

Bugs

----

In the very beginning of *tcar_setModuleEnvironment* function, it used

just non-array variables and it worked fine for top-module and sub-module

processing, however when it was needed to do sibling processing, it

didn't work as expected. The failure was produced because a wrong

variable assignment when tried to set the path of the next module to

load. There was not a clean way to ``remember'' what was the base

directory of the parent directory, so it ended up using the last

loaded module base directory which made impossible to load a sibling

module.  The *tcar_setModuleEnvironment* function as implemented in

version 0.5 of The CentOS Artwork Repository, fixes this issue 

replacing non-array variables by array variables which can remember

module information.

See also: https://centos.org.cu/bugs/[https://centos.org.cu/bugs/]

Author

------

The *centos-art.sh* script has received contribution from the

following people:

* Alain Reguera Delgado <mailto:al@centos.org.cu[al@centos.org.cu]>, 2009-2013

Copyright

---------

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.

// vim: set syntax=asciidoc: