local-lib5/man/man3/AppConfig::File.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "AppConfig::File 3"
 132 .TH AppConfig::File 3 "2007-05-30" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 AppConfig::File \- Perl5 module for reading configuration files.
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use AppConfig::File;
 139 .Ve
 140 .PP
 141 .Vb 2
 142 \&    my $state   = AppConfig::State\->new(\e%cfg1);
 143 \&    my $cfgfile = AppConfig::File\->new($state, $file);
 144 .Ve
 145 .PP
 146 .Vb 1
 147 \&    $cfgfile\->parse($file);            # read config file
 148 .Ve
 149 .SH "OVERVIEW"
 150 .IX Header "OVERVIEW"
 151 AppConfig::File is a Perl5 module which reads configuration files and use
 152 the contents therein to update variable values in an AppConfig::State
 153 object.
 154 .PP
 155 AppConfig::File is distributed as part of the AppConfig bundle.
 156 .SH "DESCRIPTION"
 157 .IX Header "DESCRIPTION"
 158 .Sh "\s-1USING\s0 \s-1THE\s0 AppConfig::File \s-1MODULE\s0"
 159 .IX Subsection "USING THE AppConfig::File MODULE"
 160 To import and use the AppConfig::File module the following line should appear
 161 in your Perl script:
 162 .PP
 163 .Vb 1
 164 \&    use AppConfig::File;
 165 .Ve
 166 .PP
 167 AppConfig::File is used automatically if you use the AppConfig module
 168 and create an AppConfig::File object through the \fIfile()\fR method.
 169 .PP
 170 AppConfig::File is implemented using object-oriented methods.  A new
 171 AppConfig::File object is created and initialised using the
 172 AppConfig::File\->\fInew()\fR method.  This returns a reference to a new
 173 AppConfig::File object.  A reference to an AppConfig::State object
 174 should be passed in as the first parameter:
 175 .PP
 176 .Vb 2
 177 \&    my $state   = AppConfig::State\->new();
 178 \&    my $cfgfile = AppConfig::File\->new($state);
 179 .Ve
 180 .PP
 181 This will create and return a reference to a new AppConfig::File object.
 182 .Sh "\s-1READING\s0 \s-1CONFIGURATION\s0 \s-1FILES\s0"
 183 .IX Subsection "READING CONFIGURATION FILES"
 184 The \f(CW\*(C`parse()\*(C'\fR method is used to read a configuration file and have the
 185 contents update the \s-1STATE\s0 accordingly.
 186 .PP
 187 .Vb 1
 188 \&    $cfgfile\->parse($file);
 189 .Ve
 190 .PP
 191 Multiple files maye be specified and will be read in turn.
 192 .PP
 193 .Vb 1
 194 \&    $cfgfile\->parse($file1, $file2, $file3);
 195 .Ve
 196 .PP
 197 The method will return an undef value if it encounters any errors opening
 198 the files.  It will return immediately without processing any further files.
 199 By default, the \s-1PEDANTIC\s0 option in the AppConfig::State object,
 200 \&\f(CW$self\fR\->{ \s-1STATE\s0 }, is turned off and any parsing errors (invalid variables,
 201 unvalidated values, etc) will generated warnings, but not cause the method
 202 to return.  Having processed all files, the method will return 1 if all
 203 files were processed without warning or 0 if one or more warnings were
 204 raised.  When the \s-1PEDANTIC\s0 option is turned on, the method generates a
 205 warning and immediately returns a value of 0 as soon as it encounters any
 206 parsing error.
 207 .PP
 208 Variables values in the configuration files may be expanded depending on
 209 the value of their \s-1EXPAND\s0 option, as determined from the App::State object.
 210 See AppConfig::State for more information on variable expansion.
 211 .Sh "\s-1CONFIGURATION\s0 \s-1FILE\s0 \s-1FORMAT\s0"
 212 .IX Subsection "CONFIGURATION FILE FORMAT"
 213 A configuration file may contain blank lines and comments which are
 214 ignored.  Comments begin with a '#' as the first character on a line
 215 or following one or more whitespace tokens, and continue to the end of
 216 the line.
 217 .PP
 218 .Vb 3
 219 \&    # this is a comment
 220 \&    foo = bar               # so is this
 221 \&    url = index.html#hello  # this too, but not the '#welcome'
 222 .Ve
 223 .PP
 224 Notice how the '#welcome' part of the \s-1URL\s0 is not treated as a comment
 225 because a whitespace character doesn't precede it.
 226 .PP
 227 Long lines can be continued onto the next line by ending the first
 228 line with a '\e'.
 229 .PP
 230 .Vb 4
 231 \&    callsign = alpha bravo camel delta echo foxtrot golf hipowls \e
 232 \&               india juliet kilo llama mike november oscar papa  \e
 233 \&               quebec romeo sierra tango umbrella victor whiskey \e
 234 \&               x\-ray yankee zebra
 235 .Ve
 236 .PP
 237 Variables that are simple flags and do not expect an argument (\s-1ARGCOUNT\s0 =
 238 \&\s-1ARGCOUNT_NONE\s0) can be specified without any value.  They will be set with
 239 the value 1, with any value explicitly specified (except \*(L"0\*(R" and \*(L"off\*(R")
 240 being ignored.  The variable may also be specified with a \*(L"no\*(R" prefix to
 241 implicitly set the variable to 0.
 242 .PP
 243 .Vb 7
 244 \&    verbose                              # on  (1)
 245 \&    verbose = 1                          # on  (1)
 246 \&    verbose = 0                          # off (0)
 247 \&    verbose off                          # off (0)
 248 \&    verbose on                           # on  (1)
 249 \&    verbose mumble                       # on  (1)
 250 \&    noverbose                            # off (0)
 251 .Ve
 252 .PP
 253 Variables that expect an argument (\s-1ARGCOUNT\s0 = \s-1ARGCOUNT_ONE\s0) will be set to
 254 whatever follows the variable name, up to the end of the current line.  An
 255 equals sign may be inserted between the variable and value for clarity.
 256 .PP
 257 .Vb 2
 258 \&    room = /home/kitchen
 259 \&    room   /home/bedroom
 260 .Ve
 261 .PP
 262 Each subsequent re-definition of the variable value overwrites the previous
 263 value.
 264 .PP
 265 .Vb 1
 266 \&    print $config\->room();               # prints "/home/bedroom"
 267 .Ve
 268 .PP
 269 Variables may be defined to accept multiple values (\s-1ARGCOUNT\s0 = \s-1ARGCOUNT_LIST\s0).
 270 Each subsequent definition of the variable adds the value to the list of
 271 previously set values for the variable.
 272 .PP
 273 .Vb 2
 274 \&    drink = coffee
 275 \&    drink = tea
 276 .Ve
 277 .PP
 278 A reference to a list of values is returned when the variable is requested.
 279 .PP
 280 .Vb 2
 281 \&    my $beverages = $config\->drinks();
 282 \&    print join(", ", @$beverages);      # prints "coffee, tea"
 283 .Ve
 284 .PP
 285 Variables may also be defined as hash lists (\s-1ARGCOUNT\s0 = \s-1ARGCOUNT_HASH\s0).
 286 Each subsequent definition creates a new key and value in the hash array.
 287 .PP
 288 .Vb 2
 289 \&    alias l="ls \-CF"
 290 \&    alias h="history"
 291 .Ve
 292 .PP
 293 A reference to the hash is returned when the variable is requested.
 294 .PP
 295 .Vb 4
 296 \&    my $aliases = $config\->alias();
 297 \&    foreach my $k (keys %$aliases) {
 298 \&        print "$k => $aliases\->{ $k }\en";
 299 \&    }
 300 .Ve
 301 .PP
 302 A large chunk of text can be defined using Perl's \*(L"heredoc\*(R" quoting
 303 style.
 304 .PP
 305 .Vb 5
 306 \&   scalar = <<BOUNDARY_STRING
 307 \&   line 1
 308 \&   line 2: Space/linebreaks within a HERE document are kept.
 309 \&   line 3: The last linebreak (\en) is stripped.
 310 \&   BOUNDARY_STRING
 311 .Ve
 312 .PP
 313 .Vb 5
 314 \&   hash   key1 = <<'FOO'
 315 \&     * Quotes (['"]) around the boundary string are simply ignored.
 316 \&     * Whether the variables in HERE document are expanded depends on
 317 \&       the EXPAND option of the variable or global setting.
 318 \&   FOO
 319 .Ve
 320 .PP
 321 .Vb 5
 322 \&   hash = key2 = <<"_bar_"
 323 \&   Text within HERE document are kept as is.
 324 \&   # comments are treated as a normal text.
 325 \&   The same applies to line continuation. \e
 326 \&   _bar_
 327 .Ve
 328 .PP
 329 Note that you cannot use \s-1HERE\s0 document as a key in a hash or a name
 330 of a variable.
 331 .PP
 332 The '\-' prefix can be used to reset a variable to its default value and
 333 the '+' prefix can be used to set it to 1
 334 .PP
 335 .Vb 2
 336 \&    \-verbose
 337 \&    +debug
 338 .Ve
 339 .PP
 340 Variable, environment variable and tilde (home directory) expansions
 341 Variable values may contain references to other AppConfig variables,
 342 environment variables and/or users' home directories.  These will be
 343 expanded depending on the \s-1EXPAND\s0 value for each variable or the \s-1GLOBAL\s0
 344 \&\s-1EXPAND\s0 value.
 345 .PP
 346 Three different expansion types may be applied:
 347 .PP
 348 .Vb 2
 349 \&    bin = ~/bin          # expand '~' to home dir if EXPAND_UID
 350 \&    tmp = ~abw/tmp       # as above, but home dir for user 'abw'
 351 .Ve
 352 .PP
 353 .Vb 2
 354 \&    perl = $bin/perl     # expand value of 'bin' variable if EXPAND_VAR
 355 \&    ripl = $(bin)/ripl   # as above with explicit parens
 356 .Ve
 357 .PP
 358 .Vb 1
 359 \&    home = ${HOME}       # expand HOME environment var if EXPAND_ENV
 360 .Ve
 361 .PP
 362 See AppConfig::State for more information on expanding variable values.
 363 .PP
 364 The configuration files may have variables arranged in blocks.  A block
 365 header, consisting of the block name in square brackets, introduces a
 366 configuration block.  The block name and an underscore are then prefixed
 367 to the names of all variables subsequently referenced in that block.  The
 368 block continues until the next block definition or to the end of the current
 369 file.
 370 .PP
 371 .Vb 2
 372 \&    [block1]
 373 \&    foo = 10             # block1_foo = 10
 374 .Ve
 375 .PP
 376 .Vb 2
 377 \&    [block2]
 378 \&    foo = 20             # block2_foo = 20
 379 .Ve
 380 .SH "AUTHOR"
 381 .IX Header "AUTHOR"
 382 Andy Wardley, <abw@wardley.org>
 383 .SH "COPYRIGHT"
 384 .IX Header "COPYRIGHT"
 385 Copyright (C) 1997\-2007 Andy Wardley.  All Rights Reserved.
 386 .PP
 387 This module is free software; you can redistribute it and/or modify it
 388 under the same terms as Perl itself.
 389 .SH "SEE ALSO"
 390 .IX Header "SEE ALSO"
 391 AppConfig, AppConfig::State