Tip
Join CentOS developers mailing list +centos-art@centos.org to share your ideas. +
centos-art command runs the
@@ -118,7 +119,7 @@ script execution environment.
`centos-art.sh' script executes the cli global function
from `cli.sh' function script to retrive command-line arguments
and define some default values that may be used later by specific
-function scripts (see section trunk/Scripts/Bash/Functions).
+function scripts (-- Removed(pxref:trunk Scripts Bash Functions) --).
As convenction, the `centos-art.sh' command-line arguments have the following format: @@ -218,7 +219,8 @@ variables and functions defined inside function environment.
The `centos-art.sh' script usage information is described inside -each specific function documentation (see section trunk/Scripts/Bash/Functions). +each specific function documentation (-- Removed(pxref:trunk Scripts Bash +Functions) --).
@@ -227,8 +229,6 @@ each specific function documentation (see sectionThe `trunk/Scripts/Bash/Functions' directory exists to organize +`centos-art.sh' specific functionalities. +
The specific functions of `centos-art.sh' script are designed +with "Software Toolbox" philosophy (see (coreutils.info)Toolbox introduction) in mind: each program "should do one +thing well". Inside `centos-art.sh' script, each specific +functionality is considered a program that should do one thing well. +Of course, if you find that they still don't do it, feel free to +improve them in order for them to do so. +
+The specific functions of `centos-art.sh' script are organized
+inside specific directories under `trunk/Scripts/Bash/Functions'
+location. Each specific function directory should be named as the
+function it represents, with the first letter in uppercase. For
+example, if the function name is render, the specific function
+directory for it would be `trunk/Scripts/Bash/Functions/Render'.
+
To better understand how specific functions of `centos-art.sh' +script are designed, lets create one function which only goal is to +output different kind of greetings to your screen. +
+When we create specific functions for `centos-art.sh' script it +is crucial to know what these functions will do exactly and if there +is any function that already does what we intend to do. If there is no +one, it is good time to create them then. Otherwise, if +functionalities already available don't do what you exactly expect, +contact their authors and work together to improve them. +
++ +Tip
Join CentOS developers mailing list +centos-art@centos.org to share your ideas. +
It is also worth to know what global functions and variables do we +have available inside `centos-art.sh' script, so advantage can be +taken from them. Global variables are defined inside global function +scripts. Global functions scripts are stored immediatly under +`trunk/Scripts/Bash/Functions' directory, in files begining with +`cli' prefix. +
+OK, let's begin with our functionality example. +
+What function name do we use? Well, lets use greet. Note that
+`hello' word is not a verb; but an expression, a kind of
+greeting, an interjection specifically. In contrast, `greet' is a
+verb and describes what we do when we say `Hello!', `Hi!',
+and similar expressions.
+
So far, we've gathered the following function information: +
+Name: greet +Path: trunk/Scripts/Bash/Functions/Greet +File: trunk/Scripts/Bash/Functions/Greet/greet.sh ++
The `greet.sh' function script is the first file
+`centos-art.sh' script loads when the `greet' functionality
+is called using commands like `centos-art greet --hello='World''.
+The `greet.sh' function script contains the greet function
+definition.
+
Inside `centos-art.sh' script, as convenction, each function +script has one top commentary, followed by one blank line, and then +one function defintion below it only. +
+Inside `centos-art.sh' script functions, top commentaries have
+the following components: the functionality description, one-line for
+copyright note with your personal information, the license under
+which the function source code is released --the `centos-art.sh'
+script is released as GPL, so do all its functions--, the $Id$
+keyword of Subversion is later expanded by svn propset
+command.
+
In our greet function example, top commentary for
+`greet.sh' function script would look like the following:
+
#!/bin/bash +# +# greet.sh -- This function outputs different kind of greetings to +# your screen. Use this function to understand how centos-art.sh +# script specific functionalities work. +# +# Copyright (C) YEAR YOURFULLNAME +# +# 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 +# USA. +# +# ---------------------------------------------------------------------- +# $Id$ +# ---------------------------------------------------------------------- ++
After top commentary, separated by one blank line, the greet
+function definition would look like the following:
+
function greet {
+
+ # Define global variables.
+
+ # Define command-line interface.
+ greet_getActions
+
+}
+
+The first definition inside greet function, are global
+variables that will be available along greet function execution
+environment. This time we didn't use global variable definitions for
+greet function execution environment, so we left that section
+empty.
+
Later, we call greet_getActions function to define the
+command-line interface of greet functionality. The command-line
+interface of greet functionality defines what and how actions
+are performed, based on arguments combination passed to
+`centos-art.sh' script.
+
function greet_getActions {
+
+ case "$ACTIONNAM" in
+ --hello )
+ greet_doHello
+ ;;
+
+ --bye )
+ greet_doBye
+ ;;
+
+ * )
+ cli_printMessage "`gettext "The option provided is not valid."`"
+ cli_printMessage "$(caller)" 'AsToKnowMoreLine'
+
+ esac
+
+}
+
+The ACTIONNAM global variable is defined in `cli.sh' +function script and contains the value passed before the equal sign +(i.e., `=') in the second command-line argument of +`centos-art.sh' script. For example, if the second command-line +argument is `--hello='World'', the value of ACTIONNAM +variable would be `--hello'. Using this configuration let us +deside which action to perform based on the action name passed to +`centos-art.sh' script as second argument. +
+The greet function definition makes available two valid
+greetings through `--hello' and `--bye' options. If no
+one of them is provided as second command-line argument, the `*'
+case is evaluated instead.
+
The `*' case and its two lines further on should always be +present in `_getActions.sh' function scripts, no matter what +specific functionality you are creating. This convenction helps the +user to find out documentation about current functionality in use, +when no valid action is provided. +
+The greet_doHello and greet_doBye function definitions
+are the core of greet specific functionality. In such function
+definitions we set what our greet function really does: to
+output different kinds of greetings.
+
function greet_doHello {
+
+ cli_printMessage "`gettext "Hello"` $ACTIONVAL"
+
+}
+
+The greet_doHello function definition is stored in
+`greet_doHello.sh' function script.
+
function greet_doBye {
+
+ cli_printMessage "`gettext "Goodbye"` $ACTIONVAL"
+
+}
+
+The greet_doBye function definition is stored in the
+`greet_doBye.sh' function script.
+
Both `greet_doHello.sh' and `greet_doBye.sh' function
+scripts are stored inside greet function directory path (i.e.
+`trunk/Scripts/Bash/Functions/Greet').
+
The ACTIONVAL global variable is defined in `cli.sh' +function script and contains the value passed after the equal sign +(i.e., `=') in the second command-line argument of +`centos-art.sh' script. For example, if the second command-line +argument is `--hello='World'', the value of ACTIONVAL +variable would be `World' without quotes. +
+Let's see how greet specific functionality files are organzied
+under greet function directory. To see file organization we use
+the tree command:
+
trunk/Scripts/Bash/Functions/Greet +|-- greet_doBye.sh +|-- greet_doHello.sh +|-- greet_getActions.sh +`-- greet.sh ++
To try the greet specific functionality we've just created,
+pass the function name (i.e., `greet') as first argument to
+`centos-art.sh' script, and any of the valid options as second
+argument. Some examples are illustrated below:
+
[centos@projects ~]$ centos-art greet --hello='World' +Hello World +[centos@projects ~]$ centos-art greet --bye='World' +Goodbye World +[centos@projects ~]$ ++
The word `World' in the examples above can be anything. In fact, +change it to have a little fun. +
+Now that we have a specific function that works as we expect, it is
+time to document it. To document greet specific functionality,
+we use its directory path and the manual functionality
+(-- Removed(pxref:trunk Scripts Bash Functions Manual) --) of `centos-art.sh'
+script, just as the following command illustrates:
+
centos-art manual --edit=trunk/Scripts/Bash/Functions/Greet ++
To have a well documented function helps user to understand how your +function really works, and how it should be used. When no valid +action is passed to a function, the `centos-art.sh' script uses +the function documentation entry as vehicle to communicate which the +valid functions are. When no documentation entry exists for a +function, the `centos-art.sh' script informs that no +documentation entry exists for such function and requests user to +create it right at that time. +
+Now that we have documented our function, it is time to translate its
+output messages to different languages. To translate specific
+functionality output messages to different languages we use the
+locale functionality (-- Removed(pxref:trunk Scripts Bash Functions
+Locale) --) of `centos-art.sh' script, just as the following command
+illustrates:
+
centos-art locale --edit ++
+ +Warning
To translate output messages in different languages, +your system locale information --as in
LANGenvironment +variable-- must be set to that locale you want to produce translated +messages for. For example, if you want to produce translated messages +for Spanish language, your system locale information must be set to +`es_ES.UTF-8', or similar, first. +
Well, it seems that our example is rather complete by now. +
+In greet function example we've described so far, we only use
+cli_printMessage global function in action specific function
+definitions in order to print messages, but more interesting things
+can be achieved inside action specific function definitions. For
+example, if you pass a directory path as action value in second
+argument, you could retrive a list of files from therein, and process
+them. If the list of files turns too long or you just want to control
+which files to process, you could add the third argument in the form
+`--filter='regex'' and reduce the amount of files to process
+using a regular expression pattern.
+
The greet function described in this section may serve you as
+an introduction to understand how specific functionalities work inside
+`centos-art.sh' script. With some of luck this introduction will
+also serve you as motivation to create your own `centos-art.sh'
+script specific functionalities.
+
By the way, the greet functionality doesn't exist inside
+`centos-art.sh' script yet. Would you like to create it?
+
The following global variables of `centos-art.sh' script, are +available for you to use inside specific functions: +
+Default domain used to retrieve translated messages. This value is set +in `initFunctions.sh' and shouldn't be changed. +
Default directory used to retrieve translated messages. This value is +set in `initFunctions.sh' and shouldn't be changed. +
Define function name. +
+Function names associate sets of actions. There is one set of actions +for each unique function name inside `centos-art.sh' script. +
+Dunction names are passed as first argument in `centos-art.sh' +command-line interface. For example, in the command `centos-art +render --entry=path/to/dir --filter=regex', the ACTION passed to +`centos-art.sh' script is `render'. +
+When first argument is not provided, the `centos-art.sh' script +immediatly ends its execution. +
Define action name. +
+Each action name identifies an specific action to perform, inside an +specific function. +
+Action name names aare passed as second argument in +`centos-art.sh' command-line interface. For example, in the +command `centos-art render --entry=path/to/dir --filter=regex', +the ACTIONNAM passed to `centos-art.sh' script is +`--entry'. +
+When second argument is not provided, the `centos-art.sh' script +immediatly ends its execution. +
Define action value. +
+Action values are associated to just one action name. Action values +contain the working copy entry over which its associated action will be +performed in. Working copy entries can be files or directories inside +the working copy. +
Define regular expression used as pattern to build the list of files +to process. +
+By default, REGEX variable is set to .+ to match all
+files.
+
Functions that need to build a list of files to process use the option +`--filter' to redefine REGEX variable default value, and +so, control the amount of files to process. +
Define optional arguments. +
+Optional arguments, inside `centos-art.sh' script, are considered +as all command-line arguments passed to `centos-art.sh' script, +from third argument position on. For example, in the command +`centos-art render --entry=path/to/dir --filter=regex' , the +optional arguments are from `--filter=regex' argument on. +
+Optional arguments are parsed using getopt command through
+the following base construction:
+
# Define short options we want to support. +local ARGSS="" + +# Define long options we want to support. +local ARGSL="filter:,to:" + +# Parse arguments using getopt(1) command parser. +cli_doParseArguments + +# Reset positional parameters using output from (getopt) argument +# parser. +eval set -- "$ARGUMENTS" + +# Define action to take for each option passed. +while true; do + case "$1" in + --filter ) + REGEX="$2" + shift 2 + ;; + --to ) + TARGET="$2" + shift 2 + ;; + * ) + break + esac +done ++
Optional arguments provide support to command options inside
+`centos-art.sh' script. For instance, consider the Subversion
+(svn) command, where there are many options (e.g.,
+`copy', `delete', `move', etc), and inside each
+option there are several modifiers (e.g., `--revision',
+`--message', `--username', etc.) that can be combined one
+another in their short or long variants.
+
The ARGUMENTS variable is used to store arguments passed from +command-line for later use inside `centos-art.sh' script. Storing +arguments is specially useful when we want to run a command with some +specific options from them. Consider the following command: +
+centos-art path --copy=SOURCE --to=TARGET --message="The commit message goes here." --username='johndoe' ++
In the above command, the `--message', and `--username'
+options are specific to svn copy command. In such cases,
+options are not interpreted by `centos-art.sh' script itself.
+Instead, the `centos-art.sh' script uses getopt to
+retrive them and store them in the ARGUMENTS variable for later
+use, as described in the following command:
+
# Build subversion command to duplicate locations inside the +# workstation. +eval svn copy $SOURCE $TARGET --quiet $ARGUMENTS ++
When getopt parses ARGUMENTS, we may use short options
+(e.g., `-m') or long options (e.g., `--message'). When
+we use short options, arguments are separated by one space from the
+option (e.g., `-m 'This is a commit message.''). When we use
+long options arguments are separated by an equal sign (`=')
+(e.g., `--message='This is a commit message'').
+
In order for getopt to parse ARGUMENTS correctly, it
+is required to provide the short and long definition of options that
+will be passed or at least supported by the command performing the
+final action the function script exists for.
+
As convenction, inside `centos-art.sh' script, short option +definitions are set in the ARGSS variable; and long option +definitions are set in the ARGSL variable. +
+When you define short and long options, it may be needed to define +which of these option arguments are required and which not. To define +an option argument as required, you need to set one colon `:' +after the option definition (e.g., `-o m: -l message:'). On +the other hand, to define an option argument as not required, you need +to set two colons `::' after the option definition (e.g., +`-o m:: -l message::'). +
Default text editor. +
+The `centos-art.sh' script uses default text EDITOR to edit
+pre-commit subversion messages, translation files, configuration
+files, script files, and similar text-based files.
+
If EDITOR environment variable is not set, `centos-art.sh'
+script uses `/usr/bin/vim' as default text editor. Otherwise, the
+following values are recognized by `centos-art.sh' script:
+
If no one of these values is set in EDITOR environment variable,
+`centos-art.sh' uses `/usr/bin/vim' text editor by default.
+
Function scripts stored directly under +`trunk/Scripts/Bash/Functions/' directory are used to define +global functions. Global functions can be used inside action specific +functionalities and or even be reused inside themselves. This section +provides introductory information to global functions you can use +inside `centos-art.sh' script. +
+Validate action value (ACTIONVAL) variable. +
+The action value variable can take one of the following values: +
+If another value different from that specified above is passed to +action value variable, the `centos-art.sh' script prints an error +message and ends script execution. +
Verify file existence. +
+cli_checkFiles receives a FILE absolute path and performs
+file verification as specified in TYPE. When TYPE is not
+specified, cli_checkFiles verifies FILE existence, no
+matter what kind of file it be. If TYPE is specified, use one
+of the following values:
+
Ends script execution if FILE is not a directory. +
+When you verify directories with cli_checkFiles, if directory doesn't +exist, `centos-art.sh' script asks you for confirmation in order +to create that directory. If you answer positively, +`centos-art.sh' script creates that directory and continues +script flows normally. Otherwise, if you answer negatively, +`centos-art.sh' ends script execution with an error and +documentation message. +
+Ends script execution if FILE is not a regular file. +
Ends script execution if FILE is not a symbolic link. +
Ends script execution if FILE is not executable. +
Ends script execution if FILE is neither a regular file nor a +symbolic link. +
Ends script execution if FILE is neither a regular file nor a +directory. +
Ends script execution if FILE is not inside the working copy. +
As default behaviour, if FILE passes all verifications, +`centos-art.sh' script continues with its normal flow. +
Syncronize changes between repository and working copy. +
+The cli_commitRepoChanges function brings changes from the
+central repository down to the working copy--using svn
+update--, checks the working copy changes--using svn
+status command--, prints status report--using both svn
+update and svn status commands output, and finally, commits
+recent changes from the working copy up to the repository--using
+svn commit command--.
+
Previous to commit the working copy changes up to the central
+repository, the cli_commitRepoChanges function asks you to
+verify changes--using svn diff command--, and later,
+another confirmation question is shown to be sure you really want to
+commit changes up to central repository.
+
If LOCATION argument is not specified, the value of +ACTIONVAL variable is used as reference instead. +
+---------------------------------------------------------------------- +--> Bringing changes from the repository into the working copy +--> Checking changes in the working copy +---------------------------------------------------------------------- +Added 0 file from the repository. +Deleted 0 file from the repository. +Updated 0 file from the repository. +Conflicted 0 file from the repository. +Merged 0 file from the repository. +Modified 4 files from the working copy. +Unversioned 0 file from the working copy. +Deleted 0 file from the working copy. +Added 0 file from the working copy. +---------------------------------------------------------------------- ++
Figure 3.3: The cli_commitRepoChanges function output.
+
+
Call the cli_commitRepoChanges function before or/and after
+calling functions that modify files or directories inside the working
+copy as you may need to.
+
Redefine arguments (ARGUMENTS) global variable using
+getopt command output. For more information about how to use
+cli_doParseArguments function, see ARGUMENTS variable
+description above.
+
Initialize/reset arguments (ARGUMENTS) global variable using +positional parameters variable ($@) as reference. +
+When we work inside function definitions, positional parameters are
+reset to the last function definition positional parameters. If you
+need to redefine positional parameters from one specific function, you
+need to call cli_doParseArgumentsReDef with the positional
+parameters variable ($@), set as first argument, to that
+specific function you want to redefine positional parameters at.
+
Initialize function name (FUNCNAM), action name +(ACTIONNAM), and action value (ACTIONVAL) global +variables, using positional parameters passed in $@ variable. +
+The cli_getArguments function is called from cli.sh
+function script, using cli function positional parameters
+(i.e., the positional parameters passed as arguments in the
+command-line) as first function argument.
+
Once command-line positional parameters are accesible to
+`centos-art.sh' script execution evironment,
+cli_getArguments uses regular expression to retrive
+action variables from first and second argument. The first argument
+defines the value used as function name (FUNCNAM), and the
+second argument defines both values used as action name
+(ACTIONNAM) and action value (ACTIONVAL), respectively.
+
The first argument is a word in lower case. This word specifies the +name of the functionality you want to use (e.g., `render' to +render images, `manual' to work on documentation, and so on.) +
+The second argument has a long option style (e.g., +`--option=value'). The `--option' represents the action name +(ACTIONNAM), and the characters inbetween the equal sign +(`=') and the first space character, are considered as the action +value (ACTIONVAL). In order to provide action values with space +characters inbetween you need to enclose action value with quotes like +in `--option='This is long value with spaces inbetween''. +Generally, action values are used to specify paths over which the +action name acts on. +
+Once action related variables (i.e., FUNCNAM, ACTIONNAM,
+and ACTIONVAL) are defined and validated,
+cli_getArguments shifts the positional arguments to remove the
+first two arguments passed (i.e., those used to retrive action related
+variables) and redefine the arguments (ARGUMENTS) global
+variable with the new positional parameters information.
+
Initialize funtionalities supported by `centos-art.sh' script. +
+Functionalities supported by `centos-art.sh' script are organized +in functionality directories under +`trunk/Scripts/Bash/Functions/' directory. Each functionality +directory stores function scripts to the functionality such directory +was created for. Function scripts contain function definitions. +Function definitions contain several commands focused on achieving one +specific task only (i.e., the one such functionality was created for). +
+In order for `centos-art.sh' script to recognize a functionality, +such functionality needs to be stored under +`trunk/Scripts/Bash/Functions/' in a directory written +capitalized (i.e., the whole name is written in lowercase except the +first character which is in uppercase). The directory where one +specific functionality is stored is known as the `functionality +directory'. +
+Inside each functionality directory, the functionalty itself is +implemented through function scripts. Function scripts are organized +in files independently one another and written in `camelCase' +format with the function name as prefix. Separation between prefix +and description is done using underscore (`_') character. +
+In order for `centos-art.sh' script to load functionalities +correctly, function definition inside function scripts should be set +using the `function' reserved word, just as in the following +example: +
+
function prefix_doSomething {
+
+ # Do something here...
+
+}
+
+The above function definition is just a convenction we use, in order
+to make identification of function names easier read and automate by
+`centos-art.sh' script initialization commands, once
+`centos-art.sh' script determines which functionality directory
+to use. Specifically, in order to initialize and export functions,
+`centos-art.sh' script executes all function scripts inside the
+functionality directory, and later grep on them using a
+regular expression pattern, where the `function' reserved word is
+used as reference to retrive the function names and export them to
+`centos-art.sh' script execution environment, and so, make
+function definitions --from function scripts inside the functionality
+directory-- available for further calls.
+
If the functionality specified in the command-line first argument +doesn't have a functionality directory, `centos-art.sh' script +considers the functionality provided in the command-line as invalid +functionality and immediatly stops script execution with an error +message. +
+In order to keep visual consistency among function scripts, please +consider using the following function script design model as template +for your own function scripts: +
+#!/bin/bash
+#
+# prefix_doSomething.sh -- This function illustrates function scripts
+# design model you can use to create your own function scripts inside
+# centos-art.sh script.
+#
+# Copyright (C) YEAR YOURFULLNAME
+#
+# 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+# USA.
+#
+# ----------------------------------------------------------------------
+# $Id$
+# ----------------------------------------------------------------------
+
+function prefix_doSomething {
+
+ # Do something here...
+
+}
+Output country codes supported by `centos-art.sh' script. +
+The cli_getCountryCodes function outputs a list with country
+codes as defined in ISO3166 standard. When FILTER is provided,
+cli_getCountryCodes outputs country codes that match
+FILTER regular expression pattern.
+
Outputs country name supported by `centos-art.sh' script. +
+The cli_getCountryName function reads one language locale code
+in the format LL_CC and outputs the name of its related country as in
+ISO3166. If filter is specified, cli_getCountryName returns the
+country name that matches the locale code specified in FILTER,
+exactly.
+
Output current locale used by `centos-art.sh' script. +
+The cli_getCurrentLocale function uses LANG environment
+variable to build a locale pattern that is later applied to
+cli_getLocales function output in order to return the current
+locale that `centos-art.sh' script works with.
+
The current locale information, returned by
+cli_getCurrentLocale, is output from more specific to less
+specific. For example, if `en_GB' locale exists in
+cli_getLocales function output, the `en_GB' locale would
+take precedence before `en' locale.
+
Locale precedence selection is quite important in order to define the +locale type we use for message translations. For example, if +`en_GB' is used, we are also saying that the common language +specification for English language (i.e., `en') is no longer +used. Instead, we are using English non-common country-specific +language specifications like `en_AU', `en_BW', `en_GB', +`en_US', etc., for message translations. +
+Use cli_getCurrentLocale function to know what current locale
+information to use inside `centos-art.sh' script.
+
Output list of files to process. +
+The cli_getFilesList function uses LOCATION variable as
+source location to build a list of files just as specified by regular
+expression (REGEX) global variable. Essentially, what the
+cli_getFilesList function does is using find command
+to look for files in the location (LOCATION) just as posix-egrep
+regular expression (REGEX) specifies.
+
If LOCATION is not specified when cli_getFilesList
+function is called, the action value (ACTIONVAL) global variable
+is used as location value instead.
+
By default, if the regular expression (REGEX) global variable is
+not redefined after its first definition in the cli function,
+all files that match default regular expression value (i.e.,
+`.+') will be added to the list of files to process. Otherwise,
+if you redefine the regular expression global variable after its first
+definition in the cli function and before calling
+cli_getFilesList function, the last value you specifed is used
+instead.
+
When you need to customize the regular expression (REGEX) global +variable value inside a function, do not redefine the global variable +(at least you be absolutly convinced you need to). Instead, set the +regular expression global variable as `local' to the function you +need a customized regular expression value for. If we don't redefine +the regular expression global variable as local to the function, or +use another name for the regular expression variable (which is not +very convenient in order to keep the amount of names to remember low), +you may experiment undesired concantenation issues that make your +regular expression to be something different from that you expect them +to be, specially if the function where you are doing the variable +redefinition is called several times during the same script execution. +
+As result, the cli_getFilesList re-defines the value of
+FILES variable with the list of files the find command
+returned. As example, consider the following construction:
+
function prefix_doSomething {
+
+ # Initialize the list of files to process.
+ local FILES=''
+
+ # Initialize location.
+ local LOCATION=/home/centos/artwork/trunk/Identity/Themes/Models/Default
+
+ # Re-define regular expression to match scalable vector graphic
+ # files only. Note how we use the global value of REGEX to build a
+ # new local REGEX value here.
+ local REGEX="${REGEX}.*\.(svgz|svg)"
+
+ # Redefine list of files to process.
+ cli_getFilesList $LOCATION
+
+ # Process list of files.
+ for FILE in $FILES;do
+ cli_printMessages "$FILE" 'AsResponseLine'
+ # Do something else here on...
+ done
+
+}
+
+Outputs language codes supported by `centos-art.sh' script. +
+cli_getLangCodes function outputs a list of language codes as
+defined in ISO639 standard. When FILTER is provided,
+cli_getLangCodes outputs language codes that match FILTER
+regular expression pattern.
+
Outputs language names supported by `centos-art.sh' script. +
+cli_getLangName function reads one language locale code in the
+format LL_CC and outputs the language related name as in ISO639. If
+filter is specified, cli_getLangName returns the language name
+that matches the locale code specified in FILTER, exactly.
+
Output locale codes supported by `centos-art.sh' script. +
+Occasionally, you use cli_getLocales function to add locale
+information in non-common country-specific language (`LL_CC')
+format for those languages (e.g., `bn_IN', `pt_BR', etc.)
+which locale differences cannot be solved using common language
+specifications (`LL') into one unique common locale specification
+(e.g., `bn', `pt', etc.).
+
Sanitate file names. +
+Inside `centos-art.sh' script, specific functionalities rely both
+in cli_getRepoName and repository file system organization to
+achieve their goals. Consider cli_getRepoName function as
+central place to manage file name convenctions for other functions
+inside `centos-art.sh' script.
+
+ +Important
cli_getRepoNamefunction doesn't verify file +or directory existence, for that purpose usecli_checkFiles+function instead. +
The NAME variable contains the file name or directory name you +want to sanitate. +
+The TYPE variable specifies what type of sanitation you want to +perform on NAME. The TYPE can be one of the following +values: +
+Sanitate directory NAMEs. +
Sanitate regular file NAMEs. +
Use cli_getRepoName function to sanitate file names and
+directory names before their utilization.
+
Use cli_getRepoName when you need to change file name
+convenctions inside `centos-art.sh' script.
+
When we change file name convenctions inside cli_getRepoName
+what we are really changing is the way functions interpret repository
+file system organization. Notice that when we change a file name
+(e.g., a function name), it is necessary to update all files where
+such file name is placed on. This may require a massive substitution
+inside the repository, each time we change name convenctions in the
+repository (-- Removed(pxref:trunk Scripts Bash Functions Path) --, for more
+information).
+
Request repository status. +
+This function requests the status of a LOCATION inside the
+working copy using the svn status command and returns the
+first character in the output line, just as described in svn
+help status. If LOCATION is not a regular file or a directory,
+inside the working copy, the `centos-art.sh' script prints a
+message and ends its execution.
+
Use this function to perform verifications based a repository +LOCATION status. +
Output absolute path to temporal file NAME. +
+The cli_getTemporalFile function uses `/tmp' directory as
+source location to store temporal files, the `centos-art.sh'
+script name, and a random identification string to let you run more
+than one `centos-art.sh' script simultaneously on the same user
+session. For example, due the following temporal file defintion:
+
cli_getTemporalFile $FILE ++
If FILE name is `instance.svg' and the unique random string +is `f16f7b51-ac12-4b7f-9e66-72df847f12de', the final temporal +file, built from previous temporal file definition, would be: +
+/tmp/centos-art.sh-f16f7b51-ac12-4b7f-9e66-72df847f12de-instance.svg ++
When you use the cli_getTemporalFile function to create
+temporal files, be sure to remove temporal files created once you've
+ended up with them. For example, consider the following construction:
+
for FILE in $FILES;do + + # Initialize temporal instance of file. + INSTANCE=$(cli_getTemporalFile $FILE) + + # Do something ... + + # Remove temporal instance of file. + if [[ -f $INSTANCE ]];then + rm $INSTANCE + fi + +done ++
Use the cli_getTemporalFile function whenever you need to
+create temporal files inside `centos-art.sh' script.
+
Output theme name. +
+In order for cli_getThemeName function to extract theme name
+correctly, the ACTIONVAL variable must contain a directory path
+under `trunk/Identity/Themes/Motifs/' directory structure.
+Otherwise, cli_getThemeName returns an empty string.
+
Define standard output message definition supported by +`centos-art.sh' script. +
+When FORMAT is not specified, cli_printMessage outputs
+information just as it was passed in MESSAGE variable.
+Otherwise, FORMAT can take one of the following values:
+
To print heading messages. +
---------------------------------------------------------------------- +$MESSAGE +---------------------------------------------------------------------- ++
To print warning messages. +
---------------------------------------------------------------------- +WARNING: $MESSAGE +---------------------------------------------------------------------- ++
To print note messages. +
---------------------------------------------------------------------- +NOTE: $MESSAGE +---------------------------------------------------------------------- ++
To print `Updating' messages on two-columns format. +
Updating $MESSAGE ++
To print `Removing' messages on two-columns format. +
Removing $MESSAGE ++
To print `Checking' messages on two-columns format. +
Checking $MESSAGE ++
To print `Creating' messages on two-columns format. +
Creating $MESSAGE ++
To print `Saved as' messages on two-columns format. +
Saved as $MESSAGE ++
To print `Linked to' messages on two-columns format. +
Linked to $MESSAGE ++
To print `Moved to' messages on two-columns format. +
Moved to $MESSAGE ++
To print `Translation' messages on two-columns format. +
Translation $MESSAGE ++
To print `Configuration' messages on two-columns format. +
Configuration $MESSAGE ++
To print response messages on one-column format. +
--> $MESSAGE ++
To print request messages on one-column format. Request messages +output messages with one colon (`:') and without trailing newline +(`\n') at message end. +
$MESSAGE: ++
To print `yes or no' request messages on one-column format. If
+something different from `y' is answered (when using
+en_US.UTF-8 locale), script execution ends immediatly.
+
$MESSAGE [y/N]: ++
When we use `centos-art.sh' script in a locale different from
+en_US.UTF-8, confirmation answer may be different from
+`y'. For example, if you use es_ES.UTF-8 locale, the
+confirmation question would look like:
+
$MESSAGE [s/N]: ++
and the confirmation answer would be `s', as it is on Spanish +`sí' word. +
+Definition of which confirmation word to use is set on translation +messages for your specific locale information. -- Removed(xref:trunk Scripts +Bash Functions Locale) --, for more information about locale-specific +translation messages. +
+To standardize `to know more, run the following command:'
+messages. When the `AsToKnowMoreLine' option is used, the
+MESSAGE value should be set to "$(caller)". caller
+is a Bash builtin that returns the context of the current subroutine
+call. `AsToKnowMoreLine' option uses caller builtin
+output to build documentation entries dynamically.
+
---------------------------------------------------------------------- +To know more, run the following command: +centos-art manual --read='path/to/dir' +---------------------------------------------------------------------- ++
Use `AsToKnowMoreLine' option after errors and for intentional +script termination. +
+To standardize regular messages on one-column format. +
+When MESSAGE contains a colon inside (e.g., `description:
+message'), the cli_printMessage function outputs MESSAGE
+on two-columns format.
+
Use cli_printMessage function whenever you need to output
+information from `centos-art.sh' script.
+
+Tip
To improve two-columns format, change the following file: +
trunk/Scripts/Bash/Styles/output_forTwoColumns.awk +
The following specific functions of `centos-art.sh' script, are +available for you to use: +
+ + +| 3.47 trunk/Scripts/Bash | + | |
| 3.60 trunk/Scripts/Bash/Locale | + |
| [ < ] | -[ > ] | +||||||||||||||||||||||||||
| [ < ] | +[ > ] | [ << ] | [ Up ] | diff --git a/Manuals/Filesystem/filesystem-html/filesystem_53.html b/Manuals/Filesystem/filesystem-html/filesystem_53.html index 527c72f..e0e1634 100644 --- a/Manuals/Filesystem/filesystem-html/filesystem_53.html +++ b/Manuals/Filesystem/filesystem-html/filesystem_53.html @@ -20,10 +20,10 @@ Send bugs and suggestions to
| [ < ] | -[ > ] | +|||||
| [ < ] | +[ > ] | [ << ] | [ Up ] | @@ -67,1292 +67,38 @@ ul.toc {list-style: none}[Index] | [ ? ] |
The `trunk/Scripts/Bash/Functions' directory exists to organize -`centos-art.sh' specific functionalities. -
- - -The specific functions of `centos-art.sh' script are designed -with "Software Toolbox" philosophy (see (coreutils.info)Toolbox introduction) in mind: each program "should do one -thing well". Inside `centos-art.sh' script, each specific -functionality is considered a program that should do one thing well. -Of course, if you find that they still don't do it, feel free to -improve them in order for them to do so. -
-The specific functions of `centos-art.sh' script are organized
-inside specific directories under `trunk/Scripts/Bash/Functions'
-location. Each specific function directory should be named as the
-function it represents, with the first letter in uppercase. For
-example, if the function name is render, the specific function
-directory for it would be `trunk/Scripts/Bash/Functions/Render'.
-
To better understand how specific functions of `centos-art.sh' -script are designed, lets create one function which only goal is to -output different kind of greetings to your screen. -
-When we create specific functions for `centos-art.sh' script it -is crucial to know what these functions will do exactly and if there -is any function that already does what we intend to do. If there is no -one, it is good time to create them then. Otherwise, if -functionalities already available don't do what you exactly expect, -contact their authors and work together to improve them. -
-- -Tip
Join CentOS developers mailing list -centos-art@centos.org to share your ideas. -
It is also worth to know what global functions and variables do we -have available inside `centos-art.sh' script, so advantage can be -taken from them. Global variables are defined inside global function -scripts. Global functions scripts are stored immediatly under -`trunk/Scripts/Bash/Functions' directory, in files begining with -`cli' prefix. -
-OK, let's begin with our functionality example. -
-What function name do we use? Well, lets use greet. Note that
-`hello' word is not a verb; but an expression, a kind of
-greeting, an interjection specifically. In contrast, `greet' is a
-verb and describes what we do when we say `Hello!', `Hi!',
-and similar expressions.
-
So far, we've gathered the following function information: -
-Name: greet -Path: trunk/Scripts/Bash/Functions/Greet -File: trunk/Scripts/Bash/Functions/Greet/greet.sh --
The `greet.sh' function script is the first file
-`centos-art.sh' script loads when the `greet' functionality
-is called using commands like `centos-art greet --hello='World''.
-The `greet.sh' function script contains the greet function
-definition.
-
Inside `centos-art.sh' script, as convenction, each function -script has one top commentary, followed by one blank line, and then -one function defintion below it only. -
-Inside `centos-art.sh' script functions, top commentaries have
-the following components: the functionality description, one-line for
-copyright note with your personal information, the license under
-which the function source code is released --the `centos-art.sh'
-script is released as GPL, so do all its functions--, the $Id$
-keyword of Subversion is later expanded by svn propset
-command.
-
In our greet function example, top commentary for
-`greet.sh' function script would look like the following:
-
#!/bin/bash -# -# greet.sh -- This function outputs different kind of greetings to -# your screen. Use this function to understand how centos-art.sh -# script specific functionalities work. -# -# Copyright (C) YEAR YOURFULLNAME -# -# 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 -# USA. -# -# ---------------------------------------------------------------------- -# $Id$ -# ---------------------------------------------------------------------- --
After top commentary, separated by one blank line, the greet
-function definition would look like the following:
-
function greet {
-
- # Define global variables.
-
- # Define command-line interface.
- greet_getActions
-
-}
-
-The first definition inside greet function, are global
-variables that will be available along greet function execution
-environment. This time we didn't use global variable definitions for
-greet function execution environment, so we left that section
-empty.
-
Later, we call greet_getActions function to define the
-command-line interface of greet functionality. The command-line
-interface of greet functionality defines what and how actions
-are performed, based on arguments combination passed to
-`centos-art.sh' script.
-
function greet_getActions {
-
- case "$ACTIONNAM" in
-
- --hello )
- greet_doHello
- ;;
-
- --bye )
- greet_doBye
- ;;
-
- * )
- cli_printMessage "`gettext "The option provided is not valid."`"
- cli_printMessage "$(caller)" 'AsToKnowMoreLine'
-
- esac
-
-}
-
-The ACTIONNAM global variable is defined in `cli.sh' -function script and contains the value passed before the equal sign -(i.e., `=') in the second command-line argument of -`centos-art.sh' script. For example, if the second command-line -argument is `--hello='World'', the value of ACTIONNAM -variable would be `--hello'. Using this configuration let us -deside which action to perform based on the action name passed to -`centos-art.sh' script as second argument. -
-The greet function definition makes available two valid
-greetings through `--hello' and `--bye' options. If no
-one of them is provided as second command-line argument, the `*'
-case is evaluated instead.
-
The `*' case and its two lines further on should always be -present in `_getActions.sh' function scripts, no matter what -specific functionality you are creating. This convenction helps the -user to find out documentation about current functionality in use, -when no valid action is provided. -
-The greet_doHello and greet_doBye function definitions
-are the core of greet specific functionality. In such function
-definitions we set what our greet function really does: to
-output different kinds of greetings.
-
function greet_doHello {
-
- cli_printMessage "`gettext "Hello"` $ACTIONVAL"
-
-}
-
-The greet_doHello function definition is stored in
-`greet_doHello.sh' function script.
-
function greet_doBye {
-
- cli_printMessage "`gettext "Goodbye"` $ACTIONVAL"
-
-}
-
-The greet_doBye function definition is stored in the
-`greet_doBye.sh' function script.
-
Both `greet_doHello.sh' and `greet_doBye.sh' function
-scripts are stored inside greet function directory path (i.e.
-`trunk/Scripts/Bash/Functions/Greet').
-
The ACTIONVAL global variable is defined in `cli.sh' -function script and contains the value passed after the equal sign -(i.e., `=') in the second command-line argument of -`centos-art.sh' script. For example, if the second command-line -argument is `--hello='World'', the value of ACTIONVAL -variable would be `World' without quotes. -
-Let's see how greet specific functionality files are organzied
-under greet function directory. To see file organization we use
-the tree command:
-
trunk/Scripts/Bash/Functions/Greet -|-- greet_doBye.sh -|-- greet_doHello.sh -|-- greet_getActions.sh -`-- greet.sh --
To try the greet specific functionality we've just created,
-pass the function name (i.e., `greet') as first argument to
-`centos-art.sh' script, and any of the valid options as second
-argument. Some examples are illustrated below:
-
[centos@projects ~]$ centos-art greet --hello='World' -Hello World -[centos@projects ~]$ centos-art greet --bye='World' -Goodbye World -[centos@projects ~]$ --
The word `World' in the examples above can be anything. In fact, -change it to have a little fun. -
-Now that we have a specific function that works as we expect, it is
-time to document it. To document greet specific functionality,
-we use its directory path and the manual functionality
-(see section trunk/Scripts/Bash/Functions/Manual) of `centos-art.sh'
-script, just as the following command illustrates:
-
centos-art manual --edit=trunk/Scripts/Bash/Functions/Greet --
To have a well documented function helps user to understand how your -function really works, and how it should be used. When no valid -action is passed to a function, the `centos-art.sh' script uses -the function documentation entry as vehicle to communicate which the -valid functions are. When no documentation entry exists for a -function, the `centos-art.sh' script informs that no -documentation entry exists for such function and requests user to -create it right at that time. -
-Now that we have documented our function, it is time to translate its
-output messages to different languages. To translate specific
-functionality output messages to different languages we use the
-locale functionality (see section trunk/Scripts/Bash/Functions/Locale) of `centos-art.sh' script, just as the following command
-illustrates:
-
centos-art locale --edit --
- -Warning
To translate output messages in different languages, -your system locale information --as in
LANGenvironment -variable-- must be set to that locale you want to produce translated -messages for. For example, if you want to produce translated messages -for Spanish language, your system locale information must be set to -`es_ES.UTF-8', or similar, first. -
Well, it seems that our example is rather complete by now. -
-In greet function example we've described so far, we only use
-cli_printMessage global function in action specific function
-definitions in order to print messages, but more interesting things
-can be achieved inside action specific function definitions. For
-example, if you pass a directory path as action value in second
-argument, you could retrive a list of files from therein, and process
-them. If the list of files turns too long or you just want to control
-which files to process, you could add the third argument in the form
-`--filter='regex'' and reduce the amount of files to process
-using a regular expression pattern.
-
The greet function described in this section may serve you as
-an introduction to understand how specific functionalities work inside
-`centos-art.sh' script. With some of luck this introduction will
-also serve you as motivation to create your own `centos-art.sh'
-script specific functionalities.
-
By the way, the greet functionality doesn't exist inside
-`centos-art.sh' script yet. Would you like to create it?
-
The following global variables of `centos-art.sh' script, are -available for you to use inside specific functions: -
-Default domain used to retrieve translated messages. This value is set -in `initFunctions.sh' and shouldn't be changed. -
Default directory used to retrieve translated messages. This value is -set in `initFunctions.sh' and shouldn't be changed. -
Define function name. -
-Function names associate sets of actions. There is one set of actions -for each unique function name inside `centos-art.sh' script. -
-Dunction names are passed as first argument in `centos-art.sh' -command-line interface. For example, in the command `centos-art -render --entry=path/to/dir --filter=regex', the ACTION passed to -`centos-art.sh' script is `render'. -
-When first argument is not provided, the `centos-art.sh' script -immediatly ends its execution. -
Define action name. -
-Each action name identifies an specific action to perform, inside an -specific function. -
-Action name names aare passed as second argument in -`centos-art.sh' command-line interface. For example, in the -command `centos-art render --entry=path/to/dir --filter=regex', -the ACTIONNAM passed to `centos-art.sh' script is -`--entry'. -
-When second argument is not provided, the `centos-art.sh' script -immediatly ends its execution. -
Define action value. -
-Action values are associated to just one action name. Action values -contain the working copy entry over which its associated action will be -performed in. Working copy entries can be files or directories inside -the working copy. -
Define regular expression used as pattern to build the list of files -to process. -
-By default, REGEX variable is set to .+ to match all
-files.
-
Functions that need to build a list of files to process use the option -`--filter' to redefine REGEX variable default value, and -so, control the amount of files to process. -
Define optional arguments. -
-Optional arguments, inside `centos-art.sh' script, are considered -as all command-line arguments passed to `centos-art.sh' script, -from third argument position on. For example, in the command -`centos-art render --entry=path/to/dir --filter=regex' , the -optional arguments are from `--filter=regex' argument on. -
-Optional arguments are parsed using getopt command through
-the following base construction:
-
# Define short options we want to support. -local ARGSS="" - -# Define long options we want to support. -local ARGSL="filter:,to:" - -# Parse arguments using getopt(1) command parser. -cli_doParseArguments - -# Reset positional parameters using output from (getopt) argument -# parser. -eval set -- "$ARGUMENTS" - -# Define action to take for each option passed. -while true; do - case "$1" in - --filter ) - REGEX="$2" - shift 2 - ;; - --to ) - TARGET="$2" - shift 2 - ;; - * ) - break - esac -done --
Optional arguments provide support to command options inside
-`centos-art.sh' script. For instance, consider the Subversion
-(svn) command, where there are many options (e.g.,
-`copy', `delete', `move', etc), and inside each
-option there are several modifiers (e.g., `--revision',
-`--message', `--username', etc.) that can be combined one
-another in their short or long variants.
-
The ARGUMENTS variable is used to store arguments passed from -command-line for later use inside `centos-art.sh' script. Storing -arguments is specially useful when we want to run a command with some -specific options from them. Consider the following command: -
-centos-art path --copy=SOURCE --to=TARGET --message="The commit message goes here." --username='johndoe' --
In the above command, the `--message', and `--username'
-options are specific to svn copy command. In such cases,
-options are not interpreted by `centos-art.sh' script itself.
-Instead, the `centos-art.sh' script uses getopt to
-retrive them and store them in the ARGUMENTS variable for later
-use, as described in the following command:
-
# Build subversion command to duplicate locations inside the -# workstation. -eval svn copy $SOURCE $TARGET --quiet $ARGUMENTS --
When getopt parses ARGUMENTS, we may use short options
-(e.g., `-m') or long options (e.g., `--message'). When
-we use short options, arguments are separated by one space from the
-option (e.g., `-m 'This is a commit message.''). When we use
-long options arguments are separated by an equal sign (`=')
-(e.g., `--message='This is a commit message'').
-
In order for getopt to parse ARGUMENTS correctly, it
-is required to provide the short and long definition of options that
-will be passed or at least supported by the command performing the
-final action the function script exists for.
-
As convenction, inside `centos-art.sh' script, short option -definitions are set in the ARGSS variable; and long option -definitions are set in the ARGSL variable. -
-When you define short and long options, it may be needed to define -which of these option arguments are required and which not. To define -an option argument as required, you need to set one colon `:' -after the option definition (e.g., `-o m: -l message:'). On -the other hand, to define an option argument as not required, you need -to set two colons `::' after the option definition (e.g., -`-o m:: -l message::'). -
Default text editor. -
-The `centos-art.sh' script uses default text EDITOR to edit
-pre-commit subversion messages, translation files, configuration
-files, script files, and similar text-based files.
-
If EDITOR environment variable is not set, `centos-art.sh'
-script uses `/usr/bin/vim' as default text editor. Otherwise, the
-following values are recognized by `centos-art.sh' script:
-
If no one of these values is set in EDITOR environment variable,
-`centos-art.sh' uses `/usr/bin/vim' text editor by default.
-
Function scripts stored directly under -`trunk/Scripts/Bash/Functions/' directory are used to define -global functions. Global functions can be used inside action specific -functionalities and or even be reused inside themselves. This section -provides introductory information to global functions you can use -inside `centos-art.sh' script. -
-Validate action value (ACTIONVAL) variable. -
-The action value variable can take one of the following values: -
-If another value different from that specified above is passed to -action value variable, the `centos-art.sh' script prints an error -message and ends script execution. -
Verify file existence. -
-cli_checkFiles receives a FILE absolute path and performs
-file verification as specified in TYPE. When TYPE is not
-specified, cli_checkFiles verifies FILE existence, no
-matter what kind of file it be. If TYPE is specified, use one
-of the following values:
-
Ends script execution if FILE is not a directory. -
-When you verify directories with cli_checkFiles, if directory doesn't -exist, `centos-art.sh' script asks you for confirmation in order -to create that directory. If you answer positively, -`centos-art.sh' script creates that directory and continues -script flows normally. Otherwise, if you answer negatively, -`centos-art.sh' ends script execution with an error and -documentation message. -
-Ends script execution if FILE is not a regular file. -
Ends script execution if FILE is not a symbolic link. -
Ends script execution if FILE is not executable. -
Ends script execution if FILE is neither a regular file nor a -symbolic link. -
Ends script execution if FILE is neither a regular file nor a -directory. -
Ends script execution if FILE is not inside the working copy. -
As default behaviour, if FILE passes all verifications, -`centos-art.sh' script continues with its normal flow. -
Syncronize changes between repository and working copy. -
-The cli_commitRepoChanges function brings changes from the
-central repository down to the working copy--using svn
-update--, checks the working copy changes--using svn
-status command--, prints status report--using both svn
-update and svn status commands output, and finally, commits
-recent changes from the working copy up to the repository--using
-svn commit command--.
-
Previous to commit the working copy changes up to the central
-repository, the cli_commitRepoChanges function asks you to
-verify changes--using svn diff command--, and later,
-another confirmation question is shown to be sure you really want to
-commit changes up to central repository.
-
If LOCATION argument is not specified, the value of -ACTIONVAL variable is used as reference instead. -
----------------------------------------------------------------------- ---> Bringing changes from the repository into the working copy ---> Checking changes in the working copy ----------------------------------------------------------------------- -Added 0 file from the repository. -Deleted 0 file from the repository. -Updated 0 file from the repository. -Conflicted 0 file from the repository. -Merged 0 file from the repository. -Modified 4 files from the working copy. -Unversioned 0 file from the working copy. -Deleted 0 file from the working copy. -Added 0 file from the working copy. ----------------------------------------------------------------------- --
Figure 3.3: The cli_commitRepoChanges function output.
-
-
Call the cli_commitRepoChanges function before or/and after
-calling functions that modify files or directories inside the working
-copy as you may need to.
-
Redefine arguments (ARGUMENTS) global variable using
-getopt command output. For more information about how to use
-cli_doParseArguments function, see ARGUMENTS variable
-description above.
-
Initialize/reset arguments (ARGUMENTS) global variable using -positional parameters variable ($@) as reference. -
-When we work inside function definitions, positional parameters are
-reset to the last function definition positional parameters. If you
-need to redefine positional parameters from one specific function, you
-need to call cli_doParseArgumentsReDef with the positional
-parameters variable ($@), set as first argument, to that
-specific function you want to redefine positional parameters at.
-
Initialize function name (FUNCNAM), action name -(ACTIONNAM), and action value (ACTIONVAL) global -variables, using positional parameters passed in $@ variable. -
-The cli_getArguments function is called from cli.sh
-function script, using cli function positional parameters
-(i.e., the positional parameters passed as arguments in the
-command-line) as first function argument.
-
Once command-line positional parameters are accesible to
-`centos-art.sh' script execution evironment,
-cli_getArguments uses regular expression to retrive
-action variables from first and second argument. The first argument
-defines the value used as function name (FUNCNAM), and the
-second argument defines both values used as action name
-(ACTIONNAM) and action value (ACTIONVAL), respectively.
-
The first argument is a word in lower case. This word specifies the -name of the functionality you want to use (e.g., `render' to -render images, `manual' to work on documentation, and so on.) -
-The second argument has a long option style (e.g., -`--option=value'). The `--option' represents the action name -(ACTIONNAM), and the characters inbetween the equal sign -(`=') and the first space character, are considered as the action -value (ACTIONVAL). In order to provide action values with space -characters inbetween you need to enclose action value with quotes like -in `--option='This is long value with spaces inbetween''. -Generally, action values are used to specify paths over which the -action name acts on. -
-Once action related variables (i.e., FUNCNAM, ACTIONNAM,
-and ACTIONVAL) are defined and validated,
-cli_getArguments shifts the positional arguments to remove the
-first two arguments passed (i.e., those used to retrive action related
-variables) and redefine the arguments (ARGUMENTS) global
-variable with the new positional parameters information.
-
Initialize funtionalities supported by `centos-art.sh' script. -
-Functionalities supported by `centos-art.sh' script are organized -in functionality directories under -`trunk/Scripts/Bash/Functions/' directory. Each functionality -directory stores function scripts to the functionality such directory -was created for. Function scripts contain function definitions. -Function definitions contain several commands focused on achieving one -specific task only (i.e., the one such functionality was created for). -
-In order for `centos-art.sh' script to recognize a functionality, -such functionality needs to be stored under -`trunk/Scripts/Bash/Functions/' in a directory written -capitalized (i.e., the whole name is written in lowercase except the -first character which is in uppercase). The directory where one -specific functionality is stored is known as the `functionality -directory'. -
-Inside each functionality directory, the functionalty itself is -implemented through function scripts. Function scripts are organized -in files independently one another and written in `camelCase' -format with the function name as prefix. Separation between prefix -and description is done using underscore (`_') character. -
-In order for `centos-art.sh' script to load functionalities -correctly, function definition inside function scripts should be set -using the `function' reserved word, just as in the following -example: -
-function prefix_doSomething {
-
- # Do something here...
-
-}
-
-The above function definition is just a convenction we use, in order
-to make identification of function names easier read and automate by
-`centos-art.sh' script initialization commands, once
-`centos-art.sh' script determines which functionality directory
-to use. Specifically, in order to initialize and export functions,
-`centos-art.sh' script executes all function scripts inside the
-functionality directory, and later grep on them using a
-regular expression pattern, where the `function' reserved word is
-used as reference to retrive the function names and export them to
-`centos-art.sh' script execution environment, and so, make
-function definitions --from function scripts inside the functionality
-directory-- available for further calls.
-
If the functionality specified in the command-line first argument -doesn't have a functionality directory, `centos-art.sh' script -considers the functionality provided in the command-line as invalid -functionality and immediatly stops script execution with an error -message. -
-In order to keep visual consistency among function scripts, please -consider using the following function script design model as template -for your own function scripts: -
-#!/bin/bash
-#
-# prefix_doSomething.sh -- This function illustrates function scripts
-# design model you can use to create your own function scripts inside
-# centos-art.sh script.
-#
-# Copyright (C) YEAR YOURFULLNAME
-#
-# 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307
-# USA.
-#
-# ----------------------------------------------------------------------
-# $Id$
-# ----------------------------------------------------------------------
-
-function prefix_doSomething {
-
- # Do something here...
-
-}
-Output country codes supported by `centos-art.sh' script. -
-The cli_getCountryCodes function outputs a list with country
-codes as defined in ISO3166 standard. When FILTER is provided,
-cli_getCountryCodes outputs country codes that match
-FILTER regular expression pattern.
-
Outputs country name supported by `centos-art.sh' script. -
-The cli_getCountryName function reads one language locale code
-in the format LL_CC and outputs the name of its related country as in
-ISO3166. If filter is specified, cli_getCountryName returns the
-country name that matches the locale code specified in FILTER,
-exactly.
-
Output current locale used by `centos-art.sh' script. -
-The cli_getCurrentLocale function uses LANG environment
-variable to build a locale pattern that is later applied to
-cli_getLocales function output in order to return the current
-locale that `centos-art.sh' script works with.
-
The current locale information, returned by
-cli_getCurrentLocale, is output from more specific to less
-specific. For example, if `en_GB' locale exists in
-cli_getLocales function output, the `en_GB' locale would
-take precedence before `en' locale.
-
Locale precedence selection is quite important in order to define the -locale type we use for message translations. For example, if -`en_GB' is used, we are also saying that the common language -specification for English language (i.e., `en') is no longer -used. Instead, we are using English non-common country-specific -language specifications like `en_AU', `en_BW', `en_GB', -`en_US', etc., for message translations. -
-Use cli_getCurrentLocale function to know what current locale
-information to use inside `centos-art.sh' script.
-
Output list of files to process. -
-The cli_getFilesList function uses LOCATION variable as
-source location to build a list of files just as specified by regular
-expression (REGEX) global variable. Essentially, what the
-cli_getFilesList function does is using find command
-to look for files in the location (LOCATION) just as posix-egrep
-regular expression (REGEX) specifies.
-
If LOCATION is not specified when cli_getFilesList
-function is called, the action value (ACTIONVAL) global variable
-is used as location value instead.
-
By default, if the regular expression (REGEX) global variable is
-not redefined after its first definition in the cli function,
-all files that match default regular expression value (i.e.,
-`.+') will be added to the list of files to process. Otherwise,
-if you redefine the regular expression global variable after its first
-definition in the cli function and before calling
-cli_getFilesList function, the last value you specifed is used
-instead.
-
When you need to customize the regular expression (REGEX) global -variable value inside a function, do not redefine the global variable -(at least you be absolutly convinced you need to). Instead, set the -regular expression global variable as `local' to the function you -need a customized regular expression value for. If we don't redefine -the regular expression global variable as local to the function, or -use another name for the regular expression variable (which is not -very convenient in order to keep the amount of names to remember low), -you may experiment undesired concantenation issues that make your -regular expression to be something different from that you expect them -to be, specially if the function where you are doing the variable -redefinition is called several times during the same script execution. -
-As result, the cli_getFilesList re-defines the value of
-FILES variable with the list of files the find command
-returned. As example, consider the following construction:
-
function prefix_doSomething {
-
- # Initialize the list of files to process.
- local FILES=''
-
- # Initialize location.
- local LOCATION=/home/centos/artwork/trunk/Identity/Themes/Models/Default
-
- # Re-define regular expression to match scalable vector graphic
- # files only. Note how we use the global value of REGEX to build a
- # new local REGEX value here.
- local REGEX="${REGEX}.*\.(svgz|svg)"
-
- # Redefine list of files to process.
- cli_getFilesList $LOCATION
-
- # Process list of files.
- for FILE in $FILES;do
- cli_printMessages "$FILE" 'AsResponseLine'
- # Do something else here on...
- done
-
-}
-
-Outputs language codes supported by `centos-art.sh' script. -
-cli_getLangCodes function outputs a list of language codes as
-defined in ISO639 standard. When FILTER is provided,
-cli_getLangCodes outputs language codes that match FILTER
-regular expression pattern.
-
Outputs language names supported by `centos-art.sh' script. -
-cli_getLangName function reads one language locale code in the
-format LL_CC and outputs the language related name as in ISO639. If
-filter is specified, cli_getLangName returns the language name
-that matches the locale code specified in FILTER, exactly.
-
Output locale codes supported by `centos-art.sh' script. -
-Occasionally, you use cli_getLocales function to add locale
-information in non-common country-specific language (`LL_CC')
-format for those languages (e.g., `bn_IN', `pt_BR', etc.)
-which locale differences cannot be solved using common language
-specifications (`LL') into one unique common locale specification
-(e.g., `bn', `pt', etc.).
-
Sanitate file names. -
-Inside `centos-art.sh' script, specific functionalities rely both
-in cli_getRepoName and repository file system organization to
-achieve their goals. Consider cli_getRepoName function as
-central place to manage file name convenctions for other functions
-inside `centos-art.sh' script.
-
- -Important
cli_getRepoNamefunction doesn't verify file -or directory existence, for that purpose usecli_checkFiles-function instead. -
The NAME variable contains the file name or directory name you -want to sanitate. -
-The TYPE variable specifies what type of sanitation you want to -perform on NAME. The TYPE can be one of the following -values: -
-Sanitate directory NAMEs. -
Sanitate regular file NAMEs. -
Use cli_getRepoName function to sanitate file names and
-directory names before their utilization.
-
Use cli_getRepoName when you need to change file name
-convenctions inside `centos-art.sh' script.
-
When we change file name convenctions inside cli_getRepoName
-what we are really changing is the way functions interpret repository
-file system organization. Notice that when we change a file name
-(e.g., a function name), it is necessary to update all files where
-such file name is placed on. This may require a massive substitution
-inside the repository, each time we change name convenctions in the
-repository (see section trunk/Scripts/Bash/Functions/Path, for more
-information).
-
Request repository status. -
-This function requests the status of a LOCATION inside the
-working copy using the svn status command and returns the
-first character in the output line, just as described in svn
-help status. If LOCATION is not a regular file or a directory,
-inside the working copy, the `centos-art.sh' script prints a
-message and ends its execution.
-
Use this function to perform verifications based a repository -LOCATION status. -
Output absolute path to temporal file NAME. -
-The cli_getTemporalFile function uses `/tmp' directory as
-source location to store temporal files, the `centos-art.sh'
-script name, and a random identification string to let you run more
-than one `centos-art.sh' script simultaneously on the same user
-session. For example, due the following temporal file defintion:
-
cli_getTemporalFile $FILE --
If FILE name is `instance.svg' and the unique random string -is `f16f7b51-ac12-4b7f-9e66-72df847f12de', the final temporal -file, built from previous temporal file definition, would be: -
-/tmp/centos-art.sh-f16f7b51-ac12-4b7f-9e66-72df847f12de-instance.svg --
When you use the cli_getTemporalFile function to create
-temporal files, be sure to remove temporal files created once you've
-ended up with them. For example, consider the following construction:
-
for FILE in $FILES;do - - # Initialize temporal instance of file. - INSTANCE=$(cli_getTemporalFile $FILE) - - # Do something ... - - # Remove temporal instance of file. - if [[ -f $INSTANCE ]];then - rm $INSTANCE - fi - -done --
Use the cli_getTemporalFile function whenever you need to
-create temporal files inside `centos-art.sh' script.
-
Output theme name. -
-In order for cli_getThemeName function to extract theme name
-correctly, the ACTIONVAL variable must contain a directory path
-under `trunk/Identity/Themes/Motifs/' directory structure.
-Otherwise, cli_getThemeName returns an empty string.
-
Define standard output message definition supported by -`centos-art.sh' script. -
-When FORMAT is not specified, cli_printMessage outputs
-information just as it was passed in MESSAGE variable.
-Otherwise, FORMAT can take one of the following values:
-
To print heading messages. -
---------------------------------------------------------------------- -$MESSAGE ----------------------------------------------------------------------- --
To print warning messages. -
---------------------------------------------------------------------- -WARNING: $MESSAGE ----------------------------------------------------------------------- --
To print note messages. -
---------------------------------------------------------------------- -NOTE: $MESSAGE ----------------------------------------------------------------------- --
To print `Updating' messages on two-columns format. -
Updating $MESSAGE --
To print `Removing' messages on two-columns format. -
Removing $MESSAGE --
To print `Checking' messages on two-columns format. -
Checking $MESSAGE --
To print `Creating' messages on two-columns format. -
Creating $MESSAGE --
To print `Saved as' messages on two-columns format. -
Saved as $MESSAGE --
To print `Linked to' messages on two-columns format. -
Linked to $MESSAGE --
To print `Moved to' messages on two-columns format. -
Moved to $MESSAGE --
To print `Translation' messages on two-columns format. -
Translation $MESSAGE --
To print `Configuration' messages on two-columns format. -
Configuration $MESSAGE --
To print response messages on one-column format. -
--> $MESSAGE --
To print request messages on one-column format. Request messages -output messages with one colon (`:') and without trailing newline -(`\n') at message end. -
$MESSAGE: --
To print `yes or no' request messages on one-column format. If
-something different from `y' is answered (when using
-en_US.UTF-8 locale), script execution ends immediatly.
-
$MESSAGE [y/N]: --
When we use `centos-art.sh' script in a locale different from
-en_US.UTF-8, confirmation answer may be different from
-`y'. For example, if you use es_ES.UTF-8 locale, the
-confirmation question would look like:
-
$MESSAGE [s/N]: --
and the confirmation answer would be `s', as it is on Spanish -`sí' word. -
-Definition of which confirmation word to use is set on translation -messages for your specific locale information. See section trunk/Scripts/Bash/Functions/Locale, for more information about locale-specific -translation messages. -
-To standardize `to know more, run the following command:'
-messages. When the `AsToKnowMoreLine' option is used, the
-MESSAGE value should be set to "$(caller)". caller
-is a Bash builtin that returns the context of the current subroutine
-call. `AsToKnowMoreLine' option uses caller builtin
-output to build documentation entries dynamically.
-
---------------------------------------------------------------------- -To know more, run the following command: -centos-art manual --read='path/to/dir' ----------------------------------------------------------------------- --
Use `AsToKnowMoreLine' option after errors and for intentional -script termination. -
-To standardize regular messages on one-column format. -
-When MESSAGE contains a colon inside (e.g., `description:
-message'), the cli_printMessage function outputs MESSAGE
-on two-columns format.
-
Use cli_printMessage function whenever you need to output
-information from `centos-art.sh' script.
-
-Tip
To improve two-columns format, change the following file: -
trunk/Scripts/Bash/Styles/output_forTwoColumns.awk -
The following specific functions of `centos-art.sh' script, are -available for you to use: -
-| 3.47 trunk/Scripts/Bash | - | |
| 3.60 trunk/Scripts/Bash/Locale | - |
| [ > ] | [ << ] | -[ Up ] | +[ Up ] | [ >> ] |
diff --git a/Manuals/Filesystem/filesystem-html/filesystem_54.html b/Manuals/Filesystem/filesystem-html/filesystem_54.html
index 9efa026..81600d9 100644
--- a/Manuals/Filesystem/filesystem-html/filesystem_54.html
+++ b/Manuals/Filesystem/filesystem-html/filesystem_54.html
@@ -20,10 +20,10 @@ Send bugs and suggestions to [Index]
[ ? ]
| 3.47 trunk/Scripts/Bash | ||
| 3.50 trunk/Scripts/Bash/Functions | - |
The render functionality exists to produce both identity and
translation files on different levels of information (i.e., different
@@ -180,7 +180,8 @@ produce image-based content, `centos-art.sh' produces
PNG (Portable Network Graphics) files with the .png
extension. Once the base image format has been produced, it is
possible for `centos-art.sh' to use it in order to automatically
-create other image formats that may be needed (see section trunk/Scripts/Bash/Functions/Render/Config).
+create other image formats that may be needed (-- Removed(pxref:trunk Scripts
+Bash Functions Render Config) --).
Inside the working copy, you can find an example of "design template without translation" configuration at `trunk/Identity/Models/'. @@ -288,7 +289,7 @@ design template instance is removed. At this point, whole production flow once again (design template by design template), until all design templates be processed.
-See section trunk/Scripts/Bash/Functions/Render/Config, for more +
-- Removed(xref:trunk Scripts Bash Functions Render Config) --, for more information.
@@ -799,10 +800,6 @@ have been duplicated, the functionality stops thereat.| 3.56 trunk/Scripts/Bash/Functions/Render/Config | - |
| [Index] | [ ? ] |
