NAME

       Config::JSON - A JSON based config file system.

VERSION

       version 1.5202

SYNOPSIS

        use Config::JSON;

        my $config = Config::JSON->create($pathToFile);
        my $config = Config::JSON->new($pathToFile);
        my $config = Config::JSON->new(pathToFile=>$pathToFile);

        my $element = $config->get($directive);

        $config->set($directive,$value);

        $config->delete($directive);
        $config->deleteFromHash($directive, $key);
        $config->deleteFromArray($directive, $value);

        $config->addToHash($directive, $key, $value);
        $config->addToArray($directive, $value);

        my $path = $config->pathToFile;
        my $filename = $config->getFilename;

   Example Config File
        # 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
           },

           # including another file
           "includes" : ["macros.conf"]
        }

DESCRIPTION

       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?
       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.

   Multi-level Directives
       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.

   Comments
       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.

   Includes
       There is a special directive called "includes", which is an array of include files that
       may be brought in to the config. Even the files you include can have an "includes"
       directive, so you can do hierarchical includes.

       Any directive in the main file will take precedence over the directives in the includes.
       Likewise the files listed first in the "includes" directive will have precedence over the
       files that come after it. When writing to the files, the same precedence is followed.

       If you're setting a new directive that doesn't currently exist, it will only be written to
       the main file.

       If a directive is deleted, it will be deleted from all files, including the includes.

INTERFACE

   addToArray ( directive, value )
       Adds a value to an array directive in the config file.

       directive

       The name of the array.

       value

       The value to add.

   addToArrayBefore ( directive, insertBefore, value )
       Inserts a value into an array immediately before another item.  If that item can't be
       found, inserts at the beginning on the array.

       directive

       The name of the array.

       insertBefore

       The value to search for and base the positioning on.

       value

       The value to insert.

   addToArrayAfter ( directive, insertAfter, value )
       Inserts a value into an array immediately after another item.  If that item can't be
       found, inserts at the end on the array.

       directive

       The name of the array.

       insertAfter

       The value to search for and base the positioning on.

       value

       The value to insert.

   addToHash ( directive, key, value )
       Adds a value to a hash directive in the config file. NOTE: This is really the same as
       $config->set("directive/key", $value);

       directive

       The name of the hash.

       key

       The key to add.

       value

       The value to add.

   create ( pathToFile )
       Constructor. Creates a new empty config file.

       pathToFile

       The path and filename of the file to create.

   delete ( directive )
       Deletes a key from the config file.

       directive

       The name of the directive to delete.

   deleteFromArray ( directive, value )
       Deletes a value from an array directive in the config file.

       directive

       The name of the array.

       value

       The value to delete.

   deleteFromHash ( directive, key )
       Delete a key from a hash directive in the config file. NOTE: This is really just the same
       as doing $config->delete("directive/key");

       directive

       The name of the hash.

       key

       The key to delete.

   get ( directive )
       Returns the value of a particular directive from the config file.

       directive

       The name of the directive to return.

   getFilename ( )
       Returns the filename for this config.

   pathToFile ( )
       Returns the filename and path for this config. May also be called as "getFilePath" for
       backward campatibility sake.

   includes ( )
       Returns an array reference of Config::JSON objects that are files included by this config.
       May also be called as "getIncludes" for backward compatibility sake.

   new ( pathToFile )
       Constructor. Builds an object around a config file.

       pathToFile

       A string representing a path such as "/etc/my-cool-config.conf".

   set ( directive, value )
       Creates a new or updates an existing directive in the config file.

       directive

       A directive name.

       value

       The value to set the paraemter to. Can be a scalar, hash reference, or array reference.

   splitKeyParts ( key )
       Returns an array of key parts.

       key

       A key string. Could be 'foo' (simple key), 'foo/bar' (a multilevel key referring to the
       bar key as a child of foo), or 'foo\/bar' (a simple key that contains a slash in the key).
       Don't forget to double escape in your perl code if you have a slash in your key parts like
       this:

        $config->get('foo\\/bar');

   write ( )
       Writes the file to the filesystem. Normally you'd never need to call this as it's called
       automatically by the other methods when a change occurs.

DIAGNOSTICS

       "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.

PREREQS

       JSON Moo List::Util Test::More Test::Deep

SUPPORT

       Repository
           <http://github.com/plainblack/Config-JSON>

       Bug Reports
           <http://rt.cpan.org/Public/Dist/Display.html?Name=Config-JSON>

AUTHOR

       JT Smith  <jt-at-plainblack-dot-com>

LEGAL

       Config::JSON is Copyright 2009 Plain Black Corporation (<http://www.plainblack.com/>) and
       is licensed under the same terms as Perl itself.