NAME
Config::Trivial - Very simple tool for reading and writing very simple configuration files
SYNOPSIS
use Config::Trivial;
my $config = Config::Trivial->new(config_file => 'path/to/my/config.conf');
my $settings = $config->read;
print "Setting Colour is:\t", $settings->{'colour'};
$settings->{'new-item'} = 'New Setting';DESCRIPTION
Use this module when you want use "Yet Another" very simple, light weight configuration file reader. The module simply returns a reference to a single hash for you to read configuration values from, and uses the same hash to write a new config file.
METHODS
new
The constructor can be called empty or with a number of optional parameters. If called with no parameters it will set the configuration file to be the file name of the file that called it.
$config = Config::Trivial->new();or
$config = Config::Trivial->new(
config_file => '/my/config/file',
debug => 'on',
strict => 'on',
no_check => 'on' );By default debug, strict and no_check are set to off. In debug mode messages and errors will be dumped automatically to STDERR. Normally messages and non-fatal errors need to be pulled from the error handler. In strict mode all warnings become fatal. Turning no_check on disables file tests which may slow the module down if used over a slow network to a NFS or CIFS filesystem.
If you set a file in the constructor that is invalid for any reason it will die in any mode - this may change in a later version.
set_config_file
The configuration file can be set after the constructor has been called. Simply set the path to the file you want to use as the config file. If the file does not exist or isn't readable the call will return false and set the error message.
$config->set_config_file("/path/to/file");You may also set a collection of configuration files by passing a reference to a hash. They keys will be used to extract data, and the values of the hash will contain the files that you wish to use.
%config_files = (
master_config => "/path/to/master.conf",
secondary_config => "/path/to/second/conf");
$config->set_config_file(\%config_files);read
The read method opens the file, and parses the configuration returning the results as a reference to an hash. If the file cannot be read it will die.
my $settings = $config->read;Alternatively if you only want a single configuration value you can pass just that key, and get back it's matching value.
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.
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.
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');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);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.
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;CONFIG FORMAT
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.
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
value-1 is bar
path \ #
__END__
value-1 is bazIf parsed the value of value-1 would be "is bar" in normal mode, issue a warning if in debug mode and die in strict mode. Everything after the __END__ will be ignored. value-0 will be "is very long so it's broken over several lines".
MISC
Prerequisites
At the moment the module only uses core modules. The test suite optionally uses POD::Coverage and Test::Pod, which will be skipped if you don't have them.
History
See Changes file.
Defects and Limitations
Patches Welcome... ;-)
https://rt.cpan.org/Dist/Display.html?Queue=Config-Trivial
To Do
Much better test suite.
Multi-write option
EXPORT
None.
AUTHOR
Adam Trickett, <atrickett@cpan.org>
SEE ALSO
perl, Config::Trivial::Storable, ConfigReader::Simple, Config::Ini, Config::General, Config::Tiny and Config::IniFiles.
LICENSE AND COPYRIGHT
Config::Trivial, Copyright Adam John Trickett 2004-2014
OSI Certified Open Source Software. Free Software Foundation Free Software.
This program 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 3 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 Lesser General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.