/ 
Apache-Admin-Config-0.13
River stage one • 2 direct dependents • 3 total dependents
/ Apache::Admin::Config

NAME

Apache::Admin::Config - A common module to manipulate Apache configuration files

SYNOPSIS

use Apache::Admin::Config;

# Parse an apache configuration file
my $obj = new Apache::Admin::Config ("/path/to/config_file.conf")
    || die $Apache::Admin::Config::ERROR;

# or parse a filehandle
open(ANHANDLE, "/path/to/a/file")...
...
my $obj = new Apache::Admin::Config (\*ANHANDLE)
    || die $Apache::Admin::Config::ERROR;


#
# working with directives
#


# Getting the full list of directives in current context. 

# Directive method called without any argument, return a list
# of all directive located in the current context. The actual
# context is called "top", because it haven't any parent.
my @directives_list = $obj->directive;

# The resulting array, is sorted by order of apparence in the
# file. So you can easly figure directive's precedence.

# Each item of @directives_list array is a "magic" string. If
# you print one, it return the name of pointed directive.
my $directive = $directives_list[3];
print $directive; # return "DocumentRoot" for example

# But this "magic" string is also an object, that have many
# methods for manage this directive.
print $directive->value;  # "/my/document/root"
print $directive->type;   # "directive"
$directive->isin($obj);   # true
$directive->delete;
...

# this print all current context's directives and it's associated
# value :
foreach my $directive ($obj->directive)
{
    printf qq(%s: '%s' has value: '%s' at line %d\n), 
        $directive->type, $directive->name, $directive->value, $directive->first_line;
}

# possible output:
directive: servertype has value: standalone at line 48
directive: serverroot has value: "@@ServerRoot@@" at line 61
directive: pidfile has value: logs/httpd.pid at line 78
directive: scoreboardfile has value: logs/apache_runtime_status at line 86
...

# you can select which directive you want
my $directive = $obj->directive(-which=>8); # you'll get the 8th directive of
                                            # the current context


# getting the full list of directive who's name is "Foo" in the current context
my @foo_directives = $obj->directive('Foo');
# or just the 4th
my $4th_foo_directive = $obj->directive('Foo', -which=>4);


# you may want just directives named "Foo" with value "Bar", it return
# a list of all directives with these name/value in list context
my @foo_bar_directives = $obj->directive(Foo=>'Bar');
# or just the last one in scalar context
my $foo_bar_directive = $obj->directive(Foo=>'Bar');
# or the second one if "-which" option is given.
my $foo_bar_directive = $obj->directive(Foo=>'Bar', -which=>2);

# working on directive "PidFile"
my $pidfile = $obj->directive(PidFile=>'logs/httpd.pid');

# changing value of directive "PidFile logs/httpd.pid" to "PidFile logs/apache.pid"
$pidfile->set_value('logs/apache.pid');


# deleting directive "PidFile logs/apache.pid"
$pidfile->delete;

# or deleting all directives "AddType"
map($_->delete, $obj->directive(AddType)); # dangerous


# adding directive "AddType text/html .shtml" just after the last AddType directive if any
# or at the end of file (or section)
$obj->add_directive(AddType=>'text/html .shtml', -after=>$obj->directive('AddType', -which=>-1))
# only if "AddType text/html .shtml" doesn't exist
unless($obj->directive(AddType=>'text/html .shtml'));

#
# working with sections
#

# you can get object to another context like this
my $section_directive_foo = $obj->section(Foo=>'Bar');
my @directives_list = $section_directive_foo->directive;

# accessing the section "<file some_file>" in the section "<directory /some/dir>" 
# of section "<virtualhost example.com>"
my $subsubsubsection = $obj->section(virtualhost=>"example.com")->section(directory=>"/some/dir")->section(file=>"some_file")

#
# reordering lines
# 

# moving all directives "LoadModule" before directives "AddModule" in the current context
my $first_addmodule = $obj->directive(AddModule, -which=>0):
foreach my $loadmodule ($obj->directive('LoadModule'))
{
    $loadmodule->move(-before=>$first_addmodule);
      if($loadmodule->line > $first_addmodule->line);
}

#
# save
#

# save change in place
$obj->save;
# or in another file (sound like "save as...")
$obj->save("/path/to/another/file");
# or in an already openned file
$obj->save(\*FILE_HANDLE);

DESCRIPTION

Apache::Admin::Config provides an object interface to handling Apache like configuration files without modifying comments, identation, or truncated lines.

METHODES

new ([/path/to/file|handle], -oldapi=>0|1)

Create or read, if given in argument, an apache like configuration file.

Arguments:

/path/to/file

Path to the configuration file to parse. If none given, create a new one.

= item handle

Instead of specify a path to a file, you can give a reference to an handle that point to an already openned file. You can do this like this :

my $conf = new Apache::Admin::Config (\*MYHANDLE);
-oldapi=>0/1

If true, keep the old api backward compatibility. Read UPGRADE-0.10 for more details. Default is false.

save ([/path/to/file|HANDLE])

Write modifications to the configuration file. If a path to a file is given, save the modification to this file instead. You also can give a reference to a filehandle like this :

$conf->save(\*MYHANDLE) or die($conf->error);

add_section (name=>'value', [-before=>target | -after=>target | -ontop | -onbottom])

$obj->add_section(foo=>'bar', -after=>$obj->directive('oof', -which=>-1));

Add the directive foo with value bar in the context pointed by $obj.

Aguments:

name

Section's name to add.

value

Value associated with this section's name

-before=>target

insert section one line before target if is in same context;

-after=>target

insert section one line after target if is in same context;

-ontop

insert section on the fist line of current context;

-onbottom

insert section on the last line of current context;

Return the added section

section ([[name], value], [-which=>number])

@sections_list      = $obj->section;
@section_values     = $obj->section(SectionName);
$section_object     = $obj->section(SectionName=>'value');

arguments:

- name

the name of section, it's File in section <File "/path/to/file">

- value

the value of the section

This method return :

-

list of sections in current context if no argument is given.

-

list of sections foo's values if the only argument is foo.

return a list in list context and a reference to an array in scalar context.

-

an object for the context pointed by the section foo with value bar if arguments given was foo and bar.

add_directive (name=>'value', [-before=>target | -after=>target | -ontop | -onbottom])

$obj->add_directive(foo=>'bar', -after=>$obj->directive('oof', -which=>-1));

Add the directive foo with value bar in the context pointed by $obj.

Aguments:

name

Directive's name to add.

value

Value associated with this directive's name

-before=>target

insert directive one line before target if is in same context;

-after=>target

insert directive one line after target if is in same context;

-ontop

insert directive on the fist line of current context;

-onbottom

insert directive on the last line of current context;

Return the added directive.

directive ([[name], value], [-which=>number])

@directives_list    = $obj->directive;
@directive_values   = $obj->directive(Foo);
$directvie_object   = $obj->directive(Foo=>'bar');

Arguments:

name

the name of directive.

value

value of the directive.

This method return :

-

list of directives in context pointed by $obj if no argument is given.

return a list in list context and a reference to an array in scalar context.

-

list of foo directive's values if the only argument is foo.

return a list in list context and a reference to an array in scalar context.

-

an object for handling directive called foo with value bar if arguments given was foo and bar. Warning, if several directive have the same name and value, the last one is taken, may change in future versions.

delete ()

$htconf->directive('AddType'=>'.pl')->delete;
$htconf->section('File'=>'/path/to/file')->delete;

Delete the current context pointed by object. Can be directive or section.

set_value (newvalue)

$htconf->directive('File'=>'/path/to/foo')->set_value('/path/to/bar');

Change the value of a directive or section. If no argument given, return the value of object $htconf.

value ()

Return the value of rule pointed by the object if any.

(value and set_value are the same method)

move (-before=>target | -after=>target | -replace=>target | -tofirst | -tolast)

under construction

name ()

Return the name of the current pointed directive or section. return undef if object point to the top context:

my $obj = new Apache:Admin::Config ("/path/to/file");

$obj->name; return undef
$obj->directive(-which=>0)->name; return first directive's name
$obj->section(Foo, -which=>0)->name; return "Foo"

lines ()

  • If the caller object point to a directive :

    Return a list of lines'number occuped by the object's directive. If more than one line'number is return, that's mean the directive is truncated on serveral lines :

    18. DirectoryIndex  index.html \
19.                 index.shtml \
20.                 index.pl \
...

$obj->directive(DirectoryIndex, -which=>x)->line # return (18, 19, 20)

  • If the caller object point to a section :

    Return a list of arrayref where all odd indexes are sections-opening and pair are sections-closing. Each arrayref conteints a list of lines'number occuped by the section rule (if section rule truncated).

    18. <VirtualHost 127.0.0.1 \
19.              10.20.30.40 \
20.              197.200.30.40>
21.     ServerName example.com
22. </VirtualHost>
...
50. <VirtualHost 127.0.0.1 10.20.30.40 197.200.30.40>
51.     ServerAlias www.example.com
52.     User        rs
53. </VirtualHost>

$obj->directive(VirtualHost, -which=>x)->lines # return ([18, 19, 20], [22], [50], [53])

first_line ()

last_line ()

dump_line line_number

$obj->dump_line($directive->first_line);

Dump the line_number line of current parsed configuration.

isin ($section_obj, [-recursif])

Return true if object point to a rule that is in the section represented by $section_obj. If -recursif option is present, true is also return if object is a sub-section of target.

<section target>
    <sub section>
        directive test
    </sub>
</section>

$test_directive->isin($target_section)              => return false
$test_directive->isin($sub_section)                 => return true
$test_directive->isin($target_section, '-recursif') => return true

parent ()

Return the parent context of object.

$obj is same as $obj->directive(-which=>0)->parent

type ()

Return the type of object. Types can be 'directive', 'section' or 'top'.

error ()

Return the last append error.

AUTHOR

Olivier Poitrey <rs@rhapsodyk.net>

AVAILABILITY

The official FTP location is :

ftp://ftp.rhapsodyk.net/pub/devel/perl/Apache-Admin-Config-current.tar.gz

Also available on CPAN.

LICENCE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc. :

59 Temple Place, Suite 330, Boston, MA 02111-1307

COPYRIGHT

Copyright (C) 2001 - Olivier Poitrey