0 0 li~j"T7qţ q{_ub &=LV[(? =head1 NAME JSON::XS - JSON serialising/deserialising, done correctly and fast =encoding utf-8 JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html) =head1 SYNOPSIS use JSON::XS; # exported functions, they croak on error # and expect/generate UTF-8 $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; # OO-interface $coder = JSON::XS->new->ascii->pretty->allow_nonref; $pretty_printed_unencoded = $coder->encode ($perl_scalar); $perl_scalar = $coder->decode ($unicode_json_text); # Note that JSON version 2.0 and above will automatically use JSON::XS # if available, at virtually no speed overhead either, so you should # be able to just: use JSON; # and do the same things, except that you have a pure-perl fallback now. =head1 DESCRIPTION This module converts Perl data structures to JSON and vice versa. Its primary goal is to be I and its secondary goal is to be I. To reach the latter goal it was written in C. See MAPPING, below, on how JSON::XS maps perl values to JSON values and vice versa. =head2 FEATURES =over =item * correct Unicode handling This module knows how to handle Unicode, documents how and when it does so, and even documents what "correct" means. =item * round-trip integrity When you serialise a perl data structure using only data types supported by JSON and Perl, the deserialised data structure is identical on the Perl level. (e.g. the string "2.0" doesn't suddenly become "2" just because it looks like a number). There I minor exceptions to this, read the MAPPING section below to learn about those. =item * strict checking of JSON correctness There is no guessing, no generating of illegal JSON texts by default, and only JSON is accepted as input by default (the latter is a security feature). =item * fast Compared to other JSON modules and other serialisers such as Storable, this module usually compares favourably in terms of speed, too. =item * simple to use This module has both a simple functional interface as well as an object oriented interface. =item * reasonably versatile output formats You can choose between the most compact guaranteed-single-line format possible (nice for simple line-based protocols), a pure-ASCII format (for when your transport is not 8-bit clean, still supports the whole Unicode range), or a pretty-printed format (for when you want to read that stuff). Or you can combine those features in whatever way you like. =back =cut package JSON::XS; use common::sense; our $VERSION = '4.03'; our @ISA = qw(Exporter); our @EXPORT = qw(encode_json decode_json); use Exporter; use XSLoader; use Types::Serialiser (); =head1 FUNCTIONAL INTERFACE The following convenience methods are provided by this module. They are exported by default: =over =item $json_text = encode_json $perl_scalar Converts the given Perl data structure to a UTF-8 encoded, binary string (that is, the string contains octets only). Croaks on error. This function call is functionally identical to: $json_text = JSON::XS->new->utf8->encode ($perl_scalar) Except being faster. =item $perl_scalar = decode_json $json_text The opposite of C: expects a UTF-8 (binary) string and tries to parse that as a UTF-8 encoded JSON text, returning the resulting reference. Croaks on error. This function call is functionally identical to: $perl_scalar = JSON::XS->new->utf8->decode ($json_text) Except being faster. =back =head1 A FEW NOTES ON UNICODE AND PERL Since this often leads to confusion, here are a few very clear words on how Unicode works in Perl, modulo bugs. =over =item 1. Perl strings can store characters with ordinal values > 255. This enables you to store Unicode characters as single characters in a Perl string - very natural. =item 2. Perl does I associate an encoding with your strings. ... until you force