Provided by: libconfig-auto-perl_0.44-2_all bug

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

   @formats = Config::Auto->formats
       Returns a list of supported formats for your config files. These formats are also the keys
       as used by the "score()" method.

       "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., foo bar baz)

       •   yaml    => yaml (via YAML.pm)

METHODS

   $obj = Config::Auto->new( [source => $text|$fh|$filename, path => \@paths, format =>
       FORMAT_NAME] );
       Returns a "Config::Auto" object based on your configs source. This can either be:

       a filehandle
           Any opened filehandle, or "IO::Handle"/"IO::String" object.

       a plain text string
           Any plain string containing one or more newlines.

       a filename
           Any plain string pointing to a file on disk

       nothing
           A heuristic will be applied to find your config file, based on the name of your
           script; $0.

       Although "Config::Auto" is at its most magical when called with no parameters, its
       behavior can be controlled explicitly by using one or two arguments.

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

       Supplying the "path" parameter will 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.

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

   $rv = $obj->parse | Config::Auto::parse( [$text|$fh|$filename, path => \@paths, format =>
       FORMAT_NAME] );
       Parses the source you provided in the "new()" call and returns a data structure
       representing your configuration file.

       You can also call it in a procedural context ("Config::Auto::parse()"), where the first
       argument is the source, and the following arguments are named. This function is provided
       for backwards compatiblity with releases prior to 0.29.

   $href = $obj->score;
       Takes a look at the contents of your configuration data and produces a 'score' determining
       which format it most likely contains.

       They keys are equal to formats as returned by the "Config::Auto->formats" and their values
       are a score between 1 and 100. The format with the highest score will be used to parse
       your configuration data, unless you provided the "format" option explicitly to the "new()"
       method.

   $aref = $obj->data;
       Returns an array ref of your configuration data, split by newlines.

   $fh = $obj->fh;
       Returns a filehandle, opened for reading, containing your configuration data. This works
       even if you provided a plain text string or filename to parse.

   $filename = $obj->file;
       Returns a filename containing your configuration data. This works even if you provided a
       plaintext string or filehandle to parse. In that case, a temporary file will be written
       holding your configuration data.

   $str = $obj->as_string;
       Returns a string representation of your configuration data.

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.