1AppConfig::File(3)    User Contributed Perl Documentation   AppConfig::File(3)
2
3
4

NAME

6       AppConfig::File - Perl5 module for reading configuration files.
7

SYNOPSIS

9           use AppConfig::File;
10
11           my $state   = AppConfig::State->new(\%cfg1);
12           my $cfgfile = AppConfig::File->new($state, $file);
13
14           $cfgfile->parse($file);            # read config file
15

OVERVIEW

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
21       AppConfig::File is distributed as part of the AppConfig bundle.
22

DESCRIPTION

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
28           use AppConfig::File;
29
30       AppConfig::File is used automatically if you use the AppConfig module
31       and create an AppConfig::File object through the file() method.
32
33       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
39           my $state   = AppConfig::State->new();
40           my $cfgfile = AppConfig::File->new($state);
41
42       This will create and return a reference to a new AppConfig::File
43       object.
44
45   READING CONFIGURATION FILES
46       The parse() method is used to read a configuration file and have the
47       contents update the STATE accordingly.
48
49           $cfgfile->parse($file);
50
51       Multiple files maye be specified and will be read in turn.
52
53           $cfgfile->parse($file1, $file2, $file3);
54
55       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
66       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
71   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
77           # this is a comment
78           foo = bar               # so is this
79           url = index.html#hello  # this too, but not the '#welcome'
80
81       Notice how the '#welcome' part of the URL is not treated as a comment
82       because a whitespace character doesn't precede it.
83
84       Long lines can be continued onto the next line by ending the first line
85       with a '\'.
86
87           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
92       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
98           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
106       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
111           room = /home/kitchen
112           room   /home/bedroom
113
114       Each subsequent re-definition of the variable value overwrites the
115       previous value.
116
117           print $config->room();               # prints "/home/bedroom"
118
119       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
123           drink = coffee
124           drink = tea
125
126       A reference to a list of values is returned when the variable is
127       requested.
128
129           my $beverages = $config->drinks();
130           print join(", ", @$beverages);      # prints "coffee, tea"
131
132       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
136           alias l="ls -CF"
137           alias h="history"
138
139       A reference to the hash is returned when the variable is requested.
140
141           my $aliases = $config->alias();
142           foreach my $k (keys %$aliases) {
143               print "$k => $aliases->{ $k }\n";
144           }
145
146       A large chunk of text can be defined using Perl's "heredoc" quoting
147       style.
148
149          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
155          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
161          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
167       Note that you cannot use HERE document as a key in a hash or a name of
168       a variable.
169
170       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
173           -verbose
174           +debug
175
176       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
182       Three different expansion types may be applied:
183
184           bin = ~/bin          # expand '~' to home dir if EXPAND_UID
185           tmp = ~abw/tmp       # as above, but home dir for user 'abw'
186
187           perl = $bin/perl     # expand value of 'bin' variable if EXPAND_VAR
188           ripl = $(bin)/ripl   # as above with explicit parens
189
190           home = ${HOME}       # expand HOME environment var if EXPAND_ENV
191
192       See AppConfig::State for more information on expanding variable values.
193
194       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
201           [block1]
202           foo = 10             # block1_foo = 10
203
204           [block2]
205           foo = 20             # block2_foo = 20
206

AUTHOR

208       Andy Wardley, <abw@wardley.org>
209
211       Copyright (C) 1997-2007 Andy Wardley.  All Rights Reserved.
212
213       This module is free software; you can redistribute it and/or modify it
214       under the same terms as Perl itself.
215

SEE ALSO

217       AppConfig, AppConfig::State
218
219
220
221perl v5.38.0                      2023-07-20                AppConfig::File(3)
Impressum