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 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 , 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: