NAME

App::CELL - Configuration, Error-handling, Localization, and Logging

VERSION

Version 0.119

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::CELL

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.

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, where en 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. See App::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 the Log::Any logger category and also in the site directory search (see App::CELL::Load)

sitedir - full path to the site directory (when App::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.