=pod

=encoding utf8

=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
L<Mojolicious> framework.  It has been adapted as a single-source-file module
of under 350 lines of code and 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 inlining.

L<Mojo::JSON> was chosen as a model because it is robust, minimal, and well
tested. Mojo::JSON's tests were also adapted to a design free of non-core
dependencies.

Much of this document is adapted directly from L<Mojo::JSON>.

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.

Dies with a C<JSON::Tiny::error> message on decode failure.

=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 with JSON::PP from the L<JSON> distribution:

=over 4

=item * L<JSON::PP> is configurable, and comparatively complex.
L<JSON::Tiny> offers sane defaults, and nothing to configure.

=item * Installation: C<cpanm JSON::PP> vs 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> only use core 
dependencies. JSON::Tiny requires Perl 5.8.4, while L<JSON::PP> requires 5.6.

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

=item * Simple Interface: L<JSON::PP> has about 42 functions and methods.
L<JSON::Tiny> has seven.

=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.
L<JSON> will automatically use L<JSON::XS> if it's available. In that
case, L<JSON::XS> wins, but it's XS.

Because JSON::Tiny doesn't pull in as many external modules, and splits the POD
into a separate file to minimize the source-code file size, startup time for
JSON::Tiny is slightly faster than for the JSON module. But, the startup time
in either case should only be a factor in applications such as CGI, where
processes may be started many times per second.

=item * Light Memory Needs: From the distribution's C<examples/> folder, 
C<json_pp_alone.pl> and  C<json_tiny_alone.pl> were tested, first with 
L<Devel::MemoryTrace::Light>, and then with 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 utilities have different methods of measuring memory use, but both show
JSON::Tiny is 600-700KB lighter than JSON::PP.

=back

=head1 CONFIGURATION AND ENVIRONMENT

Zero configuration.

=head1 DEPENDENCIES

Perl 5.8.4 or newer.

=head1 INCOMPATIBILITIES

Incompatible with L<Exporter> versions that predate Perl 5.8.4.  Perl 5.8.4
shipped with Exporter v5.58.  Exporter became dual-life as of v5.59, so
upgrading Exporter to v5.59 or newer should allow JSON::Tiny to run on Perl
versions older than 5.8.4.

=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 should be directed to the author. Direct bug reports to
CPAN's Request Tracker (RT).

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

    perldoc JSON::Tiny

You may look for additional 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> team for producing an excellent product that
offers light-weight implementations of many useful tools. This module wouldn't
exist or be as well designed and tested if it weren't for Mojolicious.

Also to Randal Schwartz for showing the Los Angeles Perl Mongers (Sept 2012)
his embeddable pure-regexp JSON parser, and explaining it on PerlMonks
(L<http://www.perlmonks.org/?node_id=995856>). He wasn't involved in
JSON::Tiny, but it was the exploration of alternatives to his solution that led
to this fork of Mojolicious's JSON parser.

=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
