NAME

Config::Singleton - one place for your app's configuration

VERSION

version 0.006

SYNOPSIS

package YourApplication::Config;

use Config::Singleton -setup => {
  filename => 'something.yaml',
  template => {
    foo => undef,
    bar => 1024,
    qux => [ 1, 2, 3],
  },
};

Elsewhere...

use YourApplication::Config 'my_instance_config.yml';

my $foo = YourApplication::Config->foo;

DESCRIPTION

Config::Singleton provides a base class for access to configuration data for your app. The basic implementation stores its configuration in YAML in a text file found in all the usual places. By default, Config::Singleton looks for myapp.yml, but an alternate filename may be passed when using the module.

This module was derived from Rubric::Config.

PERL VERSION SUPPORT

This code is effectively abandonware. Although releases will sometimes be made to update contact info or to fix packaging flaws, bug reports will mostly be ignored. Feature requests are even more likely to be ignored. (If someone takes up maintenance of this code, they will presumably remove this notice.)

USING APP::CONFIG

The "SYNOPSIS" section, above, demonstrates an example of almost every feature of Config::Singleton It's a very simple module with a very small interface.

It is not a base class. It is a utility for setting up a class that stores loaded configuration data. You just need to use the module like this:

package Your::Config;

use Config::Singleton -setup => {
  filename => 'your_program.yaml',
  template => {
    username => undef,
    hostname => undef,
    logfile  => undef,
    facility => 'local1',
    path     => [ qw(/var/spool /tmp/jobs) ],
  },
};

When another module uses Your::Config, your_program.yaml will be loaded and its contents will be merged over the defaults given by the template argument. Each entry in the template hashref becomes a method on YourProgram::Config, which returns either the value from the config file or the value from the template, if no entry exists in the config file.

So, assuming that your_program.yaml looks like this:

---
username: rjbs
hostname: fulfill.example.com

path:
  - /var/spool/jobs
  - /home/rjbs/spool/jobs

Then these are the results of method calls on Your::Config:

Your::Config->username; # 'rjbs'

Your::Config->logfile;  # undef

Your::Config->facility; # 'local0'

Your::Config->path;     # qw(/var/spool/jobs  /home/rjbs/spool/jobs)

Specifying a Config File

Config::Singleton finds a config file via a series of DWIM-my steps that are probably more complicated to explain than they are to understand.

The filename argument given when using Config::Singleton is the name of the file that will, by default, be loaded to find configuration. It may be absolute or relative. If not given, it's computed as follows: the "module base name" is made by dropping the last part of the class name, if it's multi-part, and double colons become underscores. In other words "Your::Thing::Config" becomes "Your_Thing." If the environment variable YOUR_THING_CONFIG_FILE is set, that will be used as the default. If not, your_thing.yaml will be used.

The named file will be the source of configuration for the global (class method) configuration. It can be overridden, however, when using the config module. For example, after using the following code:

use Your::Thing::Config 'special.yaml';

...the default name will have been replaced with special.yaml. If the previous default file has already been loaded, this will throw an exception. Using the module without specifying a filename will defer loading of the configuration file until it's needed. To force it to be loaded without setting an explicit filename, pass -load as the filename. (All names beginning with a dash are reserved.)

If the filename is relative, the configuration file is found by looking for the file name in the following paths (LOC is the location of the program being run, found via $0):

./
../
LOC/
LOC/../etc/
~/
/etc/

You can change the paths checked by providing a path argument, as an arrayref, in the setup arguments.

Alternate Configuration Objects

Although it's generally preferable to begin your program by forcing the loading of a configuration file and then using the global configuration, it's possible to have multiple Your::Thing::Config configurations loaded by instantiating objects of that class, like this:

my $config_obj = Your::Thing::Config->new($filename);

The named file is found via the same path resolution (if it's relative) as described above.

METHODS

Config::Singleton doesn't actually have any real public methods of its own. Its methods are all private, and serve to power its import routine. These will probably be exposed in the future to allow for subclassing of Config::Singleton, but in the meantime, don't rely on them.

TODO

• a ->new method to allow loading different configs

• a way to tell Your::Config, with no explicit filename, to die unless a filename was specified by an earlier use

ACKNOWLEDGEMENTS

Ricardo SIGNES not only wrote the inspiration for this in Rubric::Config, but he also basically wrote the majority of the implementation here, and even provided extensions of what he knew I wanted it to do, even when I said I didn't need that yet. In the end it ended up being extremely elegant, which I can say without being boastful, because he wrote the elegant bits.

AUTHORS

• Ricardo SIGNES <rjbs@semiotic.systems>

• John Cappiello <jcap@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2008 by John Cappiello.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.