1AppConfig::File(3) User Contributed Perl Documentation AppConfig::File(3)
2
6 AppConfig::File - Perl5 module for reading configuration files.
7
9 use AppConfig::File;
10 my $state = AppConfig::State->new(\%cfg1);
12 my $cfgfile = AppConfig::File->new($state, $file);
13 $cfgfile->parse($file); # read config file
15
17 AppConfig::File is a Perl5 module which reads configuration files and
18 use the contents therein to update variable values in an AppCon‐
19 fig::State object.
20 AppConfig::File is distributed as part of the AppConfig bundle.
22
24 USING THE AppConfig::File MODULE
25 To import and use the AppConfig::File module the following line should
27 appear in your Perl script:
28 use AppConfig::File;
30 AppConfig::File is used automatically if you use the AppConfig module
32 and create an AppConfig::File object through the file() method.
33 AppConfig::File is implemented using object-oriented methods. A new
35 AppConfig::File object is created and initialised using the AppCon‐
36 fig::File->new() method. This returns a reference to a new AppCon‐
37 fig::File object. A reference to an AppConfig::State object should be
38 passed in as the first parameter:
39 my $state = AppConfig::State->new();
41 my $cfgfile = AppConfig::File->new($state);
42 This will create and return a reference to a new AppConfig::File
44 object.
45 READING CONFIGURATION FILES
47 The "parse()" method is used to read a configuration file and have the
49 contents update the STATE accordingly.
50 $cfgfile->parse($file);
52 Multiple files maye be specified and will be read in turn.
54 $cfgfile->parse($file1, $file2, $file3);
56 The method will return an undef value if it encounters any errors open‐
58 ing the files. It will return immediately without processing any fur‐
59 ther files. By default, the PEDANTIC option in the AppConfig::State
60 object, $self->{ STATE }, is turned off and any parsing errors (invalid
61 variables, unvalidated values, etc) will generated warnings, but not
62 cause the method to return. Having processed all files, the method
63 will return 1 if all files were processed without warning or 0 if one
64 or more warnings were raised. When the PEDANTIC option is turned on,
65 the method generates a warning and immediately returns a value of 0 as
66 soon as it encounters any parsing error.
67 Variables values in the configuration files may be expanded depending
69 on the value of their EXPAND option, as determined from the App::State
70 object. See AppConfig::State for more information on variable expan‐
71 sion.
72 CONFIGURATION FILE FORMAT
74 A configuration file may contain blank lines and comments which are
76 ignored. Comments begin with a '#' as the first character on a line or
77 following one or more whitespace tokens, and continue to the end of the
78 line.
79 # this is a comment
81 foo = bar # so is this
82 url = index.html#hello # this too, but not the '#welcome'
83 Notice how the '#welcome' part of the URL is not treated as a comment
85 because a whitespace character doesn't precede it.
86 Long lines can be continued onto the next line by ending the first line
88 with a '\'.
89 callsign = alpha bravo camel delta echo foxtrot golf hipowls \
91 india juliet kilo llama mike november oscar papa \
92 quebec romeo sierra tango umbrella victor whiskey \
93 x-ray yankee zebra
94 Variables that are simple flags and do not expect an argument (ARGCOUNT
96 = ARGCOUNT_NONE) can be specified without any value. They will be set
97 with the value 1, with any value explicitly specified (except "0" and
98 "off") being ignored. The variable may also be specified with a "no"
99 prefix to implicitly set the variable to 0.
100 verbose # on (1)
102 verbose = 1 # on (1)
103 verbose = 0 # off (0)
104 verbose off # off (0)
105 verbose on # on (1)
106 verbose mumble # on (1)
107 noverbose # off (0)
108 Variables that expect an argument (ARGCOUNT = ARGCOUNT_ONE) will be set
110 to whatever follows the variable name, up to the end of the current
111 line. An equals sign may be inserted between the variable and value
112 for clarity.
113 room = /home/kitchen
115 room /home/bedroom
116 Each subsequent re-definition of the variable value overwrites the pre‐
118 vious value.
119 print $config->room(); # prints "/home/bedroom"
121 Variables may be defined to accept multiple values (ARGCOUNT =
123 ARGCOUNT_LIST). Each subsequent definition of the variable adds the
124 value to the list of previously set values for the variable.
125 drink = coffee
127 drink = tea
128 A reference to a list of values is returned when the variable is
130 requested.
131 my $beverages = $config->drinks();
133 print join(", ", @$beverages); # prints "coffee, tea"
134 Variables may also be defined as hash lists (ARGCOUNT = ARGCOUNT_HASH).
136 Each subsequent definition creates a new key and value in the hash
137 array.
138 alias l="ls -CF"
140 alias h="history"
141 A reference to the hash is returned when the variable is requested.
143 my $aliases = $config->alias();
145 foreach my $k (keys %$aliases) {
146 print "$k => $aliases->{ $k }\n";
147 }
148 A large chunk of text can be defined using Perl's "heredoc" quoting
150 style.
151 scalar = <<BOUNDARY_STRING
153 line 1
154 line 2: Space/linebreaks within a HERE document are kept.
155 line 3: The last linebreak (\n) is stripped.
156 BOUNDARY_STRING
157 hash key1 = <<'FOO'
159 * Quotes (['"]) around the boundary string are simply ignored.
160 * Whether the variables in HERE document are expanded depends on
161 the EXPAND option of the variable or global setting.
162 FOO
163 hash = key2 = <<"_bar_"
165 Text within HERE document are kept as is.
166 # comments are treated as a normal text.
167 The same applies to line continuation. \
168 _bar_
169 Note that you cannot use HERE document as a key in a hash or a name of
171 a variable.
172 The '-' prefix can be used to reset a variable to its default value and
174 the '+' prefix can be used to set it to 1
175 -verbose
177 +debug
178 Variable, environment variable and tilde (home directory) expansions
180 Variable values may contain references to other AppConfig variables,
181 environment variables and/or users' home directories. These will be
182 expanded depending on the EXPAND value for each variable or the GLOBAL
183 EXPAND value.
184 Three different expansion types may be applied:
186 bin = ~/bin # expand '~' to home dir if EXPAND_UID
188 tmp = ~abw/tmp # as above, but home dir for user 'abw'
189 perl = $bin/perl # expand value of 'bin' variable if EXPAND_VAR
191 ripl = $(bin)/ripl # as above with explicit parens
192 home = ${HOME} # expand HOME environment var if EXPAND_ENV
194 See AppConfig::State for more information on expanding variable values.
196 The configuration files may have variables arranged in blocks. A block
198 header, consisting of the block name in square brackets, introduces a
199 configuration block. The block name and an underscore are then pre‐
200 fixed to the names of all variables subsequently referenced in that
201 block. The block continues until the next block definition or to the
202 end of the current file.
203 [block1]
205 foo = 10 # block1_foo = 10
206 [block2]
208 foo = 20 # block2_foo = 20
209
211 Andy Wardley, <abw@wardley.org>
212
214 $Revision: 1.62 $
215
217 Copyright (C) 1997-2003 Andy Wardley. All Rights Reserved.
218 Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
220 This module is free software; you can redistribute it and/or modify it
222 under the same terms as Perl itself.
223
225 AppConfig, AppConfig::State
226perl v5.8.8 2007-01-02 AppConfig::File(3)