NAME

RSH::ConfigFile - Configuration File

SYNOPSIS

  use RSH::ConfigFile;

  my $config = new RSH::ConfigFile filename => 'foo.config';
  $config->load();
  my $setting = $config->{setting};
  $config->{setting} = 'new value';
  $config->save();

ABSTRACT

  RSH::ConfigFile is a configuration file that uses standard text
  'key = value' lines, where value can be a string, an array, or
  a hash.

DESCRIPTION

While using XML and YAML are both possible solutions for a config file syntax, both suffer from having very specific syntax, punctuation, or whitespace requirements. This module seeks to use a simple, more robust config file syntax. In addition to having simple "key = value" syntax, values can also be more complex structures.

This format is not a replacement for XML, YAML, or dump formats. It seeks to be simple and readable while providing the ability to specify slightly more complicated values then just plain strings.

EXPORT

None by default.

CLASS METHODS

serialize_value()

Converts the value into a string.

unserialize_value()

Tries to unserialize a string into a value.

load_config()

Factory method; takes a filename, creates a config object, and loads from the file, returning the freshly loaded config object.

CONSTRUCTORS

new(%ARGS)

Creates a new RSH::ConfigFile object. %ARGS contains arguments to use in initializing the new instance.

Params:

  filename => filename to load from
  default  => reference to a hash to use for default values 
            (will not be saved to file)
  values   => reference to a hash to use for values

Returns: A new RSH::ConfigFile object.

INSTANCE METHODS

Accessors

is_dirty()

Read-only accessor for the object's dirty flag. The dirty flag is set whenever a value is changed for the object's hash values.

filename()

Read-write accessor for filename attribute

error()

Read-only accessor for error attribute. Error is set when an error occurs on save or load. If a load or save returns false for success, you can check this attribute for the reason why.

warning()

Read-only accessor for warning attribute. Warning is set when an warning occurs on save or load. If a load or save returns false for success, you can check this attribute for the reason why.

md5()

Read-only accessor for md5 attribute.

no_follow()

Read-only accessor for no_follow attribute.

no_quotes()

Read-only accessor for no_quotes attribute.

compact()

Read-only accessor for compact attribute.

Functionality

load()

Loads the configuration object from a filename.

Params:

  filename => (optional) the file to load from

returns: 1 on success, 0 on failure, with exceptions for exceptionally bad errors

save()

Saves the values in this config object to the file. If the file exists, formatting will be preserved, with new values being added at the end.

Params: filename - (optional) the file to save to force - (optional) 1, force save, 0, rely on dirty flag; method assumes force => 0

returns: 1 on success, 0 on failure, with exceptions for exceptionally bad errors

remove()

Removes the config file.

string()

Returns a string representation of the object. This is useful for debugging. It is NOT suitable to be used for serializing the object. Use save for that.

get_hash()

Returns the 'hash' hash reference.

Ok, this is a bit confusing if you haven't read the overload manpage, and still confusing if you haven't tried it ;-)

The overload maps all attempts to use this object reference as a hash to this method. So, $config->{key} will actually call this method--and what this method does is return the hash table reference in 'hash'. So, a quick step by step is as follows:

$config->{key} ==> get_hash($config) ==> (returns 'hash') ==> ('hash')->{key}

So this method returns the hash, which is in turn accessed for the key 'key'. Neat and confusing, no?

SEE ALSO

http://www.rshtech.com/software/

AUTHOR

Matt Luker <mluker@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2003-2008 by Matt Luker

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.