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 $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);
 
     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 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. 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, filehandles, etc., get stringified.

  Decoding
    When decoding, null, true, and false become undef, 1, and 0,
    repectively.

    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

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

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

  to_json($data)
     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

  my ($data, $error_msg) = from_json($json_str)
     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

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>

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
     JSON
     JSON::Syck (included in YAML::Syck)

VERSION
     0.06

