


Config::Auto(3pUser Contributed Perl DocumentatioConfig::Auto(3p)


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.



perl v5.12.2                2007-04-07                          1





Config::Auto(3pUser Contributed Perl DocumentatioConfig::Auto(3p)


       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



perl v5.12.2                2007-04-07                          2





Config::Auto(3pUser Contributed Perl DocumentatioConfig::Auto(3p)


       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:

       o   perl    => perl code

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

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

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

       o   bind    => bind style (not available)

       o   irssi   => irssi style (not available)

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

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

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

       o   yaml    => yaml (via YAML.pm)

TROUBLESHOOTING




perl v5.12.2                2007-04-07                          3





Config::Auto(3pUser Contributed Perl DocumentatioConfig::Auto(3p)


       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.

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

AUTHOR
       This module by Jos Boumans <kane@cpan.org>.

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








































perl v5.12.2                2007-04-07                          4


