/ 
Config-Auto-0.15_01
River stage two • 9 direct dependents • 12 total dependents
/ Config::Auto

NAME

Config::Auto - Magical config file parser

SYNOPSIS

use Config::Auto;

# Not very magical at all.
my $config = Config::Auto::parse("myprogram.conf", format => "colon");

# Considerably more magical.
my $config = Config::Auto::parse("myprogram.conf");

# Highly magical.
my $config = Config::Auto::parse();

DESCRIPTION

This module was written after having to write Yet Another Config File Parser for some variety of colon-separated config. I decided "never again".

When you call Config::Auto::parse with no arguments, we first look at $0 to determine the program's name. Let's assume that's snerk. We look for the following files:

snerkconfig
~/snerkconfig
/etc/snerkconfig
/usr/local/etc/snerkconfig
snerk.config
~/snerk.config
/etc/snerk.config
/usr/local/etc/snerk.config
snerkrc
~/snerkrc
/etc/snerkrc
/usr/local/etc/snerkrc
.snerkrc
~/.snerkrc
/etc/.snerkrc
/usr/local/etc/.snerkrc

Additional search paths can be specified with the paths option.

We take the first one we find, and examine it to determine what format it's in. The algorithm used is a heuristic "which is a fancy way of saying that it doesn't work." (Mark Dominus.) We know about colon separated, space separated, equals separated, XML, Perl code, Windows INI, BIND9 and irssi style config files. If it chooses the wrong one, you can force it with the format option.

If you don't want it ever to detect and execute config files which are made up of Perl code, set $Config::Auto::DisablePerl = 1.

When using the perl format, your configuration file will be eval'd. This will cause taint errors. To avoid these warnings, set $Config::Auto::Untaint = 1.

When using the perl format, your configuration file will be eval'd using do(file). This will cause taint errors if the filename is not untainted. To avoid these warnings, set $Config::Auto::Untaint = 1. This setting will not untaint the data in your configuration file and should only be used if you trust the source of the filename.

Then the file is parsed and a data structure is returned. Since we're working magic, we have to do the best we can under the circumstances - "You rush a miracle man, you get rotten miracles." (Miracle Max) So there are no guarantees about the structure that's returned. If you have a fairly regular config file format, you'll get a regular data structure back. If your config file is confusing, so will the return structure be. Isn't life tragic?

Here's what we make of some common Unix config files:

/etc/resolv.conf:

$VAR1 = {
      'nameserver' => [ '163.1.2.1', '129.67.1.1', '129.67.1.180' ],
      'search' => [ 'oucs.ox.ac.uk', 'ox.ac.uk' ]
    };

/etc/passwd:

$VAR1 = {
      'root' => [ 'x', '0', '0', 'root', '/root', '/bin/bash' ],
      ...
    };

/etc/gpm.conf:

$VAR1 = {
      'append' => '""',
      'responsiveness' => '',
      'device' => '/dev/psaux',
      'type' => 'ps2',
      'repeat_type' => 'ms3'
    };

/etc/nsswitch.conf:

$VAR1 = {
      'netgroup' => 'nis',
      'passwd' => 'compat',
      'hosts' => [ 'files', 'dns' ],
      ...
};

PARAMETERS

Although Config::Auto is at its most magical when called with no parameters, its behavior can be reined in by use of one or two arguments.

If a filename is passed as the first argument to parse, the same paths are checked, but Config::Auto will look for a file with the passed name instead of the $0-based names.

use Config::Auto;

my $config = Config::Auto::parse("obscure.conf");

The above call will cause Config::Auto to look for:

obscure.conf
~/obscure.conf
/etc/obscure.conf

Parameters after the first are named.

format

forces Config::Auto to interpret the contents of the configuration file in the given format without trying to guess.

path

add additional directories to the search paths. The current directory is searched first, then the paths specified with the path parameter. path can either be a scalar or a reference to an array of paths to check.

Formats

Config::Auto recognizes the following formats:

  • perl => perl code

  • colon => colon separated (e.g., key:value)

  • space => space separated (e.g., key value)

  • equal => equal separated (e.g., key=value)

  • bind => bind style (not available)

  • irssi => irssi style (not available)

  • xml => xml (via XML::Simple)

  • ini => .ini format (via Config::IniFiles)

  • list => list (e.g., ??)

TROUBLESHOOTING

When using a Perl config file, the configuration is borked

Give Config::Auto more hints (e.g., add #!/usr/bin/perl to beginning of file) or indicate the format in the parse() command.

TODO

BIND9 and irssi file format parsers currently don't exist. It would be good to add support for mutt and vim style set-based RCs.

AUTHOR

This module by Jos Boumans, kane@cpan.org.

LICENSE

This module is copyright (c) 2003 Jos Boumans <kane@cpan.org>. All rights reserved.

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