.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" 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::Standard::Config 3pm"
.TH CGI::Application::Standard::Config 3pm "2018-03-19" "perl v5.26.1" "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
Last updated:  Sat Feb 18 23:42:29 \s-1EST 2006\s0
.SH "NAME"
CGI::Application::Standard::Config \-\- Define a standard configuration API for CGI::Application
.SH "RATIONALE"
.IX Header "RATIONALE"
This module defines a minimum standard interface that configuration plugins for
CGI::Application should meet.  Having such a standard allows other plugin
authors to rely on basic configuration functionality without coding exceptions
for several configuration modules, or giving up on such integration.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "For Average Users"
.IX Subsection "For Average Users"
Simply load the config plugin before other modules that might use it:
.PP
.Vb 2
\&  use CGI::Application::Plugin::ConfigAuto;
\&  use CGI::Application::Plugin::Session;
.Ve
.SS "For Configuration plugin authors"
.IX Subsection "For Configuration plugin authors"
Configuration plugin authors only need to follow the standards documented below.
.SS "For other plugin authors who wish to rely on the standard"
.IX Subsection "For other plugin authors who wish to rely on the standard"
Plugin authors who want to possibly use this standard can do so by simply
using this module:
.PP
.Vb 2
\&  package CGI::Application::Plugin::Session;
\&  use CGI::Application::Standard::Config;
.Ve
.PP
If a standards complaint config module hasn't already been loaded a stub for
\&\fIconfig()\fR will be added which will safely return \f(CW\*(C`undef\*(C'\fR.
.PP
\fIExample use by another plugin\fR
.IX Subsection "Example use by another plugin"
.PP
Here code first tries to get configuration details first from a
config file, then from options passed to a plugin-specific config
method, and finally applies defaults if no configuration options are found.
.PP
.Vb 3
\& my $session_options = $self\->config(\*(AqSession_options\*(Aq)
\&                                      || $self\->session_config()
\&                                      || $self\->session_defaults;
.Ve
.SH "Standard Interface Definition"
.IX Header "Standard Interface Definition"
The following defines a minimum standard for configuration plugins to meet.
.PP
Config plugins are free to provide to additional functionality.
.PP
Configuration plugins are also encourage to explicitly document that
they are using \f(CW\*(C`CGI::Application::Standard::Config\*(C'\fR.
.PP
If there are existing methods that follow the standard but have
different names, you can use this example to always export your method:
.PP
.Vb 8
\&  sub import {
\&    my $app = caller;
\&    no strict \*(Aqrefs\*(Aq;
\&    my $full_name = $app . \*(Aq::config\*(Aq;
\&    # Change cfg to your config()\-compliant method name
\&    *$full_name = \e&cfg;
\&    CGI::Application::Plugin::YourNameHere\->export_to_level(1,@_);
\&  }
.Ve
.ie n .SS "$self\->std_config"
.el .SS "\f(CW$self\fP\->std_config"
.IX Subsection "$self->std_config"
This method should be exported by default to simply declare that you  meet the
standard report which version of the standard you meet. This simple
implementation is recommended:
.PP
.Vb 1
\& sub std_config { return 1; }
.Ve
.ie n .SS "$self\->config"
.el .SS "\f(CW$self\fP\->config"
.IX Subsection "$self->config"
The intended use is to load to read-only configuration details once
from a config file at start up time.
.PP
This service is provided by plugins (list below). They must support at
at least this syntax:
.PP
.Vb 1
\& my $value = $self\->config(\*(Aqkey\*(Aq);
.Ve
.PP
By default, \f(CW\*(C`config()\*(C'\fR simply returns undef, making it safe for other
plugins to directly to check if \f(CW\*(C`$self\-\*(C'\fRconfig('key')> returns the
value it needs.
.PP
\&\fIconfig()\fR must be exported by default.
.PP
For applications that need little configuration, \fIconfig()\fR is not
necessary\*(-- using \f(CW\*(C`PARAMS\*(C'\fR in an instance script should suffice.
.PP
Also, the \f(CW\*(C`param()\*(C'\fR is the appropriate method to use to set a
configuration value at run time.
.PP
Configuration plugins that provide at least this basic \s-1API\s0 include:
.IP "CGI::Application::Plugin::ConfigAuto." 4
.IX Item "CGI::Application::Plugin::ConfigAuto."
.PP
\fIStandard config variables\fR
.IX Subsection "Standard config variables"
.PP
Users are encouraged to use these standard config variable names, to
ease compatibility between plugins:
.PP
.Vb 2
\& ROOT_URI \- A URI corresponding to the project root (http://foo.com/proj )
\& ROOT_DIR \- a file system path to the same location ( /home/joe/www/proj )
.Ve
.PP
All-caps are used to denote that config variables are essentially global
constants.
.PP
Why \s-1URI\s0 and not \s-1URL\s0? The wikipedia explains:
.PP
.Vb 5
\&  The contemporary point of view among the working group that oversees URIs is
\&  that the terms URL and URN are context\-dependent aspects of URI and rarely
\&  need to be distinguished. Furthermore, the term URL is increasingly becoming
\&  obsolete, as it is rarely necessary to differentiate between URLs and URIs,
\&  in general.
.Ve
.SH "Standard Version"
.IX Header "Standard Version"
This is 1.0 of the CGI::Application \fIconfig()\fR standard.
.SH "AUTHOR"
.IX Header "AUTHOR"
Written by Mark Stosberg <mark@summersault.com> with input from the
CGI::Application community.
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
Copyright (C) 2008, Mark Stosberg.  All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.