The POD

NAME

Config::File

SYNOPSIS

OO usage

 use Config::File;

  $conf = Config::File->new( file => $file, path => $path );

  print $conf->key;
[download]

Procedural usage, retrieving a hash

  use Config::File 'config';

  %hash = config( file => $file, path => $path );

  print $hash{key};
[download]

Procedural usage, retrieving a hashref

  use Config::File 'config';

  $hashref = config( file => $file, path => $path );

  print $hashref->{key};
[download]

DESCRIPTION

Alows complex configuration information such as nested arrays and hashes to be written in plain text files.

The config file must be in the form of an anonymous perl hash structure.

Using the OO method allows access to configuration values with a minimum of typing and also provides a safety mechanism, such that any call to a non-existant configuration key is fatal.

A procedural method 'config' is provided which will return the entire configuration data structure as a hash or hashref.

The procedural method is about 5% faster than the OO method. Using a hashref is about 1 - 2% faster than using a normal hash.

EXPORT

Exports 'config' subroutine on request.

EXAMPLE

For an example, running this code...

  use Config::File;
  $conf = Config::File->new(file => 'my.conf');
  
  print $conf->db_password, $/;
  print $conf->blocked_words->[0], $/;
  print $conf->emails->{webmaster}, $/;
[download]

...on the file 'my.conf'...

  {
    db_password => 'secret',
    
    blocked_words => ['list', 'of', 'words'],
    
    emails => { sales     => 'sales@fireartist.com',
                webmaster => 'webmaster@fireartist.com',
               }
  }
[download]

...would give the output...

  secret
  list
  webmaster@fireartist.com
[download]

And the code...

package Config::File;
$VERSION = '0.30';

use strict;
require Exporter;
use vars qw($VERSION @ISA @EXPORT_OK $AUTOLOAD);
@ISA = qw(Exporter);
@EXPORT_OK = qw/config/;

use Carp;
use File::Spec;


sub new {
  my $class = shift;
  my %arg   = @_;
  my $self  = {};
  
  bless( $self, $class );
  
  my $file = _file_path( $arg{file}, $arg{path} );
  
  $self->{conf} = do($file)
    or croak('new() could not load config file');
  
  return $self;
}


sub config {
  my $self = shift if ref $_[0];
  my %arg = @_;
  
  my $file = _file_path( $arg{file}, $arg{path} );
  
  my $conf = do($file)
    or croak('hash() could not load config file');
  
  return (wantarray ? %{ $conf } : $conf);
}


sub _file_path {
  my ($file, $path) = @_;
  my $exists;
  
  croak('_file_path requires file arg') unless defined $file;
  
  if ($path && -e File::Spec->catfile( $path, $file )) {
    $exists = File::Spec->catfile( $path, $file );
  }
  elsif ( -e $file ) {
    $exists = $file;
  }
  else {
    for (@INC) {
      if (-e File::Spec->catfile( $_, $file )) {
        $exists = File::Spec->catfile( $_, $file );
        last;
      }
    }
  }
  
  croak('could not find config file') unless defined $exists;
  
  return $exists;
}


sub AUTOLOAD {
  my $self   = shift;
  
  my $method = $AUTOLOAD;
  $method =~ s/.*://;
  
  unless (defined $self->{conf}->{$method}) {
    croak($method.' not defined in config file');
  }
  
  return $self->{conf}->{$method} if not wantarray;
  
  if (ref $self->{conf}->{$method} eq 'HASH') {
    return %{ $self->{conf}->{$method} };
  }
  elsif (ref $self->{conf}->{$method} eq 'ARRAY') {
    return @{ $self->{conf}->{$method} };
  }
  else {
    return $self->{conf}->{$method};
  }
}

sub DESTROY { }


1;
[download]