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 my $config = Config::Auto::parse("myprogram.conf", format => "colon");
13 # Considerably more magical.
15 my $config = Config::Auto::parse("myprogram.conf");
16 # Highly magical.
18 my $config = Config::Auto::parse();
19
21 This module was written after having to write Yet Another Config File
22 Parser for some variety of colon-separated config. I decided "never
23 again".
24 When you call "Config::Auto::parse" with no arguments, we first look at
26 $0 to determine the program's name. Let's assume that's "snerk". We
27 look for the following files:
28 snerkconfig
30 ~/snerkconfig
31 /etc/snerkconfig
32 /usr/local/etc/snerkconfig
33 snerk.config
34 ~/snerk.config
35 /etc/snerk.config
36 /usr/local/etc/snerk.config
37 snerkrc
38 ~/snerkrc
39 /etc/snerkrc
40 /usr/local/etc/snerkrc
41 .snerkrc
42 ~/.snerkrc
43 /etc/.snerkrc
44 /usr/local/etc/.snerkrc
45 Additional search paths can be specified with the "paths" option.
47 We take the first one we find, and examine it to determine what format
49 it's in. The algorithm used is a heuristic "which is a fancy way of
50 saying that it doesn't work." (Mark Dominus.) We know about colon
51 separated, space separated, equals separated, XML, Perl code, Windows
52 INI, BIND9 and irssi style config files. If it chooses the wrong one,
53 you can force it with the "format" option.
54 If you don't want it ever to detect and execute config files which are
56 made up of Perl code, set "$Config::Auto::DisablePerl = 1".
57 When using the perl format, your configuration file will be eval'd.
59 This will cause taint errors. To avoid these warnings, set
60 "$Config::Auto::Untaint = 1".
61 When using the perl format, your configuration file will be eval'd
63 using do(file). This will cause taint errors if the filename is not
64 untainted. To avoid these warnings, set "$Config::Auto::Untaint = 1".
65 This setting will not untaint the data in your configuration file and
66 should only be used if you trust the source of the filename.
67 Then the file is parsed and a data structure is returned. Since we're
69 working magic, we have to do the best we can under the circumstances -
70 "You rush a miracle man, you get rotten miracles." (Miracle Max) So
71 there are no guarantees about the structure that's returned. If you
72 have a fairly regular config file format, you'll get a regular data
73 structure back. If your config file is confusing, so will the return
74 structure be. Isn't life tragic?
75 Here's what we make of some common Unix config files:
77 /etc/resolv.conf:
79 $VAR1 = {
81 'nameserver' => [ '163.1.2.1', '129.67.1.1', '129.67.1.180' ],
82 'search' => [ 'oucs.ox.ac.uk', 'ox.ac.uk' ]
83 };
84 /etc/passwd:
86 $VAR1 = {
88 'root' => [ 'x', '0', '0', 'root', '/root', '/bin/bash' ],
89 ...
90 };
91 /etc/gpm.conf:
93 $VAR1 = {
95 'append' => '""',
96 'responsiveness' => '',
97 'device' => '/dev/psaux',
98 'type' => 'ps2',
99 'repeat_type' => 'ms3'
100 };
101 /etc/nsswitch.conf:
103 $VAR1 = {
105 'netgroup' => 'nis',
106 'passwd' => 'compat',
107 'hosts' => [ 'files', 'dns' ],
108 ...
109 };
110
112 Although "Config::Auto" is at its most magical when called with no
113 parameters, its behavior can be reined in by use of one or two
114 arguments.
115 If a filename is passed as the first argument to "parse", the same
117 paths are checked, but "Config::Auto" will look for a file with the
118 passed name instead of the $0-based names.
119 use Config::Auto;
121 my $config = Config::Auto::parse("obscure.conf");
123 The above call will cause "Config::Auto" to look for:
125 obscure.conf
127 ~/obscure.conf
128 /etc/obscure.conf
129 Parameters after the first are named.
131 "format"
133 forces "Config::Auto" to interpret the contents of the configuration
134 file in the given format without trying to guess.
135 "path"
137 add additional directories to the search paths. The current directory
138 is searched first, then the paths specified with the path parameter.
139 "path" can either be a scalar or a reference to an array of paths to
140 check.
141 Formats
143 "Config::Auto" recognizes the following formats:
144 · perl => perl code
146 · colon => colon separated (e.g., key:value)
148 · space => space separated (e.g., key value)
150 · equal => equal separated (e.g., key=value)
152 · bind => bind style (not available)
154 · irssi => irssi style (not available)
156 · xml => xml (via XML::Simple)
158 · ini => .ini format (via Config::IniFiles)
160 · list => list (e.g., ??)
162 · yaml => yaml (via YAML.pm)
164
166 When using a Perl config file, the configuration is borked
167 Give "Config::Auto" more hints (e.g., add #!/usr/bin/perl to
168 beginning of file) or indicate the format in the parse() command.
169
171 BIND9 and irssi file format parsers currently don't exist. It would be
172 good to add support for "mutt" and "vim" style "set"-based RCs.
173
175 Please report bugs or other issues to <bug-config-auto@rt.cpan.org>.
176
178 This module by Jos Boumans <kane@cpan.org>.
179
181 This library is free software; you may redistribute and/or modify it
182 under the same terms as Perl itself.
183perl v5.12.0 2007-04-07 Config::Auto(3)