.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 "ConfigReader 3pm"
.TH ConfigReader 3pm "2022-10-13" "perl v5.34.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"
ConfigReader \- Read directives from a configuration file.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The ConfigReader library is a set of classes which reads directives
from a configuration file.  The library is completely object oriented,
and it is envisioned that parsers for new styles of configuration
files can be easily added.
.PP
ConfigReader::Spec encapsulates a specification for configuration
directives.  You can specify which directives can be in the
configuration file, aliases for the directive, whether the directive
is required or has a default value, and how to parse the directive
value.
.PP
Here's an example of how one directive might be specified:
.PP
.Vb 1
\&     required $spec \*(AqHomePage\*(Aq, \*(Aqnew URI::URL\*(Aq;
.Ve
.PP
This defines a required directive called 'HomePage'.  To parse the
value from the configuration file, the \fBURI::URL::new()\fR method will be
called with the string value as its argument.
.PP
If the directive name is a simple string, it will be used both to
refer to the directive in the Perl program, and as the name in the
configuration file.  You can also specify an alias by using an array
ref.  For example, suppose you wanted to use \*(L"index\*(R" as the name of
the directive in the configuration file, but to avoid confusion with
Perl's \fBindex()\fR function you wanted to refer to the directive inside
the program as the \*(L"file_index\*(R".  This will do the trick:
.PP
.Vb 1
\&    [\*(Aqfile_index\*(Aq, \*(Aqindex\*(Aq]
.Ve
.PP
You can specify any number of aliases for the directive:
.PP
.Vb 1
\&    [\*(Aqfile_index\*(Aq, \*(Aqindex\*(Aq, \*(Aqfile_index\*(Aq, \*(Aqcontents\*(Aq, ...]
.Ve
.PP
The parsing function or method is called to translate the value string
from the configuration file into the value used by the program.  It
can be specified in several different ways:
.PP
code ref
static method
object method
undefined
.PP
You can also specify a default value to be used if a directive is not
specified in the configuration file.
.PP
string value
code ref
undefined
.PP
ConfigReader::Values stores a set of directive values that have been
read from a configuration file.  It stores a reference to an
associated Spec as a member variable.  Separating the specification
from the values makes it possible to use a single specification for
multiple sets of values.
.PP
ConfigReader::DirectiveStyle implements a reader for a common style of
configuration file.  It is a subclass of ConfigReader::Values.
Directive names are followed by their value, one per line:
.PP
.Vb 2
\&    HomePage   http://www.w3.org/
\&    Services   /etc/services
.Ve