.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Config::Auto 3pm"
.TH Config::Auto 3pm "2022-06-11" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Config::Auto \- Magical config file parser
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module was written after having to write Yet Another Config File Parser
for some variety of colon-separated config. I decided \*(L"never again\*(R".
.PP
Config::Auto aims to be the most \f(CW\*(C`DWIM\*(C'\fR config parser available, by detecting
configuration styles, include paths and even config filenames automagically.
.PP
See the \*(L"\s-1HOW IT WORKS\*(R"\s0 section below on implementation details.
.SH "ACCESSORS"
.IX Header "ACCESSORS"
.ie n .SS "@formats = Config::Auto\->formats"
.el .SS "\f(CW@formats\fP = Config::Auto\->formats"
.IX Subsection "@formats = Config::Auto->formats"
Returns a list of supported formats for your config files. These formats
are also the keys as used by the \f(CW\*(C`score()\*(C'\fR method.
.PP
\&\f(CW\*(C`Config::Auto\*(C'\fR recognizes the following formats:
.IP "\(bu" 4
perl    => perl code
.IP "\(bu" 4
colon   => colon separated (e.g., key:value)
.IP "\(bu" 4
space   => space separated (e.g., key value)
.IP "\(bu" 4
equal   => equal separated (e.g., key=value)
.IP "\(bu" 4
bind    => bind style (not available)
.IP "\(bu" 4
irssi   => irssi style (not available)
.IP "\(bu" 4
xml     => xml (via XML::Simple)
.IP "\(bu" 4
ini     => .ini format (via Config::IniFiles)
.IP "\(bu" 4
list    => list (e.g., foo bar baz)
.IP "\(bu" 4
yaml    => yaml (via \s-1YAML\s0.pm)
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$obj = Config::Auto\->new( [source => $text|$fh|$filename, path => \e@paths, format => \s-1FORMAT_NAME\s0] );"
.el .SS "\f(CW$obj\fP = Config::Auto\->new( [source => \f(CW$text\fP|$fh|$filename, path => \e@paths, format => \s-1FORMAT_NAME\s0] );"
.IX Subsection "$obj = Config::Auto->new( [source => $text|$fh|$filename, path => @paths, format => FORMAT_NAME] );"
Returns a \f(CW\*(C`Config::Auto\*(C'\fR object based on your configs source. This can either be:
.IP "a filehandle" 4
.IX Item "a filehandle"
Any opened filehandle, or \f(CW\*(C`IO::Handle\*(C'\fR/\f(CW\*(C`IO::String\*(C'\fR object.
.IP "a plain text string" 4
.IX Item "a plain text string"
Any plain string containing one or more newlines.
.IP "a filename" 4
.IX Item "a filename"
Any plain string pointing to a file on disk
.IP "nothing" 4
.IX Item "nothing"
A heuristic will be applied to find your config file, based on the name of
your script; \f(CW$0\fR.
.PP
Although \f(CW\*(C`Config::Auto\*(C'\fR is at its most magical when called with no parameters,
its behavior can be controlled explicitly by using one or two arguments.
.PP
If a filename is passed as the \f(CW\*(C`source\*(C'\fR argument, the same paths are checked,
but \f(CW\*(C`Config::Auto\*(C'\fR will look for a file with the passed name instead of the
\&\f(CW$0\fR\-based names.
.PP
Supplying the \f(CW\*(C`path\*(C'\fR parameter will add additional directories to the search
paths. The current directory is searched first, then the paths specified with
the path parameter. \f(CW\*(C`path\*(C'\fR can either be a scalar or a reference to an array
of paths to check.
.PP
The \f(CW\*(C`format\*(C'\fR parameters forces \f(CW\*(C`Config::Auto\*(C'\fR to interpret the contents of
the configuration file in the given format without trying to guess.
.ie n .SS "$rv = $obj\->parse | Config::Auto::parse( [$text|$fh|$filename, path => \e@paths, format => \s-1FORMAT_NAME\s0] );"
.el .SS "\f(CW$rv\fP = \f(CW$obj\fP\->parse | Config::Auto::parse( [$text|$fh|$filename, path => \e@paths, format => \s-1FORMAT_NAME\s0] );"
.IX Subsection "$rv = $obj->parse | Config::Auto::parse( [$text|$fh|$filename, path => @paths, format => FORMAT_NAME] );"
Parses the source you provided in the \f(CW\*(C`new()\*(C'\fR call and returns a data
structure representing your configuration file.
.PP
You can also call it in a procedural context (\f(CW\*(C`Config::Auto::parse()\*(C'\fR), 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.
.ie n .SS "$href = $obj\->score;"
.el .SS "\f(CW$href\fP = \f(CW$obj\fP\->score;"
.IX Subsection "$href = $obj->score;"
Takes a look at the contents of your configuration data and produces a
\&'score' determining which format it most likely contains.
.PP
They keys are equal to formats as returned by the \f(CW\*(C`Config::Auto\->formats\*(C'\fR
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
\&\f(CW\*(C`format\*(C'\fR option explicitly to the \f(CW\*(C`new()\*(C'\fR method.
.ie n .SS "$aref = $obj\->data;"
.el .SS "\f(CW$aref\fP = \f(CW$obj\fP\->data;"
.IX Subsection "$aref = $obj->data;"
Returns an array ref of your configuration data, split by newlines.
.ie n .SS "$fh = $obj\->fh;"
.el .SS "\f(CW$fh\fP = \f(CW$obj\fP\->fh;"
.IX Subsection "$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.
.ie n .SS "$filename = $obj\->file;"
.el .SS "\f(CW$filename\fP = \f(CW$obj\fP\->file;"
.IX Subsection "$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.
.ie n .SS "$str = $obj\->as_string;"
.el .SS "\f(CW$str\fP = \f(CW$obj\fP\->as_string;"
.IX Subsection "$str = $obj->as_string;"
Returns a string representation of your configuration data.
.SH "GLOBAL VARIABLES"
.IX Header "GLOBAL VARIABLES"
\fI\f(CI$DisablePerl\fI\fR
.IX Subsection "$DisablePerl"
.PP
Set this variable to true if you do not wish to \f(CW\*(C`eval\*(C'\fR perl style configuration
files.
.PP
Default is \f(CW\*(C`false\*(C'\fR
.PP
\fI\f(CI$Untaint\fI\fR
.IX Subsection "$Untaint"
.PP
Set this variable to true if you automatically want to untaint values obtained
from a perl style configuration. See \*(L"perldoc perlsec\*(R" for details on tainting.
.PP
Default is \f(CW\*(C`false\*(C'\fR
.PP
\fI\f(CI$Debug\fI\fR
.IX Subsection "$Debug"
.PP
Set this variable to true to get extra debug information from \f(CW\*(C`Config::Auto\*(C'\fR
when finding and/or parsing config files fails.
.PP
Default is \f(CW\*(C`false\*(C'\fR
.SH "HOW IT WORKS"
.IX Header "HOW IT WORKS"
When you call \f(CW\*(C`Config::Auto\->new\*(C'\fR or \f(CW\*(C`Config::Auto::parse\*(C'\fR with no
arguments, we first look at \f(CW$0\fR to determine the program's name. Let's
assume that's \f(CW\*(C`snerk\*(C'\fR. We look for the following files:
.PP
.Vb 4
\&    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
.Ve
.PP
Additional search paths can be specified with the \f(CW\*(C`path\*(C'\fR option.
.PP
We take the first one we find, and examine it to determine what format
it's in. The algorithm used is a heuristic \*(L"which is a fancy way of
saying that it doesn't work.\*(R" (Mark Dominus.) We know about colon
separated, space separated, equals separated, \s-1XML,\s0 Perl code, Windows
\&\s-1INI, BIND9\s0 and irssi style config files. If it chooses the wrong one,
you can force it with the \f(CW\*(C`format\*(C'\fR option.
.PP
If you don't want it ever to detect and execute config files which are made
up of Perl code, set \f(CW\*(C`$Config::Auto::DisablePerl = 1\*(C'\fR.
.PP
When using the perl format, your configuration file will be eval'd. This will
cause taint errors. To avoid these warnings, set \f(CW\*(C`$Config::Auto::Untaint = 1\*(C'\fR.
This setting will not untaint the data in your configuration file and should only
be used if you trust the source of the filename.
.PP
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 \-
\&\*(L"You rush a miracle man, you get rotten miracles.\*(R" (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?
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Here's what we make of some common Unix config files:
.PP
\&\fI/etc/resolv.conf\fR:
.PP
.Vb 4
\&    $VAR1 = {
\&        \*(Aqnameserver\*(Aq => [ \*(Aq163.1.2.1\*(Aq, \*(Aq129.67.1.1\*(Aq, \*(Aq129.67.1.180\*(Aq ],
\&        \*(Aqsearch\*(Aq => [ \*(Aqoucs.ox.ac.uk\*(Aq, \*(Aqox.ac.uk\*(Aq ]
\&    };
.Ve
.PP
\&\fI/etc/passwd\fR:
.PP
.Vb 4
\&    $VAR1 = {
\&        \*(Aqroot\*(Aq => [ \*(Aqx\*(Aq, \*(Aq0\*(Aq, \*(Aq0\*(Aq, \*(Aqroot\*(Aq, \*(Aq/root\*(Aq, \*(Aq/bin/bash\*(Aq ],
\&        ...
\&    };
.Ve
.PP
\&\fI/etc/gpm.conf\fR:
.PP
.Vb 7
\&    $VAR1 = {
\&        \*(Aqappend\*(Aq => \*(Aq""\*(Aq,
\&        \*(Aqresponsiveness\*(Aq => \*(Aq\*(Aq,
\&        \*(Aqdevice\*(Aq => \*(Aq/dev/psaux\*(Aq,
\&        \*(Aqtype\*(Aq => \*(Aqps2\*(Aq,
\&        \*(Aqrepeat_type\*(Aq => \*(Aqms3\*(Aq
\&    };
.Ve
.PP
\&\fI/etc/nsswitch.conf\fR:
.PP
.Vb 6
\&    $VAR1 = {
\&        \*(Aqnetgroup\*(Aq => \*(Aqnis\*(Aq,
\&        \*(Aqpasswd\*(Aq => \*(Aqcompat\*(Aq,
\&        \*(Aqhosts\*(Aq => [ \*(Aqfiles\*(Aq, \*(Aqdns\*(Aq ],
\&        ...
\&    };
.Ve
.SH "MEMORY USAGE"
.IX Header "MEMORY USAGE"
This module is as light as possible on memory, only using modules when they
are absolutely needed for configuration file parsing.
.SH "TROUBLESHOOTING"
.IX Header "TROUBLESHOOTING"
.IP "When using a Perl config file, the configuration is borked" 4
.IX Item "When using a Perl config file, the configuration is borked"
Give \f(CW\*(C`Config::Auto\*(C'\fR more hints (e.g., add #!/usr/bin/perl to beginning of
file) or indicate the format in the \f(CW\*(C`new\*(C'\fR/\f(CW\*(C`parse()\*(C'\fR command.
.SH "TODO"
.IX Header "TODO"
\&\s-1BIND9\s0 and irssi file format parsers currently don't exist. It would be
good to add support for \f(CW\*(C`mutt\*(C'\fR and \f(CW\*(C`vim\*(C'\fR style \f(CW\*(C`set\*(C'\fR\-based RCs.
.SH "BUG REPORTS"
.IX Header "BUG REPORTS"
Please report bugs or other issues to <bug\-config\-auto@rt.cpan.org>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Versions 0.04 and higher of this module by Jos Boumans <kane@cpan.org>.
.PP
This module originally by Simon Cozens.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This library is free software; you may redistribute and/or modify it
under the same terms as Perl itself.