Config::JSON - A JSON based config file system.
This document describes Config::JSON version 1.1.4
use Config::JSON; my $config = Config::JSON->create($pathToFile); my $config = Config::JSON->new($pathToFile); my $element = $config->get($directive); $config->set($directive,$value); $config->delete($directive); $config->deleteFromHash($name, $key); $config->deleteFromArray($name, $value); $config->addToHash($name, $key, $value); $config->addToArray($name, $value); my $path = $config->getFilePath; my $filename = $config->getFilename;
# config-file-type: JSON 1 { "dsn" : "DBI:mysql:test", "user" : "tester", "password" : "xxxxxx", # some colors to choose from "colors" : [ "red", "green", "blue" ], # some statistics "stats" : { "health" : 32, "vitality" : 11 } }
This package parses the config files written in JSON. It also does some non-JSON stuff, like allowing for comments in the files.
If you want to see it in action, it is used as the config file system in WebGUI http://www.webgui.org/.
Why build yet another config file system? Well there are a number of reasons: We used to use other config file parsers, but we kept running into limitations. We already use JSON in our app, so using JSON to store config files means using less memory because we already have the JSON parser in memory. In addition, with JSON we can have any number of hierarchcal data structures represented in the config file, whereas most config files will give you only one level of hierarchy, if any at all. JSON parses faster than XML and YAML. JSON is easier to read and edit than XML. Many other config file systems allow you to read a config file, but they don't provide any mechanism or utilities to write back to it. JSON is taint safe. JSON is easily parsed by languages other than Perl when we need to do that.
You may of course access a directive called "foo", but since the config is basically a hash you can traverse multiple elements of the hash when specifying a directive name by simply delimiting each level with a slash, like "foo/bar". For example you may:
my $vitality = $config->get("stats/vitality"); $config->set("stats/vitality", 15);
You may do this wherever you specify a directive name.
You can put comments in the config file as long as # is the first non-space character on the line. However, if you use this API to write to the config file, your comments will be eliminated.
Adds a value to an array directive in the config file.
The name of the array.
The value to add.
Adds a value to a hash directive in the config file. NOTE: This is really the same as $config->set("directive/key", $value);
The name of the hash.
The key to add.
Constructor. Creates a new empty config file.
The path and filename of the file to create.
Deletes a key from the config file.
The name of the directive to delete.
Deletes a value from an array directive in the config file.
The value to delete.
Delete a key from a hash directive in the config file. NOTE: This is really just the same as doing $config->delete("directive/key");
The key to delete.
Returns the value of a particular directive from the config file.
The name of the directive to return.
Returns the filename for this config.
Returns the filename and path for this config.
Constructor. Builds an object around a config file.
A string representing a path such as "/etc/my-cool-config.conf".
Creates a new or updates an existing directive in the config file.
A directive name.
The value to set the paraemter to. Can be a scalar, hash reference, or array reference.
Couldn't parse JSON in config file
This means that the config file does not appear to be formatted properly as a JSON file. Common mistakes are missing commas or trailing commas on the end of a list.
Cannot read config file
We couldn't read the config file. This usually means that the path specified in the constructor is incorrect.
Can't write to config file
We couldn't write to the config file. This usually means that the file system is full, or the that the file is write protected.
Config::JSON requires no configuration files or environment variables.
None reported.
No bugs have been reported.
Please report any bugs or feature requests to bug-config-json@rt.cpan.org, or through the web interface at http://rt.cpan.org.
bug-config-json@rt.cpan.org
JT Smith <jt-at-plainblack-dot-com>
<jt-at-plainblack-dot-com>
Copyright (c) 2006-2008, Plain Black Corporation http://www.plainblack.com/. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
To install Config::JSON, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::JSON
CPAN shell
perl -MCPAN -e shell install Config::JSON
For more information on module installation, please visit the detailed CPAN module installation guide.