NAME

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

SYNOPSIS

  use Config::Directory;

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

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

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

  # Updating values
  $qc->set('CONCURRENCY', 10);
  $etc->set('passwd.min','root:x:0:0:root:/root:/bin/bash');
  print $etc->get('passwd.min'), "\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 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, while using files for individual config items makes update interfaces much simpler, does away with lots of parsing problems, and is nicely scriptable.

METHODS

Config::Directory uses a very simple OO-style interface, with the only methods provided being new(), get(), and set(). Basic usage is as follows:

new

The Config::Directory constructor takes up to two arguments. The first is a directory or arrayref of directories to scan for files; the second is an optional hashref containing options (see OPTIONS below).

  # Constructor, with single or multiple directories
  $c = Config::Directory->new("/etc");
  $c2 = Config::Directory->new([
    "/usr/local/myapp/dist", "/usr/local/myapp/local",
  ]);

  # Constructor with options
  $c2 = Config::Directory->new("/etc", {
    ignore => '*.rpmnew', chomp => 0,
   });

The directory argument to new() can be either a single directory via a scalar, or an ordered set of directories passed in as an arrayref, which are scanned in the given order. Later files with the same names override earlier ones. The returned Config::Directory object contains 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 - see OPTIONS below).

get

An accessor method, supplied as an alternative to using the blessed hashref directly.

  $value = $c->get($name);

set

A mutator method, for updating the contents of a file. If using a set of directories, updated files are always written to the last directory in the set. Dies on error.

  $c->set($name, $value).

CONSTRUCTOR OPTIONS

The new() constructor takes an optional hashref of options. The following are recognised:

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).

chomp

Whether file values should be chomped, which allows single-line files to produce immediately useful values (default: 1).

trim

Whether whitespace at the beginnings and end of lines should be removed (default: 1).

ignore

Regex of filenames to ignore (default: none).

glob

Glob pattern (or arrayref of glob patterns) 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.

LIMITATIONS

Config::Directory is not recursive - subdirectories are simply ignored. There is also 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-2011 Gavin Carr.

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