.\" 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 "ApacheFormat 3pm"
.TH ApacheFormat 3pm "2022-06-11" "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"
Config::ApacheFormat \- use Apache format config files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Config files used with this module are in Apache's format:
.PP
.Vb 5
\&  # comment here
\&  RootDir /path/foo
\&  LogDir  /path/foo/log
\&  Colors red green orange blue \e
\&         black teal
\&
\&  <Directory /path/foo>
\&     # override Colors inside block
\&     Colors red blue black
\&  </Directory>
.Ve
.PP
Code to use this config file might look like:
.PP
.Vb 1
\&  use Config::ApacheFormat;
\&
\&  # load a conf file
\&  my $config = Config::ApacheFormat\->new();
\&  $config\->read("my.conf");
\&
\&  # access some parameters
\&  $root_dir = $config\->get("RootDir");
\&  $log_dir  = $config\->get("LogDir");
\&  @colors   = $config\->get("colors");
\&
\&  # using the autoloaded methods
\&  $config\->autoload_support(1);
\&  $root_dir = $config\->RootDir;
\&  $log_dir  = $config\->logdir;
\&
\&  # access parameters inside a block
\&  my $block = $config\->block(Directory => "/path/foo");
\&  @colors = $block\->get("colors");
\&  $root_dir = $block\->get("root_dir");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is designed to parse a configuration file in the same
syntax used by the Apache web server (see http://httpd.apache.org for
details).  This allows you to build applications which can be easily
managed by experienced Apache admins.  Also, by using this module,
you'll benefit from the support for nested blocks with built-in
parameter inheritance.  This can greatly reduce the amount or repeated
information in your configuration files.
.PP
A good reference to the Apache configuration file format can be found
here:
.PP
.Vb 1
\&  http://httpd.apache.org/docs\-2.0/configuring.html
.Ve
.PP
To quote from that document, concerning directive syntax:
.PP
.Vb 5
\& Apache configuration files contain one directive per line. The
\& back\-slash "\e" may be used as the last character on a line to
\& indicate that the directive continues onto the next line. There must
\& be no other characters or white space between the back\-slash and the
\& end of the line.
\&
\& Directives in the configuration files are case\-insensitive, but
\& arguments to directives are often case sensitive. Lines that begin
\& with the hash character "#" are considered comments, and are
\& ignored. Comments may not be included on a line after a configuration
\& directive. Blank lines and white space occurring before a directive
\& are ignored, so you may indent directives for clarity.
.Ve
.PP
And block notation:
.PP
.Vb 8
\& Directives placed in the main configuration files apply to the entire
\& server. If you wish to change the configuration for only a part of the
\& server, you can scope your directives by placing them in <Directory>,
\& <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, and
\& <LocationMatch> sections. These sections limit the application of the
\& directives which they enclose to particular filesystem locations or
\& URLs. They can also be nested, allowing for very fine grained
\& configuration.
.Ve
.PP
This module will parse actual Apache configuration files, but you will need to set some options to non-default values.  See \*(L"Parsing a Real Apache Config File\*(R".
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$config = Config::ApacheFormat\->new(opt => ""value"")" 4
.el .IP "\f(CW$config\fR = Config::ApacheFormat\->new(opt => ``value'')" 4
.IX Item "$config = Config::ApacheFormat->new(opt => value)"
This method creates an object that can then be used to read configuration
files. It does not actually read any files; for that, use the \f(CW\*(C`read()\*(C'\fR
method below. The object supports the following attributes, all of which
may be set through \f(CW\*(C`new()\*(C'\fR:
.RS 4
.IP "inheritance_support" 4
.IX Item "inheritance_support"
Set this to 0 to turn off the inheritance feature. Block inheritance
means that variables declared outside a block are available from
inside the block unless overridden.  Defaults to 1.
.IP "include_support" 4
.IX Item "include_support"
When this is set to 1, the directive \*(L"Include\*(R" will be treated
specially by the parser.  It will cause the value to be treated as a
filename and that filename will be read in.  If you use \*(L"Include\*(R"
with a directory, every file in that directory will be included.
This matches Apache's behavior and allows users to break up 
configuration files into multiple, possibly shared, pieces.  
Defaults to 1.
.IP "autoload_support" 4
.IX Item "autoload_support"
Set this to 1 and all your directives will be available as object
methods.  So instead of:
.Sp
.Vb 1
\&  $config\->get("foo");
.Ve
.Sp
You can write:
.Sp
.Vb 1
\&  $config\->foo;
.Ve
.Sp
Defaults to 0.
.IP "case_sensitive" 4
.IX Item "case_sensitive"
Set this to 1 to preserve the case of directive names.  Otherwise, all
names will be \f(CW\*(C`lc()\*(C'\fRed and matched case-insensitively.  Defaults to 0.
.IP "fix_booleans" 4
.IX Item "fix_booleans"
If set to 1, then during parsing, the strings \*(L"Yes\*(R", \*(L"On\*(R", and \*(L"True\*(R"
will be converted to 1, and the strings \*(L"No\*(R", \*(L"Off\*(R", and \*(L"False\*(R" will
be converted to 0. This allows you to more easily use \f(CW\*(C`get()\*(C'\fR in 
conditional statements.
.Sp
For example:
.Sp
.Vb 2
\&  # httpd.conf
\&  UseCanonicalName  On
.Ve
.Sp
Then in Perl:
.Sp
.Vb 2
\&  $config = Config::ApacheFormat\->new(fix_booleans => 1);
\&  $config\->read("httpd.conf");
\&
\&  if ($config\->get("UseCanonicalName")) {
\&      # this will get executed if set to Yes/On/True
\&  }
.Ve
.Sp
This option defaults to 0.
.IP "expand_vars" 4
.IX Item "expand_vars"
If set, then you can use variable expansion in your config file by 
prefixing directives with a \f(CW\*(C`$\*(C'\fR. Hopefully this seems logical to you:
.Sp
.Vb 3
\&  Website     http://my.own.dom
\&  JScript     $Website/js
\&  Images      $Website/images
.Ve
.Sp
Undefined variables in your config file will result in an error. To
use a literal \f(CW\*(C`$\*(C'\fR, simply prefix it with a \f(CW\*(C`\e\*(C'\fR (backslash). Like
in Perl, you can use brackets to delimit the variables more precisely:
.Sp
.Vb 2
\&  Nickname    Rob
\&  Fullname    ${Nickname}ert
.Ve
.Sp
Since only scalars are supported, if you use a multi-value, you will
only get back the first one:
.Sp
.Vb 2
\&  Options     Plus Minus "About the Same"
\&  Values      $Options
.Ve
.Sp
In this examples, \*(L"Values\*(R" will become \*(L"Plus\*(R". This is seldom a limitation
since in most cases, variable subsitution is used like the first example
shows. This option defaults to 0.
.IP "setenv_vars" 4
.IX Item "setenv_vars"
If this is set to 1, then the special \f(CW\*(C`SetEnv\*(C'\fR directive will be set
values in the environment via \f(CW%ENV\fR.  Also, the special \f(CW\*(C`UnSetEnv\*(C'\fR
directive will delete environment variables.
.Sp
For example:
.Sp
.Vb 2
\&  # $ENV{PATH} = "/usr/sbin:/usr/bin"
\&  SetEnv PATH "/usr/sbin:/usr/bin"
\&
\&  # $ENV{MY_SPECIAL_VAR} = 10
\&  SetEnv MY_SPECIAL_VAR 10
\&
\&  # delete $ENV{THIS}
\&  UnsetEnv THIS
.Ve
.Sp
This option defaults to 0.
.IP "valid_directives" 4
.IX Item "valid_directives"
If you provide an array of directive names then syntax errors will be
generated during parsing for invalid directives.  Otherwise, any
directive name will be accepted.  For example, to only allow
directives called \*(L"Bar\*(R" and \*(L"Bif\*(R":
.Sp
.Vb 3
\&  $config = Config::ApacheFormat\->new(
\&                      valid_directives => [qw(Bar Bif)],
\&                                     );
.Ve
.IP "valid_blocks" 4
.IX Item "valid_blocks"
If you provide an array of block names then syntax errors will be
generated during parsing for invalid blocks.  Otherwise, any block
name will be accepted.  For example, to only allow \*(L"Directory\*(R" and
\&\*(L"Location\*(R" blocks in your config file:
.Sp
.Vb 3
\&  $config = Config::ApacheFormat\->new(
\&                      valid_blocks => [qw(Directory Location)],
\&                                     );
.Ve
.IP "include_directives" 4
.IX Item "include_directives"
This directive controls the name of the include directive.  By default
it is \f(CW\*(C`[\*(AqInclude\*(Aq]\*(C'\fR, but you can set it to any list of directive
names.
.IP "root_directive" 4
.IX Item "root_directive"
This controls what the root directive is, if any.  If you set this to
the name of a directive it will be used as a base directory for
\&\f(CW\*(C`Include\*(C'\fR processing.  This mimics the behavior of \f(CW\*(C`ServerRoot\*(C'\fR in
real Apache config files, and as such you'll want to set it to
\&'ServerRoot' when parsing an Apache config.  The default is \f(CW\*(C`undef\*(C'\fR.
.IP "hash_directives" 4
.IX Item "hash_directives"
This determines which directives (if any) should be parsed so that the
first value is actually a key into the remaining values. For example,
\&\f(CW\*(C`AddHandler\*(C'\fR is such a directive.
.Sp
.Vb 2
\&  AddHandler cgi\-script .cgi .sh
\&  AddHandler server\-parsed .shtml
.Ve
.Sp
To parse this correctly, use:
.Sp
.Vb 3
\&  $config = Config::ApacheFormat\->new(
\&                      hash_directives => [qw(AddHandler PerlSetVar)]
\&                                     );
.Ve
.Sp
Then, use the two-argument form of \f(CW\*(C`get()\*(C'\fR:
.Sp
.Vb 1
\&  @values = $config\->get(AddHandler => \*(Aqcgi\-script\*(Aq);
.Ve
.Sp
This allows you to access each directive individually, which is needed
to correctly handle certain special-case Apache settings.
.IP "duplicate_directives" 4
.IX Item "duplicate_directives"
This option controls how duplicate directives are handled. By default,
if multiple directives of the same name are encountered, the last one
wins:
.Sp
.Vb 3
\&  Port 8080
\&  # ...
\&  Port 5053
.Ve
.Sp
In this case, the directive \f(CW\*(C`Port\*(C'\fR would be set to the last value, \f(CW5053\fR.
This is useful because it allows you to include other config files, which
you can then override:
.Sp
.Vb 2
\&  # default setup
\&  Include /my/app/defaults.conf
\&
\&  # override port
\&  Port 5053
.Ve
.Sp
In addition to this default behavior, \f(CW\*(C`Config::ApacheFormat\*(C'\fR also supports
the following modes:
.Sp
.Vb 3
\&  last     \-  the value from the last one is kept (default)
\&  error    \-  duplicate directives result in an error
\&  combine  \-  combine values of duplicate directives together
.Ve
.Sp
These should be self-explanatory. If set to \f(CW\*(C`error\*(C'\fR, any duplicates
will result in an error.  If set to \f(CW\*(C`last\*(C'\fR (the default), the last
value wins. If set to \f(CW\*(C`combine\*(C'\fR, then duplicate directives are
combined together, just like they had been specified on the same line.
.RE
.RS 4
.Sp
All of the above attributes are also available as accessor methods.  Thus,
this:
.Sp
.Vb 2
\&  $config = Config::ApacheFormat\->new(inheritance_support => 0,
\&                                      include_support => 1);
.Ve
.Sp
Is equivalent to:
.Sp
.Vb 3
\&  $config = Config::ApacheFormat\->new();
\&  $config\->inheritance_support(0);
\&  $config\->include_support(1);
.Ve
.RE
.ie n .IP "$config\->read(""my.conf"");" 4
.el .IP "\f(CW$config\fR\->read(``my.conf'');" 4
.IX Item "$config->read(my.conf);"
.PD 0
.ie n .IP "$config\->read(\e*FILE);" 4
.el .IP "\f(CW$config\fR\->read(\e*FILE);" 4
.IX Item "$config->read(*FILE);"
.PD
Reads a configuration file into the config object.  You must pass
either the path of the file to be read or a reference to an open
filehandle.  If an error is encountered while reading the file, this
method will \fBdie()\fR.
.Sp
Calling \fBread()\fR more than once will add the new configuration values
from another source, overwriting any conflicting values.  Call \fBclear()\fR
first if you want to read a new set from scratch.
.ie n .IP """$value = $config\->get(""var_name"")""" 4
.el .IP "\f(CW$value = $config\->get(``var_name'')\fR" 4
.IX Item "$value = $config->get(""var_name"")"
.PD 0
.ie n .IP """@vals = $config\->get(""list_name"")""" 4
.el .IP "\f(CW@vals = $config\->get(``list_name'')\fR" 4
.IX Item "@vals = $config->get(""list_name"")"
.ie n .IP """$value = $config\->get(""hash_var_name"", ""key"")""" 4
.el .IP "\f(CW$value = $config\->get(``hash_var_name'', ``key'')\fR" 4
.IX Item "$value = $config->get(""hash_var_name"", ""key"")"
.PD
Returns values from the configuration file.  If the directive contains
a single value, it will be returned.  If the directive contains a list
of values then they will be returned as a list.  If the directive does
not exist in the configuration file then nothing will be returned
(undef in scalar context, empty list in list context).
.Sp
For example, given this confiuration file:
.Sp
.Vb 2
\&  Foo 1
\&  Bar bif baz bop
.Ve
.Sp
The following code would work as expected:
.Sp
.Vb 2
\&  my $foo = $config\->get("Foo");   # $foo = 1
\&  my @bar = $config\->get("Bar");   # @bar = ("bif", "baz", "bop")
.Ve
.Sp
If the name is the name of a block tag in the configuration file then
a list of available block specifiers will be returned.  For example,
given this configuration file:
.Sp
.Vb 3
\&  <Site big>
\&     Size 10
\&  </Site>
\&
\&  <Site small>
\&     Size 1
\&  </Site>
.Ve
.Sp
This call:
.Sp
.Vb 1
\&  @sites = $config\->get("Site");
.Ve
.Sp
Will return \f(CW\*(C`([ Site =\*(C'\fR \*(L"big\*(R"], [ Site => \*(L"small\*(R" ])>.  These arrays
can then be used with the \fBblock()\fR method described below.
.Sp
If the directive was included in the file but did not have a value,
1 is returned by \fBget()\fR.
.Sp
Calling \fBget()\fR with no arguments will return the names of all available
directives.
.Sp
Directives declared in \f(CW\*(C`hash_directives\*(C'\fR require a key value:
.Sp
.Vb 1
\&  $handler = $config\->get("AddHandler", "cgi\-script");
.Ve
.Sp
\&\f(CW\*(C`directive()\*(C'\fR is available as an alias for \f(CW\*(C`get()\*(C'\fR.
.ie n .IP "$block = $config\->block(""BlockName"")" 4
.el .IP "\f(CW$block\fR = \f(CW$config\fR\->block(``BlockName'')" 4
.IX Item "$block = $config->block(BlockName)"
.PD 0
.ie n .IP "$block = $config\->block(Directory => ""/foo/bar"")" 4
.el .IP "\f(CW$block\fR = \f(CW$config\fR\->block(Directory => ``/foo/bar'')" 4
.IX Item "$block = $config->block(Directory => /foo/bar)"
.ie n .IP "$block = $config\->block(Directory => ""~"" => ""^.*/bar"")" 4
.el .IP "\f(CW$block\fR = \f(CW$config\fR\->block(Directory => ``~'' => ``^.*/bar'')" 4
.IX Item "$block = $config->block(Directory => ~ => ^.*/bar)"
.PD
This method returns a Config::ApacheFormat object used to access the
values inside a block.  Parameters specified within the block will be
available.  Also, if inheritance is turned on (the default), values
set outside the block that are not overwritten inside the block will
also be available.  For example, given this file:
.Sp
.Vb 1
\&  MaxSize 100
\&
\&  <Site "big">
\&     Size 10
\&  </Site>
\&
\&  <Site "small">
\&     Size 1
\&  </Site>
.Ve
.Sp
this code:
.Sp
.Vb 1
\&  print "Max: ", $config\->get("MaxSize"), "\en";
\&
\&  $block = $config\->block(Site => "big");
\&  print "Big: ", $block\->get("Size"), " / ", 
\&                 $block\->get("MaxSize"), "\en";
\&
\&  $block = $config\->block(Site => "small");
\&  print "Small: ", $block\->get("Size"), " / ", 
\&                   $block\->get("MaxSize"), "\en";
.Ve
.Sp
will print:
.Sp
.Vb 3
\&  Max: 100
\&  Big: 10 / 100
\&  Small: 1 / 100
.Ve
.Sp
Note that \f(CW\*(C`block()\*(C'\fR does not require any particular number of
parameters.  Any number will work, as long as they uniquely identify a
block in the configuration file.  To get a list of available blocks,
use \fBget()\fR with the name of the block tag.
.Sp
This method will \fBdie()\fR if no block can be found matching the specifier
passed in.
.ie n .IP "$config\->\fBclear()\fR" 4
.el .IP "\f(CW$config\fR\->\fBclear()\fR" 4
.IX Item "$config->clear()"
Clears out all data in \f(CW$config\fR.  Call before re-calling
\&\f(CW$config\fR\->\fBread()\fR for a fresh read.
.ie n .IP "$config\->\fBdump()\fR" 4
.el .IP "\f(CW$config\fR\->\fBdump()\fR" 4
.IX Item "$config->dump()"
This returns a dumped copy of the current configuration. It can be
used on a block object as well. Since it returns a string, you should
say:
.Sp
.Vb 1
\&    print $config\->dump;
.Ve
.Sp
Or:
.Sp
.Vb 3
\&    for ($config\->block(VirtualHost => \*(Aq10.1.65.1\*(Aq)) {
\&        print $_\->dump;
\&    }
.Ve
.Sp
If you want to see any output.
.SH "Parsing a Real Apache Config File"
.IX Header "Parsing a Real Apache Config File"
To parse a real Apache config file (ex. \f(CW\*(C`httpd.conf\*(C'\fR) you'll need to
use some non-default options.  Here's a reasonable starting point:
.PP
.Vb 8
\&  $config = Config::ApacheFormat\->new(
\&              root_directive     => \*(AqServerRoot\*(Aq,
\&              hash_directives    => [ \*(AqAddHandler\*(Aq ],
\&              include_directives => [ \*(AqInclude\*(Aq, 
\&                                      \*(AqAccessConfig\*(Aq, 
\&                                      \*(AqResourceConfig\*(Aq ],
\&              setenv_vars        => 1,
\&              fix_booleans       => 1);
.Ve
.SH "TODO"
.IX Header "TODO"
Some possible ideas for future development:
.IP "\(bu" 4
Add a \fBset()\fR method.  (useless?)
.IP "\(bu" 4
Add a \fBwrite()\fR method to create a new configuration file.  (useless?)
.SH "BUGS"
.IX Header "BUGS"
I know of no bugs in this software.  If you find one, please create a
bug report at:
.PP
.Vb 1
\&  http://rt.cpan.org/
.Ve
.PP
Include the version of the module you're using and a small piece of
code that I can run which demonstrates the problem.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2002\-2003 Sam Tregar
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl 5 itself.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "Sam Tregar <sam@tregar.com>" 4
.IX Item "Sam Tregar <sam@tregar.com>"
Original author and maintainer
.IP "Nathan Wiger <nate@wiger.org>" 4
.IX Item "Nathan Wiger <nate@wiger.org>"
Porting of features from Apache::ConfigFile
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Apache::ConfigFile
.PP
Apache::ConfigParser