NAME

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

VERSION

version 0.002

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.

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.

AUTHOR

John Cappiello, <jcap at cpan.org>

Ricardo SIGNES, <rjbs at cpan.org>

BUGS

Please report any bugs or feature requests through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config::Singleton. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Config::Singleton

You can also look for information at:

• CPAN Ratings

  http://cpanratings.perl.org/d/Config::Singleton

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Config::Singleton

• Search CPAN

  http://search.cpan.org/dist/Config::Singleton

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.

COPYRIGHT & LICENSE

Copyright 2008, John Cappiello.

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