The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


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


  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);
  print $etc->get('passwd.min'), "\n";


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


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.


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


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


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

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

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


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


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


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


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


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


Regex of filenames to ignore (default: none).


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


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_' });

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.


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.


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.


Gavin Carr, <>


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.