NAME
App::CELL - Configuration, Error-handling, Localization, and Logging
VERSION
Version 0.113
SYNOPSIS
use App::CELL;
use App::CELL::Log qw( $log );
# initialization (set up logging, load config params and messages from
# configuration directory) of an application called FooBar
App::CELL->init( ident => 'FooBar' );
# log messages (see L<App::CELL::Log> for details)
$log->debug( "Debug-level log message" );
$log->info( "Info-level log message" );
# process status objects returned by function Foo::fn
my $status = Foo::fn( ... );
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 and run your
# application again.
#
# For details, see the CELL Guide (in C<doc/>)
DESCRIPTION
This is the top-level module of App::CELL, the Configuration, Error-handling, Localization, and Logging framework for applications written in Perl.
App::CELL is released under the GNU Affero General Public License Version 3 in the hopes that it will be useful, but with no warrany of any kind. For details, see the LICENSE
file in the top-level distro directory.
This module 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::CELLset_meta
- set a meta parameter to an arbitrary valuemeta
- get value of a meta parameterconfig
- 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.
PACKAGE VARIABLES
METHODS
init
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
-
App::CELL uses
Log::Any
to log its activities. WIP - - load message templates
-
CELL message templates are a special type of meta parameter that is loaded from files whose names look like
[...]_Message_en.pm
, whereen
can 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. - - 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
[...]_Meta.pm
. SeeApp::CELL::Config
for 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
[...]_Config.pm
and[...]_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.
Optionally takes arguments as a PARAMHASH. The following params are recognized:
appname
- name of the application (used to set theLog::Any
logger category and also in the site directory search (seeApp::CELL::Load
)sitedir
- full path to the site directory (whenApp::CELL::Load
conducts its site dir search, it will look here first)
Returns an App::CELL::Status
object with level either "OK" (on success) or "CRIT" (on failure). On success, it also sets the CELL_META_INIT_STATUS_BOOL
and CELL_META_START_DATETIME
meta parameters.
set_meta
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.
meta
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
The 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 returned.