.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" 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 "Gantry::Conf::Tutorial 3"
.TH Gantry::Conf::Tutorial 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Gantry::Conf::Tutorial \- Tutorial on how to use Gantry::Conf
.SH "INTRO"
.IX Header "INTRO"
This document explains both how to use Gantry::Conf to configure
a set of applications and how to extend Gantry::Conf to suit your needs.
.SH "CONFIGURING"
.IX Header "CONFIGURING"
Gantry::Conf uses a central config file to control how a set of applications
bootstrap their own configuration.  By default, this file live in
/etc/gantry.conf, but you can control that, see below.  That file is parsed
by Config::General and looks something like this:
.PP
.Vb 3
\&    <global>
\&        database_server_name ourdb.ourcompany.com
\&    </global>
.Ve
.PP
.Vb 4
\&    <shared appearance>
\&        background white
\&        foreground blue
\&    </shared>
.Ve
.PP
.Vb 4
\&    <instance app1>
\&        ConfigureVia FlatFile Config::General /path/to/file
\&        use appearance
\&    </instance>
.Ve
.PP
.Vb 4
\&    <instance app2>
\&        ConfigureVia HTTP Config::General http://conf.oc.com/conf
\&        use appearance
\&    </instance>
.Ve
.PP
.Vb 4
\&    <instance right_here>
\&        var   value
\&        color blue
\&    </instance>
.Ve
.PP
.Vb 1
\&    include /etc/gantry.d/*.conf
.Ve
.PP
Then in /etc/gantry.d/app3.conf:
.PP
.Vb 4
\&    <instance app3>
\&        ConfigureVia FlatFile Config::Tiny /path/to/conf
\&        ConfigureVia HTTP Config::General http://conf.oc.com/conf
\&    </instance>
.Ve
.PP
Each application instance has a section in this file, unless its instance
can be gleaned from /etc/gantry.d.  This allows not only multiple apps, but
also multiple instances of the same app running in the same server.  The
instance name must be unique and is what the app uses to find its conf.
.PP
In the instance block, you may choose to define conf variables and their
values directly (as the \f(CW\*(C`right_here\*(C'\fR instance does above).  Otherwise,
the core of any instance's configuration is the ConfigureVia
statement(s).  The form of these statments vary by the configuration
method.
.PP
The methods supported are:
.IP "PerlSetVar" 4
.IX Item "PerlSetVar"
This method is designed for use in a mod_perl setting.  Here's a typical
example:
.Sp
.Vb 5
\&    <instance inmod_perl>
\&        ConfigureVia PerlSetVar
\&        LoadParameters the variables you need here note the \e
\&                       backslash allowed by Config General
\&    </instance>
.Ve
.Sp
The listed parameters are loaded using dir_config on the apache
request object.
.Sp
In the future, it may be possible to use this method outside of mod_perl.
In that case, you will have to factor out the part of the apache conf
relating to this application into a separate file and include:
.Sp
.Vb 1
\&    ApacheConfigFile /path/to/your.conf
.Ve
.Sp
This will only be used outside of mod_perl.
.Sp
Note that this feature is not yet available and may never be.
.IP "ParamBuilder" 4
.IX Item "ParamBuilder"
This method is not yet available, but it will work like PerlSetVar above,
except it will expect to see variables defined for ParamBuilder use.
.IP "FlatFile" 4
.IX Item "FlatFile"
Use this if you keep your conf in one or more flat files somewhere on
your local system.
.Sp
.Vb 3
\&    <instance app>
\&        ConfigureVia FlatFile Config::General file1 [file2...]
\&    </instance>
.Ve
.Sp
In this case, I chose to use Config::General to parse the file.  The
other current choice is Config::Tiny.  If you need a different flat
file syntax, you need to implement a provider for it, see
\&\*(L"\s-1EXTENDING\s0 Gantry::Conf\*(R".
.Sp
See the perldoc for your provider for the syntax your conf file must follow.
.IP "\s-1SQL\s0" 4
.IX Item "SQL"
.PD 0
.IP "\s-1HTTP\s0" 4
.IX Item "HTTP"
.PD
If your conf is available through the web, via http or https use
this method to retrieve your config information from a remote system: 
.Sp
.Vb 3
\&    <instance app>
\&        ConfigureVia HTTP Config::General url [url...]
\&    </instance>
.Ve
.Sp
You can use all the same providers for the \s-1HTTP\s0 method as you use for
the FlatFile method.  That provider is responsible for converting the
response from the server into a conf hash.
.Sp
To include apache basic auth information, add it to the url:
.Sp
.Vb 1
\&    http://user:pass@host.example.com/path/to/conf
.Ve
.Sp
Note that ssl is supported (by \s-1LWP\s0), so you can use https://... to keep
your configuration information from traveling in the clear. 
.IP "Default" 4
.IX Item "Default"
Normally, you get the default merely by omitting the ConfigureVia statement
from an instance block.  Then the configuration must be included
directly in Gantry::Conf format in the <instance> block.
.PP
Any instance can share conf with other instances in three ways:
.IP "repeated ConfigureVia statements" 4
.IX Item "repeated ConfigureVia statements"
Each instance block can have as many ConfigureVia statements as you want.
Earlier ones have precedence.  In the example above, the app3 instance has
its own flat file of conf information, but also refers to the http served
conf that app2 is using.
.Sp
I'll say it again: precedence goes the earliest file listed. So if you
have an instance that looks like this: 
.Sp
.Vb 4
\&  <instance appoverride> 
\&    ConfigureVia FlatFile Config::Tiny /etc/appoverride.conf 
\&    ConfigureVia HTTP Config::General http://dev.domain.com/main.conf 
\&  </instance>
.Ve
.Sp
then any configuration options in /etc/appoverride.conf 
will override those found in the remote http://dev.domain.com/main.conf.  
.IP "global" 4
.IX Item "global"
If you define a global block, all instances will have the variables defined
in it included in their conf hashes.  To override a global, define the
same variable in the conf data source of one of your ConfigVia statements.
In the example above, all three instances share the database_server_name
variable (unless their individual conf data sources define the same variable).
.IP "use" 4
.IX Item "use"
If two or more apps need to share a set of configuration options which 
you want to define directly in the Gantry::Conf file, put them in a 
shared block.  Then include a use statement in each instance block 
which should share this data.  To override a shared variable, define 
the same variable in the conf data source of one of your ConfigVia 
statements.  In the example above, app1 and app2 share all the variables 
in the appearance shared block.
.PP
The precedence is:
.IP "1." 4
ConfigVia statements in the order they appear.
.IP "2." 4
Any variables declared in the global block.
.IP "3." 4
Any shared blocks used by the instance in the order they appear.
.PP
Note that you may use \f(CW\*(C`include\*(C'\fR at any point passing it a shell style
file glob.  Any matching files will be included at that point as if typed
there.  This is highly convenient for separating config information into
separate files by app.  Then your master config file (/etc/gantry.conf)
might be as simple as:
.PP
.Vb 1
\&    include /etc/gantr.d/*.conf
.Ve
.SH "USING A CONFIGURATION"
.IX Header "USING A CONFIGURATION"
Once you have a configuration for your applications, you can load the
conf easily through the \f(CW\*(C`<Gantry::Conf\-\*(C'\fRretrieve method>>:
.PP
.Vb 1
\&    use Gantry::Conf;
.Ve
.PP
.Vb 6
\&    my $conf = Gantry::Conf->retrieve(
\&        {
\&            instance    => 'app1',
\&            config_file => '/etc/gantry.confs/standard.conf',
\&        }
\&    );
.Ve
.PP
When calling retrieve, you must provide the parameters by name in a hash
reference.  The only required key is \f(CW\*(C`instance\*(C'\fR.  Gantry::Conf will look
for the instance in the \f(CW\*(C`config_file\*(C'\fR.  By default the config_file is
\&\f(CW\*(C`/etc/gantry.conf\*(C'\fR.  If your config files use GantryLocation blocks,
like this:
.PP
.Vb 3
\&    level_name top
\&    all_share 5
\&    reset 5
.Ve
.PP
.Vb 4
\&    <GantryLocation /second>
\&        level_name second
\&        reset 4
\&    </GantryLevel>
.Ve
.PP
.Vb 4
\&    <GantryLocation /second/nested>
\&        level_name second.nested
\&        reset 2
\&    </GantryLevel>
.Ve
.PP
You can pass \f(CW\*(C`location\*(C'\fR to retrieve, then you will get the values for
the specified location.  Note that parameters are not inherited from
\&\*(L"parent\*(R" locations.  All locations are thought to be independent.
Thus, if \f(CW\*(C`/second/nested\*(C'\fR above did not define \f(CW\*(C`reset\*(C'\fR, its value for
it would be 5 (inherited from the top level) and not 4 (which \f(CW\*(C`/second\*(C'\fR
defined).
.SH "EXTENDING Gantry::Conf"
.IX Header "EXTENDING Gantry::Conf"
You can implement your own providers for FlatFile and \s-1SQL\s0 configuration
methods.  (Note that FlatFile providers are also \s-1HTTP\s0 providers.)
.PP
To implement your own FlatFile provider name it like this:
.PP
.Vb 1
\&    package Gantry::Conf::Provider::Module;
.Ve
.PP
Then put a method in it called config which is called as a class method
taking a single parameter.  For example, here is the whole Config::General
provider:
.PP
.Vb 1
\&    package Gantry::Conf::Provider::FlatFile::Config::General;
.Ve
.PP
.Vb 2
\&    use strict;
\&    use warnings;
.Ve
.PP
.Vb 1
\&    use Carp qw(croak);
.Ve
.PP
.Vb 3
\&    use Config::General;
\&    use Gantry::Conf::Provider;
\&    use base qw( Gantry::Conf::Provider );
.Ve
.PP
.Vb 3
\&    sub config {
\&        my $self    =   shift;
\&        my $file    =   shift;
.Ve
.PP
.Vb 2
\&        my $config = Config::General->new( $file ) or
\&                croak "Unable to create Config::General object: $!";
.Ve
.PP
.Vb 1
\&        my %confs = $config->getall;
.Ve
.PP
.Vb 1
\&        return( \e%confs );
.Ve
.PP
.Vb 1
\&    } # END config
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIGantry\fR\|(3), \fIGantry::Conf\fR\|(3), \fIGanty::Conf::FAQ\fR\|(3)
.SH "AUTHOR"
.IX Header "AUTHOR"
Phil Crow <pcrow@sunflowerbroadband.com>
.PP
Frank Wiles <frank@revsys.com> 
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
Copyright (c) 2006, Frank Wiles. 
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.