.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "AppConfig::File 3pm"
.TH AppConfig::File 3pm "2023-09-28" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
AppConfig::File \- Perl5 module for reading configuration files.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use AppConfig::File;
\&
\&    my $state   = AppConfig::State\->new(\e%cfg1);
\&    my $cfgfile = AppConfig::File\->new($state, $file);
\&
\&    $cfgfile\->parse($file);            # read config file
.Ve
.SH "OVERVIEW"
.IX Header "OVERVIEW"
AppConfig::File is a Perl5 module which reads configuration files and use 
the contents therein to update variable values in an AppConfig::State 
object.
.PP
AppConfig::File is distributed as part of the AppConfig bundle.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "\s-1USING THE\s0 AppConfig::File \s-1MODULE\s0"
.IX Subsection "USING THE AppConfig::File MODULE"
To import and use the AppConfig::File module the following line should appear
in your Perl script:
.PP
.Vb 1
\&    use AppConfig::File;
.Ve
.PP
AppConfig::File is used automatically if you use the AppConfig module 
and create an AppConfig::File object through the \fBfile()\fR method.
.PP
AppConfig::File is implemented using object-oriented methods.  A new 
AppConfig::File object is created and initialised using the 
AppConfig::File\->\fBnew()\fR method.  This returns a reference to a new 
AppConfig::File object.  A reference to an AppConfig::State object 
should be passed in as the first parameter:
.PP
.Vb 2
\&    my $state   = AppConfig::State\->new();
\&    my $cfgfile = AppConfig::File\->new($state);
.Ve
.PP
This will create and return a reference to a new AppConfig::File object.
.SS "\s-1READING CONFIGURATION FILES\s0"
.IX Subsection "READING CONFIGURATION FILES"
The \f(CW\*(C`parse()\*(C'\fR method is used to read a configuration file and have the 
contents update the \s-1STATE\s0 accordingly.
.PP
.Vb 1
\&    $cfgfile\->parse($file);
.Ve
.PP
Multiple files maye be specified and will be read in turn.
.PP
.Vb 1
\&    $cfgfile\->parse($file1, $file2, $file3);
.Ve
.PP
The method will return an undef value if it encounters any errors opening
the files.  It will return immediately without processing any further files.
By default, the \s-1PEDANTIC\s0 option in the AppConfig::State object, 
\&\f(CW$self\fR\->{ \s-1STATE\s0 }, is turned off and any parsing errors (invalid variables,
unvalidated values, etc) will generated warnings, but not cause the method
to return.  Having processed all files, the method will return 1 if all
files were processed without warning or 0 if one or more warnings were
raised.  When the \s-1PEDANTIC\s0 option is turned on, the method generates a
warning and immediately returns a value of 0 as soon as it encounters any
parsing error.
.PP
Variables values in the configuration files may be expanded depending on 
the value of their \s-1EXPAND\s0 option, as determined from the App::State object.
See AppConfig::State for more information on variable expansion.
.SS "\s-1CONFIGURATION FILE FORMAT\s0"
.IX Subsection "CONFIGURATION FILE FORMAT"
A configuration file may contain blank lines and comments which are
ignored.  Comments begin with a '#' as the first character on a line
or following one or more whitespace tokens, and continue to the end of
the line.
.PP
.Vb 3
\&    # this is a comment
\&    foo = bar               # so is this
\&    url = index.html#hello  # this too, but not the \*(Aq#welcome\*(Aq
.Ve
.PP
Notice how the '#welcome' part of the \s-1URL\s0 is not treated as a comment
because a whitespace character doesn't precede it.
.PP
Long lines can be continued onto the next line by ending the first 
line with a '\e'.
.PP
.Vb 4
\&    callsign = alpha bravo camel delta echo foxtrot golf hipowls \e
\&               india juliet kilo llama mike november oscar papa  \e
\&               quebec romeo sierra tango umbrella victor whiskey \e
\&               x\-ray yankee zebra
.Ve
.PP
Variables that are simple flags and do not expect an argument (\s-1ARGCOUNT\s0 = 
\&\s-1ARGCOUNT_NONE\s0) can be specified without any value.  They will be set with 
the value 1, with any value explicitly specified (except \*(L"0\*(R" and \*(L"off\*(R")
being ignored.  The variable may also be specified with a \*(L"no\*(R" prefix to 
implicitly set the variable to 0.
.PP
.Vb 7
\&    verbose                              # on  (1)
\&    verbose = 1                          # on  (1)
\&    verbose = 0                          # off (0)
\&    verbose off                          # off (0)
\&    verbose on                           # on  (1)
\&    verbose mumble                       # on  (1)
\&    noverbose                            # off (0)
.Ve
.PP
Variables that expect an argument (\s-1ARGCOUNT\s0 = \s-1ARGCOUNT_ONE\s0) will be set to 
whatever follows the variable name, up to the end of the current line.  An
equals sign may be inserted between the variable and value for clarity.
.PP
.Vb 2
\&    room = /home/kitchen     
\&    room   /home/bedroom
.Ve
.PP
Each subsequent re-definition of the variable value overwrites the previous
value.
.PP
.Vb 1
\&    print $config\->room();               # prints "/home/bedroom"
.Ve
.PP
Variables may be defined to accept multiple values (\s-1ARGCOUNT\s0 = \s-1ARGCOUNT_LIST\s0).
Each subsequent definition of the variable adds the value to the list of
previously set values for the variable.
.PP
.Vb 2
\&    drink = coffee
\&    drink = tea
.Ve
.PP
A reference to a list of values is returned when the variable is requested.
.PP
.Vb 2
\&    my $beverages = $config\->drinks();
\&    print join(", ", @$beverages);      # prints "coffee, tea"
.Ve
.PP
Variables may also be defined as hash lists (\s-1ARGCOUNT\s0 = \s-1ARGCOUNT_HASH\s0).
Each subsequent definition creates a new key and value in the hash array.
.PP
.Vb 2
\&    alias l="ls \-CF"
\&    alias h="history"
.Ve
.PP
A reference to the hash is returned when the variable is requested.
.PP
.Vb 4
\&    my $aliases = $config\->alias();
\&    foreach my $k (keys %$aliases) {
\&        print "$k => $aliases\->{ $k }\en";
\&    }
.Ve
.PP
A large chunk of text can be defined using Perl's \*(L"heredoc\*(R" quoting
style.
.PP
.Vb 5
\&   scalar = <<BOUNDARY_STRING
\&   line 1
\&   line 2: Space/linebreaks within a HERE document are kept.
\&   line 3: The last linebreak (\en) is stripped.
\&   BOUNDARY_STRING
\&
\&   hash   key1 = <<\*(AqFOO\*(Aq
\&     * Quotes ([\*(Aq"]) around the boundary string are simply ignored.
\&     * Whether the variables in HERE document are expanded depends on
\&       the EXPAND option of the variable or global setting.
\&   FOO
\&
\&   hash = key2 = <<"_bar_"
\&   Text within HERE document are kept as is.
\&   # comments are treated as a normal text.
\&   The same applies to line continuation. \e
\&   _bar_
.Ve
.PP
Note that you cannot use \s-1HERE\s0 document as a key in a hash or a name 
of a variable.
.PP
The '\-' prefix can be used to reset a variable to its default value and
the '+' prefix can be used to set it to 1
.PP
.Vb 2
\&    \-verbose
\&    +debug
.Ve
.PP
Variable, environment variable and tilde (home directory) expansions
Variable values may contain references to other AppConfig variables, 
environment variables and/or users' home directories.  These will be 
expanded depending on the \s-1EXPAND\s0 value for each variable or the \s-1GLOBAL
EXPAND\s0 value.
.PP
Three different expansion types may be applied:
.PP
.Vb 2
\&    bin = ~/bin          # expand \*(Aq~\*(Aq to home dir if EXPAND_UID
\&    tmp = ~abw/tmp       # as above, but home dir for user \*(Aqabw\*(Aq
\&
\&    perl = $bin/perl     # expand value of \*(Aqbin\*(Aq variable if EXPAND_VAR
\&    ripl = $(bin)/ripl   # as above with explicit parens
\&
\&    home = ${HOME}       # expand HOME environment var if EXPAND_ENV
.Ve
.PP
See AppConfig::State for more information on expanding variable values.
.PP
The configuration files may have variables arranged in blocks.  A block 
header, consisting of the block name in square brackets, introduces a 
configuration block.  The block name and an underscore are then prefixed 
to the names of all variables subsequently referenced in that block.  The 
block continues until the next block definition or to the end of the current 
file.
.PP
.Vb 2
\&    [block1]
\&    foo = 10             # block1_foo = 10
\&
\&    [block2]
\&    foo = 20             # block2_foo = 20
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Wardley, <abw@wardley.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 1997\-2007 Andy Wardley.  All Rights Reserved.
.PP
This module is free software; you can redistribute it and/or modify it 
under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
AppConfig, AppConfig::State