.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 >0, 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 "CGI::Application::Plugin::Config::Simple 3pm"
.TH CGI::Application::Plugin::Config::Simple 3pm "2021-01-07" "perl v5.32.0" "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"
CGI::Application::Plugin::Config::Simple \- Add Config::Simple support to CGI::Application
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
in your CGI::Application based module
.PP
.Vb 1
\&        use CGI::Application::Plugin::Config::Simple;
\&
\&    sub cgiapp_init {
\&          my $self = shift;
\&          #set my config file
\&          $self\->config_file(\*(Aqmyapp.conf\*(Aq);
\&
\&          #
\&          #do other stuff
\&          #
\&        }
\&
\&        #later on in a run mode
\&        sub run_mode1 {
\&          my $self = shift;
\&
\&          #just get a single parameter from my config file
\&          my $value = $self\->config_param(\*(Aqmy_param\*(Aq);
\&
\&          #get a parameter in a block (if using ini style files)
\&          $value = $self\->config_param(\*(Aqmy_block.my_param\*(Aq);
\&
\&          #the entire config hash reference
\&          my $config_vars = $self\->config_param();
\&
\&          #get my Config::Simple object for direct access
\&          my $config = $self\->config;
\&        }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module acts as a plugin for Config::Simple to be easily used inside of a 
CGI::Application module. It does not provide every method available from Config::Simple
but rather easy access to your configuration variables. It does however provide direct 
access to the underlying Config::General object created if you want to use it's full
power.
.PP
The module tries to make the getting and setting of configuration variables as easy as
possible. Only three methods are exported into your CGI::Application module and they
are described below.
.PP
Before I wrote this module sometimes I would put my code that read in the configuration file
into the \fBcgiapp_init()\fR or \fBcgiapp_prerun()\fR methods but then if I had a run mode that didn't need
those config variables it was run anyway. This module helps to solve this is. The Config::Simple
object is not created (and the config file is not read and parsed) until after your first call
to \fBconfig()\fR or \fBconfig_param()\fR to either retrieve/set values, or get the Config::Simple
object. This lazy loading idea came from Cees Hek's CGI::Application::Plugin::Session module.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fBconfig_param()\fP"
.IX Subsection "config_param()"
This method acts as an accessor/mutator for configuration variables coming from the
configuration file.
.PP
This method will behave in three different ways depending on how many parameters it
is passed. If 0 parameters are passed then the entire config structure will be returned
as a hash ref. If 1 parameters is passed then the value of that parameter in the config
file will be returned. If more than 1 parameter is passed then it will treat them as name
value pairs and will set the parameters in the config file accordingly. In this case, if
we successfully set the parameters then a true value will be returned.
.PP
.Vb 6
\&        #get the complete config hash
\&        my $config_hash = $self\->config_param();
\&        #just get one config value
\&        my $value = $self\->config_param($parameter);
\&        #set multiple config values
\&        my $success = $self\->config_param(param1 => $value1, param2 => $value2);
.Ve
.PP
This method uses Config::Simple so if you are using ini-files then you can set
the values of variables inside blocks as well using the '.' notation. See Config::Simple;
.PP
You must set the name of the configuration file either using the \fBconfig_file()\fR method
or the \s-1CGIAPP_CONFIG_FILE\s0 environment variable before calling this method or it will 'die'.
.SS "\fBconfig()\fP"
.IX Subsection "config()"
This method will return the underlying Config::Simple object for more direct use by your
application. You must set the name of the configuration file either using the \fBconfig_file()\fR method
or the \s-1CGIAPP_CONFIG_FILE\s0 environment variable before calling this method or it will 'die'.
.PP
.Vb 1
\&        my $conf = $self\->config();
.Ve
.SS "config_file([$file_name])"
.IX Subsection "config_file([$file_name])"
This method acts as an accessor/mutator to either get the name of the current config file
or to change/initialize it. This method must be called to initialize the name of the config
file before any call can be made to either \fBconfig()\fR or \fBconfig_param()\fR unless the
\&'\s-1CGIAPP_CONFIG_FILE\s0' environment variable has been set. If this environment variable is set
it will be used as the initial value of the config file. This is useful if we are running in
a mod_perl environment when can use a statement like this in your httpd.conf file:
.PP
.Vb 1
\&        PerlSetEnv  CGIAPP_CONFIG_FILE  /path/to/my/conf
.Ve
.PP
It is typical to set the name of the config file in the \fBcgiapp_init()\fR phase of your application.
.PP
If a value is passed as a parameter then the config file with that name is used. It will always
return the name of the current config file.
.PP
.Vb 3
\&        #get the value of the CGIAPP_CONFIG_FILE environment variable (if there is one)
\&        #since we haven\*(Aqt set the config file\*(Aqs name with config_file() yet.
\&        my $file_name = $self\->config_file();
\&                                                                                                                                             
\&        #set the config file\*(Aqs name
\&        $self\->config_file(\*(Aqmyapp.conf\*(Aq);
\&                                                                                                                                             
\&        #get the name of the config file
\&        $file_name = $self\->config_file();
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
The CGI::Application object is implemented as a hash and we store the variables used by this
module's methods inside of it as a hash named _\|_CONFIG_SIMPLE. If you use any other CGI::Application
plugins there would be problems if they also used \f(CW$self\fR\->{_\|_CONFIG_SIMPLE} but in practice this should
never actually happen.
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael Peters <mpeters@plusthree.com>
.PP
Thanks to Plus Three, \s-1LP\s0 (http://www.plusthree.com) for sponsoring my work on this module
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 8
CGI::Application
.IP "\(bu" 8
Config::Simple
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.