Scott Wiersdorf > Config-Savelogs-0.11 > Config::Savelogs

Download:
Config-Savelogs-0.11.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.11   Source  

NAME ^

Config::Savelogs - Read and write savelogs configuration files

SYNOPSIS ^

  use Config::Savelogs;
  my $conf = new Config::Savelogs('/etc/savelogs.conf');
  $conf->add_group( ApacheHost => [ 'new.domain.name5', 'new.domain.name6' ],
                    Period     => 10,
                    Chown      => 'phil' );
  $conf->remove_group( match => { ApacheHost => 'new.domain.name8' } );
  $conf->write;

DESCRIPTION ^

This module is for reading and writing savelogs configuration files. Their format is described in the savelogs manual that comes with savelogs.

new

Creates a new config object. If you pass in the name of a file that exists, it will be parsed. This also sets the object's internal filename (used in write).

  ## empty object
  $conf = new Savelogs::Config

  ## read from a file
  $conf = new Savelogs::Config('/etc/savelogs.conf');

read

If you didn't pass in a filename to new, you can instantiate an empty object and populate it with the contents of a config file with this method.

  $conf->read('/etc/savelogs.conf');

file

Returns the name of the file we're writing to by default. This is set in the new constructor, the read or write methods. You may pass in a filename to file also to set the filename.

  ## style 1
  print "Writing to " . $conf->file . "\n";

  ## style 2
  $conf->file('/tmp/newfile.conf');

set

Sets internal properties of a config object.

  $conf->set( ApacheConf => '/usr/local/apache/conf/httpd.conf',
              PostMoveHook => 'apachectl graceful',
              groups => [ { ApacheHost => [ 'www.foo.com', 'www.bar.com' ],
                            Period     => 5,
                            Touch      => 0 },
                          { ApacheHost => [ 'www.domain.name1' ],
                            Period     => 8 } ] );

This creates a config file that looks like this:

  ApacheConf    /usr/local/apache/conf/httpd.conf
  PostMoveHook  /bin/true
  
  <Group>
    ApacheHost  www.foo.com
    ApacheHost  www.bar.com
    Period      5
    Touch       0
  </Group>

  <Group>
    ApacheHost  www.domain.name1
    Period      8
  </Group>

add_group

Adds a new group to the existing object.

  $conf->add_group( ApacheHost => 'new.domain.name',
                    Period     => 10 );

You may add multiple ApacheHost or Log directives:

  $conf->add_group( Log    => [ 'domain1.tld', 'domain2.tld' ],
                    Period => 30 );

remove_group

Removes a group from the config object. Because groups don't have a unique identifier, you have to specify match criteria to determine the group you're referring to. All matching groups are removed.

  ## remove any group containing an ApacheHost of 'www.somewhere.tld'
  $conf->remove_group( match => { ApacheHost => 'www.somewhere.tld' } );

find_group

Returns a reference to a group as a hashref. This reference may be manipulated. As long as the original reference is intact (you don't make a deep copy of the object), changes you make to this reference will be reflected in the object.

  $group = $conf->find_group( match => { Chown => 'fred' } );
  $group->{chown} = 'phil';
  $conf->write;

add_to_group

Adds an ApacheHost directive to a group. In the future, this will add any multiple directive (Log, etc.) to a group.

  $conf->add_to_group( match => { ApacheHost => 'foo.com' },
                       apachehost => 'foo.net' );

remove_from_group

Removes an ApacheHost directive from a group. In the future, this will remove any multiple directive (Log, etc.) from a group.

If at the time when the data method is invoked the group has no ApacheHost or Log directives, that group will be removed completely.

  $conf->remove_from_group( match => { Period => 30, Chown => 'mike' },
                            apachehost => 'foo.net' );

data

Returns a convenience reference to the configuration file as a hash reference. This works like find_group except you get the whole enchilada. During this method, each group is checked for sanity and any group caught without an ApacheHost or Log directive is removed from the groups list.

  my $data = $conf->data;

  $data = {
    'apacheconf' => '/www/conf/httpd.conf',
    'postmovehook' => '/bin/true'
    'groups' => [
                  {
                    'period' => '5',
                    'touch' => '0',
                    'apachehost' => [
                                      'www.foo.com',
                                      'www.bar.com'
                                    ]
                  },
                  {
                    'period' => '8',
                    'apachehost' => [
                                      'www.domain.name1'
                                    ]
                  }
                ],
  }

The hash keys will be downcased.

It's currently best if you don't manipulate this structure other than to find what you're looking for. Please use the provided methods to alter the data.

is_dirty

Returns whether the current object is changed from its original state.

  print "config file changed" if $cs->is_dirty;

revert

Reverts the object back to its state after the last read or write. If called on an object that wasn't initialized from a file, it will reset the object to an empty state.

  $cs = new Config::Savelogs('/some/file.conf');
  ... make changes ...
  $cs->revert;  ## puts it back how it was when we read from /some/file.conf

Or:

  $cs = new Config::Savelogs('/some/file.conf');
  ... make changes ...
  $cs->write;     ## remember this!
  ... make more changes ...
  $cs->revert;    ## goes back to state at 'remember this!'

write

Writes the config object to file. If a filename was specified in new or read, it will use that file. Otherwise (or additionally), you may specify a file name to write to a new file.

write does pretty-printing, including whitespace and word casing.

  ## writes to the last file the object
  ## was read from or initialized with
  $conf->write;

  ## writes to a specific location
  $conf->write('/etc/savelogs.new.conf');

Group references ^

When you call find_group you get a hashref back, which you may manipulate. This hashref looks like this:

  {
    'period' => '10',
    'apachehost' => [
                      'new.domain.name5',
                      'new.domain.name6',
                      'new.domain.name7'
                    ],
    'chown' => 'phil'
  }

Group directives which may appear multiple times (ApacheHost, Log, ApacheLogExclude, and NoLog) will have arrayref values, all others will be scalars.

The keys will always be downcased.

SEE ALSO ^

savelogs

AUTHOR ^

Scott Wiersdorf, <scott@perlcode.org>

COPYRIGHT AND LICENSE ^

Copyright (C) 2009 by Scott Wiersdorf

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.

syntax highlighting: