1=head1 NAME
2
3ConfigReader - Read directives from a configuration file.
4
5=head1 DESCRIPTION
6
7The ConfigReader library is a set of classes which reads directives
8from a configuration file.  The library is completely object oriented,
9and it is envisioned that parsers for new styles of configuration
10files can be easily added.
11
12ConfigReader::Spec encapsulates a specification for configuration
13directives.  You can specify which directives can be in the
14configuration file, aliases for the directive, whether the directive
15is required or has a default value, and how to parse the directive
16value.
17
18Here's an example of how one directive might be specified:
19
20     required $spec 'HomePage', 'new URI::URL';
21
22This defines a required directive called 'HomePage'.  To parse the
23value from the configuration file, the URI::URL::new() method will be
24called with the string value as its argument.
25
26If the directive name is a simple string, it will be used both to
27refer to the directive in the Perl program, and as the name in the
28configuration file.  You can also specify an alias by using an array
29ref.  For example, suppose you wanted to use "index" as the name of
30the directive in the configuration file, but to avoid confusion with
31Perl's index() function you wanted to refer to the directive inside
32the program as the "file_index".  This will do the trick:
33
34    ['file_index', 'index']
35
36You can specify any number of aliases for the directive:
37
38    ['file_index', 'index', 'file_index', 'contents', ...]
39
40The parsing function or method is called to translate the value string
41from the configuration file into the value used by the program.  It
42can be specified in several different ways:
43
44code ref
45static method
46object method
47undefined
48
49You can also specify a default value to be used if a directive is not
50specified in the configuration file.
51
52string value
53code ref
54undefined
55
56ConfigReader::Values stores a set of directive values that have been
57read from a configuration file.  It stores a reference to an
58associated Spec as a member variable.  Separating the specification
59from the values makes it possible to use a single specification for
60multiple sets of values.
61
62ConfigReader::DirectiveStyle implements a reader for a common style of
63configuration file.  It is a subclass of ConfigReader::Values.
64Directive names are followed by their value, one per line:
65
66    HomePage   http://www.w3.org/
67    Services   /etc/services
68
69