- HOW TO USE THIS MODULE
App::CELL - Configuration, Error-handling, Localization, and Logging
use App::CELL; # initialization (set up logging, load config params and messages from # configuration directory) App::CELL->init; # write arbitrary, non-localized strings to syslog App::CELL->log_debug( "DEBUG level message" ); App::CELL->log_info( "INFO level message" ); # use status objects as return values: success return App::CELL->status_ok; # use status objects as return values: failure return App::CELL->status( level => 'ERR', code => 'MY_ERROR_MESSAGE_CODE', ); # process status objects returned by invoked function my $status = Function::invocation( ... ); return $status unless $status->ok; # set the value of a meta parameter META_MY_PARAM to 42 App::CELL->set_meta( 'META_MY_PARAM', 42 ); # get the value of a meta parameter my $value = App::CELL->meta( 'META_MY_PARAM' ); # get the value of a site configuration parameter $value = App::CELL->config( 'MY_PARAM' ); # note: site configuration parameters are read-only: to change # them, edit the core and site configuration files. # # For details, see the CELL Guide (in C<doc/>)
This is the top-level module of App::CELL, the Configuration, Error-handling, Localization, and Logging framework for Perl applications running under Unix-like systems such as SUSE Linux Enterprise.
Configuration, error-handling, localization, and logging may seem like diverse topics. In the author's experience, however, applications written for "users" (however that term may be defined) frequently need to:
- 1. be configurable by the user or site administrator
- 2. handle errors robustly, without hangs and crashes
- 3. potentially display messages in various languages
- 4. log various types of messages to syslog
Since these basic functions seem to work well together, CELL is designed to provide them in an integrated, well-documented, straightforward, and reusable package.
For details, see the CELL Guide (in
CELL was written by Smithfarm in late 2013 and early 2014, initially as part of the Dochazka project [[ link to SourceForge ]]. Due to its generic nature, it was spun off into a separate project.
This top-level module is all the application programmer needs to gain access to the CELL's key functions.
This module provides CELL's Configuration functionality.
Status.pm provides CELL's Error-handling functionality. Since status objects inherit from message objects, the application programmer can instruct CELL to generate localized status messages (errors, warnings, notices) if she wishes.
Localization is on the wish-list of many software projects. With CELL, I can easily design and write my application to be localizable from the very beginning, without having to invest much effort.
Logging is simple in Perl, thanks to CPAN modules like
Log::Fast, but CELL tries to make it even simpler.
HOW TO USE THIS MODULE
lib/App/CELL.pm, provides a number of public methods. For the sake of uniformity, no functions are exported: the methods are designed to be called using "arrow" notation, i.e.:
App::CELL->method_name( args );
Some of the methods are "constructors" in the sense that they return objects.
init- initialize App::CELL
log_debug- send DEBUG-level message to syslog
log_info- send INFO-level message to syslog
status_ok- construct an "OK" status object
status- construct an arbitrary status object
set_meta- set a meta parameter to an arbitrary value
meta- get value of a meta parameter
config- get value of a site parameter
Each of these methods is described in somewhat more detail in the "METHODS" section, which contains links to the actual functions for those methods that are merely wrappers.
This method needs to be called at least once, preferably before calling any of the other methods. It performs all necessary initialization tasks. It is designed to be re-entrant, which means you can call it more than once.
The first time the function is called, it performs the following tasks:
- - configure logging
CELL uses the syslog facility to log its activities, and provides logging methods to enable the application to do the same. It is recommended that syslog be configured to send CELL-related log messages to a separate file, e.g.
- - load meta parameters
Meta parameters are a replacement for global variables. They are programatically changeable and their defaults are loaded from configuration files with names of the format
App::CELL::Configfor more information.
- - load core and site parameters
Core and site configuration parameters are strictly read-only, and are stored in any number of files whose names have the format
[...]_SiteConfig.pm. These two types of parameters are designed to work together, with core parameters providing defaults and site parameters providing site-specific overrides. See the CELL Guide for more information on using CELL for configuration.
- - load message templates
CELL message templates are a special type of meta parameter that is loaded from files whose names look like
encan be any language tag (actually, any string, but you should stick to real language tags at all if possible). See the CELL Guide for more information on using CELL for localization.
Takes one argument: string to be used as identifier (
ident) for syslog. This string, usually the application name, will be pre-pended to all messages and can be used to configure syslog to put all log messages related to your application in a separate file within
/var/log, or elsewhere. Returns an
App::CELL::Status object with level either "OK" (on success) or "CRIT" (on failure).
On success, it also sets the
META_CELL_STATUS_DATETIME meta parameters.
Send a DEBUG-level message to syslog. Takes a string. Returns nothing.
Send an INFO-level message to syslog. Takes a string. Returns nothing.
Wrapper for App::CELL::Status::ok
Wrapper for App::CELL::Status::new
Set a meta parameter. Wrapper for App::CELL::Config::set_meta. Takes two arguments: string containing name of meta parameter, and value (scalar, arrayref, or hashref) to assign to the parameter. Returns a status object.
Get value of a meta parameter. Wrapper for App::CELL::MetaConfig::get_param. Takes one argument: string containing name of meta parameter. Returns value of meta parameter if the parameter exists, otherwise undef.
config method provides clients access to site configuration parameters. A simple logic is applied: if the parameter is defined in 'site', we're done: that is the value. If the parameter is not defined in 'site', check 'core' and use that value, if available.
If neither 'site' nor 'core' has a definition for the parameter, undef is