Lines Matching defs:JSON
3 JSON::XS - JSON serialising/deserialising, done correctly and fast
7 JSON::XS - ��������������������� JSON ������������������/���������������������
8 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
12 use JSON::XS;
22 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
26 # Note that JSON version 2.0 and above will automatically use JSON::XS
30 use JSON;
36 This module converts Perl data structures to JSON and vice versa. Its
40 Beginning with version 2.0 of the JSON module, when both JSON and
41 JSON::XS are installed, then JSON will fall back on JSON::XS (this can be
43 and methods). If JSON::XS is not available, it will fall back to the
44 compatible JSON::PP module as backend, so using JSON instead of JSON::XS
45 gives you a portable JSON API that can be fast when you need and doesn't
48 As this is the n-th-something JSON module on CPAN, what was the reason
49 to write yet another JSON module? While it seems there are many JSON
54 See MAPPING, below, on how JSON::XS maps perl values to JSON values and
69 by JSON and Perl, the deserialised data structure is identical on the Perl
74 =item * strict checking of JSON correctness
76 There is no guessing, no generating of illegal JSON texts by default,
77 and only JSON is accepted as input by default (the latter is a security
82 Compared to other JSON modules and other serialisers such as Storable,
102 package JSON::XS;
113 Carp::croak ("JSON::XS::to_json has been renamed to encode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
118 Carp::croak ("JSON::XS::from_json has been renamed to decode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
138 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
145 to parse that as an UTF-8 encoded JSON text, returning the resulting
150 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
154 =item $is_boolean = JSON::XS::is_bool $scalar
156 Returns true if the passed scalar represents either JSON::XS::true or
157 JSON::XS::false, two constants that act like C<1> and C<0>, respectively
158 and are used to represent JSON C<true> and C<false> values in Perl.
160 See MAPPING, below, for more information on how JSON values are mapped to
221 =item $json = new JSON::XS
223 Creates a new JSON::XS object that can be used to de/encode JSON
226 The mutators for flags all return the JSON object again and thus calls can
229 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
240 as per RFC4627. The resulting encoded JSON text can be treated as a native
245 characters unless required by the JSON syntax or other flags. This results
251 The main use for this flag is to produce JSON texts that can be
252 transmitted over a 7-bit channel, as the encoded JSON texts will not
255 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
263 the resulting JSON text as latin1 (or iso-8859-1), escaping any characters
265 latin1-encoded JSON text or a native Unicode string. The C<decode> method
270 characters unless required by the JSON syntax or other flags.
275 The main use for this flag is efficiently encoding binary data as JSON
277 size. The disadvantage is that the resulting JSON text is encoded
279 transferring), a rare encoding for JSON. It is therefore most useful when
281 in files or databases, not when talking to other JSON encoders/decoders.
283 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
291 the JSON result into UTF-8, as required by many protocols, while the
298 If C<$enable> is false, then the C<encode> method will return the JSON
306 Example, output UTF-16BE-encoded JSON:
309 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
311 Example, decode UTF-32LE-encoded JSON:
314 $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
324 my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
342 resulting JSON text is guaranteed not to contain any C<newlines>.
344 This setting has no effect when decoding JSON texts.
351 optional space before the C<:> separating keys from values in JSON objects.
356 This setting has no effect when decoding JSON texts. You will also
368 optional space after the C<:> separating keys from values in JSON objects
375 This setting has no effect when decoding JSON texts.
386 extensions to normal JSON syntax (see below). C<encode> will not be
388 JSON texts as if they were valid!>. I suggest only to use this option to
393 valid JSON texts.
401 JSON I<separates> array elements and key-value pairs with commas. This
402 can be annoying if you write JSON texts manually and want to be able to
417 Whenever JSON allows whitespace, shell-style comments are additionally
422 1, # this comment not allowed in JSON
432 If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
440 the same JSON text (given the same overall settings). If it is disabled,
444 This setting has no effect when decoding JSON texts.
453 non-reference into its corresponding string, number or null JSON value,
454 which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
458 passed an arrayref or hashref, as JSON texts must either be an object
460 JSON object or array.
462 Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
463 resulting in an invalid JSON text:
465 JSON::XS->new->allow_nonref->encode ("Hello, World!")
473 exception when it encounters values it cannot represent in JSON (for
474 example, filehandles) but instead will encode a JSON C<null> value. Note
479 exception when it encounters anything it cannot encode as JSON.
527 time it decodes a JSON object. The only argument is a reference to the
539 Example, convert all JSON objects into the integer 5:
541 my $js = JSON::XS->new->filter_json_object (sub { 5 });
551 JSON objects having a single key named C<$key>.
554 C<filter_json_object>, if any. It gets passed the single value in the JSON
566 as single-key JSON objects are as close to the type-tagged value concept
567 as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not
576 Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
580 JSON::XS
607 memory when your JSON texts are either very very long or you have many
633 or decoding. If a higher nesting level is detected in JSON text or a Perl
658 Set the maximum length a JSON text may have (in bytes) where decoding is
672 to a hash or array) to its JSON representation. Simple scalars will be
673 converted into JSON string or number sequences, while references to arrays
674 become JSON arrays and references to hashes become JSON objects. Undefined
675 Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
680 The opposite of C<encode>: expects a JSON text and tries to parse it,
683 JSON numbers and strings become simple Perl scalars. JSON arrays become
684 Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
690 when there is trailing garbage after the first JSON object, it will
694 This is useful if your JSON texts are not delimited by an outer protocol
696 to know where the JSON text ends.
698 JSON::XS->new->decode_prefix ("[1] the tail")
706 In some cases, there is the need for incremental parsing of JSON
707 texts. While this module always has to keep both JSON text and resulting
709 JSON stream incrementally. It does so by accumulating text until it has
710 a full JSON object, which it then can decode. This process is similar to
711 using C<decode_prefix> to see if a full JSON object is available, but
715 JSON::XS will only attempt to parse the JSON text once it is sure it
720 soon as a syntactically valid JSON text has been seen. This means you need
735 existing JSON fragment stored in the C<$json> object.
742 exactly I<one> JSON object. If that is successful, it will return this
750 otherwise. For this to work, there must be no separators between the JSON
753 case. Note that in this case, any previously-parsed JSON texts will be
756 Example: Parse some JSON arrays/objects in a given string and return
759 my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
763 This method returns the currently stored JSON fragment as an lvalue, that
772 JSON object or b) parsing multiple JSON objects separated by non-JSON text
791 This is useful if you want to repeatedly parse JSON objects and want to
801 work sensibly: JSON objects and arrays are self-delimited, i.e. you can concatenate
803 for JSON numbers, however.
805 For example, is the string C<1> a single JSON number, or is it simply the
806 start of C<12>? Or is C<12> a single JSON number, or the concatenation
807 of C<1> and C<2>? In neither case you can tell, and this is why JSON::XS
813 works similarly to C<decode_prefix>: We want to decode the JSON object at
814 the start of a string and identify the portion after the JSON object:
818 my $json = new JSON::XS;
821 or die "expected JSON object or array at beginning of string";
829 you read some requests from a TCP stream, and each request is a JSON
832 the start of the JSON text, which makes it possible to test said protocol
838 my $json = new JSON::XS;
849 Another complicated example: Assume you have a string with JSON objects
851 [3]>). To parse them, we have to skip the commas between the JSON texts,
855 my $json = new JSON::XS;
870 JSON array-of-objects, many gigabytes in size, and you want to parse it,
874 Well, you lost, you have to implement your own JSON parser. But JSON::XS
876 JSON decode the array elements, which are all full JSON objects on their
877 own (this wouldn't work if the array elements could be JSON numbers, for
880 my $json = new JSON::XS;
901 # in this loop we read data until we got a single JSON object
950 This section describes how JSON::XS maps Perl values to JSON values and
960 =head2 JSON -> PERL
966 A JSON object becomes a reference to a hash in Perl. No ordering of object
967 keys is preserved (JSON does not preserve object key ordering itself).
971 A JSON array becomes a reference to an array in Perl.
975 A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON
981 A JSON number becomes either an integer, numeric (floating point) or
987 If the number consists of digits only, JSON::XS will try to represent
991 which case you lose roundtripping ability, as the JSON number will be
992 re-encoded toa JSON string).
997 the JSON number will still be re-encoded as a JSON number).
1001 floating point, JSON::XS only guarantees precision up to but not including
1006 These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
1008 C<1> and C<0>. You can check whether a scalar is a JSON boolean by using
1009 the C<JSON::XS::is_bool> function.
1013 A JSON null atom becomes C<undef> in Perl.
1018 =head2 PERL -> JSON
1020 The mapping from Perl to JSON is slightly more difficult, as Perl is a
1021 truly typeless language, so we can only guess which JSON type is meant by
1028 Perl hash references become JSON objects. As there is no inherent ordering
1029 in hash keys (or JSON objects), they will usually be encoded in a
1031 stays generally the same within a single run of a program. JSON::XS can
1033 the same datastructure will serialise to the same JSON text (given same
1034 settings and version of JSON::XS), but this incurs a runtime overhead
1035 and is only rarely useful, e.g. when you want to compare some JSON text
1040 Perl array references become JSON arrays.
1046 C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
1047 also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
1049 encode_json [\0, JSON::XS::true] # yields [false,true]
1051 =item JSON::XS::true, JSON::XS::false
1053 These special values become JSON true and JSON false values,
1058 Blessed objects are not directly representable in JSON. See the
1067 difficult objects to encode: JSON::XS will encode undefined scalars as
1068 JSON C<null> values, scalars that have last been used in a string context
1069 before encoding as JSON strings, and anything else as number value:
1083 You can force the type to be a JSON string by stringifying it:
1090 You can force the type to be a JSON number by numifying it:
1104 infinities or NaN's - these cannot be represented in JSON, and it is an
1116 C<utf8> controls whether the JSON text created by C<encode> (and expected
1148 want to have UTF-16 encoded JSON texts) or when some other layer does
1192 they only govern when the JSON output engine escapes a character or not.
1195 as JSON, at the expense of breaking compatibility with most JSON decoders.
1201 when your channel for JSON transfer is not 8-bit clean or the encoding
1208 =head2 JSON and ECMAscript
1210 JSON syntax is based on how literals are represented in javascript (the
1214 However, JSON is not a subset (and also not a superset of course) of
1218 If you want to use javascript's C<eval> function to "parse" JSON, you
1219 might run into parse errors for valid JSON texts, or the resulting data
1223 JSON strings, but are not allowed in ECMAscript string literals, so the
1227 use JSON::XS;
1231 The right fix for this is to use a proper JSON parser in your javascript
1236 ASCII-only JSON:
1238 use JSON::XS;
1240 print JSON::XS->new->ascii->encode ([chr 0x2028]);
1242 Note that this will enlarge the resulting JSON text quite a bit if you
1247 my $json = JSON::XS->new->utf8->encode ([chr 0x2028]);
1262 If that is a problem, you could parse try to filter the resulting JSON
1273 =head2 JSON and YAML
1275 You often hear that JSON is a subset of YAML. This is, however, a mass
1278 JSON::XS to output a data structure as valid YAML> that works in all
1281 If you really must use JSON::XS to generate YAML, you should use this
1284 my $to_yaml = JSON::XS->new->utf8->space_after (1);
1287 This will I<usually> generate JSON texts that also parse as valid
1289 lengths that JSON doesn't have and also has different and incompatible
1294 sequences in strings (which JSON::XS does not I<currently> generate, but
1295 other JSON generators might).
1299 general you should not try to generate YAML with a JSON generator or vice
1300 versa, or try to parse JSON with a YAML parser or vice versa: chances are
1311 bitten by this "JSON is YAML" lie, I refused and said I will continue to
1318 proponents, I would kindly suggest reading the JSON spec (which is not
1324 Addendum/2009: the YAML 1.2 spec is still incompatible with JSON, even
1327 of JSON. It would be so easy to fix, but apparently, bullying people and
1335 It seems that JSON::XS is surprisingly fast, as shown in the following
1337 in the JSON::XS distribution, to make it easy to compare on your own
1341 a very short single-line JSON string (also available at
1348 It shows the number of encodes/decodes per second (JSON::XS uses
1349 the functional interface, while JSON::XS/2 uses the OO interface
1350 with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1351 shrink. JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ
1356 JSON::DWIW/DS | 86302.551 | 102300.098 |
1357 JSON::DWIW/FJ | 86302.551 | 75983.768 |
1358 JSON::PP | 15827.562 | 6638.658 |
1359 JSON::Syck | 63358.066 | 47662.545 |
1360 JSON::XS | 511500.488 | 511500.488 |
1361 JSON::XS/2 | 291271.111 | 388361.481 |
1362 JSON::XS/3 | 361577.931 | 361577.931 |
1366 That is, JSON::XS is almost six times faster than JSON::DWIW on encoding,
1368 faster than JSON's pure perl implementation. It also compares favourably
1376 JSON::DWIW/DS | 1647.927 | 2673.916 |
1377 JSON::DWIW/FJ | 1630.249 | 2596.128 |
1378 JSON::PP | 400.640 | 62.311 |
1379 JSON::Syck | 1481.040 | 1524.869 |
1380 JSON::XS | 20661.596 | 9541.183 |
1381 JSON::XS/2 | 10683.403 | 9416.938 |
1382 JSON::XS/3 | 20661.596 | 9400.054 |
1386 Again, JSON::XS leads by far (except for Storable which non-surprisingly
1390 (such as JSON::PC) seem to decode faster than JSON::XS, but the result
1398 When you are using JSON in a protocol, talking to untrusted potentially
1401 First of all, your JSON decoder should be secure, that is, should not have
1406 limit the size of JSON texts you accept, or make sure then when your
1408 can crash safely). The size of a JSON text in octets or characters is
1410 it into a Perl structure. While JSON::XS can check the size of the JSON
1414 Third, JSON::XS recurses using the C stack when decoding objects and
1417 only 14k nested JSON objects (due to perl itself recursing deeply on croak
1426 Also keep in mind that JSON::XS might leak contents of your Perl data
1428 information you might want to make sure that exceptions thrown by JSON::XS
1431 If you are using JSON::XS to return packets to consumption
1461 our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
1462 our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
1468 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
1469 # or UNIVERSAL::isa $_[0], "JSON::Literal"
1472 XSLoader::load "JSON::XS", $VERSION;
1474 package JSON::XS::Boolean;