.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "App::CELL::Load 3pm"
.TH App::CELL::Load 3pm "2016-09-03" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
App::CELL::Load \-\- find and load message files and config files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use App::CELL::Load;
\&
\&    # Load App::CELL\*(Aqs internal messages and config params and then
\&    # attempt to load the application\*(Aqs messages and config params
\&    $status = App::CELL::Load::init();
\&    return $status if $status\->not_ok;
\&
\&    # attempt to determine the site configuration directory
\&    my $resulthash = App::CELL::Load::get_sitedir();
\&
\&    # get a reference to a list of configuration files (full paths) of a
\&    # given type under a given directory
\&    my $metafiles = App::CELL::Load::find_files( \*(Aq/etc/CELL\*(Aq, \*(Aqmeta\*(Aq );
\&   
\&    # load messages from all message file in a given directory and all its
\&    # subdirectories
\&    $status = message_files( \*(Aq/etc/CELL\*(Aq );
\&
\&    # load meta, core, and site params from all meta, core, and site
\&    # configuration files in a given directory and all its subdirectories
\&    $status = meta_core_site_files( \*(Aq/etc/CELL\*(Aq );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The purpose of the App::CELL::Load module is to provide message and config
file finding and loading functionality to the App::CELL::Message and
App::CELL::Config modules.
.SH "PACKAGE VARIABLES"
.IX Header "PACKAGE VARIABLES"
This module provides the following package variables
.ie n .IP "$sharedir \- the full path of the sharedir" 4
.el .IP "\f(CW$sharedir\fR \- the full path of the sharedir" 4
.IX Item "$sharedir - the full path of the sharedir"
.PD 0
.ie n .IP "$sharedir_loaded \- whether it has been loaded or not" 4
.el .IP "\f(CW$sharedir_loaded\fR \- whether it has been loaded or not" 4
.IX Item "$sharedir_loaded - whether it has been loaded or not"
.ie n .IP "@sitedir \- the full path of the site configuration directory" 4
.el .IP "\f(CW@sitedir\fR \- the full path of the site configuration directory" 4
.IX Item "@sitedir - the full path of the site configuration directory"
.PD
.SH "MODULES"
.IX Header "MODULES"
.SS "init"
.IX Subsection "init"
Idempotent initialization function.
.PP
Optionally takes a \s-1PARAMHASH.\s0 The following arguments are recognized:
.ie n .IP """sitedir"" \*(-- full path to the/a site dir" 4
.el .IP "\f(CWsitedir\fR \*(-- full path to the/a site dir" 4
.IX Item "sitedir full path to the/a site dir"
.PD 0
.ie n .IP """enviro"" \*(-- name of environment variable containing sitedir path" 4
.el .IP "\f(CWenviro\fR \*(-- name of environment variable containing sitedir path" 4
.IX Item "enviro name of environment variable containing sitedir path"
.ie n .IP """verbose"" \*(-- increase logging verbosity of the load routine" 4
.el .IP "\f(CWverbose\fR \*(-- increase logging verbosity of the load routine" 4
.IX Item "verbose increase logging verbosity of the load routine"
.PD
.PP
E.g.:
.PP
.Vb 4
\&    my $status = App::CELL::Load::init( 
\&                                         sitedir => \*(Aq/etc/foo\*(Aq, 
\&                                         verbose => 1 
\&                                      );
.Ve
.PP
See App::CELL::Guide for details.
.SS "message_files"
.IX Subsection "message_files"
Loads message files from the given directory. Takes: full path to
configuration directory. Returns: result hash containing 'quantfiles'
(total number of files processed) and 'count' (total number of
messages loaded).
.SS "meta_core_site_files"
.IX Subsection "meta_core_site_files"
Loads meta, core, and site config files from the given directory. Takes:
full path to configuration directory. Returns: result hash containing
\&'quantfiles' (total number of files processed) and 'count' (total number of
configuration parameters loaded).
.SS "get_sitedir"
.IX Subsection "get_sitedir"
This function implements the algorithm described in
\&\*(L"Sitedir search algorithm\*(R" in App::CELL::Guide to find a sitedir candidate.
configuration directory.
.PP
On success \*(-- i.e., as soon as the algorithm finds a viable sitedir
candidate \*(-- the sitedir (full path) is added to \s-1CELL_META_SITEDIR_LIST\s0 and
an \s-1OK\s0 status object is returned, with the sitedir in the payload.
.PP
On failure, the function returns an \s-1ERR\s0 or \s-1WARN\s0 status object containing
a description of what went wrong.
.SS "find_files"
.IX Subsection "find_files"
Takes two arguments: full directory path and config file type.
.PP
Always returns an array reference. On \*(L"failure\*(R", the array reference will
be empty.
.PP
How it works: first, the function checks a state variable to see if the
\&\*(L"work\*(R" of walking the configuration directory has already been done.  If
so, then the function simply returns the corresponding array reference from
its cache (the state hash \f(CW%resultlist\fR). If this is the first invocation
for this directory, the function walks the directory (and all its
subdirectories) to find files matching one of the four regular expressions
corresponding to the four types of configuration files('meta', 'core',
\&'site', 'message'). For each matching file, the full path is pushed onto
the corresponding array in the cache.
.PP
Note that there is a ceiling on the number of files that will be considered
while walking the directory tree. This ceiling is defined in the package
variable \f(CW$max_files\fR (see below).
.SS "parse_message_file"
.IX Subsection "parse_message_file"
This function is where message files are parsed. It takes a \s-1PARAMHASH\s0
consisting of:
.ie n .IP """File"" \- filename (full path)" 4
.el .IP "\f(CWFile\fR \- filename (full path)" 4
.IX Item "File - filename (full path)"
.PD 0
.ie n .IP """Dest"" \- hash reference (where to store the message templates)." 4
.el .IP "\f(CWDest\fR \- hash reference (where to store the message templates)." 4
.IX Item "Dest - hash reference (where to store the message templates)."
.PD
.PP
Returns: number of stanzas successfully parsed and loaded
.SS "parse_config_file"
.IX Subsection "parse_config_file"
Parses a configuration file and adds the parameters found to the hashref
provided. If a parameter already exists in the hashref, a warning is
generated, the existing parameter is not overwritten, and processing
continues.
.PP
This function doesn't care what type of configuration parameters
are in the file, except that they must be scalar values. Since the
configuration files are actually Perl modules, the value can even be
a reference (to an array, a hash, or a subroutine, or any other complex
data structure).
.PP
The technique used in the \f(CW\*(C`eval\*(C'\fR, derived from Request Tracker, can be
described as follows: a local typeglob \*(L"set\*(R" is defined, containing a
reference to an anonymous subroutine. Subsequently, a config file (Perl
module) consisting of calls to this \*(L"set\*(R" subroutine is \f(CW\*(C`require\*(C'\fRd.
.PP
Note: If even one call to \f(CW\*(C`set\*(C'\fR fails to compile, the entire file will be
rejected and no configuration parameters from that file will be loaded.
.PP
The \f(CW\*(C`parse_config_file\*(C'\fR function takes a \s-1PARAMHASH\s0 consisting of:
.ie n .IP """File"" \- filename (full path)" 4
.el .IP "\f(CWFile\fR \- filename (full path)" 4
.IX Item "File - filename (full path)"
.PD 0
.ie n .IP """Dest"" \- hash reference (where to store the config params)." 4
.el .IP "\f(CWDest\fR \- hash reference (where to store the config params)." 4
.IX Item "Dest - hash reference (where to store the config params)."
.PD
.PP
Returns: number of configuration parameters parsed/loaded
.PP
(\s-1IMPORTANT NOTE:\s0 If even one call to \f(CW\*(C`set\*(C'\fR fails to compile, the entire
file will be rejected and no configuration parameters from that file will
be loaded.)
.SS "_conf_from_config"
.IX Subsection "_conf_from_config"
This function takes a target hashref (which points to one of the 'meta',
\&'core', or 'site' package hashes in \f(CW\*(C`App::CELL::Config\*(C'\fR), a config parameter
(i.e. a string), config value, config file name, and line number.
.PP
Let's imagine that the configuration parameter is \*(L"\s-1FOO_BAR\*(R".\s0 The function
first checks if a key named \*(L"\s-1FOO_BAR\*(R"\s0 already exists in the package hash
(which is passed into the function as \f(CW%ARGS{\*(AqDest\*(Aq}\fR). If there isn't
one, it creates that key. If there is one, it leaves it untouched and
triggers a warning.
.PP
Although the arguments are passed to the function in the form of a
\&\s-1PARAMHASH,\s0 the function converts them into ordinary private variables.
This was necessary to avoid extreme notational ugliness.