Newcomen

Description A static content generator.
Newcomen > Perl Modules > Newcomen::Config
Source

Index

NAME ^

Newcomen::Config - Configuration frontend.

SYNOPSIS ^

use Newcomen::Config;

my $config = Newcomen::Config -> new ();

# Load user configuration:
$config -> add_config ($backend_name, $backend_options);

# A plugin may add default values:
$config -> add_default ($default_options);

# Access options:
my $value = 'some default';
if ($config -> exists (['some', 'option'])) {
   $value = $config -> get (['some', 'option']);
}

DESCRIPTION ^

Newcomen::Config manages Newcomen's configuration.

User configuration settings are loaded by configuration backends, currently the only one available is Newcomen::Config::Perl. Plugins may add default values for their configuration options. User and default values are kept separate, adding default values after the user configuration has been loaded will not override the user defined values. That means that calls to get() or exists() will always return the expected value.

Access to the configuration options works like access to data stored in an Newcomen::Data instance. The methods get() and exists() are equivalent to the Newcomen::Data methods of the same name. So are the methods path() and key(), included for convenience should they be required. Please see Newcomen::Data for details on how to access individual elements/options.

Plugins may use Newcomen::Role::Attribute::Config to access the main configuration instance.

CLASS METHODS ^

new

my $config = Newcomen::Config -> new ();

Constructor. Expects no parameters. The initial configuration will be empty.

INSTANCE METHODS ^

Setting Configuration Values

Note that there is no method to set a single option to a specific value, i.e. there is no equivalent to Newcomen::Data's set() method. The only way to add stuff to the configuration is to use one of the two methods, add_config() or add_default(), described below.

Using one of these two methods will merge the new values with the already existing ones. No option already set will ever be deleted, but existing options may be overridden if they are defined again in a configuration loaded later on.

add_config

Toggle source:   add_config 

sub add_config {

   my $self    = shift;
   my $name    = shift;
   my $opts    = shift // Newcomen::Data -> new ();
   my $backend = undef;

   $opts = Newcomen::Data -> new () -> merge ($opts) if ref $opts eq 'HASH';

   for ($self -> backends ()) {
      if (lc "Newcomen::Config::$name" eq lc $_) {
         $backend = $self -> backend ($_);
         last;
      }
   }

   confess "Configuration backend $name not found" unless $backend;

   $self -> _merge_user ($backend -> config ($opts));

}
$config -> add_config ($backend_name, $backend_options);

Uses the specified backend to load user configuration. The first parameter must be the basename of the backend module, i.e. the module name without the 'Newcomen::Config::' prefix. The name is not case sensitive. If the specified backend does not exist, this method will die(). The second parameter is optional. If it is specified, it must be a hashref or an Newcomen::Data instance containing the options to be passed to the backend (the hashref, or Newcomen::Data instance, may be empty). Different backends may use different options, see the individual backends for details.

Note: The backend's name matching is not case sensitive, as mentioned above. Matching is performed using Perl's built-in lc() function, which may not work with UTF-8 module names. Using ASCII only is recommended.

add_default

Toggle source:   add_default 

sub add_default {

   my $self = shift;
   my $conf = shift;

   $self -> _merge_default ($conf);

}
$config -> add_default ($default_options);

This method may be used by plugins to add default values for their configuration options. The method must be called with one parameter, which must be a hashref containing the default options/values to be set.

Accessing Configuration Settings

exists

my $exists = $config -> exists ($path);

Checks if the specified configuration option exists. The one (required) parameter has to be an arrayref or a string specifying the path to the configuration option. See Newcomen::Data for more details on this parameter's format.

get

my $value = $config -> get ($path);

Returns the value of the specified configuration option. This will be undef if the option does not exist, use exists() if you need to know. If the user configuration includes a setting for the option, this value will be returned. If the default values include this option, and no user setting overrides it, the default will be returned. The required parameter specifies the requested configuration option. See Newcomen::Data for a description of the possible values.

Backends

The following methods allow access to the configuration backends, though usually this should not be necessary.

backend

my $backend = $config -> backend ($full_name);

Returns a configuration backend instance. The parameter must be the full module name, including the 'Newcomen::Config::' prefix. This name is case sensitive.

backend_exists

my $exists = $config -> backend_exists ($full_name).

Returns a true value if the backend (specified by its full module name as described above) exists.

backends

my @backends = $config -> backends ();

Returns a list containing the full module names of all available configuration backends.

Miscellaneous Methods

key

my $key = $config -> key ($path);

See Newcomen::Data's key() method.

path

my $path = $config -> path ($key);

See Newcomen::Data's path() method.

MISCELLANEOUS ^

Backends must use Newcomen::Config::Backend as their base class. They must be placed in the Newcomen::Config namespace, and implement a _do_config() method. See Newcomen::Config::Backend for more details.

SEE ALSO ^

Newcomen::Config::Backend, Newcomen::Config::Perl, Newcomen::Data, Newcomen::Role::Attribute::Config, Newcomen::Role::Frontend

VERSION ^

This is version 2014052501.

AUTHOR ^

Stefan Goebel - newcomen {at} subtype {dot} de

COPYRIGHT AND LICENSE ^

Copyright 2013-2014 Stefan Goebel.

This file is part of Newcomen.

Newcomen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the license, or (at your option) any later version.

Newcomen is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Newcomen. If not, see <http://www.gnu.org/licenses/>.

generated by (a slightly patched) Pod::ProjectDocs 0.41