--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.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. | will give a
+.\" real vertical bar. \*(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-|\(bv\*(Tr
+.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" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" 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 "Catalyst::Plugin::ConfigLoader 3"
+.TH Catalyst::Plugin::ConfigLoader 3 "2009-08-13" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Catalyst::Plugin::ConfigLoader \- Load config files of various types
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& package MyApp;
+.Ve
+.PP
+.Vb 3
+\& # ConfigLoader should be first in your list so
+\& # other plugins can get the config information
+\& use Catalyst qw( ConfigLoader ... );
+.Ve
+.PP
+.Vb 3
+\& # by default myapp.* will be loaded
+\& # you can specify a file if you'd like
+\& __PACKAGE__\->config( 'Plugin::ConfigLoader' => { file => 'config.yaml' } );
+.Ve
+.PP
+.Vb 1
+\& In the file, assuming it's in YAML format:
+.Ve
+.PP
+.Vb 1
+\& foo: bar
+.Ve
+.PP
+.Vb 1
+\& Accessible through the context object, or the class itself
+.Ve
+.PP
+.Vb 2
+\& $c\->config\->{foo} # bar
+\& MyApp\->config\->{foo} # bar
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+This module will attempt to load find and load a configuration
+file of various types. Currently it supports \s-1YAML\s0, \s-1JSON\s0, \s-1XML\s0,
+\&\s-1INI\s0 and Perl formats. Special configuration for a particular driver format can
+be stored in \f(CW\*(C`MyApp\->config\->{ 'Plugin::ConfigLoader' }\->{ driver }\*(C'\fR.
+For example, to pass arguments to Config::General, use the following:
+.PP
+.Vb 5
+\& __PACKAGE__\->config( 'Plugin::ConfigLoader' => {
+\& driver => {
+\& 'General' => { \-LowerCaseNames => 1 }
+\& }
+\& } );
+.Ve
+.PP
+See Config::Any's \f(CW\*(C`driver_args\*(C'\fR parameter for more information.
+.PP
+To support the distinction between development and production environments,
+this module will also attemp to load a local config (e.g. myapp_local.yaml)
+which will override any duplicate settings. See
+get_config_local_suffix
+for details on how this is configured.
+.SH "METHODS"
+.IX Header "METHODS"
+.Sh "setup( )"
+.IX Subsection "setup( )"
+This method is automatically called by Catalyst's setup routine. It will
+attempt to use each plugin and, once a file has been successfully
+loaded, set the \f(CW\*(C`config()\*(C'\fR section.
+.Sh "load_config"
+.IX Subsection "load_config"
+This method handles loading the configuration data into the Catalyst
+context object. It does not return a value.
+.Sh "find_files"
+.IX Subsection "find_files"
+This method determines the potential file paths to be used for config loading.
+It returns an array of paths (up to the filename less the extension) to pass to
+Config::Any for loading.
+.Sh "get_config_path"
+.IX Subsection "get_config_path"
+This method determines the path, filename prefix and file extension to be used
+for config loading. It returns the path (up to the filename less the
+extension) to check and the specific extension to use (if it was specified).
+.PP
+The order of preference is specified as:
+.ie n .IP "* $ENV{ MYAPP_CONFIG }" 4
+.el .IP "* \f(CW$ENV{ MYAPP_CONFIG }\fR" 4
+.IX Item "$ENV{ MYAPP_CONFIG }"
+.PD 0
+.ie n .IP "* $ENV{ CATALYST_CONFIG }" 4
+.el .IP "* \f(CW$ENV{ CATALYST_CONFIG }\fR" 4
+.IX Item "$ENV{ CATALYST_CONFIG }"
+.ie n .IP "* ""$c\->config\->{ 'Plugin::ConfigLoader' }\->{ file }""" 4
+.el .IP "* \f(CW$c\->config\->{ 'Plugin::ConfigLoader' }\->{ file }\fR" 4
+.IX Item "$c->config->{ 'Plugin::ConfigLoader' }->{ file }"
+.ie n .IP "* ""$c\->path_to( $application_prefix )""" 4
+.el .IP "* \f(CW$c\->path_to( $application_prefix )\fR" 4
+.IX Item "$c->path_to( $application_prefix )"
+.PD
+.PP
+If either of the first two user-specified options are directories, the
+application prefix will be added on to the end of the path.
+.Sh "get_config_local_suffix"
+.IX Subsection "get_config_local_suffix"
+Determines the suffix of files used to override the main config. By default
+this value is \f(CW\*(C`local\*(C'\fR, which will load \f(CW\*(C`myapp_local.conf\*(C'\fR. The suffix can
+be specified in the following order of preference:
+.ie n .IP "* $ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }" 4
+.el .IP "* \f(CW$ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }\fR" 4
+.IX Item "$ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }"
+.PD 0
+.ie n .IP "* $ENV{ CATALYST_CONFIG_LOCAL_SUFFIX }" 4
+.el .IP "* \f(CW$ENV{ CATALYST_CONFIG_LOCAL_SUFFIX }\fR" 4
+.IX Item "$ENV{ CATALYST_CONFIG_LOCAL_SUFFIX }"
+.ie n .IP "* ""$c\->config\->{ 'Plugin::ConfigLoader' }\->{ config_local_suffix }""" 4
+.el .IP "* \f(CW$c\->config\->{ 'Plugin::ConfigLoader' }\->{ config_local_suffix }\fR" 4
+.IX Item "$c->config->{ 'Plugin::ConfigLoader' }->{ config_local_suffix }"
+.PD
+.PP
+The first one of these values found replaces the default of \f(CW\*(C`local\*(C'\fR in the
+name of the local config file to be loaded.
+.PP
+For example, if \f(CW $ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }\fR is set to \f(CW\*(C`testing\*(C'\fR,
+ConfigLoader will try and load \f(CW\*(C`myapp_testing.conf\*(C'\fR instead of
+\&\f(CW\*(C`myapp_local.conf\*(C'\fR.
+.Sh "finalize_config"
+.IX Subsection "finalize_config"
+This method is called after the config file is loaded. It can be
+used to implement tuning of config values that can only be done
+at runtime. If you need to do this to properly configure any
+plugins, it's important to load ConfigLoader before them.
+ConfigLoader provides a default finalize_config method which
+walks through the loaded config hash and calls the \f(CW\*(C`config_substitutions\*(C'\fR
+sub on any string.
+.ie n .Sh "config_substitutions( $value )"
+.el .Sh "config_substitutions( \f(CW$value\fP )"
+.IX Subsection "config_substitutions( $value )"
+This method substitutes macros found with calls to a function. There are three
+default macros:
+.ie n .IP "* ""_\|_HOME_\|_""\fR \- replaced with \f(CW""$c\->path_to('')""" 4
+.el .IP "* \f(CW_\|_HOME_\|_\fR \- replaced with \f(CW$c\->path_to('')\fR" 4
+.IX Item "__HOME__ - replaced with $c->path_to('')"
+.PD 0
+.ie n .IP "* ""_\|_ENV(foo)_\|_""\fR \- replaced with the value of \f(CW$ENV{foo}" 4
+.el .IP "* \f(CW_\|_ENV(foo)_\|_\fR \- replaced with the value of \f(CW$ENV{foo}\fR" 4
+.IX Item "__ENV(foo)__ - replaced with the value of $ENV{foo}"
+.ie n .IP "* ""_\|_path_to(foo/bar)_\|_""\fR \- replaced with \f(CW""$c\->path_to('foo/bar')""" 4
+.el .IP "* \f(CW_\|_path_to(foo/bar)_\|_\fR \- replaced with \f(CW$c\->path_to('foo/bar')\fR" 4
+.IX Item "__path_to(foo/bar)__ - replaced with $c->path_to('foo/bar')"
+.ie n .IP "* ""_\|_literal(_\|_FOO_\|_)_\|_""\fR \- leaves _\|_FOO_\|_ alone (allows you to use \f(CW""_\|_DATA_\|_"" as a config value, for example)" 4
+.el .IP "* \f(CW_\|_literal(_\|_FOO_\|_)_\|_\fR \- leaves _\|_FOO_\|_ alone (allows you to use \f(CW_\|_DATA_\|_\fR as a config value, for example)" 4
+.IX Item "__literal(__FOO__)__ - leaves __FOO__ alone (allows you to use __DATA__ as a config value, for example)"
+.PD
+.PP
+The parameter list is split on comma (\f(CW\*(C`,\*(C'\fR). You can override this method to
+do your own string munging, or you can define your own macros in
+\&\f(CW\*(C`MyApp\->config\->{ 'Plugin::ConfigLoader' }\->{ substitutions }\*(C'\fR.
+Example:
+.PP
+.Vb 3
+\& MyApp\->config\->{ 'Plugin::ConfigLoader' }\->{ substitutions } = {
+\& baz => sub { my $c = shift; qux( @_ ); }
+\& }
+.Ve
+.PP
+The above will respond to \f(CW\*(C`_\|_baz(x,y)_\|_\*(C'\fR in config strings.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Brian Cassidy <bricas@cpan.org>
+.SH "CONTRIBUTORS"
+.IX Header "CONTRIBUTORS"
+The following people have generously donated their time to the
+development of this module:
+.IP "* Joel Bernstein <rataxis@cpan.org> \- Rewrite to use Config::Any" 4
+.IX Item "Joel Bernstein <rataxis@cpan.org> - Rewrite to use Config::Any"
+.PD 0
+.IP "* David Kamholz <dkamholz@cpan.org> \- Data::Visitor integration" 4
+.IX Item "David Kamholz <dkamholz@cpan.org> - Data::Visitor integration"
+.IP "* Stuart Watt \- Addition of \s-1ENV\s0 macro." 4
+.IX Item "Stuart Watt - Addition of ENV macro."
+.PD
+.PP
+Work to this module has been generously sponsored by:
+.IP "* Portugal Telecom <http://www.sapo.pt/> \- Work done by Joel Bernstein" 4
+.IX Item "Portugal Telecom <http://www.sapo.pt/> - Work done by Joel Bernstein"
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 2006\-2009 by Brian Cassidy
+.PP
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.IP "* Catalyst" 4
+.IX Item "Catalyst"
+.PD 0
+.IP "* Catalyst::Plugin::ConfigLoader::Manual" 4
+.IX Item "Catalyst::Plugin::ConfigLoader::Manual"
+.IP "* Config::Any" 4
+.IX Item "Config::Any"
projects / catagits/Gitalist.git / blobdiff