1Config::Auto(3)       User Contributed Perl Documentation      Config::Auto(3)
2
3
4

NAME

6       Config::Auto - Magical config file parser
7

SYNOPSIS

9           use Config::Auto;
10
11           ### Not very magical at all.
12           $config = Config::Auto::parse("myprogram.conf", format => "colon");
13
14           ### Considerably more magical.
15           $config = Config::Auto::parse("myprogram.conf");
16
17           ### Highly magical.
18           $config = Config::Auto::parse();
19
20           ### Using the OO interface
21           $ca     = Config::Auto->new( source => $text );
22           $ca     = Config::Auto->new( source => $fh );
23           $ca     = Config::Auto->new( source => $filename );
24
25           $href   = $ca->score;           # compute the score for various formats
26
27           $config = $ca->parse;           # parse the config
28
29           $format = $ca->format;          # detected (or provided) config format
30           $str    = $ca->as_string;       # config file stringified
31           $fh     = $ca->fh;              # config file handle
32           $file   = $ca->file;            # config filename
33           $aref   = $ca->data;            # data from your config, split by newlines
34

DESCRIPTION

36       This module was written after having to write Yet Another Config File
37       Parser for some variety of colon-separated config. I decided "never
38       again".
39
40       Config::Auto aims to be the most "DWIM" config parser available, by
41       detecting configuration styles, include paths and even config filenames
42       automagically.
43
44       See the "HOW IT WORKS" section below on implementation details.
45

ACCESSORS

47   @formats = Config::Auto->formats
48       Returns a list of supported formats for your config files. These
49       formats are also the keys as used by the "score()" method.
50
51       "Config::Auto" recognizes the following formats:
52
53       •   perl    => perl code
54
55       •   colon   => colon separated (e.g., key:value)
56
57       •   space   => space separated (e.g., key value)
58
59       •   equal   => equal separated (e.g., key=value)
60
61       •   bind    => bind style (not available)
62
63       •   irssi   => irssi style (not available)
64
65       •   xml     => xml (via XML::Simple)
66
67       •   ini     => .ini format (via Config::IniFiles)
68
69       •   list    => list (e.g., foo bar baz)
70
71       •   yaml    => yaml (via YAML.pm)
72

METHODS

74   $obj = Config::Auto->new( [source => $text|$fh|$filename, path => \@paths,
75       format => FORMAT_NAME] );
76       Returns a "Config::Auto" object based on your configs source. This can
77       either be:
78
79       a filehandle
80           Any opened filehandle, or "IO::Handle"/"IO::String" object.
81
82       a plain text string
83           Any plain string containing one or more newlines.
84
85       a filename
86           Any plain string pointing to a file on disk
87
88       nothing
89           A heuristic will be applied to find your config file, based on the
90           name of your script; $0.
91
92       Although "Config::Auto" is at its most magical when called with no
93       parameters, its behavior can be controlled explicitly by using one or
94       two arguments.
95
96       If a filename is passed as the "source" argument, the same paths are
97       checked, but "Config::Auto" will look for a file with the passed name
98       instead of the $0-based names.
99
100       Supplying the "path" parameter will add additional directories to the
101       search paths. The current directory is searched first, then the paths
102       specified with the path parameter. "path" can either be a scalar or a
103       reference to an array of paths to check.
104
105       The "format" parameters forces "Config::Auto" to interpret the contents
106       of the configuration file in the given format without trying to guess.
107
108   $rv = $obj->parse | Config::Auto::parse( [$text|$fh|$filename, path =>
109       \@paths, format => FORMAT_NAME] );
110       Parses the source you provided in the "new()" call and returns a data
111       structure representing your configuration file.
112
113       You can also call it in a procedural context ("Config::Auto::parse()"),
114       where the first argument is the source, and the following arguments are
115       named. This function is provided for backwards compatiblity with
116       releases prior to 0.29.
117
118   $href = $obj->score;
119       Takes a look at the contents of your configuration data and produces a
120       'score' determining which format it most likely contains.
121
122       They keys are equal to formats as returned by the
123       "Config::Auto->formats" and their values are a score between 1 and 100.
124       The format with the highest score will be used to parse your
125       configuration data, unless you provided the "format" option explicitly
126       to the "new()" method.
127
128   $aref = $obj->data;
129       Returns an array ref of your configuration data, split by newlines.
130
131   $fh = $obj->fh;
132       Returns a filehandle, opened for reading, containing your configuration
133       data. This works even if you provided a plain text string or filename
134       to parse.
135
136   $filename = $obj->file;
137       Returns a filename containing your configuration data. This works even
138       if you provided a plaintext string or filehandle to parse. In that
139       case, a temporary file will be written holding your configuration data.
140
141   $str = $obj->as_string;
142       Returns a string representation of your configuration data.
143

GLOBAL VARIABLES

145       $DisablePerl
146
147       Set this variable to true if you do not wish to "eval" perl style
148       configuration files.
149
150       Default is "false"
151
152       $Untaint
153
154       Set this variable to true if you automatically want to untaint values
155       obtained from a perl style configuration. See "perldoc perlsec" for
156       details on tainting.
157
158       Default is "false"
159
160       $Debug
161
162       Set this variable to true to get extra debug information from
163       "Config::Auto" when finding and/or parsing config files fails.
164
165       Default is "false"
166

HOW IT WORKS

168       When you call "Config::Auto->new" or "Config::Auto::parse" with no
169       arguments, we first look at $0 to determine the program's name. Let's
170       assume that's "snerk". We look for the following files:
171
172           snerkconfig
173           ~/snerkconfig
174           /etc/snerkconfig
175           /usr/local/etc/snerkconfig
176
177           snerk.config
178           ~/snerk.config
179           /etc/snerk.config
180           /usr/local/etc/snerk.config
181
182           snerkrc
183           ~/snerkrc
184           /etc/snerkrc
185           /usr/local/etc/snerkrc
186
187           .snerkrc
188           ~/.snerkrc
189           /etc/.snerkrc
190           /usr/local/etc/.snerkrc
191
192       Additional search paths can be specified with the "path" option.
193
194       We take the first one we find, and examine it to determine what format
195       it's in. The algorithm used is a heuristic "which is a fancy way of
196       saying that it doesn't work." (Mark Dominus.) We know about colon
197       separated, space separated, equals separated, XML, Perl code, Windows
198       INI, BIND9 and irssi style config files. If it chooses the wrong one,
199       you can force it with the "format" option.
200
201       If you don't want it ever to detect and execute config files which are
202       made up of Perl code, set "$Config::Auto::DisablePerl = 1".
203
204       When using the perl format, your configuration file will be eval'd.
205       This will cause taint errors. To avoid these warnings, set
206       "$Config::Auto::Untaint = 1".  This setting will not untaint the data
207       in your configuration file and should only be used if you trust the
208       source of the filename.
209
210       Then the file is parsed and a data structure is returned. Since we're
211       working magic, we have to do the best we can under the circumstances -
212       "You rush a miracle man, you get rotten miracles." (Miracle Max) So
213       there are no guarantees about the structure that's returned. If you
214       have a fairly regular config file format, you'll get a regular data
215       structure back. If your config file is confusing, so will the return
216       structure be. Isn't life tragic?
217

EXAMPLES

219       Here's what we make of some common Unix config files:
220
221       /etc/resolv.conf:
222
223           $VAR1 = {
224               'nameserver' => [ '163.1.2.1', '129.67.1.1', '129.67.1.180' ],
225               'search' => [ 'oucs.ox.ac.uk', 'ox.ac.uk' ]
226           };
227
228       /etc/passwd:
229
230           $VAR1 = {
231               'root' => [ 'x', '0', '0', 'root', '/root', '/bin/bash' ],
232               ...
233           };
234
235       /etc/gpm.conf:
236
237           $VAR1 = {
238               'append' => '""',
239               'responsiveness' => '',
240               'device' => '/dev/psaux',
241               'type' => 'ps2',
242               'repeat_type' => 'ms3'
243           };
244
245       /etc/nsswitch.conf:
246
247           $VAR1 = {
248               'netgroup' => 'nis',
249               'passwd' => 'compat',
250               'hosts' => [ 'files', 'dns' ],
251               ...
252           };
253

MEMORY USAGE

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

TROUBLESHOOTING

259       When using a Perl config file, the configuration is borked
260           Give "Config::Auto" more hints (e.g., add #!/usr/bin/perl to
261           beginning of file) or indicate the format in the "new"/"parse()"
262           command.
263

TODO

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

BUG REPORTS

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

AUTHOR

272       Versions 0.04 and higher of this module by Jos Boumans <kane@cpan.org>.
273
274       This module originally by Simon Cozens.
275
277       This library is free software; you may redistribute and/or modify it
278       under the same terms as Perl itself.
279
280
281
282perl v5.34.0                      2022-01-21                   Config::Auto(3)
Impressum