.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Config::JSON 3pm"
.TH Config::JSON 3pm "2010-12-09" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Config::JSON \- A JSON based config file system.
.SH "VERSION"
.IX Header "VERSION"
version 1.5100
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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;
.Ve
.SS "Example Config File"
.IX Subsection "Example Config File"
.Vb 5
\& # 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"]
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package parses the config files written in \s-1JSON\s0. It also does some non-JSON stuff, like allowing for comments in the files.
.PP
If you want to see it in action, it is used as the config file system in WebGUI <http://www.webgui.org/>.
.SS "Why?"
.IX Subsection "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 \s-1JSON\s0 in our app, so using
\&\s-1JSON\s0 to store config files means using less memory because we already
have the \s-1JSON\s0 parser in memory. In addition, with \s-1JSON\s0 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. \s-1JSON\s0 parses faster than \s-1XML\s0 and \s-1YAML\s0.
\&\s-1JSON\s0 is easier to read and edit than \s-1XML\s0. 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. \s-1JSON\s0 is taint safe.
\&\s-1JSON\s0 is easily parsed by languages other than Perl when we need to
do that.
.SS "Multi-level Directives"
.IX Subsection "Multi-level Directives"
You may of course access a directive called \*(L"foo\*(R", 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
\&\*(L"foo/bar\*(R". For example you may:
.PP
.Vb 2
\& my $vitality = $config\->get("stats/vitality");
\& $config\->set("stats/vitality", 15);
.Ve
.PP
You may do this wherever you specify a directive name.
.SS "Comments"
.IX Subsection "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 \s-1API\s0 to write to the config file, your comments will be eliminated.
.SS "Includes"
.IX Subsection "Includes"
There is a special directive called \*(L"includes\*(R", which is an array of include files that may be brought in to
the config. Even the files you include can have an \*(L"includes\*(R" directive, so you can do hierarchical includes.
.PP
Any directive in the main file will take precedence over the directives in the includes. Likewise the files
listed first in the \*(L"includes\*(R" directive will have precedence over the files that come after it. When writing
to the files, the same precedence is followed.
.PP
If you're setting a new directive that doesn't currently exist, it will only be written to the main file.
.PP
If a directive is deleted, it will be deleted from all files, including the includes.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "addToArray ( directive, value )"
.IX Subsection "addToArray ( directive, value )"
Adds a value to an array directive in the config file.
.PP
\fIdirective\fR
.IX Subsection "directive"
.PP
The name of the array.
.PP
\fIvalue\fR
.IX Subsection "value"
.PP
The value to add.
.SS "addToArrayBefore ( directive, insertBefore, value )"
.IX Subsection "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.
.PP
\fIdirective\fR
.IX Subsection "directive"
.PP
The name of the array.
.PP
\fIinsertBefore\fR
.IX Subsection "insertBefore"
.PP
The value to search for and base the positioning on.
.PP
\fIvalue\fR
.IX Subsection "value"
.PP
The value to insert.
.SS "addToArrayAfter ( directive, insertAfter, value )"
.IX Subsection "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.
.PP
\fIdirective\fR
.IX Subsection "directive"
.PP
The name of the array.
.PP
\fIinsertAfter\fR
.IX Subsection "insertAfter"
.PP
The value to search for and base the positioning on.
.PP
\fIvalue\fR
.IX Subsection "value"
.PP
The value to insert.
.SS "addToHash ( directive, key, value )"
.IX Subsection "addToHash ( directive, key, value )"
Adds a value to a hash directive in the config file. \fB\s-1NOTE:\s0\fR This is really the same as
\&\f(CW$config\fR\->set(\*(L"directive/key\*(R", \f(CW$value\fR);
.PP
\fIdirective\fR
.IX Subsection "directive"
.PP
The name of the hash.
.PP
\fIkey\fR
.IX Subsection "key"
.PP
The key to add.
.PP
\fIvalue\fR
.IX Subsection "value"
.PP
The value to add.
.SS "create ( pathToFile )"
.IX Subsection "create ( pathToFile )"
Constructor. Creates a new empty config file.
.PP
\fIpathToFile\fR
.IX Subsection "pathToFile"
.PP
The path and filename of the file to create.
.SS "delete ( directive )"
.IX Subsection "delete ( directive )"
Deletes a key from the config file.
.PP
\fIdirective\fR
.IX Subsection "directive"
.PP
The name of the directive to delete.
.SS "deleteFromArray ( directive, value )"
.IX Subsection "deleteFromArray ( directive, value )"
Deletes a value from an array directive in the config file.
.PP
\fIdirective\fR
.IX Subsection "directive"
.PP
The name of the array.
.PP
\fIvalue\fR
.IX Subsection "value"
.PP
The value to delete.
.SS "deleteFromHash ( directive, key )"
.IX Subsection "deleteFromHash ( directive, key )"
Delete a key from a hash directive in the config file. \fB\s-1NOTE:\s0\fR This is really just the same as doing
\&\f(CW$config\fR\->delete(\*(L"directive/key\*(R");
.PP
\fIdirective\fR
.IX Subsection "directive"
.PP
The name of the hash.
.PP
\fIkey\fR
.IX Subsection "key"
.PP
The key to delete.
.SS "get ( directive )"
.IX Subsection "get ( directive )"
Returns the value of a particular directive from the config file.
.PP
\fIdirective\fR
.IX Subsection "directive"
.PP
The name of the directive to return.
.SS "getFilename ( )"
.IX Subsection "getFilename ( )"
Returns the filename for this config.
.SS "pathToFile ( )"
.IX Subsection "pathToFile ( )"
Returns the filename and path for this config. May also be called as \f(CW\*(C`getFilePath\*(C'\fR for backward campatibility sake.
.SS "includes ( )"
.IX Subsection "includes ( )"
Returns an array reference of Config::JSON objects that are files included by this config. May also be called as \f(CW\*(C`getIncludes\*(C'\fR for backward compatibility sake.
.SS "new ( pathToFile )"
.IX Subsection "new ( pathToFile )"
Constructor. Builds an object around a config file.
.PP
\fIpathToFile\fR
.IX Subsection "pathToFile"
.PP
A string representing a path such as \*(L"/etc/my\-cool\-config.conf\*(R".
.SS "set ( directive, value )"
.IX Subsection "set ( directive, value )"
Creates a new or updates an existing directive in the config file.
.PP
\fIdirective\fR
.IX Subsection "directive"
.PP
A directive name.
.PP
\fIvalue\fR
.IX Subsection "value"
.PP
The value to set the paraemter to. Can be a scalar, hash reference, or array reference.
.SS "splitKeyParts ( key )"
.IX Subsection "splitKeyParts ( key )"
Returns an array of key parts.
.PP
\fIkey\fR
.IX Subsection "key"
.PP
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\e/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:
.PP
.Vb 1
\& $config\->get(\*(Aqfoo\e\e/bar\*(Aq);
.Ve
.SS "write ( )"
.IX Subsection "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.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP """Couldn\*(Aqt parse JSON in config file""" 4
.el .IP "\f(CWCouldn\*(Aqt parse JSON in config file\fR" 4
.IX Item "Couldnt parse JSON in config file"
This means that the config file does not appear to be formatted properly as a \s-1JSON\s0 file. Common mistakes are missing commas or trailing commas on the end of a list.
.ie n .IP """Cannot read config file""" 4
.el .IP "\f(CWCannot read config file\fR" 4
.IX Item "Cannot read config file"
We couldn't read the config file. This usually means that the path specified in the constructor is incorrect.
.ie n .IP """Can\*(Aqt write to config file""" 4
.el .IP "\f(CWCan\*(Aqt write to config file\fR" 4
.IX Item "Cant 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.
.SH "PREREQS"
.IX Header "PREREQS"
\&\s-1JSON\s0 Moose List::Util Test::More Test::Deep
.SH "SUPPORT"
.IX Header "SUPPORT"
.IP "Repository" 4
.IX Item "Repository"
<http://github.com/plainblack/Config\-JSON>
.IP "Bug Reports" 4
.IX Item "Bug Reports"
<http://rt.cpan.org/Public/Dist/Display.html?Name=Config\-JSON>
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\s-1JT\s0 Smith  <jt\-at\-plainblack\-dot\-com>
.SH "LEGAL"
.IX Header "LEGAL"
Config::JSON is Copyright 2009 Plain Black Corporation (<http://www.plainblack.com/>) and is licensed under the same terms as Perl itself.