Encoding

Scalars that have been used as both a string and a number will be output as a string. A reference to a reference is currently output as an empty string, but this may change.

You may notice there is a deserialize function, but not a serialize one. The deserialize function was written as a full rewrite (the parsing is in a separate, event-based library now) of from_json (now from_json calls deserialize). In the future, there will be a serialize function that is a rewrite of to_json.

Decoding

The parser is flexible in what it accepts and handles some things not in the JSON spec:

quotes

Both single and double quotes are allowed for quoting a string, e.g.,

    [ "string1", 'string2' ]
    

bare keys

Object/hash keys can be bare if they look like an identifier, e.g.,

    { var1: "myval1", var2: "myval2" }
    

extra commas

Extra commas in objects/hashes and arrays are ignored, e.g.,

    [1,2,3,,,4,]
    

becomes a 4 element array containing 1, 2, 3, and 4.

escape sequences

Latin1 hexadecimal escape sequences (\xHH) are accepted, as in Javascript. Also, the vertical tab escape \v is recognized (\u000b).

comments

C, C++, and shell-style comments are accepted. That is

 /* this is a comment */
 // this is a comment

 # this is also a comment
    

"new(\%options)"

%options is an optional hash of parameters that will change the bahavior of this module when encoding to JSON. You may also pass these options as the second argument to "to_json()" and "from_json()". The following options are supported:

bare_keys

If set to a true value, keys in hashes will not be quoted when converted to JSON if they look like identifiers. This is valid Javascript in current browsers, but not in JSON.

use_exceptions

If set to a true value, errors found when converting to or from JSON will result in "die()" being called with the error message. The default is to not use exceptions.

bad_char_policy

This options indicates what should be done if bad characters are found, e.g., bad utf-8 sequence. The default is to return an error and drop all the output.

The following values for bad_char_policy are supported:

error

default action, i.e., drop any output built up and return an error

convert

Convert to a utf-8 char using the value of the byte as a code point. This is basically the same as assuming the bad character is in latin-1 and converting it to utf-8.

pass_through

Ignore the error and pass through the raw bytes (invalid JSON)

escape_multi_byte

If set to a true value, escape all multi-byte characters (e.g., \u00e9) when converting to JSON.

ascii

Synonym for escape_multi_byte

pretty

Add white space to the output when calling to_json() to make the output easier for humans to read.

convert_bool

When converting from JSON, return objects for booleans so that "true" and "false" can be maintained when encoding and decoding. If this flag is set, then "true" becomes a JSON::DWIW::Boolean object that evaluates to true in a boolean context, and "false" becomes an object that evaluates to false in a boolean context. These objects are recognized by the to_json() method, so they will be output as "true" or "false" instead of "1" or "0".

bare_solidus

Don't escape solidus characters ("/") in strings. The output is still legal JSON with this option turned on.

minimal_escaping

Only do required escaping in strings (solidus and quote). Tabs, newlines, backspaces, etc., will not be escaped with this optioned turned on (but the output will still be valid JSON).

sort_keys

Set to a true value to sort hash keys (alphabetically) when converting to JSON.

parse_number

A subroutine reference to call when parsing a number. The subroutine will be provided one string that is the number being parsed. The return value from the subroutine will be used to populate the return data instead of converting to a number.

E.g.,

  my $json = '{ "a": 6.3e-10 }';
  my $cb = sub { my ($val) = @_; return "I got the number '$val'"; };
 
  my $data = JSON::DWIW::deserialize($json, { parse_number => $cb });

parse_constant

A subroutine reference to call when parsing a constant (true, false, or null). The subroutine will be provided one string that is the constant being parsed. The return value from the subroutine will be used to populate the return data instead of converting to a boolean or undef. See the "parse_number" option.

start_depth

Depth at which "start_depth_handler" should be called. See "start_depth_handler".

start_depth_handler

A reference to a subroutine to called when parsing and at level start_depth in the data structure. When specified along with start_depth, the parser does not return the entire data structure. Instead, it calls start_depth_handler for each element in the array when the parser is at level start_depth. This is useful for parsing a very large array without loading all the data into memory (especially when using "deserialize_file").

E.g., with start_depth set to 1 and start_depth_handler set to $handler:

    my $str = '[ { "foo": "bar", "cat": 1 }, { "concat": 1, "lambda" : [ "one", 2, 3 ] } ]';
 
    my $foo = { foo => [ ] };
    my $handler = sub { push @{$foo->{foo}}, $_[0]; return 1; };
 
    my $data = JSON::DWIW::deserialize($str, { start_depth => 1,
                                               start_depth_handler => $handler });
    print STDERR Data::Dumper->Dump([ $foo ], [ 'foo' ]) . "\n";
    print STDERR Data::Dumper->Dump([ $data ], [ 'leftover_data' ]) . "\n";

    # Output
    $foo = {
             'foo' => [
                        {
                          'cat' => 1,
                          'foo' => 'bar'
                        },
                        {
                          'lambda' => [
                                      'one',
                                      2,
                                      3
                                    ],
                          'concat' => 1
                        }
                      ]
           };


    $leftover_data = [];

"to_json"

Called in list context, this method returns a list whose first element is the encoded JSON string and the second element is an error message, if any. If $error_msg is defined, there was a problem converting to JSON. You may also pass a second argument to to_json() that is a reference to a hash of options -- see new().

     my $json_str = JSON::DWIW->to_json($data);
 
     my ($json_str, $error_msg) = JSON::DWIW->to_json($data);
 
     my $json_str = JSON::DWIW->to_json($data, { use_exceptions => 1 });

Aliases: toJson, toJSON, objToJson

"deserialize($json_str, \%options)"

This function should not be called as a method (for performance reasons). Unlike "from_json()", it returns a single value, the data structure resulting from the conversion. If the return value is undef, check the result of the "get_error_string()" function/method to see if an error is defined.

"deserialize_file($file, \%options)"

"from_json"

Called in list context, this method returns a list whose first element is the data and the second element is the error message, if any. If $error_msg is defined, there was a problem parsing the JSON string, and $data will be undef. You may also pass a second argument to "from_json()" that is a reference to a hash of options -- see "new()".

     my $data = from_json($json_str)
 
     my ($data, $error_msg) = from_json($json_str)

Aliases: fromJson, fromJSON, jsonToObj

"from_json_file"

my ($data, $error_msg) = $json->from_json_file($file, \%options)

"to_json_file"

 my ($ok, $error) = $json->to_json_file($data, $file, \%options);

"get_error_string"

 my $data = JSON::DWIW->from_json($json_str)
     or die "JSON error: " . JSON::DWIW->get_error_string;
 
 my $data = $json_obj->from_json($json_str)
     or die "JSON error: " . $json_obj->get_error_string;

Aliases: get_err_str(), errstr()

"get_error_data"

 $error_data = {
                'byte' => 23,
                'byte_col' => 23,
                'col' => 22,
                'char' => 22,
                'version' => '0.15a',
                'line' => 1
              };

This is really only useful when decoding JSON.

Aliases: get_error(), error()

"get_stats"

    $stats = {
               'bytes' => 78,
               'nulls' => 1,
               'max_string_bytes' => 5,
               'max_depth' => 2,
               'arrays' => 1,
               'numbers' => 6,
               'lines' => 1,
               'max_string_chars' => 5,
               'strings' => 6,
               'bools' => 1,
               'chars' => 78,
               'hashes' => 1
             };

"true"

"false"

"json_to_xml($json, \%params)"

Any characters in hash keys not in "[\w-]" (i.e., letters, numbers, underscore, or dash), get converted to underscore ("_") when output as XML tags.

Valid parameters in "\%params" are the same as for passing to "deserialize()" or "from_json()", plus the "pretty" option, which will add newlines and indentation to the XML to make it more human-readable.

"flagged_as_utf8($str)"

"flag_as_utf8($str)"

"unflag_as_utf8($str)"

"is_valid_utf8($str)"

"upgrade_to_utf8($str)"

"code_point_to_utf8_str($cp)"

"code_point_to_hex_bytes($cp)"

 my $hex_bytes = JSON::DWIW->code_point_to_hex_bytes(0xe9);
 print "$hex_bytes\n"; # \xc3\xa9

"bytes_to_code_points($str)"

"peek_scalar($scalar)"