Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

JSON::DWIW
JSON converter that Does What I Want

JSON::DWIW - JSON converter that Does What I Want



NAME

JSON::DWIW - JSON converter that Does What I Want


SYNOPSIS


 use JSON::DWIW;

 my $json_obj = JSON::DWIW->new;

 my $data = $json_obj->from_json($json_str);

 my $str = $json_obj->to_json($data);

 my $error_string = $json_obj->get_error_string;

 my $error_data = $json_obj->get_error_data;

 my $stats = $json_obj->get_stats;

 my $data = $json_obj->from_json_file($file)

 my $ok = $json_obj->to_json_file($data, $file);

 my $data = JSON::DWIW->from_json($json_str);

 my $str = JSON:DWIW->to_json($data);

 my $data = JSON::DWIW->from_json($json_str, \%options);

 my $str = JSON::DWIW->to_json($data, \%options);

 my $true_value = JSON::DWIW->true;

 my $false_value = JSON::DWIW->false;

 my $data = { var1 => "stuff", var2 => $true_value,

              var3 => $false_value, };

 my $str = JSON::DWIW->to_json($data);

 use JSON::DWIW qw(:all);

 my $data = from_json($json_str);

 my $str = to_json($data);


DESCRIPTION

Other JSON modules require setting several parameters before calling the conversion methods to do what I want. This module does things by default that I think should be done when working with JSON in Perl. This module also encodes and decodes faster than JSON.pm and JSON::Syck in my benchmarks.

This means that any piece of data in Perl (assuming it's valid unicode) will get converted to something in JSON instead of throwing an exception. It also means that output will be strict JSON, while accepted input will be flexible, without having to set any options.

Encoding

Perl objects get encoded as their underlying data structure, with the exception of Math::BigInt and Math::BigFloat, which will be output as numbers, and JSON::DWIW::Boolean, which will get output as a true or false value (see the true() and false() methods). For example, a blessed hash ref will be represented as an object in JSON, a blessed array will be represented as an array. etc. A reference to a scalar is dereferenced and represented as the scalar itself. Globs, Code refs, etc., get stringified, and undef becomes null.

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.

Decoding

When decoding, null, true, and false become undef, 1, and 0, repectively. Numbers that appear to be too long to be supported natively are converted to Math::BigInt or Math::BigFloat objects, if you have them installed. Otherwise, long numbers are turned into strings to prevent data loss.

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.


METHODS

new(\%options)


 Create a new JSON::DWIW object.

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

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

to_json


 Returns the JSON representation of $data (arbitrary

 datastructure).  See http://www.json.org/ for details.

 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

from_json


 Returns the Perl data structure for the given JSON string.  The

 value for true becomes 1, false becomes 0, and null gets

 converted to undef.

 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)

     my $data = from_json($json_str, { use_exceptions => 1 })

 Aliases: fromJson, fromJSON, jsonToObj

from_json_file


 Returns the Perl data structure for the JSON object in the given

 file.  Currently, this method slurps in the whole file, then

 parses it.

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

to_json_file


 Converts $data to JSON and writes the result to the file $file.

 Currently, this is simply a convenience routine that converts

 the data to a JSON string and then writes it to the file.

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

get_error_string


 Returns the error message from the last call, if there was one, e.g.,

 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


 Returns the error details from the last call, in a hash ref, e.g.,

 $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


 Returns statistics from the last method called to encode or

 decode.  E.g., for an encoding (to_json() or to_json_file()),

    $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


 Returns an object that will get output as a true value when encoding to JSON.

false


 Returns an object that will get output as a false value when encoding to JSON.


BENCHMARKS


 Latest benchmarks against JSON and JSON::Syck run on my MacBook

 Pro:

 Using a small data set:

    Encode (50000 iterations):

    ==========================

                  Rate       JSON JSON::Syck JSON::DWIW

    JSON        2648/s         --       -72%       -86%

    JSON::Syck  9416/s       256%         --       -51%

    JSON::DWIW 19380/s       632%       106%         --

    Decode (50000 iterations):

    ==========================

                  Rate       JSON JSON::Syck JSON::DWIW

    JSON        2288/s         --       -81%       -93%

    JSON::Syck 12195/s       433%         --       -60%

    JSON::DWIW 30675/s      1240%       152%         --

 Using a larger data set (8KB JSON string) generated from Yahoo!

 Local's search API (http://nanoref.com/yahooapis/mgPdGg)

    Encode (1000 iterations):

    =========================

                Rate       JSON JSON::Syck JSON::DWIW

    JSON       133/s         --       -54%       -66%

    JSON::Syck 289/s       118%         --       -26%

    JSON::DWIW 389/s       193%        35%         --

    Decode (1000 iterations):

    =========================

                 Rate       JSON JSON::Syck JSON::DWIW

    JSON       35.5/s         --       -92%       -94%

    JSON::Syck  427/s      1103%         --       -25%

    JSON::DWIW  571/s      1508%        34%         --


DEPENDENCIES

Perl 5.6 or later


BUGS/LIMITATIONS

If you find a bug, please file a tracker request at <http://rt.cpan.org/Public/Dist/Display.html?Name=JSON-DWIW>.

When decoding a JSON string, it is a assumed to be utf-8 encoded. The module should detect whether the input is utf-8, utf-16, or utf-32.


AUTHOR

Don Owens <don@regexguy.com>


ACKNOWLEDGEMENTS

Thanks to Asher Blum for help with testing.

Thanks to Nigel Bowden for helping with compilation on Windows.


LICENSE AND COPYRIGHT

Copyright (c) 2007 Don Owens <don@regexguy.com>. All rights reserved.

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


SEE ALSO


 The JSON home page: L<http://json.org/>;

 The JSON spec: L<http://www.ietf.org/rfc/rfc4627.txt>;

 The JSON-RPC spec: L<http://json-rpc.org/wd/JSON-RPC-1-1-WD-20060807.html>;

 L<JSON>

 L<JSON::Syck> (included in L<YAML::Syck>)


VERSION

0.19

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy