NAME¶

Config::Auto - Magical config file parser

SYNOPSIS¶

    use Config::Auto;
    ### Not very magical at all.
    $config = Config::Auto::parse("myprogram.conf", format => "colon");
    ### Considerably more magical.
    $config = Config::Auto::parse("myprogram.conf");
    ### Highly magical.
    $config = Config::Auto::parse();
    ### Using the OO interface
    $ca     = Config::Auto->new( source => $text );
    $ca     = Config::Auto->new( source => $fh );
    $ca     = Config::Auto->new( source => $filename );
    $href   = $ca->score;           # compute the score for various formats
    $config = $ca->parse;           # parse the config
    $format = $ca->format;          # detected (or provided) config format
    $str    = $ca->as_string;       # config file stringified
    $fh     = $ca->fh;              # config file handle
    $file   = $ca->file;            # config filename
    $aref   = $ca->data;            # data from your config, split by newlines

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

Config::Auto aims to be the most "DWIM" config parser available, by detecting configuration styles, include paths and even config filenames automagically.

See the "HOW IT WORKS" section below on implementation details.

ACCESSORS¶

METHODS¶

GLOBAL VARIABLES¶

$DisablePerl

Set this variable to true if you do not wish to "eval" perl style configuration files.

Default is "false"

$Untaint

Set this variable to true if you automatically want to untaint values obtained from a perl style configuration. See "perldoc perlsec" for details on tainting.

Default is "false"

$Debug

Set this variable to true to get extra debug information from "Config::Auto" when finding and/or parsing config files fails.

Default is "false"

HOW IT WORKS¶

When you call "Config::Auto->new" or "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 "path" 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". 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?

EXAMPLES¶

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' ],
        ...
    };

MEMORY USAGE¶

This module is as light as possible on memory, only using modules when they are absolutely needed for configuration file parsing.

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 "new"/"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.

BUG REPORTS¶

Please report bugs or other issues to <bug-config-auto@rt.cpan.org>.

AUTHOR¶

Versions 0.04 and higher of this module by Jos Boumans <kane@cpan.org>.

This module originally by Simon Cozens.

COPYRIGHT¶

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