view release on metacpan or  search on metacpan

lib/App/Conf.pod  view on Meta::CPAN

######################################################################
## $Id: Conf.pod 3208 2002-09-09 01:34:11Z spadkins $
######################################################################

=head1 NAME

App::Conf - Load and access configuration data

=head1 SYNOPSIS

   use App::Conf;

   $config = App::Conf->new();
   $config = App::Conf->new("file" => $file);
   $config = App::Conf->new("file" => $file, "configClass" => "App::Conf::XML");
   print $config->dump(), "\n";       # use Data::Dumper to spit out the Perl representation

   # accessors
   $property_value = $config->get($property_name);
   $branch = $config->get_branch($branch_name);  # get hashref of properties

   # on-demand loading helper methods (private methods)
   $config->overlay($config2);        # merge the two config structures using overlay rules
   $config->overlay($config1, $config2);  # merge $config2 onto $config1
   $config->graft($branch_name, $config2);  # graft new config structure onto branch

   # By convention, the configurations for each App-Context service will be located
   # two levels under the hash ref as shown.

   $config->{Conf}             # config settings for all Conf services
   $config->{Conf}{default}    # config settings for the default Conf service
   $config->{Security}           # config settings for all Security services
   $config->{Security}{default}  # config settings for the default Security service
   $config->{TemplateEngine}{tt} # config settings for the Template service named "tt"

   # The default driver (if "configClass" not supplied) reads in a Perl
   # data structure from the file.  Alternate drivers can read a Storable,
   # unvalidated XML, DTD-validated XML, RDF-validated XML, or any other
   # file format or data source anyone cares to write a driver for.

   $conf = {
     'Standard' => {
       'Log-Dispatch' => {
         'logdir' => '/var/p5ee',
       }
     },
     'Authen' => {
       'passwd' => '/etc/passwd',
       'seed' => '303292',
     },
   };

   # A comparable unvalidating XML file would look like this.

   <conf>
     <Standard>
       <Log-Dispatch logdir="/var/p5ee"/>
     </Standard>
     <Authen passwd="/etc/passwd" seed="303292"/>
   </conf>

   # A comparable ini file (.ini) would look like this.

   [Standard.Log-Dispatch]
   logdir = /var/p5ee
   [Authen]
   passwd = /etc/passwd
   seed = 303292

   # A comparable Java properties-like file would look like this.

   Standard.Log-Dispatch.logdir = /var/p5ee
   Authen.passwd = /etc/passwd
   Authen.seed = 303292

=head1 DESCRIPTION

App::Conf is the class which represents data which is configured
at application deployment time (not at App-Context development time). 

=cut

#############################################################################
# CLASS GROUP

lib/App/Conf.pod  view on Meta::CPAN

current class.

=cut

#############################################################################
# init()
#############################################################################

=head2 init()

The init() method is called from within the standard Conf constructor.
The init() method in this class does nothing.
It allows subclasses of the Conf to customize the behavior of the
constructor by overriding the init() method. 

    * Signature: init($named)
    * Param:     $named        {}    [in]
    * Return:    void
    * Throws:    App::Exception::Conf
    * Since:     0.01

    Sample Usage: 

    $config->init($args);

=cut

#############################################################################
# load()
#############################################################################

=head2 load()

    * Signature: $config_data = $config->load($named);
    * Param:     void
    * Param:     configFile     string
    * Return:    $config_data   {}
    * Throws:    App::Exception::Conf
    * Since:     0.01

    Sample Usage: 

    $config_data = $config->load();
    $config_data = $config->load(
        configFile => "config.xml",
    );

=cut

#############################################################################
# PRIVATE METHODS
#############################################################################

=head1 Private Methods:

The following methods are intended to be called only within this class.

=cut

#############################################################################
# overlay()
#############################################################################

=head2 overlay()

    * Signature: $config->overlay($config2);
    * Signature: $config->overlay($config1, $config2);
    * Param:     $config1      {}
    * Param:     $config2      {}
    * Return:    void
    * Throws:    App::Exception::Conf
    * Since:     0.01

    Sample Usage: 

    # merge the two config structures using overlay rules
    $config->overlay($config2);

    # merge $config2 onto $config1
    $config->overlay($config1, $config2);

=cut

#############################################################################
# graft()
#############################################################################

=head2 graft()

    * Signature: $config->graft($branch_name, $config2);
    * Param:     $branch_name   string
    * Param:     $config2       {}
    * Return:    void
    * Throws:    App::Exception::Conf
    * Since:     0.01

    Sample Usage: 

    # graft new config structure onto branch
    $config->graft($branch_name, $config2);

=cut

=head1 ACKNOWLEDGEMENTS

 * Author:  Stephen Adkins <stephen.adkins@officevision.com>
 * License: This is free software. It is licensed under the same terms as Perl itself.

=head1 SEE ALSO

L<C<App>|App>,
L<C<App::Context>|App::Context>

=cut

1;