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.

    <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

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 <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.

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 library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

COPYRIGHT

To install Apache::Admin::Config, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Apache::Admin::Config

CPAN shell

perl -MCPAN -e shell
install Apache::Admin::Config

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODES

NEW

SAVE

DUMP_RAW

SELECT

DIRECTIVE

SECTION

COMMENT

BLANK

ADD

ADD_SECTION

ADD_DIRECTIVE

ADD_COMMENT

ADD_BLANK

DELETE

SET_VALUE

VALUE

MOVE

FIRST_LINE

LAST_LINE

ISIN

NAME

PARENT

TYPE

ERROR

EXAMPLES

AUTHOR

AVAILABILITY

LICENCE

COPYRIGHT

Module Install Instructions