view release on metacpan or  search on metacpan

lib/App/CELL/Guide.pm  view on Meta::CPAN

# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
# 
# 1. Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
# 
# 2. Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
# 
# 3. Neither the name of SUSE LLC nor the names of its contributors may be
# used to endorse or promote products derived from this software without
# specific prior written permission.
# 
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
# ************************************************************************* 

package App::CELL::Guide;

use strict;
use warnings;
use 5.012;



=head1 NAME

App::CELL::Guide - Introduction to App::CELL (POD-only module)



=head1 VERSION

Version 0.231

=cut

our $VERSION = '0.231';



=head1 SYNOPSIS

   $ perldoc App::CELL::Guide



=head1 INTRODUCTION

L<App::CELL> is the Configuration, Error-handling, Localization, and Logging
(CELL) framework for applications written in Perl. In the L</GENERAL APPROACH>
section, this Guide describes the CELL approach to each of these four areas,
separately. Then, in the L</RATIONALE> section, it presents the author's reasons
for bundling them together.



=head1 HISTORY

The original L<App::CELL> was written by Nathan Cutler in 2013 and 2014,
initially as part of the L<App::Dochazka::REST> project. Later, with a view to
its generic nature, it was spun off into a separate project.



=head1 GENERAL APPROACH

This section presents CELL's approach to each of its four principal
functions: L</Configuration>, L</Error handling>, L<Localization>, and
L<Logging>.


=head2 Approach to configuration

CELL provides the application developer and site administrator with a
straightforward and powerful way to define configuration parameters as
needed by the application. If you are familiar with Request Tracker, you
will know that there is a directory (C</opt/...> by default) which contains
two files, called C<RT_Config.pm> and C<RT_SiteConfig.pm> -- as their names
would indicate, they are actually Perl modules. The former is provided by
the upstream developers and contains all of RT's configuration parameters
and their "factory default" settings. The content of the latter is entirely
up to the RT site administrator and contains only those parameters that
need to be different from the defaults. Parameter settings in
C<RT_SiteConfig.pm>, then, override the defaults set in C<RT_Config.pm>.

L<App::CELL> provides this same functionality in a drop-in Perl module,
with some subtle differences. While RT uses a syntax like this:

   set( 'MY_PARAM', ...arguments...);

where C<...arguments...> is a list of scalar values (as with any Perl
subroutine), L<App::CELL> uses a slightly different format:

   set( 'MY_PARAM', $scalar );

where C<$scalar> can be any scalar value, i.e. including references. 

(Another difference is that L<App::CELL> provides both immutable site
parameters _and_ mutable C<meta> configuration parameters, whereas RT's
meta parameters are only used by RT itself.) For more information on
configuration, see L</Configuration in depth>.


=head2 Error handling

To facilitate error handling and make the application's source code easier
to read and understand, or at least mitigate its impenetrability, CELL
provides the L<App::CELL::Status> module, which enables functions in the
application to return status objects if desired.