ConfigurationThreetypesofparameters
CELL recognizes three types of configuration parameters: "meta", "core", and "site". These parameters and
their values are loaded from files prepared and placed in the sitedir in advance.
Meta parameters
Meta parameters are by definition mutable: the application can change a meta parameter's value any number
of times, and App::CELL will not care. Initial "meta" param settings are placed in a file entitled
"$str_MetaConfig.pm" (where $str is a string free of underscore characters) in the sitedir. For example,
if the application name is FooApp, its initial "meta" parameter settings could be contained in a file
called "FooApp_MetaConfig.pm". At initialization time, App::CELL looks in the sitedir for files matching
this description, and attempts to load them. (See "How configuration files are named".)
Core parameters
As in Request Tracker, "core" parameters have immutable values and are intended to be used as "factory
defaults", set by the developer, that the site administrator can override by setting site parameters. If
the application is called FooApp, its core configuration settings could be contained in a file called
"FooApp_Config.pm" located in the sitedir. (See "How configuration files are named" for details.)
Site parameters
Site parameters are kept separate from core parameters, but are closely related to them. As far as the
application is concerned, there are only site parameters. How this works is best explained by two
examples.
Let "FOO" be an application that uses App::CELL.
In the first example, core param "FOO" is set to "Bar" and site param "FOO" is not set at all. When the
application calls "$site->FOO" the core parameter value "Bar" is returned.
In the second example, the core param "FOO" is set to "Bar" and site param "FOO" is also set, but to a
different value: "Whizzo". In this scenario, when the application calls "$site->FOO" the site parameter
("Whizzo") value is returned.
This setup allows the site administrator to customize the application.
Site parameters are set in a file called "$str_SiteConfig.pm", where $str could be the appname.
Conclusion
How these three types of parameters are defined and used is up to the application. As far as App::CELL is
concerned, they are all optional.
App::CELL itself has its own internal meta, core, and site parameters, but these are located elsewhere --
in the so-called "sharedir", a directory that is internal to the App::CELL distro/package.
All these internal parameters start with "CELL_" and are stored in the same namespaces as the
application's parameters. That means the application programmer should avoid using parameters starting
with "CELL_".
Whereconfigurationfilesarelocated
sitedir
Configuration parameters are placed in specially-named files within a directory referred to by App::CELL
as the "site configuration directory", or "sitedir". This directory is not a part of the App::CELL
distribution and App::CELL does not create it. Instead, the application is expected to provide the full
path to this directory to CELL's initialization route, either via an argument to the function call or
with the help of an environment variable. CELL's initialization routine calls App::CELL::Load::init to do
the actual work of walking the directory.
This "sitedir" (site configuration directory) is assumed to be the place (or a place) where the
application can store its configuration information in the form of "core", "site", and "meta" parameters.
For "LOCALIZATION" purposes, "message" codes and their corresponding texts (in one or more languages) can
be stored here as well, if desired.
sharedir
CELL itself has an analogous configuration directory, called the "sharedir", where it's own internal
configuration defaults are stored. CELL's own core parameters can be overridden by the application's
site params, and in some cases this can even be desirable. For example, the parameter "CELL_DEBUG_MODE"
can be overridden in the site configuration to tell CELL to include debug-level messages in the log.
During initialization, CELL walks first the sharedir, and then the sitedir, looking through those
directories and all their subdirectories for meta, core, site, and message configuration files.
The sharedir is part of the App::CELL distro and CELL's initialization routine finds it via a call to the
"dist_dir" routine in the File::ShareDir module.
Howthesitedirisspecified
The sitedir must be created and populated with configuration files by the application programmer.
Typically, this directory would form part of the application distro and the site administrator would be
expected to make a site configuration file for application-specific parameters. The application developer
and site administrator have flexibility in this regard -- CELL's initialization routine, "$CELL->load"
will work without a sitedir, with one sitedir, or even with multiple sitedirs.
No sitedir
It is possible, but probably not useful, to call "$CELL->load" without a sitedir parameter and without
any sitedir specified in the environment. In this case, CELL just loads the sharedir and returns OK.
One sitedir
If there is only one sitedir, there are three possible ways to specify it to CELL's load routine: (1) a
"sitedir" parameter, (2) an "enviro" parameter, or (3) the hard-coded "CELL_SITEDIR" environment
variable.
Multiple sitedirs
If the application needs to load configuration parameters from multiple sitedirs, this can be
accomplished simply by calling "$CELL->load" multiple times with different "sitedir" arguments.
Sitedirsearchalgorithm
Every time it is called, the load routine uses the following algorithm to search for a/the sitedir:
"sitedir" parameter -- a "sitedir" parameter containing the full path to the sitedir can be passed. If it
is present, CELL will try it first. If needed for portability, the path can be constructed using
File::Spec (e.g. the "catfile" method) or similar. It should be string containing the full path to the
directory. If the "sitedir" argument points to a valid sitedir, it is loaded and OK is returned. If a
"sitedir" argument is present but invalid, an ERR status results. If no "sitedir" argument was given,
CELL continues to the next step.
"enviro" parameter -- if no "sitedir" parameter is given, "$CELL->load" looks for a parameter called
"enviro" which it interprets as the name of an environment variable containing the sitedir path. If the
"enviro" argument points to a valid sitedir, it is loaded and OK is returned. If an "enviro" argument is
present but invalid, an ERR status results. If there is no "enviro" argument at all, CELL continues to
the next step.
"CELL_SITEDIR" environment variable -- if no viable sitedir can be found by consulting the function call
parameters, CELL's load routine falls back to this hardcoded environment variable. If the "CELL_SITEDIR"
environment variable exists and points to a valid sitedir, it is loaded and OK is returned. If it exists
but the directory is invalid, an ERR status is returned. If the environment variable doesn't exist, CELL
writes a warning to the log (all attempts to find the sitedir failed). The return status in this case can
be either WARN (if no sitedir was found in a previous call to the function) or OK if at least one sitedir
has been loaded.
The "load" routine is re-entrant: it can be called any number of times. On first call, it will load
CELL's own sharedir, as well as any sitedir that can be found using the above algorithm. All further
calls will just run the sitedir search algorithm again. Each time it will find and load at most one
sitedir. CELL maintains a list of loaded sitedirs in "$meta->CELL_META_SITEDIR_LIST".
For examples of how to call the "load" routine, see "SYNOPSIS" in App::CELL.
Howconfigurationfilesarenamed
Once it finds a valid sitedir, CELL walks it (including all its subdirectories), assembling a list of
filenames matching one four regular expressions:
"^.+_MetaConfig.pm$" (meta)
"^.+_Config.pm$" (core)
"^.+_SiteConfig.pm$" (site)
"^.+_Message(_[^_]+){0,1}.conf$" (message)
Files with names that don't match any of the above regexes are ignored.
After the directory is walked, the files are loaded (i.e. parsed for config params and messages).
The syntax of these files is simple and should be obvious from an examination of CELL's own configuration
files in the sharedir ("config/" in the distro). All four types of configuration file are there, with
comments.
Since the configuration files are Perl modules, Perl itself is leveraged to parse them. Values can be any
legal scalar value, so references to arrays, hashes, or subroutines can be used, as well as simple
numbers and strings. For details, see "SITE CONFIGURATION DIRECTORY", App::CELL::Config and
App::CELL::Load.
Message file parsing is done by a parsing routine that resides in App::CELL::Load. For details on the
syntax and how the parser works, see LOCALIZATION.
Configurationdiagnostics
CELL provides several ways for the application to find out if the configuration files were loaded
properly. First of all, the load routine ("$CELL->load") returns a status object: if the status is not
OK, something went wrong and the application should look at the status more closely.
After program control returns from the load routine, the following methods and attributes can be used to
find out what happened:
"$site->CELL_SHAREDIR_LOADED" (boolean value)
"$site->CELL_SHAREDIR_FULLPATH" (full path of CELL's sharedir)
"$meta->CELL_META_SITEDIR_LOADED" (boolean value: true if at least one sitedir has been loaded)
"$meta->CELL_META_SITEDIR_LIST" (reference to a list of all sitedirs that have been loaded -- full paths)
Verboseanddebugmode
The load routine takes two options to increase its verbosity. The first option, "verbose", can be passed
like this:
my $status = $CELL->load( verbose => 1 );
It causes the load routine to write additional information to the log. Since even this can easily be too
much, the default value for "verbose" is zero (terse logging).
The load routine also has a "debug" mode which should be activated in combination with "verbose". Debug
mode is actually a function of the CELL logger, and is activated like this:
$log->init( debug_mode => 1 );
Ordinarily the logger suppresses all log messages below "info" level (i.e., "debug" and "trace"). When
"debug_mode" is activated, all messages are logged, regardless of level.
ErrorhandlingSTATUSOBJECTS
The most frequent case will be a status code of "OK" with no message (shown here with optional "payload",
which is whatever the function is supposed to return on success:
# all green
return App::CELL::Status->new( level => 'OK',
payload => $my_return_value,
);
To ensure this is as simple as possible in cases when no return value (other than the simple fact of an
OK status) is needed, we provide a special constructor method:
# all green
return App::CELL::Status->ok;
In most other cases, we will want the status message to be linked to the filename and line number where
the "new" method was called. If so, we call the method like this:
# relative to me
App::CELL::Status->new( level => 'ERR',
code => 'CODE1',
args => [ 'foo', 'bar' ],
);
It is also possible to report the caller's filename and line number:
# relative to my caller
App::CELL::Status->new( level => 'ERR',
code => 'CODE1',
args => [ 'foo', 'bar' ],
caller => [ CORE::caller() ],
);
It is also possible to pass a message object in lieu of "code" and "msg_args" (this could be useful if we
already have an appropriate message on hand):
# with pre-existing message object
App::CELL::Status->new( level => 'ERR',
msg_obj => $my_msg;
);
Permitted levels are listed in the @permitted_levels package variable in "App::CELL::Log".
LocalizationIntroduction
To an application programmer, localization may seem like a daunting proposition, and All strings the
application displays to users must be replaced by variable names. Then you have to figure out where to
put all the strings, translate them into multiple languages, write a library (or find an existing one) to
display the right string in the right language at the right time and place. What is more, the application
must be configurable, so the language can be changed by the user or the site administrator.
All of this is a lot of work, particularly for already existing, non-localized applications, but even for
new applications designed from the start to be localizable.
App::CELL's objective is to provide a simple, straightforward way to write and maintain localizable
applications in Perl. Notice the key word "localizable" -- the application may not, and most likely will
not, be localized in the initial stages of development, but that is the time when localization-related
design decisions need to be made. App::CELL tries to take some of the guesswork out of those decisions.
Later, when it really is time for the application to be translated into one or more additional languages,
this becomes a relatively simple matter of translating a bunch of text strings that are grouped together
in one or more configuration files with syntax so trivial that no technical expertise is needed to work
with them. (Often, the person translating the application is not herself technically inclined.)
LocalizationwithApp::CELL
All strings that may potentially need be localized (even if we don't have them translated into other
languages yet) are placed in message files under the site configuration directory. In order to be found
and parsed by App::CELL, message files must meet some basic conditions:
1. file name format: "AppName_Message_lang.conf"
2. file location: anywhere under the site configuration directory
3. file contents: must be parsable
Formatofmessagefilenames
At initialization time, App::CELL walks the site configuration directory tree looking for filenames that
meet certain regular expressions. The regular expression for message files is:
^.+_Message(_[^_]+){0,1}.conf$
In less-precise human terms, this means that the initialization routine looks for filenames consisting of
at least three, but possibly four, components:
1. the application name (this can be anything)
2. followed by "_Message"
3. optionally followed by "_languagetag" where "languagetag" is a language tag (see "..link.." for
details)
4. ending in ".conf"
Examples:
CELL_Message.conf
CELL_Message_en.conf
CELL_Message_cs-CZ.conf
DifferentApplication_Message.conf
Locationofmessagefiles
As noted above, message files will be found as long as they are readable and located anywhere under the
base site configuration directory. For details on how this base site configuration directory is searched
for and determined, see "..link..".
Howmessagefilesareparsed
Message files are parsed line-by-line. The parser routine is "parse_message_file" in the "CELL::Load"
module. Lines beginning with a hash sign ('#') are ignored. The remaining lines are divided into
"stanzas", which must be separated by one or more blank lines.
Stanzas are interpreted as follows: the first line of the stanza should contain a message code, which is
simply a string. Any legal Perl scalar value can be used, as long as it doesn't contain white space. CELL
itself uses ALL_CAPS strings starting with "CELL_".
The remaining lines of the stanza are assumed to be the message text. Two caveats here:
1. In the configuration file, message text strings can be written on multiple lines
2. However, this is intended purely as a convenience for the application programmer. When
"parse_message_file" encounters multiple lines of text, it simply concatenated them together to form a
single, long string.
For details, see the "parse_message_file" function in "App::CELL::Load", as well as App::CELL's own
message file(s) in "config/CELL" directory of the App::CELL distro.
Howthelanguageisdetermined
Internally, each message text string is stored along with a language tag, which defines which language
the message text is written in. The language tag is derived from the filename using a regular expression
like this one:
_Message_([^_]+).conf$
(The part in parentheses signifies the part between "_Message_" and ".conf" -- this is stored in the
"language" attribute of the message object.)
No sanity checks are conducted on the language tag. Whatever string the regular expression produces
becomes the language tag for all messages in that file. If no language tag is found, CELL first looks for
a config parameter called "CELL_DEFAULT_LANGUAGE" and, failing that, the hard-coded fallback value is
"en".
I'll repeat that, since it's important: CELL assumes that the message file names contain the relevant
language tag. If the message file name is "MyApp_Message_foo-bar.conf", then CELL will tag all messages
in that file as being in the "foo-bar" language. Message files can also be named like this:
"MyApp_Message.conf", i.e. without a language tag. In this case, CELL will attempt to determine the
default language from a site configuration parameter ("CELL_DEFAULT_LANGUAGE"). If this parameter is not
set, then CELL will give up and assume that all message text strings are in English (language tag "en" --
CELL's author's native tongue).
Languagetagsingeneral
See the W3C's "Language tags in HTML and XML" white paper for a detailed explanation of language tags:
L<http://www.w3.org/International/articles/language-tags/>
And see here for list of all language tags:
L<http://www.langtag.net/registries/lsr-language.txt>
Note that you should use hyphens, and not underscores, to separate components within the language tag,
i.e.:
MyApp_Message_cs-CZ.conf # correct
MyApp_Message_cs_CZ.conf # WRONG!!
Non-ASCII characters in config/message file names: may or may not work. Better to avoid them.
Normalusage
In normal usage, the programmer adds messages to the respective message files. After CELL initialization,
these messages (or, more precisely, message code-language pairs) will be available to the programmer to
use, either directly via CELL::Message->new or indirectly as status codes.
If a message code has text strings in multiple languages, these language variants can be obtained by
specifying the "lang" parameter to CELL::Message->new. If the "lang" parameter is not specified, CELL
will always try to use the default language ("CELL_DEF_LANG" or English if that parameter has not been
set).
Logging
CELL's logging facility is based on Log::Any. In practice, this means that App::CELL::Log is simply a
wrapper around this useful module. To use it, one imports the Log::Any singleton via App::CELL like this:
use App::CELL qw( $log );
Since this is the Log::Any singleton, all Log::Any methods can be used with it. CELL provides some
conveniences, but they are optional. Actually, if the developer does not intend to use any of CELL's
conveniences, there is no reason to import it through App::CELL at all and one can use Log::Any directly.
In this case, CELL's log messages will go to the same log as the application's provided the Log::Any
category is the same as the CELL "appname".
See "Verbose and debug mode" for a description of how to increase logging verbosity of the load routine.
Install Now
PNG Icons
