1Config::Auto(3) User Contributed Perl Documentation Config::Auto(3)
2
6 Config::Auto - Magical config file parser
7
9 use Config::Auto;
10 ### Not very magical at all.
12 $config = Config::Auto::parse("myprogram.conf", format => "colon");
13 ### Considerably more magical.
15 $config = Config::Auto::parse("myprogram.conf");
16 ### Highly magical.
18 $config = Config::Auto::parse();
19 ### 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 $href = $ca->score; # compute the score for various formats
26 $config = $ca->parse; # parse the config
28 $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
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 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 See the "HOW IT WORKS" section below on implementation details.
45
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 "Config::Auto" recognizes the following formats:
52 • perl => perl code
54 • colon => colon separated (e.g., key:value)
56 • space => space separated (e.g., key value)
58 • equal => equal separated (e.g., key=value)
60 • bind => bind style (not available)
62 • irssi => irssi style (not available)
64 • xml => xml (via XML::Simple)
66 • ini => .ini format (via Config::IniFiles)
68 • list => list (e.g., foo bar baz)
70 • yaml => yaml (via YAML.pm)
72
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 a filehandle
80 Any opened filehandle, or "IO::Handle"/"IO::String" object.
81 a plain text string
83 Any plain string containing one or more newlines.
84 a filename
86 Any plain string pointing to a file on disk
87 nothing
89 A heuristic will be applied to find your config file, based on the
90 name of your script; $0.
91 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 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 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 The "format" parameters forces "Config::Auto" to interpret the contents
106 of the configuration file in the given format without trying to guess.
107 $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 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 $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 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 $aref = $obj->data;
129 Returns an array ref of your configuration data, split by newlines.
130 $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 $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 $str = $obj->as_string;
142 Returns a string representation of your configuration data.
143
145 $DisablePerl
146 Set this variable to true if you do not wish to "eval" perl style
148 configuration files.
149 Default is "false"
151 $Untaint
153 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 Default is "false"
159 $Debug
161 Set this variable to true to get extra debug information from
163 "Config::Auto" when finding and/or parsing config files fails.
164 Default is "false"
166
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 snerkconfig
173 ~/snerkconfig
174 /etc/snerkconfig
175 /usr/local/etc/snerkconfig
176 snerk.config
178 ~/snerk.config
179 /etc/snerk.config
180 /usr/local/etc/snerk.config
181 snerkrc
183 ~/snerkrc
184 /etc/snerkrc
185 /usr/local/etc/snerkrc
186 .snerkrc
188 ~/.snerkrc
189 /etc/.snerkrc
190 /usr/local/etc/.snerkrc
191 Additional search paths can be specified with the "path" option.
193 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 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 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 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
219 Here's what we make of some common Unix config files:
220 /etc/resolv.conf:
222 $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 /etc/passwd:
229 $VAR1 = {
231 'root' => [ 'x', '0', '0', 'root', '/root', '/bin/bash' ],
232 ...
233 };
234 /etc/gpm.conf:
236 $VAR1 = {
238 'append' => '""',
239 'responsiveness' => '',
240 'device' => '/dev/psaux',
241 'type' => 'ps2',
242 'repeat_type' => 'ms3'
243 };
244 /etc/nsswitch.conf:
246 $VAR1 = {
248 'netgroup' => 'nis',
249 'passwd' => 'compat',
250 'hosts' => [ 'files', 'dns' ],
251 ...
252 };
253
255 This module is as light as possible on memory, only using modules when
256 they are absolutely needed for configuration file parsing.
257
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
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
269 Please report bugs or other issues to <bug-config-auto@rt.cpan.org>.
270
272 Versions 0.04 and higher of this module by Jos Boumans <kane@cpan.org>.
273 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.
279perl v5.36.0 2023-01-20 Config::Auto(3)