GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  JSON::TINY (3)

.ds Aq ’

NAME

JSON::Tiny - Minimalistic JSON. No dependencies.

CONTENTS

SYNOPSIS



  use JSON::Tiny qw(decode_json encode_json);

  my $bytes = encode_json {foo => [1, 2], bar => hello!, baz => \1};
  my $hash  = decode_json $bytes;



DESCRIPTION

JSON::Tiny is a minimalistic standalone adaptation of Mojo::JSON, from the Mojolicious framework. It is a single-source-file module with under 300 lines of code and core-only dependencies.

Features include transparent Unicode support, speed, small memory footprint, and a minimal code base ideal for bundling or inlining. Along with <Mojo:JSON>, it is among the fastest pure-Perl implementations of RFC 7159 <http://tools.ietf.org/html/rfc7159>.

JSON::Tiny supports normal Perl data types like scalar, array reference, hash reference, and will try to call the TO_JSON method on blessed references, or stringify them if it doesn’t exist.

Differentiating between strings and numbers in Perl is hard; depending on how it has been used, a scalar can be both at the same time. The string value has a higher precedence unless both representations are equivalent.



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



Literal names will be translated to and from JSON::Tiny constants or a similar native Perl value.



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



Scalar references will be used to generate Booleans, based on if their values are true or false.



  \1 => true
  \0 => false



The two Unicode whitespace characters u2028 and u2029 will always be escaped to make JSONP easier, and the character / to prevent XSS attacks.

FUNCTIONS

JSON::Tiny implements the following functions, which can be imported individually.

    decode_json



  my $value = decode_json $bytes;



Decode JSON to Perl value and die if decoding fails.

    encode_json



  my $bytes = encode_json {foo => bar};



Encode Perl value to JSON.

    false



  my $false = false;



False value, used because Perl has no equivalent.

    from_json



  my $value = from_json $chars;



Decode JSON text that is not UTF-8 encoded to Perl value and die if decoding fails.

    j



  my $bytes = j [1, 2, 3];
  my $bytes = j {foo => bar};
  my $value = j $bytes;



Encode Perl data structure (which may only be an array reference or hash reference) or decode JSON. An undef return value indicates a bare null. Dies if decoding fails.

    to_json



  my $chars = to_json {i => X Perl};



Encode Perl value to JSON text without UTF-8 encoding it.

    true



  my $true = true;



True value, used because Perl has no native equivalent.

More on Booleans

A reference to a scalar (even if blessed) is encoded as a Boolean value unless it has a TO_JSON method.



  my $json = $j->encode( { b => \1, a => \0 } ); # {"b":true,"a":false}



Boolean false and true values returned when JSON is decoded are JSON::Tiny::_Bool objects with overloaded stringification.

<B>Advanced optionB>: Users requiring a plain old literal 0 or 1, may set $JSON::Tiny::FALSE = 0; and $JSON::Tiny::TRUE = 1;. Any value, including blessed references will work. This must be set prior to calling a JSON decoding function. Use local to limit scope.

Tiny

JSON::Tiny compared with JSON::PP from the JSON distribution:
o JSON::PP is configurable, but more complex. JSON::Tiny offers sane defaults, and no configuration.
o Download and install with cpanm: JSON::PP, 5.2 seconds. JSON::Tiny, 1.9 seconds.
o Minimal Dependencies: Both JSON::PP and JSON::Tiny only use core dependencies. JSON::Tiny requires Perl 5.8.4, while JSON::PP requires 5.6.
o Simple Design: JSON has 2254 lines of code, six modules and five files. Distribution: 85KB.

JSON::Tiny has under 300 lines of code; an embeddable single-file module. Distribution: 18KB.

o JSON::PP has 42 functions and methods. JSON::Tiny has seven.
o Performance:



             Rate   JSON_PP JSON_Tiny
  JSON_PP   304/s        --      -52%
  JSON_Tiny 636/s      109%        --



JSON uses JSON::XS if it’s available, in which case JSON wins. See examples/json_bench.pl for benchmark code.

JSON::Tiny’s lightweight design reduces its startup time compared to the JSON module. This may benefit frequently run applications like CGI.

o Light Memory Needs: Memory usage was tested with <http://valgrind.org/valgrind> and Devel::MemoryTrace::Light by running examples/json_pp.pl and examples/json_tiny.pl.



             valgrind  Devel::MemoryTrace::Light
  JSON::PP   5.1MB     3.7MB
  JSON::Tiny 4.5MB     2.6MB



CONFIGURATION AND ENVIRONMENT

No configuration.

DEPENDENCIES

Perl 5.8.4 or newer. <B>Perl 5.10+ is recommended due to bugs in Perl 5.8’s regular expression engine.B>

INCOMPATIBILITIES

Incompatible with Exporter versions older than 5.59 (ie, predating Perl 5.8.4).

AUTHOR

David Oswald, <davido at cpan.org>

Code and tests adapted from Mojo::JSON.

SUPPORT

Direct support requests 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:
o Github: Development is hosted on Github at:

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

o RT: CPAN’s request tracker (bug reports)

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

o AnnoCPAN: Annotated CPAN documentation

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

o CPAN Ratings

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

o Search CPAN

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

ACKNOWLEDGEMENTS

Mojolicious team for its lightweight JSON implementation. This module was adapted from Mojo::JSON because it is robust, minimal, and well tested. Mojo::JSON’s tests were also adapted to a dependency-free design.

Christian Hansen, whos GitHub Gist <https://gist.github.com/chansen/810296> formed the basis for Mojo::JSON, and subsequently JSON::Tiny.

Randal Schwartz showed his pure-regexp JSON parser (PerlMonks <http://perlmonks.org/?node_id=995856>) to Los Angeles Perl Mongers (09/2012). He wasn’t involved in JSON::Tiny, but exploring alternatives to his solution led to this project.

LICENSE AND COPYRIGHT

Copyright 2012-2014 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 <http://www.perlfoundation.org/artistic_license_2_0> for more information.

SEE ALSO

Mojo::JSON, JSON, RFC7159 <http://tools.ietf.org/html/rfc7159>.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 JSON::TINY (3) 2015-01-26

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.