view release on metacpan or  search on metacpan

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

message files. After CELL initialization, these messages (or, more
precisely, message code-language pairs) will be available to the
programmer to use, either directly via CELL::Message->new or
indirectly as status codes.

If a message code has text strings in multiple languages, these language
variants can be obtained by specifying the C<lang> parameter to
CELL::Message->new. If the C<lang> parameter is not specified, CELL will
always try to use the default language (C<CELL_DEF_LANG> or English if
that parameter has not been set).


=head2 Logging

CELL's logging facility is based on L<Log::Any>. In practice, this means
that L<App::CELL::Log> is simply a wrapper around this useful module. To
use it, one imports the L<Log::Any> singleton via L<App::CELL> like
this:

    use App::CELL qw( $log );

Since this I<is> the L<Log::Any> singleton, all L<Log::Any> methods can be
used with it. CELL provides some conveniences, but they are optional.
Actually, if the developer does not intend to use any of CELL's
conveniences, there is no reason to import it through L<App::CELL> at all
and one can use L<Log::Any> directly. In this case, CELL's log messages
will go to the same log as the application's provided the L<Log::Any>
category is the same as the CELL C<appname>.

See L</Verbose and debug mode> for a description of how to increase logging
verbosity of the load routine.


=head1 CAVEATS


=head2 Internal parameters

L<App::CELL> stores its own parameters (mostly meta and core, but also one
site param) in a separate directory, but when loaded they end up in the
same namespaces as the application's meta, core, and site parameters.
The names of these internal parameters are always prefixed with C<CELL_>.

Therefore, the application programmer should avoid using parameters
starting with C<CELL_>.


=head2 Mutable and immutable parameters

It is important to realize that, although core parameters can be overridden
by site parameters, internally the values of both are immutable. Although
it is possible to change them by cheating, the 'set' method of C<$core> and
C<$site> will refuse to change the value of an existing core/site parameter.

Therefore, use C<$meta> to store mutable values.


=head2 Taint mode

Since it imports configuration data at runtime from files supplied by the
user, L<App::CELL> should not be run under taint mode. The C<< load >>
routine checks this and will refuse to do anything if running with C<-T>.

To recapitulate: don't run L<App::CELL> in taint mode.


=head2 Installation issues with CELL internal sharedir

The easiest way to install L<App::CELL> is to use a package manager (e.g.
C<zypper>). Another way to install directly from CPAN using, e.g.,
C<cpanm>). The former way installs to the C<vendor_perl> tree, while the
latter installs to the C<site_perl> tree.

If you install two different versions of L<App::CELL>, one via package
manager and another directly from CPAN, a conflict can arise, and it may be
necessary to examine CELL's log to determine which one is being used.

Even after running, e.g., C<cpanm -U App::CELL>, to uninstall from
C<site_perl>, I found that CELL's internal sharedir remained intact in the
C<site_perl> tree and had to be wiped manually.

As long as you always install either one way or other other (i.e. package
manager or direct from CPAN), you won't get bitten by this.



=head1 COMPONENTS


=head2 L<App::CELL>

This top-level module exports a singleton, C<$CELL>, which is all the
application programmer needs to gain access to the CELL's key functions.


=head2 C<App::CELL::Config>

This module provides CELL's Configuration functionality.


=head2 C<App::CELL::Guide>

This guide.


=head2 C<App::CELL::Load>

This module hides all the complexity of loading messages and config params
from files in two directories: (1) the App::CELL distro sharedir containing
App::CELL's own configuration, and (2) the site configuration directory, if
present.


=head2 C<App::CELL::Log>

Logging is accomplished by using and extending L<Log::Any>.


=head2 C<App::CELL::Message>

Localization is on the wish-list of many software projects. With CELL,
the programmer can easily design and write my application to be localizable
from the very beginning, without having to invest much effort.