view release on metacpan or  search on metacpan

Directory.pm  view on Meta::CPAN

    my $file = File::Spec->catfile($dir,$name);
    open OUT, ">$file" or die "unable to open '$file' for write: $!";
    {
        local $\ = undef;
        print OUT $value;
        print OUT "\n"
            unless substr($value,-1) eq "\n" || length($value) == 0 || 
                  (exists $ARG->{'chomp'} && $ARG->{'chomp'} == 0);
    }
    close OUT or die "unable to close '$file': $!";

    # Update $self
    $self->{$name} = $value;
}

1;

__END__

=head1 NAME

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


=head1 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";


=head1 ABSTRACT

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


=head1 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.

=head2 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:

=over 4

=item B<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). 

=item B<get>

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

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

=item B<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).

=back