NAME

Parse::JCONF - Parse JCONF (JSON optimized for configs)

SYNOPSIS

use strict;
use Parse::JCONF;

my $raw_cfg = do { local $/; <DATA> };
my $parser = Parse::JCONF->new(autodie => 1);

$cfg = $parser->parse($raw_cfg);

$cfg->{modules}{Mo}[1]; # 0.08
$cfg->{enabled}; # Parse::JCONF::Boolean::TRUE or "1" in string context
$cfg->{enabled} == Parse::JCONF::Boolean::TRUE; # yes
$cfg->{enabled} == 1; # no
if ($cfg->{enabled}) { 1 }; # yes
$cfg->{data}[0]; # Test data
$cfg->{query}; # SELECT * from pkg
               # LEFT JOIN ver ON pkg.id=ver.pkg_id
               # WHERE pkg.name IN ("Moose", "Mouse", "Moo", "Mo")
__DATA__
modules = {
    Moose: 1,
    Mouse: 0.91,
    Moo: 0.05, # some comment here about version
    Mo: [0.01, 0.08],
}

enabled = true
data = ["Test data", "Production data"] # some comment about data

query = "SELECT * from pkg
         LEFT JOIN ver ON pkg.id=ver.pkg_id
         WHERE pkg.name IN (\"Moose\", \"Mouse\", \"Moo\", \"Mo\")"

DESCRIPTION

JSON is good, but not very handy for configuration files. JCONF intended to fix this.

It has several differences with JSON format:

bareword - the word which matches /^\w+$/

some_word   # valid
some word   # invalid
"some_word" # invalid

bareword may be used only as object key or root key

object key may be bareword or string

{test: 1}   # valid
{"test": 1} # valid

JCONF root always consists of 0 or more trines: root key (bareword), equals sign (=), any valid JCONF value (number/string/true/false/null/object/array)

value1 = [1,2] # root trine: root key (bareword), equals sign (=), any valid JCONF value

values in the object/array or root trines may be devided with comma "," (like in JSON) or with new line (or even several)

val = [1,2,3,4] # with comma

val = [         # with new line
    1
    2
    3
    4
]

val = {         # several newlines are ok
    a: 1
    
    b: 2
}

val = {        # comma and newlines are ok
    a: 1,
    b: 2
}

val = {       # invalid, several commas is not ok
    a: 1,,b:2
}

comma separator allowed after last element

[1,2,3,4,] # ok
{a:1,b:2,} # ok

new lines, carriage return, tabs are valid symbols in the string

str = "This is valid multiline
JCONF string"

# - is start of the comment, all from this symbol to the end of line will be interpreted as comment

obj = {
    bool: false # this is comment
}

METHODS

new

This is parser object constructor. Available parameters are:

autodie

Throw exception on any error if true, default is false (in this case parser methods will return undef on error and error may be found with "last_error" method)

keep_order

Store key/value pairs in the hash which keeps order if true, default is false. This is useful when you need to store your configuration back to the file (for example with JCONF::Writer) and want to save same order as it was before. You must have $Parse::JCONF::HashClass installed which default value is Tie::IxHash.

parse

Parses string provided as parameter. Expected string encoding is utf8. On success returns reference to hash. On fail returns undef/throws exception (according to autodie option in the constructor). Exception will be of type Parse::JCONF::Error::Parser.

parse_file

Parses content of the file which path provided as parameter. Expected file content encoding is utf8. On success returns reference to hash. On fail returns undef/throws exception (according to autodie option in the constructor). Exception will be of type Parse::JCONF::Error::IO or Parse::JCONF::Error::Parser.

last_error

Returns error occured for last parse() or parse_file() call. Error will be one of Parse::JCONF::Error subclass or undef (if there was no error).

SEE ALSO

Parse::JCONF::Error, Parse::JCONF::Boolean, JCONF::Writer

COPYRIGHT

Copyright Oleg G <oleg@cpan.org>.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.