
=pod

=head1 NAME

JSON::Tiny - Minimalistic JSON. No dependencies.

=head1 SYNOPSIS

    # Encode and decode JSON
    use JSON::Tiny;

    my $json  = JSON::Tiny->new;
    my $bytes = $json->encode({foo => [1, 2], bar => 'hello!', baz => \1});
    my $hash  = $json->decode($bytes);

    # Check for errors
    my $json = JSON::Tiny->new;
    if(defined(my $hash = $json->decode($bytes))) { say $hash->{message} }
    else { say 'Error: ', $json->error }

    # Use the alternative interface
    use JSON::Tiny 'j';
    my $bytes = j({foo => [1, 2], bar => 'hello!', baz => \1});
    my $hash  = j($bytes);
    
=head1 DESCRIPTION

L<JSON::Tiny> is a standalone adaptation of L<Mojo::JSON>, from the fabulous
L<Mojolicious> "web in a box" framework (version 3.52).  It has been adapted as
a single-source-file module of about 345 lines of code with core-only
dependencies.

Key features include relaxed JSON handling, transparent Unicode support, speed,
small memory footprint, and a minimal code base ideal for bundling or embedding.

Mojo::JSON was chosen as a launch point because it is already light-weight,
robust, and well tested. Furthermore, Mojo::JSON's tests were able to be adapted
as easily as the module itself to a configuration free of non-core dependencies.

Most of the remainder of this document is adapted directly from
L<Mojo::JSON>. The names have been changed to protect the innocent.

L<JSON::Tiny> is a minimalistic and relaxed implementation of RFC 4627. While
it is possibly the fastest pure-Perl JSON parser available, you should not use
it for validation.

It supports normal Perl data types like C<Scalar>, C<Array> reference, C<Hash>
reference and will try to call the C<TO_JSON> method on blessed references, or
stringify them if it doesn't exist.

    [1, -2, 3]     -> [1, -2, 3]
    {"foo": "bar"} -> {foo => 'bar'}

Literal names will be translated to and from L<JSON::Tiny> constants or a
similar native Perl value. In addition C<Scalar> references will be used to
generate booleans, based on if their values are true or false.

    true  -> JSON::Tiny->true
    false -> JSON::Tiny->false
    null  -> undef

Decoding UTF-16 (LE/BE) and UTF-32 (LE/BE) will be handled transparently,
encoding will only generate UTF-8. The two Unicode whitespace characters
C<u2028> and C<u2029> will always be escaped to make JSONP easier.

=head1 FUNCTIONS

L<JSON::Tiny> implements the following functions.

=head2 j

    my $bytes = j([1, 2, 3]);
    my $bytes = j({foo => 'bar'});
    my $array = j($bytes);
    my $hash  = j($bytes);

Encode Perl data structure or decode JSON and return C<undef> if decoding fails.

=head1 ATTRIBUTES

L<JSON::Tiny> implements the following attributes.

=head2 error

    my $err = $json->error;
    $json   = $json->error('Parser error');

Parser errors.

=head1 METHODS

L<JSON::Tiny> implements the following methods.

=head2 new

    my $json = JSON::Tiny->new;

Instantiate a JSON::Tiny object.

=head2 decode

    my $array = $json->decode($bytes);
    my $hash  = $json->decode($bytes);

Decode JSON to Perl data structure and return C<undef> if decoding fails.

=head2 encode

    my $bytes = $json->encode([1, 2, 3]);
    my $bytes = $json->encode({foo => 'bar'});

Encode Perl data structure to JSON.

=head2 false

    my $false = JSON::Tiny->false;
    my $false = $json->false;

False value, used because Perl has no native equivalent.

=head2 true

    my $true = JSON::Tiny->true;
    my $true = $json->true;

True value, used because Perl has no native equivalent.

=head1 It's Tiny

Comparing JSON::Tiny to JSON::PP (from the L<JSON> distribution):


=over 4

=item * L<JSON::PP> is highly configurable (and comparatively complex).
L<JSON::Tiny> provides sane defaults, and a tiny zero-configuration API.

=item * Installation: C<cpanm JSON::PP> versus C<cpanm JSON::Tiny>:
L<JSON::PP>: 5.2 seconds. L<JSON::Tiny>: 1.9 seconds (including download).

=item * Minimal Dependencies: Both L<JSON::PP> and L<JSON::Tiny> use only core 
dependencies.  JSON::Tiny requires Perl 5.10+, while L<JSON::PP> requires 5.6+.

=item * Simple Design: L<JSON> has 2254 lines of code in six modules and five
files with a distribution tarball of 84KB. L<JSON::Tiny> has 345 lines of code,
and a single module in a single file.  It can even be easily embedded within
existing code.  The tarball is 17KB.

=item * Simple Interface: L<JSON::PP> has around 42 functions and methods.
L<JSON::Tiny> has six.  The simplified interface provides reasonable DWIM
defaults without complexity.

=item * Fast Performance (Benchmarks):

               Rate   JSON_PP JSON_Tiny
    JSON_PP   288/s        --      -62%
    JSON_Tiny 767/s      166%        --

The benchmark script is included in this distribution's C<examples/> folder.
Note: L<JSON> will automatically use L<JSON::XS> if it's available, and in that
case, L<JSON::XS> wins by an order of magnitude, but it's XS.

=item * Light Memory Demands: From the distribution's C<examples/> folder, 
C<json_pp_alone.pl> and  C<json_tiny_alone.pl> were tested, first using 
L<Devel::MemoryTrace::Light>, and then using L<http://valgrind.org/valgrind>.
The results were as follows:

=over 4

=item * L<JSON> (JSON::PP): Devel::MemoryTrace::Lite: About 1.7MB. valgrind:
about 6.1MB.

=item * L<JSON::Tiny>: Devel::MemoryTrace::Lite: About 1.1MB. valgrind:
about 5.4MB.

=back

These two utilities have different methods of measuring memory use, but both
show JSON::Tiny to be 600-700KB lighter weight than JSON::PP.

=back

=head1 CONFIGURATION AND ENVIRONMENT

No special considerations.

=head1 DEPENDENCIES

This module uses only core dependencies and Perl 5.10+.

=head1 INCOMPATIBILITIES

This module isn't compatible with Perl versions pre-5.10.0.

=head1 AUTHOR

David Oswald, C<< <davido at cpan.org> >>

The code and tests were adapted with minimal changes from L<Mojo::JSON>.

=head1 SUPPORT

Support requests for this module should be directed to the author.  Direct
bug reports to CPAN's Request Tracker (RT), listed below.

You can find documentation for this module with the perldoc command.

    perldoc JSON::Tiny

This module is maintained in a public Github repo.  You may look for
information at:

=over 4

=item * Github: Development is hosted on Github at:

L<http://www.github.com/daoswald/JSON-Tiny>

=item * RT: CPAN's request tracker (report bugs here)

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=JSON-Tiny>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/JSON-Tiny>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/JSON-Tiny>

=item * Search CPAN

L<http://search.cpan.org/dist/JSON-Tiny/>

=back

=head1 ACKNOWLEDGEMENTS

Thank-you to the L<Mojolicious> development team for producing an excellent
product that implements light-weight versions of many useful tools. This 
module wouldn't exist (or be as well tested and designed) if it had to be
written from scratch.

Also to I<Randal Schwartz> for mentioning that he had a need for an embeddable
light-weight JSON parser, presenting a pure-Regex parser on PerlMonks
(L<http://www.perlmonks.org/?node_id=995856>), and showing it to Los Angeles
Perl Mongers (September 2012).  Though he wasn't involved in JSON::Tiny, it was
the exploration of alternatives to his solution that provided the inspiration.

=head1 LICENSE AND COPYRIGHT

Copyright 2012 David Oswald.

This program is free software, you can redistribute it and/or modify it under
the terms of the Artistic License version 2.0.

See L<http://www.perlfoundation.org/artistic_license_2_0> for more information.

=head1 SEE ALSO

L<JSON>, L<JSON::PP>, L<JSON::XS>, L<Mojo::JSON>, L<Mojolicious>.

=cut
