Understanding Modules
=====================
Alain Reguera Delgado <al@centos.org.cu>
v1.0, Oct 2013

Introduction
------------

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 defined in the very beginning of *centos-art.sh*
script and remain in memory for you to call whenever you need it using
a regular function call syntax. The module-specific functions, on the
other hand, are defined at demand for specific tasks and removed from
memory once the task they were created for is over.  The collection of
all module-specific functions related to the same task is what we call
a module environment.  Module environments can be either top-module,
sub-module or sib-module and all are executed through the
*tcar_setModuleEnvironment* global function.

This article describes the modular design of *centos-art.sh* script.
It is a good place to start if you are planning to contribute new
module environments to *centos-art.sh* script. The next section
delves into what a module environment is, the tree module types you
can find and the correct way of execute them.

The Module Environment
----------------------

The module environment provides an array of strings (called the
environment). You can use this environment to deploy solutions for
specific problems.  Inside the *centos-art.sh* script, module
environments are made of small functions that create small
environments to solve small problems. Then they are combined in a
specific order to solve bigger problems.  The process of initiating a
module environment inside *centos-art.sh* script starts at the end of
the *centos-art.sh* file itself, with the invocation of the
*tcar_setModuleEnvironment* function. This function, at this point,
executes the module environment for the module name you specified in
the first argument of the command-line.  The modules you specified in
the command-line are also known as top-modules.

Top-modules initiate the higher module environment inside
*centos-art.sh* script. This means that variables and functions
defined inside it will be available as long as its execution-time
last.  Top-modules are stored directly inside the +Modules/+ directory
of *centos-art.sh* script, as described in <<directory-structure>>.
Top-modules use to be small and have well defined goals. Top-modules
exist to define global variables for task-specific actions, interpret
module-specific options passed through the command-line and execute
the appropriate actions based on them. These actions can be involve
calling other top-modules or sub-modules.

Sub-modules are also module environments. They are executed by the
*tcar_setModuleEnvironment* function when the *-t sub-module* option
is passed to it. Sub-modules have the characteristic of being nested
modules. They are generally executed one inside another to create 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 related but
different 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 but related kind
of processing and jump from one to another without destroying the
common information.  However, when one of the specific ways of
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.

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, it is worth to know that all global array variables the
*tcar_setModuleEnvironment* function uses to store module-specific
information remain active until the last module environment is
destroyed (i.e., the top-module executed from the command-line).  This
make possible for *centos-art.sh* script to ``remember'' information
about all different but related module environments loaded to perform
specific tasks. Such remembering feature is what make possible to
implement sib-modules as described above.

[[module-implementation]]
Module Implementation
---------------------

The implementation of module environments take place in two locations.
The first location is the module directory structure and the second
location *tcar_setModuleEnvironment* function. The module directory
structure contains a standard distribution of files and directories
that the *tcar_setModuleEnvironment* function recognizes and uses for
executing functions inside it.  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.

The *tcar_setModuleEnvironment* function is stored in the +Scripts/+
directory. It 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 destroyed, 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.
======================================================================

To illustrate how modules need to be implemented inside
*centos-art.sh* script in order for *tcar_setModuleEnvironment* to
execute them correctly, we'll use a module named ``hello'' as example
in the next sections to describe the steps you need to follow for
creating new modules from scratch.  The purpose of *hello* module is
to print out greetings to standard output and exit successfully. See
*hello(1)*, for more information about it.

Planning New Module
-------------------

Planning is probably the first thing you need to do in order to create
a new module to *centos-art.sh* script. It would be very helpful if
you read documentation and bugs related to modules and function in
order to find out possible tasks you might take as motivation for your
contributions. Such investigation always help.

The motivation behind the *hello* module came with the need of having
a simple module that could be used as reference to describe how to
create and execute new modules inside *centos-art.sh* script. The top
modules we have by now aren't suitable for a simple description about
how to create new modules from scratch.  Instead, I thought that
creating a simple module for that purpose would be better. Suddenly, I
recalled the GNU's hello package which describes their standards about
well written GNU packages and found motivation enough to create a
*hello* module under the same idea but this time focused on
*centos-art.sh* script, instead.

The motivation for planning your own modules might vary. No matter
what it would be, use it with confidence, plan your module, set the
final spot where you want to get to and then, read the next section.
It describes the steps you need to follow in order to write a
functional module inside *centos-art.sh* script.

Creating New Module
-------------------

The <<directory-structure>>, shows a basic module structure. In this
example, we see that module directories are written capitalized while
module initialization file and related functions are all written in
lower-case. Note also how the module directory and files inside it use
the module's name in their file names to get identified. This is a
convention that should be followed in order for *centos-art.sh* script
to execute modules. Another convention you should follow, when
creating related functions, is using underscore (``_'') to separate
the module's name from the function's descriptive name. In these
cases, the function's descriptive name is always written in camel-case
followed by the +.sh+ extension.

[[directory-structure]]
.The directory structure
======================================================================
----------------------------------------------------------------------
.
|-- COPYING                     <-- Contains the GPL license.
|-- Locales/                    <-- localization of all sh files.
|-- Manuals/                    <-- manuals for main and global functions.
|-- Modules/                    <-- top-modules are stored here.
|   `-- Hello/                  <-- top-module directory.
|       `-- hello.sh            <-- top-module initialization file.
|-- Scripts/                    <-- global functions are stored here.
|-- centos-art.conf.sh          <-- main configuration file.
`-- centos-art.sh               <-- main initialization file.
----------------------------------------------------------------------
======================================================================

[[directory-structure-extended]]
.The directory structure with extended functionality
======================================================================
----------------------------------------------------------------------
.
|-- COPYING
|-- Locales/
|-- Manuals/
|-- Modules/
|   `-- Hello/
|       |-- Modules/            <-- Hello sub-modules are stored here.
|       |   |-- Actions/        <-- Sub-module of Hello but sib-module of Lowercase and Uppercase
|       |   |   `-- actions.sh  <-- sub-module initialization file.
|       |   |-- Lowercase/      <-- Sub-module of Hello but sib-module of Actions and Uppercase.
|       |   |   `-- lowercase.sh
|       |   `-- Uppercase/      <-- Sub-module of Hello but sib-module of Actions and Lowercase.
|       |       `-- uppercase.sh
|       `-- hello.sh
|-- Scripts/
|-- centos-art.conf.sh
`-- centos-art.sh
----------------------------------------------------------------------
======================================================================

The module's initialization file contains the main function definition
of your module. It is a good place to define variables that must be
always available inside the module. There is also a top-comment that
collects information about the function files you are writing (e.g., a
small description, a written by section, the copyright note and the
legal status of the file). Even using a top comment like this is not
required for *centos-art.sh* script to execute modules properly, it is
very useful as matter of consistency and style inside it (and the
copyright and legal notice might be required for legal protection of
your code as set by GPL).  Finally, there is the function definition
named +hello+ just as the directory that holds it but all in lowercase.
Inside this function definition is where we write what we want the
*hello* module does for us. This way, following with the *hello* example,
we create an array variable inside it holding all the suggestions we
would like to print, as described in <<initialization-file>>.

[[initialization-file]]
.The initialization file of 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 "Hello, World!"

}
----------------------------------------------------------------------
======================================================================

You can nest modules by creating directory structures like this,
inside the Modules/ directory of the higher module you want to extend
its functionality.

Inside the repository, modules related to *centos-art.sh* script are
stored in the directory +Automation/Modules/${MODULE_NAME}/+.

*Modules/*::
    This directory contains module's modules.
*Manuals/*::
    This directory contains module's documentation produced by *help*
    module.  The structure of this directory looks as follow:
+
----------------------------------------------------------------------
Manuals/
|-- ${LANG}/
|   |-- man${SECTION_NUMBER}
|   `-- ${MODULE_NAME}.${SECTION_NUMBER}
`-- man${SECTION_NUMBER}
    `-- ${MODULE_NAME}.${SECTION_NUMBER}
----------------------------------------------------------------------

*Locales/*::
    This directory contains module's translations produced by *locale*
    module. The structure of this directory looks as follow:
+
----------------------------------------------------------------------
Locales/
`-- ${LANG}/
    |-- LC_MESSAGES
    |   |-- ${MODULE_NAME}.sh.mo
    |   `-- ${MODULE_NAME}.docbook.mo
    |-- ${MODULE_NAME}.sh.po
    |-- ${MODULE_NAME}.sh.pot
    |-- ${MODULE_NAME}.docbook.po
    `-- ${MODULE_NAME}.docbook.pot
----------------------------------------------------------------------

*Scripts/*::
    This directory contains function scripts written by module's
    writers. Here is where all the tasks the module is useful for are
    written and stored in.  As convention the following structure is
    used:
+
----------------------------------------------------------------------
Scripts/
`-- ${MODULE_NAME}_${FUNCTION_NAME}.sh
----------------------------------------------------------------------
+
{asccidoc-br}
+
Inside each function script, there is a top comment where you should
put the name of the function script, a brief description about what it
does, as well as author and copying information. After the top comment
and separated by one white line, you should define the function
sentence using the long format.
+
----------------------------------------------------------------------
#!/bin/bash
######################################################################
#
#   ${MODULE_NAME}_${FUNCTION_NAME}.sh -- ${FUNCTION_DESCRIPTION}
#
#   Written by:
#   * ${AUTHOR_NAME} <${AUTHOR_EMAIL}>, ${YEARS}
#
# Copyright (C) ${YEAR} 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 ${MODULE_NAME}_${FUNCTION_NAME} {
    ...
}
----------------------------------------------------------------------
+
[NOTE]
If your are planning to contribute a new module to *centos-art.sh*
script, please, consider using the layout described above for all your
function scripts, consistently.

*$\{MODULE_NAME}.asciidoc*::
    This file contains the module's documentation source. From this
    file it is possible to produce the same documentation in other
    formats including manpage, html and pdf. Whenever you need to
    improve the module's documentation, edit this file.
*$\{MODULE_NAME}.conf*::
    This file contains the module's configuration variables. These
    variables are exported to the environment and remain there as long
    as the script execution environment is alive. Some variables are
    read-only others not.
+
The configuration file provides explanation about each environment
variable it exports. If you want to know more about what these
variables are, open this file and read the comments near each
variable.

*$\{MODULE_NAME}.sh*::
    This is the module's initialization script. The first file
    executed when the module called from the command-line. This file
    provides access to argument parsing and controls how
    module-specific function scripts are called. This is the starting
    point for writing modules. You can write a complete module using
    this file only but, frequently, it is convenient as the module
    complexity grows to divide it in smaller pieces (function scripts)
    to improve maintainability and error findings.

// vim: set syntax=asciidoc: