view release on metacpan or  search on metacpan

lib/Config/Trivial.pm  view on Meta::CPAN

  my $colour = $config->read('colour');

Each call to read will make the module re-read and parse the configuration file.
If you want to re-read data from the oject use the get_configuration method.

=head2 get_configuration

This method simply returns the value requested or a hash reference
of the configuration data. It does NOT perform a re-read of the
data on the disk.

  $settings = $config->get_configuration;

or

  $colour = $config->get_configuration{'colour'};

If your configuration data is from muliple files, then passing a key
will return a hash reference of the "key" file requested rather than
an indiviudal value.

=head2 multi_read

This method is used to read a multiple set of configutaion files in one go.

  my $settings = $config->multi_read;

Alternativly you can return just one hash of one configutation file with.

  my $master = $config->multi_read('master_config');

=head2 set_configuration

If you need to set the configuration object with data you can
pass in a reference to a hash with this method. Any existing
data will be over-written. Returns false on failure.

  $config->set_configuration(\%settings);

or

  $config->set_configuration($hash_ref);

=head2 write

The write method simply writes the configuration hash back out
to the configuration file. It will try to not write to a file if
it has the same filename of the script that called it. This can
easily be bypassed, and bad things will happen!

There are two optional parameters that can be passed, a file
name to use instead of the current one, and a reference of a
hash to write out instead of the currently loaded one.

  $config->write(
    config_file => '/path/to/somewhere/else',
    configuration => $settings);

The method returns true on success. If the file already exists
then it is backed up first. The write is not 'atomic' or
locked for reading in anyway. If the file cannot be written to
then it will die.

Configuration data passed by this method is only written to
file, it is not stored in the internal configuration object.
To store data in the internal use the set_configuration data
method. The option to pass a hash_ref in this method may
be removed in future versions.

=head2 get_error

In normal operation the module will only die if it is unable to read
or write the configuration file, or an invalid file is set in the
constructor. Other errors are non-fatal. If an error occurs it can
be read with the get_error method. Only the most recent error is
stored.

  my $settings = $config->read();
  print get_error unless $settings;

=head1 CONFIG FORMAT

=head2 About The Configuration File Format

The configuration file is a plain text file with a simple structure. Each
setting is stored as a key value pair separated by the first space. Empty
lines are ignored and anything after a hash # is treated as a comment and
is ignored. Depending upon mode, duplicate entries will be silently ignored,
warned about, or cause the module to die.

At the moment this module does not encode or decode data, data remains
in perl native format.

All key names are forced into lower case when read in, values are left intact.

On write spaces in key names will either cause the script to die (strict),
blurt out a warning and substitute an underscore (debug), or silently change
to an underscore. Underscores in keys are NOT changed back to spaces on read.

If you delete a key/value pair it will not be written out when you do a write.
When a key has an undef value, the key will be written out with no matching
value. When you read a key with no value in, in debug mode you will get a warning.

You can continue configuration data over several lines, in a shell like manner,
by placing a backslash at the end of the line followed by a new line. White space
between the backslash and the new line will be ignored and also trigger line
continuation.

If you need to have a backslash at the end of your data, for example a windows
path, then place a # mark after your backslash.

=head2 Sample Configuration File

  #
  # This is a sample config file
  #

  value-0 is very \
  long so it's broken \
  over several lines
  value-1 is foo