From a760558bf8d9296829edaa1f292f3b8d18028c70 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Oct 11 2013 20:44:13 +0000 Subject: Update understanding_modules.asciidoc file. --- diff --git a/Automation/Manuals/Understanding_Modules/understanding_modules.asciidoc b/Automation/Manuals/Understanding_Modules/understanding_modules.asciidoc index a5b863b..1069386 100644 --- a/Automation/Manuals/Understanding_Modules/understanding_modules.asciidoc +++ b/Automation/Manuals/Understanding_Modules/understanding_modules.asciidoc @@ -1,238 +1,539 @@ Understanding Modules ===================== Alain Reguera Delgado -v1.0, Oct 2013 +v0.1, Oct 2013 -Introduction ------------- +Overview +-------- -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 +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). -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 <>. -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 ---------------------- +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 this execution environment +through the files +centos-art.sh+ and +centos-art.conf.sh+. These +files don't provide too much functionality so module environments are +executed inside it 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 create 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.'' + +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 <>, 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 +---------------------------------------------------------------------- +====================================================================== -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] +<> 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 interaction, then using ``_child modules_'' +is a more suitable approach. + +[[child-modules]] +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 interaction 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 interaction 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]] +.Debugging execution of child modules ====================================================================== -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. +---------------------------------------------------------------------- +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 +---------------------------------------------------------------------- ====================================================================== -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 <>, 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 +The module environment described in <> 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 <>. + +In <>, 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 ====================================================================== ---------------------------------------------------------------------- -. -|-- 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. +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 +---------------------------------------------------------------------- +====================================================================== + +<> shows a single interaction 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 <>. + +[CAUTION] +When you execute modules recursively, you should be very careful not +to get trapped into an endless loop. + +In <>, 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 ---------------------------------------------------------------------- ====================================================================== -[[directory-structure-extended]] -.The directory structure with extended functionality +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 <> +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 +--------------------- + +Parent Modules +~~~~~~~~~~~~~~ + +The <>, 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. + +[[hello-simplest-directory-structure]] +.Simplest directory structure of hello module. ====================================================================== ---------------------------------------------------------------------- . -|-- COPYING -|-- Locales/ -|-- Manuals/ -|-- Modules/ +|-- 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/ -| |-- 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 +|-- Scripts/ <-- global functions are stored here. +|-- centos-art.conf.sh <-- main configuration file. +`-- centos-art.sh <-- main initialization file. ---------------------------------------------------------------------- ====================================================================== @@ -246,7 +547,7 @@ 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. +named +hello+ just as the directory that holds it but all in lower. 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 @@ -291,124 +592,23 @@ function hello { ---------------------------------------------------------------------- ====================================================================== -You can nest modules by creating directory structures like this, -inside the Modules/ directory of the higher module you want to extend -its functionality. +Child Modules +~~~~~~~~~~~~~ +... -Inside the repository, modules related to *centos-art.sh* script are -stored in the directory +Automation/Modules/${MODULE_NAME}/+. +Sibling Modules +~~~~~~~~~~~~~~~ -*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 ----------------------------------------------------------------------- +Recursive Modules +~~~~~~~~~~~~~~~~~ -*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. +Summary +~~~~~~~ + +... // vim: set syntax=asciidoc: