NAME

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

VERSION

Version 0.066

SYNOPSIS

   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/>)
   

DESCRIPTION

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 doc/)

HISTORY

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.

COMPONENTS

lib/App/CELL.pm

This top-level module is all the application programmer needs to gain access to the CELL's key functions.

See "SYNOPSIS" for code snippets, and "METHODS" for details.

lib/App/CELL/Config.pm

This module provides CELL's Configuration functionality.

lib/App/CELL/Status.pm

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.

lib/App/CELL/Message.pm

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.

lib/App/CELL/Log.pm

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

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.

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

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. /var/log/[APP].

- 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.

- 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.

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 a App::CELL::Status object with level either "OK" (on success) or "CRIT" (on failure).

On success, it also sets the META_CELL_STATUS_BOOL and META_CELL_STATUS_DATETIME meta parameters.

log_debug

Send a DEBUG-level message to syslog. Takes a string. Returns nothing.

log_info

Send an INFO-level message to syslog. Takes a string. Returns nothing.

status_ok

Wrapper for App::CELL::Status::ok

status

Wrapper for App::CELL::Status::new

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

cpanm App::CELL

perl -MCPAN -e shell
install App::CELL