NAME

Config::Directory - hash-based interface to directories of files

SYNOPSIS

use Config::Directory;

# Simple 
$c = Config::Directory->new("/etc");
print $c->{passwd}, "\n";

# Multiple config directories
$cc = Config::Directory->new([ "/usr/local/myapp/conf", "$HOME/.myapp" ]);

# Options: add prefix, export values to environment, read only first line
#   ignore all README.* files
$qc = Config::Directory->new("/var/qmail/service/qmail/env",
    { prefix => 'QMAIL_', env => 1, lines => 1, ignore => 'README.*' });
print $q->{QMAIL_CONCURRENCY}, $ENV{QMAIL_CONCURRENCY}, "\n";

ABSTRACT

OO-interface to directories of files, particularly suited to configs 
loaded from multiple small files across multiple cascading 
directories.

DESCRIPTION

Config::Directory presents an OO hash-based read-only interface to directories of files. It is particularly suited to configuration directories where settings can cascade across multiple directories with multiple files per directory. Using multiple directories for configuration data allows an application to support, for example, distribution defaults, global site settings, and user-specific local settings. Using multiple configuration files can often simplify formatting, reduce parsing requirements, and improve scriptability (e.g. 'echo 10 > conf/MAXSIZE').

Config::Directory uses a very simple OO-style interface - only the new() method exists. Basic usage is:

# Load all files in a single directory
$c = Config::Directory->new("/etc");
print $c->{passwd};

where the returned Config::Directory object will contain a hash reference of the files in the directory, keyed by filename, with each entry containing the (chomped) contents of the relevant file. Subdirectories are ignored, as are zero-length files and files greater than 100K in size (the limit is tunable via the 'maxsize' option).

The directory argument to new() can be either a single directory, as in the example above, or an arrayref of directories to allow multiple cascading configuration directories. Thus:

# Multiple config directories
$cc = Config::Directory->new([ "/usr/local/myapp/conf", "$HOME/.myapp" ]);

loads the files from /usr/local/myapp/conf, followed by those from $HOME/.myapp. Later files with the same name override previous ones.

new() also takes an optional hashref of options. The following are currently defined:

lines

The maximum number of lines (newline-delimited) to read from a file (default: unlimited).

maxsize

Maximum size of file to read - files larger than maxsize are ignored (default: 100K).

ignore

Regex of filenames to ignore (default: none).

glob

Glob pattern of filenames to include - all other files are ignored (default: none).

prefix

Prefix to prepend to key values (filenames) in the returned hashref, and to environment variables, if the env option is set (default: none). e.g.

$cc = Config::Directory("$HOME/.myapp", { prefix => 'MYAPP_' });

env

Flag to indicate whether single-line values should be set as environment variables. If env is 1, the variable name will be the same as the corresponding key value (including a prefix, if set). If env is true but != 1, the env value will be used as the prefix prepended to the filename when setting the environment variables (default: none). e.g.

$cc = Config::Directory("$HOME/.myapp", { env => 'MYAPP_' });

will set environment variables MYAPP_filename1, MYAPP_filename2, etc.

chomp

By default, all file values are chomped, which allows single-line files to produce immediately useful values. If you don't like this, you can turn it off by setting chomp to zero.

LIMITATIONS

Config::Directory is currently read-only. A read-write interface is likely in the future (see e.g. Tie::TextDir in the meantime).

It's also not recursive - subdirectories are simply ignored. And there is no file-merging support - files of the same name in later directories simply overwrite the previous ones.

SEE ALSO

The Tie::TextDir and DirDB modules are conceptually similar, but use a TIEHASH interface and do not support inheritance across multiple directories. The facility to export to the environment is inspired by the env_dir utility in Dan J. Bernstein's daemontools.

AUTHOR

Gavin Carr, <gavin@openfusion.com.au>

COPYRIGHT AND LICENSE

Copyright 2003 by Gavin Carr and Open Fusion Pty. Ltd.

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