Apache::Admin::Config 0.53
==========================
INSTALLATION
To install this module type the following:
perl Makefile.PL
make
make test
make install
UPGRADING FROM PREVIOUS VERSIONS
* Upgrading from version 0.08 or earlier: read UPGRADE-0.10
CHANGES
0.53 Mon Jul 15 14:36:56 CEST 2002
- Bugfix in saveas method
0.52 Mon Jul 15 14:01:11 CEST 2002
- Correct a big memory leak problem (thanks to Scott Beck)
- Misc bugfix
0.51 Fri Jun 7 19:12:02 CEST 2002
- Bugfix in select method
0.50 Fri Jun 7 18:25:39 CEST 2002
- Many major bugfix
- Complete rewrite of module with new algorithm
- Homogenisation of API (may distrub you old applications !)
- No longer support old API (-oldapi option)
- Now, all methods are overloaded to return its value, but
using overloading feature is really deprecated
- New: support indentation
- New: can handle comment and blank lines
- New methods : add, select
add_comment, comment
add_blank, blank
- Upgrade documentation
- Optimisations, it's now very fast ! =)
0.21 Mon Jun 3 16:39:41 2002
- Major bugfix: correction of the behavior of the parameters
'-ontop', '-onbottom', '-after' and '-before' in methods
'add_directive' and 'add_section'.
0.20 Mon Jun 3 11:03:05 2002
- Many major bugfix
- Algorithm rewriten, it's 65 times faster !
0.16 Thu Apr 11 16:44:53 2002
- Major bugfix: no longer merging namespace of identical
sections (same name/value)
0.15 Tue Dec 11 14:18:07 2001
- Minor bugfix: add_(section|directive) with option -onbottom
were dont work properly
- Added dump_raw() method
0.14 Sat Dec 8 14:14:50 2001
- Major bugfix that cause an endless loop in the constructor
with perl 5.005 and maybe 5.6
- Some corrections in error messages
0.13 Thu Dec 6 11:26:05 2001
- Fix compatibility problem with perl 5.005, thinks to
Anton Berezin
- Bigfix, error when add_(directive|section) on an empty
file
0.12 Sun Nov 11 10:49:40 2001
- New feature: you now can pase a file handle to the constructor
new() and the save() method instead of a path (thanks to
Peter Suschlik for his patch).
0.11 Thu Oct 25 20:57:52 2001
- Bugfix in add_section method. add_section will add entries
before the last context's section line.
0.10 Thu Oct 12 02:36:17 2001
- Bugfix in test scripts, that makes test fail randomly
- Major feature enhancements
(DIRECTIVE|SECTION) METHOD
- directive() now returns full list of directives, sorted
as it comes in the file. Each element of this list is
an object that points to the directive entry.
- directive(Foo) also returns a full list of value of all
"Foo" directive in current context, also sorted as it comes
in the file. Each list's element is also an object that
points to the directive entry.
- directive(Foo, Bar) returns an object that points to the
last directive (if more than one) wich has the same
directive's name/value. In list context, it returns the
full list of same directive's name/value.
- directive() can now takes the -which=>N parameter to
select the entry's number to return (if exists).
ADD_(DIRECTIVE|SECTION) METHOD
- can take 4 parameters:
- -before=>target where target is an Apache::Admin::Config
object, that points to a section or directive of the same
context than add_directive() method's object caller. The
directive if added just before the target.
- -after=>target idem but after the target.
- -ontop added on the top of current context.
- -onbottom added on the bottom of current context.
- Internal parser modification that allows a section to have
same name than a directive in the same context without no clash.
- New methods (see documentation for more details):
- first_line: return the first line of rule pointed by caller object
- last_line: return the last
- lines: return all lines occuped by the rule
- dump_line: dump a line
- isin: true if caller object is in the same context than one given in argument
- type: return the type of caller object
- name: return the name of caller object
- API had change, so contructor can take the -oldapi=>1 argument for
a backward compatibility
0.07 Thu Sep 20 02:36:17 2001
- Major change, section and directive methods no any longer
return an arrayref in list context but a simple list.
Documentation corrected (thanx to Nathan Wiger for this
suggestion).
0.06 Tue Sep 18 01:09:24 2001
- Make a quick and dirty documentation
- value() return the context value if no arguments given
- new() can be called without argument, save() need an
argument in this case
0.05 Sat Aug 18 14:39:45 2001
- Major bug fix, if config file wasn't exists, module won't work !
- Bug fix, value method wasn't took the appropriate value for change
it, resulted to an unchanged value
- Bug fix, $master and $root value was undefined in value method,
so value wasn't work at all
0.04 Fri Aug 17 01:42:16 2001
- Fix a minor bug in directive method.
0.03 Fri Aug 17 01:07:17 2001
- Fix a major bug in directive method.
0.02 Thu Aug 16 01:48:54 2001
- Put module on CPAN
- Fix a very major bug that cause "syntax error" from parser on
directives with no value like "clearmodulelist", thanx A2 for
this report.
0.01 Sun Aug 12 11:58:10 2001
- Original version; created by h2xs 1.21 with options -AX -n Apache::Admin
NAME
Apache::Admin::Config - A common module to manipulate Apache
configuration files
SYNOPSIS
use Apache::Admin::Config;
# Parse an apache configuration file
my $conf = new Apache::Admin::Config "/path/to/config_file.conf"
or die $Apache::Admin::Config::ERROR;
# or parse a filehandle
open(ANHANDLE, "/path/to/a/file")...
my $conf = new Apache::Admin::Config \*ANHANDLE
or die $Apache::Admin::Config::ERROR;
...
# Directive method called without any argument, return a list
# of all directive located in the current context.
my @directives_list = $conf->directive;
# This method returns a list of object (one object by directive)
# sorted by order of apparence in the file.
# You can easly get the 3th directive of the context
my $directive = $directives_list[2];
# or
my $directive = $conf->directive(-which=>2);
# Then, you can manipulate object like this
if(defined $directive)
{
print $directive->name; # "documentroot"
print $directive->value; # "/my/document/root"
print $directive->type; # "directive"
$directive->isin($conf); # true
...
$directive->delete;
}
# this print all current context's directives names
foreach($conf->directive)
{
print $_->name, "\n";
}
# You want get all directives of current context who's name is "Foo",
# juste give the string "Foo" at first argument to methode `directive' :
my @foo_directives = $obj->directive('Foo');
# or just the 4th
my $4th_foo_directive = $obj->directive('Foo', -which=>4);
# you may want all directives named "Foo" but with value "Bar", so
# give the wanted value as second argument to `directive' :
my @foo_bar_directives = $conf->directive(Foo=>'Bar');
# or just the last one in scalar context
my $foo_bar_directive = $conf->directive(Foo=>'Bar');
# or the second one if "-which" option is given.
my $foo_bar_directive = $conf->directive(Foo=>'Bar', -which=>2);
# Working on directive "PidFile" :
#
# getting the last pidfile directive
my $pidfile = $conf->directive('PidFile');
# changing its value to '/var/run/apache.pid'
my $pidfile_value = '/var/run/apache.pid';
if(defined $pidfile)
{
$pidfile->set_value($pidfile_value)
unless $pidfile->value eq $pidfile_value;
}
else
{
$conf->add_directive(PidFile => $pidfile_value);
}
# Deleting all directives "AddType"
foreach($conf->directive(AddType))
{
$_->delete;
}
# Adding directive "AddType text/html .shtml" just after the last AddType directive if any
# or at the end of file (or section)
my $last_addtype = $obj->directive('AddType', -which=>-1);
if(defined $last_addtype)
{
$conf->add_directive(AddType => 'text/html .shtml', -after=>$last_addtype);
}
else
{
$conf->add_directive(AddType => 'text/html .shtml', '-bottom');
}
# You can get a directive located in a section like this
my $section = $conf->section(Foo=>'Bar');
my $subdirective;
if(defined $section)
{
$subdirective = $section->directive(Bar=>'foo');
}
# saving changes in place
$conf->save;
# or in another file (sound like "save as...")
$conf->save("/path/to/another/file");
# or in an already openned file
$conf->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
$obj = new Apache::Admin::Config [/path/to/file|handle], [-indent => $integer]
Create or read, if given in argument, an apache like configuration file,
and return an Apache::Admin::Config instence.
Arguments:
*"/path/to/file"*
Path to the configuration file to parse. If none given, create a new
one.
*"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 $obj = new Apache::Admin::Config (\*MYHANDLE);
*-indent* => *$integer*
If greater than 0, activates the indentation on added lines, the
integer tell how many spaces you went per level of indentation
(suggest 4). A negative value means padding with tabulation(s).
SAVE
$obj->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);
DUMP_RAW
$obj->dump_raw
Returns the configuration file as same as it will be if it saved in a
file with the save() method. If you don't call this method from the top
level section, it returns the part of the configuration file that is
under the object's context.
SELECT
$obj->select
(
[-type => $type],
[-name => $name],
[-value => $value],
[-which => $index],
);
@directives = $obj->select('directive');
@sections_foo = $obj->select('section', 'Foo');
This method search in the current context for items (directives,
sections, comments...) that correspond to a properties given by
arguments. It returns a list of matched objects.
This method can only be called on an object of type "section". This
method search only for elements in the section pointed by object, and
isn't recursive. So elements in sub-sections of current section aren's
seek.
Arguments:
"type"
The type of searched item.
"name"
The name of item.
"value"
Value of item.
"which"
Instead of returns a list of objects, returns only ones pointed by
index given to the -which option. Caution, returns an empty string
if none selected, so don't cascade your methodes calls like
$obj->select(-which=>0)->name.
Method returns a list of object(s) founds.
DIRECTIVE
$obj->directive(args...)
Same as calling select('directive', args...)
SECTION
$obj->section(args...)
Same as calling select('section', args...)
COMMENT
$obj->comment(args...)
Same as calling select('comment', args...)
BLANK
$obj->blank(args...)
Same as calling select('blank', args...)
ADD
$obj->add
(
$type, [$name], [$value],
[-before => $target | -after => $target | '-ontop' | '-onbottom']
);
$obj->add('section', foo => 'bar', -after => $conf_item_object);
$obj->add('comment', 'a simple comment', '-ontop');
Add a line of type *$type* with name *foo* and value *bar* in the
context pointed by $object.
Aguments:
"type"
Type of object to add (directive, section, comment or blank)
"name"
Only relevant for directives and sections.
"value"
For directive and section, it defines the value, for comments it
defined the text.
"-before" => *target*
Inserts item one line before *target*. *target* _have_ to be in the
same context
"-after" => *target*
Inserts item one line after *target*. *target* _have_ to be in the
same context
"-ontop"
Insert item on the fist line of current context;
"-onbottom"
Iinsert item on the last line of current context;
Returns the added item
ADD_SECTION
$obj->add_section(args...)
Same as calling add('section', args...)
ADD_DIRECTIVE
$obj->add_directive(args...)
Same as calling add('directive', args...)
ADD_COMMENT
$obj->add_comment(args...)
Same as calling add('comment', args...)
ADD_BLANK
$obj->add_blank(args...)
Same as calling add('blank', args...)
DELETE
$item->delete;
Delete the current context pointed by object. Can be directive or
section.
SET_VALUE
$obj->set_value($newvalue)
Change the value of a directive or section. If no argument given, return
the value.
VALUE
Return the value of rule pointed by the object if any.
("value" and "set_value" are the same method)
MOVE
$obj->move
(
-before => target |
-after => $target |
-replace => $target |
'-ontop' |
'-onbottom'
)
not yet implemented
FIRST_LINE
LAST_LINE
ISIN
$obj->($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.
$test_directive->isin($target_section) => return false
$test_directive->isin($sub_section) => return true
$test_directive->isin($target_section, '-recursif') => return true
NAME
Returns the name of the current pointed object if any
PARENT
Returns the parent context of object. This method on the top level
object returns "undef".
TYPE
Returns the type of object.
ERROR
Return the last append error.
EXAMPLES
#
# Managing virtual-hosts:
#
my $conf = new Apache::Admin::Config "/etc/apache/httpd.conf";
# adding a new virtual-host:
my $vhost = $conf->add_section(VirtualHost=>'127.0.0.1');
$vhost->add_directive(ServerAdmin=>'webmaster@localhost.localdomain');
$vhost->add_directive(DocumentRoot=>'/usr/share/www');
$vhost->add_directive(ServerName=>'www.localhost.localdomain');
$vhost->add_directive(ErrorLog=>'/var/log/apache/www-error.log');
my $location = $vhost->add_section(Location=>'/admin');
$location->add_directive(AuthType=>'basic');
$location->add_directive(Require=>'group admin');
$conf->save;
# selecting a virtual-host:
my $vhost;
foreach my $vh (@{$conf->section('VirtualHost')})
{
if($vh->directive('ServerName')->value eq 'www.localhost.localdomain')
{
$vhost = $vh;
last;
}
}
#
# Suppress all comments in the file
#
sub delete_comments
{
foreach(shift->comment)
{
$_->delete;
}
}
sub delete_all_comments
{
foreach($_[0]->section)
{
parse_all($_);
}
delete_comments($_[0]);
}
delete_all_comments($conf);
AUTHOR
Olivier Poitrey
AVAILABILITY
The official FTP location is:
ftp://ftp.rhapsodyk.net/pub/devel/perl/Apache-Admin-Config-current.tar.g
z
Also available on CPAN.
anonymous CVS repository:
CVS_RSH=ssh cvs -d anonymous@cvs.rhapsodyk.net:/devel co
Apache-Admin-Config
(supply an empty string as password)
CVS repository on the web:
http://www.rhapsodyk.net/cgi-bin/cvsweb/Apache-Admin-Config/
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
NAME
Apache::Admin::Config - A common module to manipulate Apache
configuration files
SYNOPSIS
use Apache::Admin::Config;
# Parse an apache configuration file
my $conf = new Apache::Admin::Config "/path/to/config_file.conf"
or die $Apache::Admin::Config::ERROR;
# or parse a filehandle
open(ANHANDLE, "/path/to/a/file")...
my $conf = new Apache::Admin::Config \*ANHANDLE
or die $Apache::Admin::Config::ERROR;
...
# Directive method called without any argument, return a list
# of all directive located in the current context.
my @directives_list = $conf->directive;
# This method returns a list of object (one object by directive)
# sorted by order of apparence in the file.
# You can easly get the 3th directive of the context
my $directive = $directives_list[2];
# or
my $directive = $conf->directive(-which=>2);
# Then, you can manipulate object like this
if(defined $directive)
{
print $directive->name; # "documentroot"
print $directive->value; # "/my/document/root"
print $directive->type; # "directive"
$directive->isin($conf); # true
...
$directive->delete;
}
# this print all current context's directives names
foreach($conf->directive)
{
print $_->name, "\n";
}
# You want get all directives of current context who's name is "Foo",
# juste give the string "Foo" at first argument to methode `directive' :
my @foo_directives = $obj->directive('Foo');
# or just the 4th
my $4th_foo_directive = $obj->directive('Foo', -which=>4);
# you may want all directives named "Foo" but with value "Bar", so
# give the wanted value as second argument to `directive' :
my @foo_bar_directives = $conf->directive(Foo=>'Bar');
# or just the last one in scalar context
my $foo_bar_directive = $conf->directive(Foo=>'Bar');
# or the second one if "-which" option is given.
my $foo_bar_directive = $conf->directive(Foo=>'Bar', -which=>2);
# Working on directive "PidFile" :
#
# getting the last pidfile directive
my $pidfile = $conf->directive('PidFile');
# changing its value to '/var/run/apache.pid'
my $pidfile_value = '/var/run/apache.pid';
if(defined $pidfile)
{
$pidfile->set_value($pidfile_value)
unless $pidfile->value eq $pidfile_value;
}
else
{
$conf->add_directive(PidFile => $pidfile_value);
}
# Deleting all directives "AddType"
foreach($conf->directive(AddType))
{
$_->delete;
}
# Adding directive "AddType text/html .shtml" just after the last AddType directive if any
# or at the end of file (or section)
my $last_addtype = $obj->directive('AddType', -which=>-1);
if(defined $last_addtype)
{
$conf->add_directive(AddType => 'text/html .shtml', -after=>$last_addtype);
}
else
{
$conf->add_directive(AddType => 'text/html .shtml', '-bottom');
}
# You can get a directive located in a section like this
my $section = $conf->section(Foo=>'Bar');
my $subdirective;
if(defined $section)
{
$subdirective = $section->directive(Bar=>'foo');
}
# saving changes in place
$conf->save;
# or in another file (sound like "save as...")
$conf->save("/path/to/another/file");
# or in an already openned file
$conf->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
$obj = new Apache::Admin::Config [/path/to/file|handle], [-indent => $integer]
Create or read, if given in argument, an apache like configuration file,
and return an Apache::Admin::Config instence.
Arguments:
*"/path/to/file"*
Path to the configuration file to parse. If none given, create a new
one.
*"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 $obj = new Apache::Admin::Config (\*MYHANDLE);
*-indent* => *$integer*
If greater than 0, activates the indentation on added lines, the
integer tell how many spaces you went per level of indentation
(suggest 4). A negative value means padding with tabulation(s).
SAVE
$obj->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);
DUMP_RAW
$obj->dump_raw
Returns the configuration file as same as it will be if it saved in a
file with the save() method. If you don't call this method from the top
level section, it returns the part of the configuration file that is
under the object's context.
SELECT
$obj->select
(
[-type => $type],
[-name => $name],
[-value => $value],
[-which => $index],
);
@directives = $obj->select('directive');
@sections_foo = $obj->select('section', 'Foo');
This method search in the current context for items (directives,
sections, comments...) that correspond to a properties given by
arguments. It returns a list of matched objects.
This method can only be called on an object of type "section". This
method search only for elements in the section pointed by object, and
isn't recursive. So elements in sub-sections of current section aren's
seek.
Arguments:
"type"
The type of searched item.
"name"
The name of item.
"value"
Value of item.
"which"
Instead of returns a list of objects, returns only ones pointed by
index given to the -which option. Caution, returns an empty string
if none selected, so don't cascade your methodes calls like
$obj->select(-which=>0)->name.
Method returns a list of object(s) founds.
DIRECTIVE
$obj->directive(args...)
Same as calling select('directive', args...)
SECTION
$obj->section(args...)
Same as calling select('section', args...)
COMMENT
$obj->comment(args...)
Same as calling select('comment', args...)
BLANK
$obj->blank(args...)
Same as calling select('blank', args...)
ADD
$obj->add
(
$type, [$name], [$value],
[-before => $target | -after => $target | '-ontop' | '-onbottom']
);
$obj->add('section', foo => 'bar', -after => $conf_item_object);
$obj->add('comment', 'a simple comment', '-ontop');
Add a line of type *$type* with name *foo* and value *bar* in the
context pointed by $object.
Aguments:
"type"
Type of object to add (directive, section, comment or blank)
"name"
Only relevant for directives and sections.
"value"
For directive and section, it defines the value, for comments it
defined the text.
"-before" => *target*
Inserts item one line before *target*. *target* _have_ to be in the
same context
"-after" => *target*
Inserts item one line after *target*. *target* _have_ to be in the
same context
"-ontop"
Insert item on the fist line of current context;
"-onbottom"
Iinsert item on the last line of current context;
Returns the added item
ADD_SECTION
$obj->add_section(args...)
Same as calling add('section', args...)
ADD_DIRECTIVE
$obj->add_directive(args...)
Same as calling add('directive', args...)
ADD_COMMENT
$obj->add_comment(args...)
Same as calling add('comment', args...)
ADD_BLANK
$obj->add_blank(args...)
Same as calling add('blank', args...)
DELETE
$item->delete;
Delete the current context pointed by object. Can be directive or
section.
SET_VALUE
$obj->set_value($newvalue)
Change the value of a directive or section. If no argument given, return
the value.
VALUE
Return the value of rule pointed by the object if any.
("value" and "set_value" are the same method)
MOVE
$obj->move
(
-before => target |
-after => $target |
-replace => $target |
'-ontop' |
'-onbottom'
)
not yet implemented
FIRST_LINE
LAST_LINE
ISIN
$obj->($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.
$test_directive->isin($target_section) => return false
$test_directive->isin($sub_section) => return true
$test_directive->isin($target_section, '-recursif') => return true
NAME
Returns the name of the current pointed object if any
PARENT
Returns the parent context of object. This method on the top level
object returns "undef".
TYPE
Returns the type of object.
ERROR
Return the last append error.
EXAMPLES
#
# Managing virtual-hosts:
#
my $conf = new Apache::Admin::Config "/etc/apache/httpd.conf";
# adding a new virtual-host:
my $vhost = $conf->add_section(VirtualHost=>'127.0.0.1');
$vhost->add_directive(ServerAdmin=>'webmaster@localhost.localdomain');
$vhost->add_directive(DocumentRoot=>'/usr/share/www');
$vhost->add_directive(ServerName=>'www.localhost.localdomain');
$vhost->add_directive(ErrorLog=>'/var/log/apache/www-error.log');
my $location = $vhost->add_section(Location=>'/admin');
$location->add_directive(AuthType=>'basic');
$location->add_directive(Require=>'group admin');
$conf->save;
# selecting a virtual-host:
my $vhost;
foreach my $vh (@{$conf->section('VirtualHost')})
{
if($vh->directive('ServerName')->value eq 'www.localhost.localdomain')
{
$vhost = $vh;
last;
}
}
#
# Suppress all comments in the file
#
sub delete_comments
{
foreach(shift->comment)
{
$_->delete;
}
}
sub delete_all_comments
{
foreach($_[0]->section)
{
parse_all($_);
}
delete_comments($_[0]);
}
delete_all_comments($conf);
AUTHOR
Olivier Poitrey
AVAILABILITY
The official FTP location is:
ftp://ftp.rhapsodyk.net/pub/devel/perl/Apache-Admin-Config-current.tar.g
z
Also available on CPAN.
anonymous CVS repository:
CVS_RSH=ssh cvs -d anonymous@cvs.rhapsodyk.net:/devel co
Apache-Admin-Config
(supply an empty string as password)
CVS repository on the web:
http://www.rhapsodyk.net/cgi-bin/cvsweb/Apache-Admin-Config/
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