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