| 1 | package Cpanel::JSON::XS; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2 | 69 | our $VERSION = '4.82'; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 3 | 69 | our $XS_VERSION = $VERSION; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 4 | # $VERSION = eval $VERSION; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 5 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 6 | =pod | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 7 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 8 | =head1 NAME | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 9 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 10 | Cpanel::JSON::XS - cPanel fork of JSON::XS, fast and correct serializing | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 11 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 12 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 13 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 14 | use Cpanel::JSON::XS; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 15 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 16 | # exported functions, they croak on error | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 17 | # and expect/generate UTF-8 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 18 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 19 | $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 20 | $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 21 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 22 | # OO-interface | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 23 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 24 | $coder = Cpanel::JSON::XS->new->ascii->pretty->allow_nonref; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 25 | $pretty_printed_unencoded = $coder->encode ($perl_scalar); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 26 | $perl_scalar = $coder->decode ($unicode_json_text); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 27 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 28 | # Note that 5.6 misses most smart utf8 and encoding functionalities | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 29 | # of newer releases. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 30 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 31 | # Note that L<JSON::MaybeXS> will automatically use Cpanel::JSON::XS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 32 | # if available, at virtually no speed overhead either, so you should | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 33 | # be able to just: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 34 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 35 | use JSON::MaybeXS; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 36 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 37 | # and do the same things, except that you have a pure-perl fallback now. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 38 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 39 | Note that this module will be replaced by a new JSON::Safe module soon, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 40 | with the same API just guaranteed safe defaults. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 41 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 42 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 43 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 44 | This module converts Perl data structures to JSON and vice versa. Its | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 45 | primary goal is to be I<correct> and its secondary goal is to be | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 46 | I<fast>. To reach the latter goal it was written in C. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 47 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 50 | modules, none of them correctly handle all corner cases, and in most cases | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 51 | their maintainers are unresponsive, gone missing, or not listening to bug | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 52 | reports for other reasons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 53 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 54 | See below for the cPanel fork. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 56 | See MAPPING, below, on how Cpanel::JSON::XS maps perl values to JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 57 | values and vice versa. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 58 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 59 | =head2 FEATURES | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 60 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 61 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 62 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 63 | =item * correct Unicode handling | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 64 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 65 | This module knows how to handle Unicode with Perl version higher than 5.8.5, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 66 | documents how and when it does so, and even documents what "correct" means. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 67 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 68 | =item * round-trip integrity | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 69 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 70 | When you serialize a perl data structure using only data types supported | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 71 | by JSON and Perl, the deserialized data structure is identical on the Perl | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 72 | level. (e.g. the string "2.0" doesn't suddenly become "2" just because | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 73 | it looks like a number). There I<are> minor exceptions to this, read the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 74 | MAPPING section below to learn about those. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 75 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 76 | =item * strict checking of JSON correctness | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 77 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 78 | There is no guessing, no generating of illegal JSON texts by default, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 79 | and only JSON is accepted as input by default. the latter is a security | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 80 | feature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 81 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 82 | =item * fast | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 83 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 84 | Compared to other JSON modules and other serializers such as Storable, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 85 | this module usually compares favourably in terms of speed, too. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 86 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 87 | =item * simple to use | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 88 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 89 | This module has both a simple functional interface as well as an object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 90 | oriented interface. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 91 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 92 | =item * reasonably versatile output formats | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 93 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 94 | You can choose between the most compact guaranteed-single-line format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 95 | possible (nice for simple line-based protocols), a pure-ASCII format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 96 | (for when your transport is not 8-bit clean, still supports the whole | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 97 | Unicode range), or a pretty-printed format (for when you want to read that | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 98 | stuff). Or you can combine those features in whatever way you like. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 99 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 100 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 101 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 102 | =head2 cPanel fork | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 103 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 104 | Since the original author MLEHMANN has no public | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 105 | bugtracker, this cPanel fork sits now on github. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 106 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 107 | src repo: L<https://github.com/rurban/Cpanel-JSON-XS> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 108 | original: L<http://cvs.schmorp.de/JSON-XS/> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 109 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 110 | RT: L<https://github.com/rurban/Cpanel-JSON-XS/issues> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 111 | or L<https://rt.cpan.org/Public/Dist/Display.html?Queue=Cpanel-JSON-XS> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 112 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 113 | B<Changes to JSON::XS> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 114 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 115 | - bare hashkeys are now checked for utf8. (GH #209) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 116 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 117 | - stricter decode_json() as documented. non-refs are disallowed. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 118 | safe by default. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 119 | added a 2nd optional argument. decode() honors now allow_nonref. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 120 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 121 | - fixed encode of numbers for dual-vars. Different string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 122 | representations are preserved, but numbers with temporary strings | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 123 | which represent the same number are here treated as numbers, not | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 124 | strings. Cpanel::JSON::XS is a bit slower, but preserves numeric | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 125 | types better. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 126 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 127 | - numbers ending with .0 stray numbers, are not converted to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 128 | integers. [#63] dual-vars which are represented as number not | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 129 | integer (42+"bar" != 5.8.9) are now encoded as number (=> 42.0) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 130 | because internally it's now a NOK type. However !!1 which is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 131 | wrongly encoded in 5.8 as "1"/1.0 is still represented as integer. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 132 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 133 | - different handling of inf/nan. Default now to null, optionally with | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 134 | stringify_infnan() to "inf"/"nan". [#28, #32] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 135 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 136 | - added C<binary> extension, non-JSON and non JSON parsable, allows | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 137 | C<\xNN> and C<\NNN> sequences. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 138 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 139 | - 5.6.2 support; sacrificing some utf8 features (assuming bytes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 140 | all-over), no multi-byte unicode characters with 5.6. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 141 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 142 | - interop for true/false overloading. JSON::XS, JSON::PP and Mojo::JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 143 | representations for booleans are accepted and JSON::XS accepts | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 144 | Cpanel::JSON::XS booleans [#13, #37] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 145 | Fixed overloading of booleans. Cpanel::JSON::XS::true stringifies again | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 146 | to "1", not "true", analog to all other JSON modules. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 147 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 148 | - native boolean mapping of yes and no to true and false, as in YAML::XS. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 149 | In perl C<!0> is yes, C<!1> is no. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 150 | The JSON value true maps to 1, false maps to 0. [#39] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 151 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 152 | - support arbitrary stringification with encode, with convert_blessed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 153 | and allow_blessed. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 154 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 155 | - ithread support. Cpanel::JSON::XS is thread-safe, JSON::XS not | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 156 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 157 | - is_bool can be called as method, JSON::XS::is_bool not. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 158 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 159 | - performance optimizations for threaded Perls | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 160 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 161 | - relaxed mode, allowing many popular extensions | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 162 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 163 | - protect our magic object from corruption by wrong or missing external | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 164 | methods, like FREEZE/THAW or serialization with other methods. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 165 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 166 | - additional fixes for: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 167 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 168 | - #208 - no security-relevant out-of-bounds reading of module memory | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 169 | when decoding hash keys without ending ':' | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 170 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 171 | - [cpan #88061] AIX atof without USE_LONG_DOUBLE | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 172 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 173 | - #10 unshare_hek crash | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 174 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 175 | - #7, #29 avoid re-blessing where possible. It fails in JSON::XS for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 176 | READONLY values, i.e. restricted hashes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 177 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 178 | - #41 overloading of booleans, use the object not the reference. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 179 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 180 | - #62 -Dusequadmath conversion and no SEGV. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 181 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 182 | - #72 parsing of values followed \0, like 1\0 does fail. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 183 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 184 | - #72 parsing of illegal unicode or non-unicode characters. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 185 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 186 | - #96 locale-insensitive numeric conversion. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 187 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 188 | - #154 numeric conversion fixed since 5.22, using the same strtold as perl5. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 189 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 190 | - #167 sort tied hashes with canonical. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 191 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 192 | - #212 fix utf8 object stringification | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 193 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 194 | - public maintenance and bugtracker | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 195 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 196 | - use ppport.h, sanify XS.xs comment styles, harness C coding style | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 197 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 198 | - common::sense is optional. When available it is not used in the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 199 | published production module, just during development and testing. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 200 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 201 | - extended testsuite, passes all http://seriot.ch/projects/parsing_json.html | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 202 | tests. In fact it is the only know JSON decoder which does so, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 203 | while also being the fastest. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 204 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 205 | - support many more options and methods from JSON::PP: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 206 | stringify_infnan, allow_unknown, allow_stringify, allow_barekey, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 207 | encode_stringify, allow_bignum, allow_singlequote, dupkeys_as_arrayref, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 208 | sort_by (partially), escape_slash, convert_blessed, ... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 209 | optional decode_json(, allow_nonref) arg. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 210 | relaxed implements allow_dupkeys. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 211 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 212 | - support all 5 unicode L<BOM|/BOM>'s: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 213 | UTF-32BE, encoding internally to UTF-8. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 214 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 215 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 216 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 217 | 69 | our @ISA = qw(Exporter); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 218 | 69 | our @EXPORT = qw(encode_json decode_json to_json from_json); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 219 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 220 | 0 | ▶ | sub to_json($@) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
to_json: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 221 | 0 | ▶ | if ($] >= 5.008) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 222 | 0 | require Carp; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 223 | 0 | Carp::croak ("Cpanel::JSON::XS::to_json has been renamed to encode_json,". | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 224 | " either downgrade to pre-2.0 versions of Cpanel::JSON::XS or". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 225 | " rename the call"); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 226 | } else { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 227 | 0 | _to_json(@_); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 228 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 229 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 230 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 231 | 0 | ▶ | sub from_json($@) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
from_json: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 232 | 0 | ▶ | if ($] >= 5.008) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 233 | 0 | require Carp; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 234 | 0 | Carp::croak ("Cpanel::JSON::XS::from_json has been renamed to decode_json,". | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 235 | " either downgrade to pre-2.0 versions of Cpanel::JSON::XS or". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 236 | " rename the call"); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 237 | } else { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 238 | 0 | _from_json(@_); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 239 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 240 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 241 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 242 | 69 | ▶ | use Exporter; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 243 | 69 | ▶ | use XSLoader; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 244 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 245 | =head1 FUNCTIONAL INTERFACE | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 246 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 247 | The following convenience methods are provided by this module. They are | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 248 | exported by default: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 249 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 250 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 251 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 252 | =item $json_text = encode_json $perl_scalar, [json_type] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 253 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 254 | Converts the given Perl data structure to a UTF-8 encoded, binary string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 255 | (that is, the string contains octets only). Croaks on error. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 256 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 257 | This function call is functionally identical to: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 258 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 259 | $json_text = Cpanel::JSON::XS->new->utf8->encode ($perl_scalar, $json_type) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 260 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 261 | Except being faster. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 262 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 263 | For the type argument see L<Cpanel::JSON::XS::Type>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 264 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 265 | =item $perl_scalar = decode_json $json_text [, $allow_nonref [, my $json_type ] ] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 266 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 267 | The opposite of C<encode_json>: expects an UTF-8 (binary) string of an | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 268 | json reference and tries to parse that as an UTF-8 encoded JSON text, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 269 | returning the resulting reference. Croaks on error. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 270 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 271 | This function call is functionally identical to: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 272 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 273 | $perl_scalar = Cpanel::JSON::XS->new->utf8->decode ($json_text, $json_type) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 274 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 275 | except being faster. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 276 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 277 | Note that older decode_json versions in Cpanel::JSON::XS older than | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 278 | 3.0116 and JSON::XS did not set allow_nonref but allowed them due to a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 279 | bug in the decoder. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 280 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 281 | Since version 4.42, C<allow_nonref> is enabled by default, matching | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 282 | JSON::XS 4.0+. The 2nd optional C<$allow_nonref> argument can be set | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 283 | to false (C<0>) to disable it. When enabled, the function accepts all | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 284 | JSON values: objects, arrays, strings, numbers, C<null>, C<true>, and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 285 | C<false>. See L</"OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)> for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 286 | why you might not want this. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 287 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 288 | For the 3rd optional type argument see L<Cpanel::JSON::XS::Type>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 289 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 290 | =item $is_boolean = Cpanel::JSON::XS::is_bool $scalar | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 291 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 292 | Returns true if the passed scalar represents either C<JSON::PP::true> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 293 | or C<JSON::PP::false>, two constants that act like C<1> and C<0>, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 294 | respectively and are used to represent JSON C<true> and C<false> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 295 | values in Perl. (Also recognizes the booleans produced by L<JSON::XS>.) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 296 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 297 | See MAPPING, below, for more information on how JSON values are mapped | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 298 | to Perl. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 299 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 300 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 301 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 302 | =head1 DEPRECATED FUNCTIONS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 303 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 304 | =over | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 305 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 306 | =item from_json | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 307 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 308 | from_json has been renamed to decode_json | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 309 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 310 | =item to_json | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 311 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 312 | to_json has been renamed to encode_json | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 313 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 314 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 315 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 316 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 317 | =head1 A FEW NOTES ON UNICODE AND PERL | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 318 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 319 | Since this often leads to confusion, here are a few very clear words on | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 320 | how Unicode works in Perl, modulo bugs. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 321 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 322 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 323 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 324 | =item 1. Perl strings can store characters with ordinal values > 255. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 325 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 326 | This enables you to store Unicode characters as single characters in a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 327 | Perl string - very natural. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 328 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 329 | =item 2. Perl does I<not> associate an encoding with your strings. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 330 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 331 | ... until you force it to, e.g. when matching it against a regex, or | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 332 | printing the scalar to a file, in which case Perl either interprets | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 333 | your string as locale-encoded text, octets/binary, or as Unicode, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 334 | depending on various settings. In no case is an encoding stored | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 335 | together with your data, it is I<use> that decides encoding, not any | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 336 | magical meta data. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 337 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 338 | =item 3. The internal utf-8 flag has no meaning with regards to the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 339 | encoding of your string. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 340 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 341 | =item 4. A "Unicode String" is simply a string where each character | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 342 | can be validly interpreted as a Unicode code point. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 343 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 344 | If you have UTF-8 encoded data, it is no longer a Unicode string, but | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 345 | a Unicode string encoded in UTF-8, giving you a binary string. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 346 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 347 | =item 5. A string containing "high" (> 255) character values is I<not> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 348 | a UTF-8 string. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 349 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 350 | =item 6. Raw non-Unicode characters below U+10FFFF are allowed. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 351 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 352 | The 66 Unicode noncharacters U+FDD0..U+FDEF, and U+*FFFE, U+*FFFF are | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 353 | allowed without warning, as JSON::PP does, see | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 354 | L<http://www.unicode.org/versions/corrigendum9.html>. But illegal | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 355 | surrogate pairs fail to parse. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 356 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 357 | =item 7. Raw non-Unicode characters above U+10FFFF are disallowed. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 358 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 359 | Raw non-Unicode characters outside the valid unicode range fail to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 360 | parse, because "A string is a sequence of zero or more Unicode | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 361 | characters" RFC 7159 section 1 and "JSON text SHALL be encoded in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 362 | Unicode RFC 7159 section 8.1. We use now the UTF8_DISALLOW_SUPER | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 363 | flag when parsing unicode. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 364 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 365 | =item 8. Lone surrogates or illegal surrogate pairs are disallowed. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 366 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 367 | Since RFC 3629, U+D800 through U+DFFF are not legal Unicode values and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 368 | their UTF-8 encodings must be treated as an invalid byte sequence. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 369 | RFC 8259 section 8.2 admits the spec allows string values that contain | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 370 | bit sequences that cannot encode Unicode characters and that the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 371 | behavior of software that receives such values is unpredictable. To | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 372 | avoid introducing non-Unicode strings into Perl we use the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 373 | UTF8_DISALLOW_SURROGATE flag when parsing Unicode and verify escaped | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 374 | surrogates form valid pairs. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 375 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 376 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 377 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 378 | I hope this helps :) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 379 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 380 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 381 | =head1 OBJECT-ORIENTED INTERFACE | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 382 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 383 | The object oriented interface lets you configure your own encoding or | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 384 | decoding style, within the limits of supported formats. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 385 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 386 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 387 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 388 | =item $json = new Cpanel::JSON::XS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 389 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 390 | Creates a new JSON object that can be used to de/encode JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 391 | strings. All boolean flags described below are by default I<disabled>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 392 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 393 | The mutators for flags all return the JSON object again and thus calls can | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 394 | be chained: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 395 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 396 | my $json = Cpanel::JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 397 | => {"a": [1, 2]} | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 398 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 399 | =item $json = $json->ascii ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 400 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 401 | =item $enabled = $json->get_ascii | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 402 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 403 | If C<$enable> is true (or missing), then the C<encode> method will not | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 404 | generate characters outside the code range C<0..127> (which is ASCII). Any | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 405 | Unicode characters outside that range will be escaped using either a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 406 | single C<\uXXXX> (BMP characters) or a double C<\uHHHH\uLLLLL> escape sequence, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 407 | as per RFC4627. The resulting encoded JSON text can be treated as a native | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 408 | Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 409 | or any other superset of ASCII. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 410 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 411 | If C<$enable> is false, then the C<encode> method will not escape Unicode | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 412 | characters unless required by the JSON syntax or other flags. This results | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 413 | in a faster and more compact format. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 414 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 415 | See also the section I<ENCODING/CODESET FLAG NOTES> later in this | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 416 | document. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 417 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 418 | The main use for this flag is to produce JSON texts that can be | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 419 | transmitted over a 7-bit channel, as the encoded JSON texts will not | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 420 | contain any 8 bit characters. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 421 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 422 | Cpanel::JSON::XS->new->ascii (1)->encode ([chr 0x10401]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 423 | => ["\ud801\udc01"] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 424 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 425 | =item $json = $json->latin1 ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 426 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 427 | =item $enabled = $json->get_latin1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 428 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 429 | If C<$enable> is true (or missing), then the C<encode> method will encode | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 430 | the resulting JSON text as latin1 (or ISO-8859-1), escaping any characters | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 431 | outside the code range C<0..255>. The resulting string can be treated as a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 432 | latin1-encoded JSON text or a native Unicode string. The C<decode> method | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 433 | will not be affected in any way by this flag, as C<decode> by default | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 434 | expects Unicode, which is a strict superset of latin1. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 435 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 436 | If C<$enable> is false, then the C<encode> method will not escape Unicode | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 437 | characters unless required by the JSON syntax or other flags. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 438 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 439 | See also the section I<ENCODING/CODESET FLAG NOTES> later in this | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 440 | document. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 441 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 442 | The main use for this flag is efficiently encoding binary data as JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 443 | text, as most octets will not be escaped, resulting in a smaller encoded | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 444 | size. The disadvantage is that the resulting JSON text is encoded | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 445 | in latin1 (and must correctly be treated as such when storing and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 446 | transferring), a rare encoding for JSON. It is therefore most useful when | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 447 | you want to store data structures known to contain binary data efficiently | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 448 | in files or databases, not when talking to other JSON encoders/decoders. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 449 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 450 | Cpanel::JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 451 | => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 452 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 453 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 454 | =item $json = $json->binary ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 455 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 456 | =item $enabled = $json = $json->get_binary | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 457 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 458 | If the C<$enable> argument is true (or missing), then the C<encode> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 459 | method will not try to detect an UTF-8 encoding in any JSON string, it | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 460 | will strictly interpret it as byte sequence. The result might contain | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 461 | new C<\xNN> sequences, which is B<unparsable JSON>. The C<decode> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 462 | method forbids C<\uNNNN> sequences and accepts C<\xNN> and octal | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 463 | C<\NNN> sequences. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 464 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 465 | There is also a special logic for perl 5.6 and utf8. 5.6 encodes any | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 466 | string to utf-8 automatically when seeing a codepoint >= C<0x80> and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 467 | < C<0x100>. With the binary flag enabled decode the perl utf8 encoded | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 468 | string to the original byte encoding and encode this with C<\xNN> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 469 | escapes. This will result to the same encodings as with newer | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 470 | perls. But note that binary multi-byte codepoints with 5.6 will | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 471 | result in C<illegal unicode character in binary string> errors, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 472 | unlike with newer perls. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 473 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 474 | If C<$enable> is false, then the C<encode> method will smartly try to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 475 | detect Unicode characters unless required by the JSON syntax or other | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 476 | flags and hex and octal sequences are forbidden. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 477 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 478 | See also the section I<ENCODING/CODESET FLAG NOTES> later in this | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 479 | document. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 480 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 481 | The main use for this flag is to avoid the smart unicode detection and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 482 | possible double encoding. The disadvantage is that the resulting JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 483 | text is encoded in new C<\xNN> and in latin1 characters and must | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 484 | correctly be treated as such when storing and transferring, a rare | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 485 | encoding for JSON. It will produce non-readable JSON strings in the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 486 | browser. It is therefore most useful when you want to store data | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 487 | structures known to contain binary data efficiently in files or | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 488 | databases, not when talking to other JSON encoders/decoders. The | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 489 | binary decoding method can also be used when an encoder produced a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 490 | non-JSON conformant hex or octal encoding C<\xNN> or C<\NNN>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 491 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 492 | Cpanel::JSON::XS->new->binary->encode (["\x{89}\x{abc}"]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 493 | 5.6: Error: malformed or illegal unicode character in binary string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 494 | >=5.8: ['\x89\xe0\xaa\xbc'] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 495 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 496 | Cpanel::JSON::XS->new->binary->encode (["\x{89}\x{bc}"]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 497 | => ["\x89\xbc"] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 498 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 499 | Cpanel::JSON::XS->new->binary->decode (["\x89\ua001"]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 500 | Error: malformed or illegal unicode character in binary string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 501 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 502 | Cpanel::JSON::XS->new->decode (["\x89"]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 503 | Error: illegal hex character in non-binary string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 504 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 505 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 506 | =item $json = $json->utf8 ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 507 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 508 | =item $enabled = $json->get_utf8 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 509 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 510 | If C<$enable> is true (or missing), then the C<encode> method will encode | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 511 | the JSON result into UTF-8, as required by many protocols, while the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 512 | C<decode> method expects to be handled an UTF-8-encoded string. Please | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 513 | note that UTF-8-encoded strings do not contain any characters outside the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 514 | range C<0..255>, they are thus useful for bytewise/binary I/O. In future | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 515 | versions, enabling this option might enable autodetection of the UTF-16 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 516 | and UTF-32 encoding families, as described in RFC4627. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 517 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 518 | If C<$enable> is false, then the C<encode> method will return the JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 519 | string as a (non-encoded) Unicode string, while C<decode> expects thus a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 520 | Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 521 | to be done yourself, e.g. using the Encode module. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 522 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 523 | See also the section I<ENCODING/CODESET FLAG NOTES> later in this | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 524 | document. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 525 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 526 | Example, output UTF-16BE-encoded JSON: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 527 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 528 | use Encode; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 529 | $jsontext = encode "UTF-16BE", Cpanel::JSON::XS->new->encode ($object); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 530 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 531 | Example, decode UTF-32LE-encoded JSON: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 532 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 533 | use Encode; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 534 | $object = Cpanel::JSON::XS->new->decode (decode "UTF-32LE", $jsontext); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 535 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 536 | =item $json = $json->pretty ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 537 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 538 | This enables (or disables) all of the C<indent>, C<space_before> and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 539 | C<space_after> (and in the future possibly more) flags in one call to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 540 | generate the most readable (or most compact) form possible. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 541 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 542 | Example, pretty-print some simple structure: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 543 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 544 | my $json = Cpanel::JSON::XS->new->pretty(1)->encode ({a => [1,2]}) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 545 | => | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 546 | { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 547 | "a" : [ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 548 | 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 549 | 2 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 550 | ] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 551 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 552 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 553 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 554 | =item $json = $json->indent ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 555 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 556 | =item $enabled = $json->get_indent | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 557 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 558 | If C<$enable> is true (or missing), then the C<encode> method will use | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 559 | a multiline format as output, putting every array member or | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 560 | object/hash key-value pair into its own line, indenting them properly. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 561 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 562 | If C<$enable> is false, no newlines or indenting will be produced, and the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 563 | resulting JSON text is guaranteed not to contain any C<newlines>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 564 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 565 | This setting has no effect when decoding JSON texts. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 566 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 567 | =item $json = $json->indent_length([$number_of_spaces]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 568 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 569 | =item $length = $json->get_indent_length() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 570 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 571 | Set the indent length (default C<3>). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 572 | This option is only useful when you also enable indent or pretty. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 573 | The acceptable range is from 0 (no indentation) to 15 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 574 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 575 | =item $json = $json->space_before ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 576 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 577 | =item $enabled = $json->get_space_before | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 578 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 579 | If C<$enable> is true (or missing), then the C<encode> method will add an extra | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 580 | optional space before the C<:> separating keys from values in JSON objects. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 581 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 582 | If C<$enable> is false, then the C<encode> method will not add any extra | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 583 | space at those places. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 584 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 585 | This setting has no effect when decoding JSON texts. You will also | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 586 | most likely combine this setting with C<space_after>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 587 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 588 | Example, space_before enabled, space_after and indent disabled: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 589 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 590 | {"key" :"value"} | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 591 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 592 | =item $json = $json->space_after ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 593 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 594 | =item $enabled = $json->get_space_after | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 595 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 596 | If C<$enable> is true (or missing), then the C<encode> method will add | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 597 | an extra optional space after the C<:> separating keys from values in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 598 | JSON objects and extra whitespace after the C<,> separating key-value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 599 | pairs and array members. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 600 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 601 | If C<$enable> is false, then the C<encode> method will not add any extra | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 602 | space at those places. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 603 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 604 | This setting has no effect when decoding JSON texts. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 605 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 606 | Example, space_before and indent disabled, space_after enabled: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 607 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 608 | {"key": "value"} | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 609 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 610 | =item $json = $json->relaxed ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 611 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 612 | =item $enabled = $json->get_relaxed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 613 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 614 | If C<$enable> is true (or missing), then C<decode> will accept some | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 615 | extensions to normal JSON syntax (see below). C<encode> will not be | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 616 | affected in anyway. I<Be aware that this option makes you accept invalid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 617 | JSON texts as if they were valid!>. I suggest only to use this option to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 618 | parse application-specific files written by humans (configuration files, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 619 | resource files etc.) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 620 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 621 | If C<$enable> is false (the default), then C<decode> will only accept | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 622 | valid JSON texts. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 623 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 624 | Currently accepted extensions are: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 625 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 626 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 627 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 628 | =item * list items can have an end-comma | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 629 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 630 | JSON I<separates> array elements and key-value pairs with commas. This | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 631 | can be annoying if you write JSON texts manually and want to be able to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 632 | quickly append elements, so this extension accepts comma at the end of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 633 | such items not just between them: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 634 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 635 | [ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 636 | 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 637 | 2, <- this comma not normally allowed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 638 | ] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 639 | { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 640 | "k1": "v1", | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 641 | "k2": "v2", <- this comma not normally allowed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 642 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 643 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 644 | =item * shell-style '#'-comments | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 645 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 646 | Whenever JSON allows whitespace, shell-style comments are additionally | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 647 | allowed. They are terminated by the first carriage-return or line-feed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 648 | character, after which more white-space and comments are allowed. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 649 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 650 | [ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 651 | 1, # this comment not allowed in JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 652 | # neither this one... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 653 | ] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 654 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 655 | =item * literal ASCII TAB characters in strings | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 656 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 657 | Literal ASCII TAB characters are now allowed in strings (and treated as | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 658 | C<\t>) in relaxed mode. Despite JSON mandates, that TAB character is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 659 | substituted for "\t" sequence. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 660 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 661 | [ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 662 | "Hello\tWorld", | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 663 | "Hello<TAB>World", # literal <TAB> would not normally be allowed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 664 | ] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 665 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 666 | =item * allow_singlequote | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 667 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 668 | Single quotes are accepted instead of double quotes. See the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 669 | L</allow_singlequote> option. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 670 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 671 | { "foo":'bar' } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 672 | { 'foo':"bar" } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 673 | { 'foo':'bar' } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 674 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 675 | =item * allow_barekey | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 676 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 677 | Accept unquoted object keys instead of with mandatory double quotes. See the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 678 | L</allow_barekey> option. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 679 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 680 | { foo:"bar" } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 681 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 682 | =item * allow_dupkeys | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 683 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 684 | Allow decoding of duplicate keys in hashes. By default duplicate keys are forbidden. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 685 | See L<http://seriot.ch/projects/parsing_json.php#24>: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 686 | RFC 7159 section 4: "The names within an object should be unique." | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 687 | See the C<allow_dupkeys> option. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 688 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 689 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 690 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 691 | =item $json = $json->canonical ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 692 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 693 | =item $enabled = $json->get_canonical | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 694 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 695 | If C<$enable> is true (or missing), then the C<encode> method will | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 696 | output JSON objects by sorting their keys. This is adding a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 697 | comparatively high overhead. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 698 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 699 | If C<$enable> is false, then the C<encode> method will output key-value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 700 | pairs in the order Perl stores them (which will likely change between runs | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 701 | of the same script, and can change even within the same run from 5.18 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 702 | onwards). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 703 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 704 | This option is useful if you want the same data structure to be encoded as | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 705 | the same JSON text (given the same overall settings). If it is disabled, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 706 | the same hash might be encoded differently even if contains the same data, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 707 | as key-value pairs have no inherent ordering in Perl. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 708 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 709 | This setting has no effect when decoding JSON texts. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 710 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 711 | This is now also done with tied hashes, contrary to L<JSON::XS>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 712 | But note that with most large tied hashes stored as tree it is advised to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 713 | sort the iterator already and don't sort the hash output here. Most such | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 714 | iterators are already sorted, as such e.g. L<DB_File> with C<DB_BTREE>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 715 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 716 | =item $json = $json->sort_by (undef, 0, 1 or a block) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 717 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 718 | This currently only (un)sets the C<canonical> option, and ignores | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 719 | custom sort blocks. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 720 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 721 | This setting has no effect when decoding JSON texts. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 722 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 723 | This setting has currently no effect on tied hashes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 724 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 725 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 726 | =item $json = $json->escape_slash ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 727 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 728 | =item $enabled = $json->get_escape_slash | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 729 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 730 | According to the JSON Grammar, the I<forward slash> character (U+002F) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 731 | C<"/"> need to be escaped. But by default strings are encoded without | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 732 | escaping slashes in all perl JSON encoders. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 733 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 734 | If C<$enable> is true (or missing), then C<encode> will escape slashes, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 735 | C<"\/">. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 736 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 737 | This setting has no effect when decoding JSON texts. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 738 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 739 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 740 | =item $json = $json->unblessed_bool ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 741 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 742 | =item $enabled = $json->get_unblessed_bool | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 743 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 744 | $json = $json->unblessed_bool([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 745 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 746 | If C<$enable> is true (or missing), then C<decode> will return Perl | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 747 | non-object boolean variables (1 and 0 as numbers or "1" and "" as | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 748 | strings) for JSON booleans (C<true> and C<false>). If C<$enable> is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 749 | false, then C<decode> will return C<JSON::PP::Boolean> objects for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 750 | JSON booleans. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 751 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 752 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 753 | =item $json = $json->allow_singlequote ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 754 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 755 | =item $enabled = $json->get_allow_singlequote | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 756 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 757 | $json = $json->allow_singlequote([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 758 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 759 | If C<$enable> is true (or missing), then C<decode> will accept | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 760 | JSON strings quoted by single quotations that are invalid JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 761 | format. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 762 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 763 | $json->allow_singlequote->decode({"foo":'bar'}); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 764 | $json->allow_singlequote->decode({'foo':"bar"}); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 765 | $json->allow_singlequote->decode({'foo':'bar'}); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 766 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 767 | This is also enabled with C<relaxed>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 768 | As same as the C<relaxed> option, this option may be used to parse | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 769 | application-specific files written by humans. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 770 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 771 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 772 | =item $json = $json->allow_barekey ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 773 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 774 | =item $enabled = $json->get_allow_barekey | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 775 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 776 | $json = $json->allow_barekey([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 777 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 778 | If C<$enable> is true (or missing), then C<decode> will accept | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 779 | bare keys of JSON object that are invalid JSON format. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 780 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 781 | Same as with the C<relaxed> option, this option may be used to parse | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 782 | application-specific files written by humans. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 783 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 784 | $json->allow_barekey->decode('{foo:"bar"}'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 785 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 786 | =item $json = $json->allow_bignum ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 787 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 788 | =item $enabled = $json->get_allow_bignum | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 789 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 790 | $json = $json->allow_bignum([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 791 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 792 | If C<$enable> is true (or missing), then C<decode> will convert | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 793 | the big integer Perl cannot handle as integer into a L<Math::BigInt> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 794 | object and convert a floating number (any) into a L<Math::BigFloat>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 795 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 796 | $int = $json->allow_nonref->allow_bignum->decode(1); # => 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 797 | $bigint = $json->allow_bignum->decode('100000000000000000000000000000000000000'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 798 | $bigfloat = $json->allow_bignum->decode(1.0); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 799 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 800 | On the contrary, C<encode> converts C<Math::BigInt> objects and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 801 | C<Math::BigFloat> objects into JSON numbers with C<allow_blessed> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 802 | enable. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 803 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 804 | $json->allow_nonref->allow_blessed->allow_bignum; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 805 | $bigfloat = $json->decode('2.000000000000000000000000001'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 806 | print $json->encode($bigfloat); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 807 | # => 2.000000000000000000000000001 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 808 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 809 | See L</MAPPING> about the normal conversion of JSON number. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 810 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 811 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 812 | =item $json = $json->allow_bigint ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 813 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 814 | This option is obsolete and replaced by allow_bignum. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 815 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 816 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 817 | =item $json = $json->allow_nonref ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 818 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 819 | =item $enabled = $json->get_allow_nonref | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 820 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 821 | If C<$enable> is true (or missing), then the C<encode> method can | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 822 | convert a non-reference into its corresponding string, number or null | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 823 | JSON value, which is an extension to RFC4627. Likewise, C<decode> will | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 824 | accept those JSON values instead of croaking. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 825 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 826 | B<This option is now enabled by default> (since version 4.42), matching | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 827 | the behavior of JSON::XS 4.0+ and the broken RFC 7159. JSON texts | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 828 | consisting of a bare scalar (string, number, C<true>, C<false>, C<null>) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 829 | are accepted by C<encode> and C<decode> without explicitly requesting it. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 830 | If you need strict RFC 4627 compliance, you must explicitly disable it: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 831 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 832 | Cpanel::JSON::XS->new->allow_nonref(0); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 833 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 834 | When disabled, C<encode> will croak if it isn't passed an arrayref or | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 835 | hashref, as JSON texts must either be an object or array. Likewise, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 836 | C<decode> will croak if given something that is not a JSON object or array. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 837 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 838 | =item $json = $json->allow_unknown ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 839 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 840 | =item $enabled = $json->get_allow_unknown | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 841 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 842 | If C<$enable> is true (or missing), then C<encode> will I<not> throw an | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 843 | exception when it encounters values it cannot represent in JSON (for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 844 | example, filehandles) but instead will encode a JSON C<null> value. Note | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 845 | that blessed objects are not included here and are handled separately by | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 846 | c<allow_nonref>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 847 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 848 | If C<$enable> is false (the default), then C<encode> will throw an | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 849 | exception when it encounters anything it cannot encode as JSON. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 850 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 851 | This option does not affect C<decode> in any way, and it is recommended to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 852 | leave it off unless you know your communications partner. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 853 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 854 | =item $json = $json->allow_stringify ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 855 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 856 | =item $enabled = $json->get_allow_stringify | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 857 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 858 | If C<$enable> is true (or missing), then C<encode> will stringify the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 859 | non-object perl value or reference. Note that blessed objects are not | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 860 | included here and are handled separately by C<allow_blessed> and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 861 | C<convert_blessed>. String references are stringified to the string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 862 | value, other references as in perl. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 863 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 864 | This option does not affect C<decode> in any way. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 865 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 866 | This option is special to this module, it is not supported by other | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 867 | encoders. So it is not recommended to use it. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 868 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 869 | =item $json = $json->require_types ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 870 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 871 | =item $enable = $json->get_require_types | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 872 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 873 | $json = $json->require_types([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 874 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 875 | If C<$enable> is true (or missing), then C<encode> will require | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 876 | either enabled C<type_all_string> or second argument with supplied JSON types. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 877 | See L<Cpanel::JSON::XS::Type>. When C<type_all_string> is not enabled or | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 878 | second argument is not provided (or is undef), then C<encode> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 879 | croaks. It also croaks when the type for provided structure in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 880 | C<encode> is incomplete. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 881 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 882 | =item $json = $json->type_all_string ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 883 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 884 | =item $enable = $json->get_type_all_string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 885 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 886 | $json = $json->type_all_string([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 887 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 888 | If C<$enable> is true (or missing), then C<encode> will always | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 889 | produce stable deterministic JSON string types in resulted output. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 890 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 891 | When C<$enable> is false, then result of encoded JSON output may be | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 892 | different for different Perl versions and may depends on loaded modules. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 893 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 894 | This is useful it you need deterministic JSON types, independently of used | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 895 | Perl version and other modules, but do not want to write complicated type | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 896 | definitions for L<Cpanel::JSON::XS::Type>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 897 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 898 | When combined with C<allow_blessed> and/or C<convert_blessed>, blessed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 899 | objects are handled by those options first, B<not> stringified by | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 900 | C<type_all_string>. For example, with C<allow_blessed + type_all_string>, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 901 | blessed objects are encoded as the JSON value C<null> (not C<"null">). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 902 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 903 | =item $json = $json->allow_dupkeys ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 904 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 905 | =item $enabled = $json->get_allow_dupkeys | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 906 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 907 | If C<$enable> is true (or missing), then the C<decode> method will not | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 908 | die when it encounters duplicate keys in a hash. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 909 | C<allow_dupkeys> is also enabled in the C<relaxed> mode. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 910 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 911 | The JSON spec allows duplicate name in objects but recommends to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 912 | disable it, however with Perl hashes they are impossible, parsing | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 913 | JSON in Perl silently ignores duplicate names, using the last value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 914 | found. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 915 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 916 | See L<http://seriot.ch/projects/parsing_json.php#24>: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 917 | RFC 7159 section 4: "The names within an object should be unique." | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 918 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 919 | =item $json = $json->dupkeys_as_arrayref ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 920 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 921 | =item $enabled = $json->get_dupkeys_as_arrayref | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 922 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 923 | If enabled, allow decoding of duplicate keys in hashes and store the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 924 | values as arrayref in the hash instead. By default duplicate keys are | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 925 | forbidden. Enabling this also enables the L</allow_dupkeys> option, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 926 | but disabling this does not disable the L</allow_dupkeys> option. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 927 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 928 | Example: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 929 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 930 | $json->dupkeys_as_arrayref; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 931 | print encode_json ($json->decode ('{"a":"b","a":"c"}')); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 932 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 933 | => {"a":["b","c"]} | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 934 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 935 | This changes the result structure, thus cannot be enabled by default. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 936 | The client must be aware of it. The resulting arrayref is not yet marked somehow | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 937 | (blessed or such). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 938 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 939 | =item $json = $json->allow_blessed ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 940 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 941 | =item $enabled = $json->get_allow_blessed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 942 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 943 | If C<$enable> is true (or missing), then the C<encode> method will not | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 944 | barf when it encounters a blessed reference. Instead, the value of the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 945 | B<convert_blessed> option will decide whether C<null> (C<convert_blessed> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 946 | disabled or no C<TO_JSON> method found) or a representation of the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 947 | object (C<convert_blessed> enabled and C<TO_JSON> method found) is being | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 948 | encoded. Has no effect on C<decode>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 949 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 950 | If C<$enable> is false (the default), then C<encode> will throw an | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 951 | exception when it encounters a blessed object without C<convert_blessed> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 952 | and a C<TO_JSON> method. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 953 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 954 | This setting has no effect on C<decode>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 955 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 956 | =item $json = $json->convert_blessed ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 957 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 958 | =item $enabled = $json->get_convert_blessed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 959 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 960 | If C<$enable> is true (or missing), then C<encode>, upon encountering a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 961 | blessed object, will check for the availability of the C<TO_JSON> method | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 962 | on the object's class. If found, it will be called in scalar context | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 963 | and the resulting scalar will be encoded instead of the object. If no | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 964 | C<TO_JSON> method is found, a stringification overload method is tried next. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 965 | If both are not found, the value of C<allow_blessed> will decide what | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 966 | to do. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 967 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 968 | The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 969 | returns other blessed objects, those will be handled in the same | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 970 | way. C<TO_JSON> must take care of not causing an endless recursion | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 971 | cycle (== crash) in this case. The same care must be taken with | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 972 | calling encode in stringify overloads (even if this works by luck in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 973 | older perls) or other callbacks. The name of C<TO_JSON> was chosen | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 974 | because other methods called by the Perl core (== not by the user of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 975 | the object) are usually in upper case letters and to avoid collisions | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 976 | with any C<to_json> function or method. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 977 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 978 | If C<$enable> is false (the default), then C<encode> will not consider | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 979 | this type of conversion. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 980 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 981 | This setting has no effect on C<decode>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 982 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 983 | =item $json = $json->allow_tags ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 984 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 985 | =item $enabled = $json->get_allow_tags | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 986 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 987 | See L<OBJECT SERIALIZATION> for details. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 988 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 989 | If C<$enable> is true (or missing), then C<encode>, upon encountering a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 990 | blessed object, will check for the availability of the C<FREEZE> method on | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 991 | the object's class. If found, it will be used to serialize the object into | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 992 | a nonstandard tagged JSON value (that JSON decoders cannot decode). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 993 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 994 | It also causes C<decode> to parse such tagged JSON values and deserialize | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 995 | them via a call to the C<THAW> method. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 996 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 997 | If C<$enable> is false (the default), then C<encode> will not consider | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 998 | this type of conversion, and tagged JSON values will cause a parse error | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 999 | in C<decode>, as if tags were not part of the grammar. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1000 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1001 | =item $json = $json->filter_json_object ([$coderef->($hashref)]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1002 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1003 | When C<$coderef> is specified, it will be called from C<decode> each | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1004 | time it decodes a JSON object. The only argument is a reference to the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1005 | newly-created hash. If the code references returns a single scalar (which | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1006 | need not be a reference), this value (i.e. a copy of that scalar to avoid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1007 | aliasing) is inserted into the deserialized data structure. If it returns | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1008 | an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1009 | original deserialized hash will be inserted. This setting can slow down | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1010 | decoding considerably. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1011 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1012 | When C<$coderef> is omitted or undefined, any existing callback will | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1013 | be removed and C<decode> will not change the deserialized hash in any | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1014 | way. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1015 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1016 | Example, convert all JSON objects into the integer 5: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1017 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1018 | my $js = Cpanel::JSON::XS->new->filter_json_object (sub { 5 }); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1019 | # returns [5] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1020 | $js->decode ('[{}]') | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1021 | # throw an exception because allow_nonref is not enabled | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1022 | # so a lone 5 is not allowed. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1023 | $js->decode ('{"a":1, "b":2}'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1024 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1025 | =item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1026 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1027 | Works remotely similar to C<filter_json_object>, but is only called for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1028 | JSON objects having a single key named C<$key>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1029 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1030 | This C<$coderef> is called before the one specified via | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1031 | C<filter_json_object>, if any. It gets passed the single value in the JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1032 | object. If it returns a single value, it will be inserted into the data | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1033 | structure. If it returns nothing (not even C<undef> but the empty list), | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1034 | the callback from C<filter_json_object> will be called next, as if no | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1035 | single-key callback were specified. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1036 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1037 | If C<$coderef> is omitted or undefined, the corresponding callback will be | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1038 | disabled. There can only ever be one callback for a given key. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1039 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1040 | As this callback gets called less often then the C<filter_json_object> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1041 | one, decoding speed will not usually suffer as much. Therefore, single-key | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1042 | objects make excellent targets to serialize Perl objects into, especially | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1043 | as single-key JSON objects are as close to the type-tagged value concept | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1044 | as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1045 | support this in any way, so you need to make sure your data never looks | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1046 | like a serialized Perl hash. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1047 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1048 | Typical names for the single object key are C<__class_whatever__>, or | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1049 | C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1050 | things like C<__class_md5sum(classname)__>, to reduce the risk of clashing | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1051 | with real hashes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1052 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1053 | Example, decode JSON objects of the form C<< { "__widget__" => <id> } >> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1054 | into the corresponding C<< $WIDGET{<id>} >> object: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1055 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1056 | # return whatever is in $WIDGET{5}: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1057 | Cpanel::JSON::XS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1058 | ->new | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1059 | ->filter_json_single_key_object (__widget__ => sub { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1060 | $WIDGET{ $_[0] } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1061 | }) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1062 | ->decode ('{"__widget__": 5') | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1063 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1064 | # this can be used with a TO_JSON method in some "widget" class | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1065 | # for serialization to json: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1066 | sub WidgetBase::TO_JSON { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1067 | my ($self) = @_; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1068 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1069 | unless ($self->{id}) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1070 | $self->{id} = ..get..some..id..; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1071 | $WIDGET{$self->{id}} = $self; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1072 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1073 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1074 | { __widget__ => $self->{id} } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1075 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1076 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1077 | =item $json = $json->shrink ([$enable]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1078 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1079 | =item $enabled = $json->get_shrink | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1080 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1081 | Perl usually over-allocates memory a bit when allocating space for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1082 | strings. This flag optionally resizes strings generated by either | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1083 | C<encode> or C<decode> to their minimum size possible. This can save | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1084 | memory when your JSON texts are either very very long or you have many | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1085 | short strings. It will also try to downgrade any strings to octet-form | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1086 | if possible: perl stores strings internally either in an encoding called | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1087 | UTF-X or in octet-form. The latter cannot store everything but uses less | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1088 | space in general (and some buggy Perl or C code might even rely on that | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1089 | internal representation being used). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1090 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1091 | The actual definition of what shrink does might change in future versions, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1092 | but it will always try to save space at the expense of time. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1093 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1094 | If C<$enable> is true (or missing), the string returned by C<encode> will | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1095 | be shrunk-to-fit, while all strings generated by C<decode> will also be | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1096 | shrunk-to-fit. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1097 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1098 | If C<$enable> is false, then the normal perl allocation algorithms are used. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1099 | If you work with your data, then this is likely to be faster. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1100 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1101 | In the future, this setting might control other things, such as converting | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1102 | strings that look like integers or floats into integers or floats | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1103 | internally (there is no difference on the Perl level), saving space. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1104 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1105 | =item $json = $json->max_depth ([$maximum_nesting_depth]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1106 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1107 | =item $max_depth = $json->get_max_depth | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1108 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1109 | Sets the maximum nesting level (default C<512>) accepted while encoding | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1110 | or decoding. If a higher nesting level is detected in JSON text or a Perl | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1111 | data structure, then the encoder and decoder will stop and croak at that | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1112 | point. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1113 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1114 | Nesting level is defined by number of hash- or arrayrefs that the encoder | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1115 | needs to traverse to reach a given point or the number of C<{> or C<[> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1116 | characters without their matching closing parenthesis crossed to reach a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1117 | given character in a string. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1118 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1119 | Setting the maximum depth to one disallows any nesting, so that ensures | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1120 | that the object is only a single hash/object or array. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1121 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1122 | If no argument is given, the highest possible setting will be used, which | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1123 | is rarely useful. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1124 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1125 | Note that nesting is implemented by recursion in C. The default value has | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1126 | been chosen to be as large as typical operating systems allow without | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1127 | crashing. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1128 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1129 | See L</SECURITY CONSIDERATIONS>, below, for more info on why this is useful. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1130 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1131 | =item $json = $json->max_size ([$maximum_string_size]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1132 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1133 | =item $max_size = $json->get_max_size | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1134 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1135 | Set the maximum length a JSON text may have (in bytes) where decoding is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1136 | being attempted. The default is C<0>, meaning no limit. When C<decode> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1137 | is called on a string that is longer then this many bytes, it will not | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1138 | attempt to decode the string but throw an exception. This setting has no | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1139 | effect on C<encode> (yet). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1140 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1141 | If no argument is given, the limit check will be deactivated (same as when | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1142 | C<0> is specified). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1143 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1144 | See L</SECURITY CONSIDERATIONS>, below, for more info on why this is useful. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1145 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1146 | =item $json->stringify_infnan ([$infnan_mode = 1]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1147 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1148 | =item $infnan_mode = $json->get_stringify_infnan | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1149 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1150 | Get or set how Cpanel::JSON::XS encodes C<inf>, C<-inf> or C<nan> for numeric | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1151 | values. Also qnan, snan or negative nan on some platforms. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1152 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1153 | C<null>: infnan_mode = 0. Similar to most JSON modules in other languages. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1154 | Always null. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1155 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1156 | stringified: infnan_mode = 1. As in Mojo::JSON. Platform specific strings. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1157 | Stringified via sprintf(%g), with double quotes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1158 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1159 | inf/nan: infnan_mode = 2. As in JSON::XS, and older releases. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1160 | Passes through platform dependent values, invalid JSON. Stringified via | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1161 | sprintf(%g), but without double quotes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1162 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1163 | "inf/-inf/nan": infnan_mode = 3. Platform independent inf/nan/-inf | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1164 | strings. No QNAN/SNAN/negative NAN support, unified to "nan". Much | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1165 | easier to detect, but may conflict with valid strings. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1166 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1167 | =item $json_text = $json->encode ($perl_scalar, $json_type) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1168 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1169 | Converts the given Perl data structure (a simple scalar or a reference | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1170 | to a hash or array) to its JSON representation. Simple scalars will be | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1171 | converted into JSON string or number sequences, while references to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1172 | arrays become JSON arrays and references to hashes become JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1173 | objects. Undefined Perl values (e.g. C<undef>) become JSON C<null> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1174 | values. Neither C<true> nor C<false> values will be generated. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1175 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1176 | For the type argument see L<Cpanel::JSON::XS::Type>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1177 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1178 | =item $bytes_written = $json->encode_to ($filehandle, $perl_scalar, $json_type) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1179 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1180 | Like C<encode>, but writes the JSON representation directly to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1181 | C<$filehandle> as it is generated, instead of building the whole result | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1182 | in memory and returning it as a string. Returns the number of bytes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1183 | (octets) written, and croaks (as C<encode> does) if C<$perl_scalar> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1184 | cannot be represented, and if the write to C<$filehandle> fails. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1185 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1186 | This is useful for very large data structures, where it lowers peak | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1187 | memory usage and gives the reader on the other end a head start instead | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1188 | of waiting for the whole document to be assembled first: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1189 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1190 | open my $fh, ">", "big.json" or die $!; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1191 | $json->encode_to ($fh, $data); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1192 | close $fh; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1193 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1194 | C<encode_to> always writes raw bytes: character data is emitted using | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1195 | the same octet encoding C<encode> would produce for the object's current | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1196 | flags (see C<utf8>, C<ascii>, C<latin1>, C<binary>), regardless of any | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1197 | PerlIO encoding layer already present on C<$filehandle>. As with | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1198 | C<encode>, do not additionally push a C<:encoding(UTF-8)> (or similar) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1199 | layer onto the handle, or the output will be double-encoded. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1200 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1201 | =item $perl_scalar = $json->decode ($json_text, my $json_type) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1202 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1203 | The opposite of C<encode>: expects a JSON text and tries to parse it, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1204 | returning the resulting simple scalar or reference. Croaks on error. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1205 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1206 | JSON numbers and strings become simple Perl scalars. JSON arrays become | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1207 | Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1208 | C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1209 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1210 | For the type argument see L<Cpanel::JSON::XS::Type>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1211 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1212 | =item $perl_scalar = $json->decode_and_validate ($json_text, $schema) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1213 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1214 | Like C<decode>, but additionally validates the decoded structure | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1215 | against C<$schema>, a schema hash built from the type spec building | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1216 | blocks in L<Cpanel::JSON::XS::Type> (plain C<JSON_TYPE_*> constants | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1217 | or their short names, C<json_type_arrayof>, C<json_type_hashof>, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1218 | C<json_type_anyof>, C<json_type_optional>, ...). Croaks with one line | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1219 | per mismatch (missing/unexpected hash keys, wrong scalar type, wrong | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1220 | array length/element type) if C<$data> doesn't match C<$schema>; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1221 | otherwise returns the decoded data exactly like C<decode> would. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1222 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1223 | use Cpanel::JSON::XS::Type; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1224 | my $schema = { id => JSON_TYPE_INT, name => 'Str', tags => json_type_arrayof('Str') }; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1225 | my $data = $json->decode_and_validate($json_text, $schema); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1226 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1227 | See L<Cpanel::JSON::XS::Type/check_type> for the full schema | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1228 | semantics, including how it differs from the encoder's permissive | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1229 | hash type spec. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1230 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1231 | =item ($perl_scalar, $characters) = $json->decode_prefix ($json_text) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1232 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1233 | This works like the C<decode> method, but instead of raising an exception | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1234 | when there is trailing garbage after the first JSON object, it will | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1235 | silently stop parsing there and return the number of characters consumed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1236 | so far. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1237 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1238 | This is useful if your JSON texts are not delimited by an outer protocol | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1239 | and you need to know where the JSON text ends. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1240 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1241 | Cpanel::JSON::XS->new->decode_prefix ("[1] the tail") | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1242 | => ([1], 3) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1243 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1244 | =item $json->to_json ($perl_hash_or_arrayref) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1245 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1246 | Deprecated method for perl 5.8 and newer. Use L<encode_json> instead. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1247 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1248 | =item $json->from_json ($utf8_encoded_json_text) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1249 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1250 | Deprecated method for perl 5.8 and newer. Use L<decode_json> instead. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1251 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1252 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1253 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1254 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1255 | =head1 INCREMENTAL PARSING | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1256 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1257 | In some cases, there is the need for incremental parsing of JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1258 | texts. While this module always has to keep both JSON text and resulting | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1259 | Perl data structure in memory at one time, it does allow you to parse a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1260 | JSON stream incrementally. It does so by accumulating text until it has | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1261 | a full JSON object, which it then can decode. This process is similar to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1262 | using C<decode_prefix> to see if a full JSON object is available, but | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1263 | is much more efficient (and can be implemented with a minimum of method | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1264 | calls). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1265 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1266 | Cpanel::JSON::XS will only attempt to parse the JSON text once it is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1267 | sure it has enough text to get a decisive result, using a very simple | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1268 | but truly incremental parser. This means that it sometimes won't stop | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1269 | as early as the full parser, for example, it doesn't detect mismatched | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1270 | parentheses. The only thing it guarantees is that it starts decoding | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1271 | as soon as a syntactically valid JSON text has been seen. This means | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1272 | you need to set resource limits (e.g. C<max_size>) to ensure the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1273 | parser will stop parsing in the presence of syntax errors. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1274 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1275 | The following methods implement this incremental parser. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1276 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1277 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1278 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1279 | =item [void, scalar or list context] = $json->incr_parse ([$string]) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1280 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1281 | This is the central parsing function. It can both append new text and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1282 | extract objects from the stream accumulated so far (both of these | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1283 | functions are optional). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1284 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1285 | If C<$string> is given, then this string is appended to the already | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1286 | existing JSON fragment stored in the C<$json> object. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1287 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1288 | After that, if the function is called in void context, it will simply | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1289 | return without doing anything further. This can be used to add more text | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1290 | in as many chunks as you want. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1291 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1292 | If the method is called in scalar context, then it will try to extract | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1293 | exactly I<one> JSON object. If that is successful, it will return this | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1294 | object, otherwise it will return C<undef>. If there is a parse error, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1295 | this method will croak just as C<decode> would do (one can then use | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1296 | C<incr_skip> to skip the erroneous part). This is the most common way of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1297 | using the method. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1298 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1299 | And finally, in list context, it will try to extract as many objects | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1300 | from the stream as it can find and return them, or the empty list | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1301 | otherwise. For this to work, there must be no separators between the JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1302 | objects or arrays, instead they must be concatenated back-to-back. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1303 | an error occurs, an exception will be raised as in the scalar context | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1304 | case. Note that in this case, any previously-parsed JSON texts will be | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1305 | lost. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1306 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1307 | Example: Parse some JSON arrays/objects in a given string and return | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1308 | them. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1309 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1310 | my @objs = Cpanel::JSON::XS->new->incr_parse ("[5][7][1,2]"); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1311 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1312 | =item $lvalue_string = $json->incr_text (>5.8 only) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1313 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1314 | This method returns the currently stored JSON fragment as an lvalue, that | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1315 | is, you can manipulate it. This I<only> works when a preceding call to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1316 | C<incr_parse> in I<scalar context> successfully returned an object, and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1317 | 2. only with Perl >= 5.8 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1318 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1319 | Under all other circumstances you must not call this function (I mean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1320 | it. although in simple tests it might actually work, it I<will> fail | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1321 | under real world conditions). As a special exception, you can also | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1322 | call this method before having parsed anything. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1323 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1324 | This function is useful in two cases: a) finding the trailing text after a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1325 | JSON object or b) parsing multiple JSON objects separated by non-JSON text | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1326 | (such as commas). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1327 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1328 | =item $json->incr_skip | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1329 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1330 | This will reset the state of the incremental parser and will remove | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1331 | the parsed text from the input buffer so far. This is useful after | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1332 | C<incr_parse> died, in which case the input buffer and incremental parser | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1333 | state is left unchanged, to skip the text parsed so far and to reset the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1334 | parse state. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1335 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1336 | The difference to C<incr_reset> is that only text until the parse error | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1337 | occurred is removed. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1338 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1339 | =item $json->incr_reset | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1340 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1341 | This completely resets the incremental parser, that is, after this call, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1342 | it will be as if the parser had never parsed anything. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1343 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1344 | This is useful if you want to repeatedly parse JSON objects and want to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1345 | ignore any trailing data, which means you have to reset the parser after | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1346 | each successful decode. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1347 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1348 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1349 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1350 | =head2 LIMITATIONS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1351 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1352 | All options that affect decoding are supported, except | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1353 | C<allow_nonref>. The reason for this is that it cannot be made to work | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1354 | sensibly: JSON objects and arrays are self-delimited, i.e. you can | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1355 | concatenate them back to back and still decode them perfectly. This | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1356 | does not hold true for JSON numbers, however. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1357 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1358 | For example, is the string C<1> a single JSON number, or is it simply | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1359 | the start of C<12>? Or is C<12> a single JSON number, or the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1360 | concatenation of C<1> and C<2>? In neither case you can tell, and this | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1361 | is why Cpanel::JSON::XS takes the conservative route and disallows | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1362 | this case. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1363 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1364 | Since C<allow_nonref> became the default (4.42), C<incr_parse> still | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1365 | rejects a top-level number, C<true>, C<false> or C<null> unless | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1366 | C<allow_nonref> was enabled explicitly, in which case the ambiguity above | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1367 | applies. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1368 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1369 | =head2 EXAMPLES | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1370 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1371 | Some examples will make all this clearer. First, a simple example that | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1372 | works similarly to C<decode_prefix>: We want to decode the JSON object at | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1373 | the start of a string and identify the portion after the JSON object: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1374 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1375 | my $text = "[1,2,3] hello"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1376 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1377 | my $json = new Cpanel::JSON::XS; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1378 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1379 | my $obj = $json->incr_parse ($text) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1380 | or die "expected JSON object or array at beginning of string"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1381 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1382 | my $tail = $json->incr_text; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1383 | # $tail now contains " hello" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1384 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1385 | Easy, isn't it? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1386 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1387 | Now for a more complicated example: Imagine a hypothetical protocol where | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1388 | you read some requests from a TCP stream, and each request is a JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1389 | array, without any separation between them (in fact, it is often useful to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1390 | use newlines as "separators", as these get interpreted as whitespace at | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1391 | the start of the JSON text, which makes it possible to test said protocol | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1392 | with C<telnet>...). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1393 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1394 | Here is how you'd do it (it is trivial to write this in an event-based | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1395 | manner): | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1396 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1397 | my $json = new Cpanel::JSON::XS; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1398 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1399 | # read some data from the socket | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1400 | while (sysread $socket, my $buf, 4096) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1401 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1402 | # split and decode as many requests as possible | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1403 | for my $request ($json->incr_parse ($buf)) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1404 | # act on the $request | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1405 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1406 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1407 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1408 | Another complicated example: Assume you have a string with JSON objects | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1409 | or arrays, all separated by (optional) comma characters (e.g. C<[1],[2], | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1410 | [3]>). To parse them, we have to skip the commas between the JSON texts, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1411 | and here is where the lvalue-ness of C<incr_text> comes in useful: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1412 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1413 | my $text = "[1],[2], [3]"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1414 | my $json = new Cpanel::JSON::XS; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1415 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1416 | # void context, so no parsing done | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1417 | $json->incr_parse ($text); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1418 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1419 | # now extract as many objects as possible. note the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1420 | # use of scalar context so incr_text can be called. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1421 | while (my $obj = $json->incr_parse) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1422 | # do something with $obj | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1423 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1424 | # now skip the optional comma | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1425 | $json->incr_text =~ s/^ \s* , //x; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1426 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1427 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1428 | Now lets go for a very complex example: Assume that you have a gigantic | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1429 | JSON array-of-objects, many gigabytes in size, and you want to parse it, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1430 | but you cannot load it into memory fully (this has actually happened in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1431 | the real world :). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1432 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1433 | Well, you lost, you have to implement your own JSON parser. But | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1434 | Cpanel::JSON::XS can still help you: You implement a (very simple) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1435 | array parser and let JSON decode the array elements, which are all | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1436 | full JSON objects on their own (this wouldn't work if the array | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1437 | elements could be JSON numbers, for example): | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1438 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1439 | my $json = new Cpanel::JSON::XS; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1440 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1441 | # open the monster | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1442 | open my $fh, "<bigfile.json" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1443 | or die "bigfile: $!"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1444 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1445 | # first parse the initial "[" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1446 | for (;;) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1447 | sysread $fh, my $buf, 65536 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1448 | or die "read error: $!"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1449 | $json->incr_parse ($buf); # void context, so no parsing | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1450 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1451 | # Exit the loop once we found and removed(!) the initial "[". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1452 | # In essence, we are (ab-)using the $json object as a simple scalar | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1453 | # we append data to. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1454 | last if $json->incr_text =~ s/^ \s* \[ //x; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1455 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1456 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1457 | # now we have the skipped the initial "[", so continue | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1458 | # parsing all the elements. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1459 | for (;;) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1460 | # in this loop we read data until we got a single JSON object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1461 | for (;;) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1462 | if (my $obj = $json->incr_parse) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1463 | # do something with $obj | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1464 | last; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1465 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1466 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1467 | # add more data | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1468 | sysread $fh, my $buf, 65536 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1469 | or die "read error: $!"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1470 | $json->incr_parse ($buf); # void context, so no parsing | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1471 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1472 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1473 | # in this loop we read data until we either found and parsed the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1474 | # separating "," between elements, or the final "]" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1475 | for (;;) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1476 | # first skip whitespace | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1477 | $json->incr_text =~ s/^\s*//; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1478 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1479 | # if we find "]", we are done | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1480 | if ($json->incr_text =~ s/^\]//) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1481 | print "finished.\n"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1482 | exit; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1483 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1484 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1485 | # if we find ",", we can continue with the next element | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1486 | if ($json->incr_text =~ s/^,//) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1487 | last; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1488 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1489 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1490 | # if we find anything else, we have a parse error! | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1491 | if (length $json->incr_text) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1492 | die "parse error near ", $json->incr_text; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1493 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1494 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1495 | # else add more data | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1496 | sysread $fh, my $buf, 65536 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1497 | or die "read error: $!"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1498 | $json->incr_parse ($buf); # void context, so no parsing | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1499 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1500 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1501 | This is a complex example, but most of the complexity comes from the fact | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1502 | that we are trying to be correct (bear with me if I am wrong, I never ran | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1503 | the above example :). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1504 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1505 | =head1 BOM | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1506 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1507 | Detect all unicode B<Byte Order Marks> on decode. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1508 | Which are UTF-8, UTF-16LE, UTF-16BE, UTF-32LE and UTF-32BE. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1509 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1510 | The BOM encoding is set only for one specific decode call, it does not | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1511 | change the state of the JSON object. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1512 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1513 | B<Warning>: With perls older than 5.20 you need load the Encode module | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1514 | before loading a multibyte BOM, i.e. >= UTF-16. Otherwise an error is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1515 | thrown. This is an implementation limitation and might get fixed later. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1516 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1517 | See L<https://tools.ietf.org/html/rfc7159#section-8.1> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1518 | I<"JSON text SHALL be encoded in UTF-8, UTF-16, or UTF-32."> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1519 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1520 | I<"Implementations MUST NOT add a byte order mark to the beginning of a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1521 | JSON text", "implementations (...) MAY ignore the presence of a byte | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1522 | order mark rather than treating it as an error".> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1523 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1524 | See also L<http://www.unicode.org/faq/utf_bom.html#BOM>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1525 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1526 | Beware that Cpanel::JSON::XS is currently the only JSON module which | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1527 | does accept and decode a BOM. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1528 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1529 | The latest JSON spec | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1530 | L<https://www.greenbytes.de/tech/webdav/rfc8259.html#character.encoding> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1531 | forbid the usage of UTF-16 or UTF-32, the character encoding is UTF-8. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1532 | Thus in subsequent updates BOM's of UTF-16 or UTF-32 will throw an error. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1533 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1534 | =head1 MAPPING | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1535 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1536 | This section describes how Cpanel::JSON::XS maps Perl values to JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1537 | values and vice versa. These mappings are designed to "do the right | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1538 | thing" in most circumstances automatically, preserving round-tripping | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1539 | characteristics (what you put in comes out as something equivalent). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1540 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1541 | For the more enlightened: note that in the following descriptions, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1542 | lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1543 | refers to the abstract Perl language itself. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1544 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1545 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1546 | =head2 JSON -> PERL | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1547 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1548 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1549 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1550 | =item object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1551 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1552 | A JSON object becomes a reference to a hash in Perl. No ordering of object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1553 | keys is preserved (JSON does not preserve object key ordering itself). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1554 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1555 | =item array | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1556 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1557 | A JSON array becomes a reference to an array in Perl. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1558 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1559 | =item string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1560 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1561 | A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1562 | are represented by the same codepoints in the Perl string, so no manual | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1563 | decoding is necessary. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1564 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1565 | =item number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1566 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1567 | A JSON number becomes either an integer, numeric (floating point) or | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1568 | string scalar in perl, depending on its range and any fractional parts. On | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1569 | the Perl level, there is no difference between those as Perl handles all | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1570 | the conversion details, but an integer may take slightly less memory and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1571 | might represent more values exactly than floating point numbers. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1572 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1573 | If the number consists of digits only, Cpanel::JSON::XS will try to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1574 | represent it as an integer value. If that fails, it will try to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1575 | represent it as a numeric (floating point) value if that is possible | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1576 | without loss of precision. Otherwise it will preserve the number as a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1577 | string value (in which case you lose roundtripping ability, as the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1578 | JSON number will be re-encoded to a JSON string). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1579 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1580 | Numbers containing a fractional or exponential part will always be | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1581 | represented as numeric (floating point) values, possibly at a loss of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1582 | precision (in which case you might lose perfect roundtripping ability, but | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1583 | the JSON number will still be re-encoded as a JSON number). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1584 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1585 | Note that precision is not accuracy - binary floating point values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1586 | cannot represent most decimal fractions exactly, and when converting | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1587 | from and to floating point, C<Cpanel::JSON::XS> only guarantees precision | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1588 | up to but not including the least significant bit. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1589 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1590 | =item true, false | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1591 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1592 | When C<unblessed_bool> is set to true, then JSON C<true> becomes C<1> and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1593 | JSON C<false> becomes C<0>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1594 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1595 | Otherwise these JSON atoms become C<JSON::PP::true> and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1596 | C<JSON::PP::false>, respectively. They are C<JSON::PP::Boolean> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1597 | objects and are overloaded to act almost exactly like the numbers C<1> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1598 | and C<0>. You can check whether a scalar is a JSON boolean by using | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1599 | the C<Cpanel::JSON::XS::is_bool> function. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1600 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1601 | The other round, from perl to JSON, C<!0> which is represented as | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1602 | C<yes> becomes C<true>, and C<!1> which is represented as | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1603 | C<no> becomes C<false>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1604 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1605 | Via L<Cpanel::JSON::XS::Type> you can now even force negation in C<encode>, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1606 | without overloading of C<!>: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1607 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1608 | my $false = Cpanel::JSON::XS::false; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1609 | print($json->encode([!$false], [JSON_TYPE_BOOL])); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1610 | => [true] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1611 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1612 | =item null | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1613 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1614 | A JSON null atom becomes C<undef> in Perl. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1615 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1616 | =item shell-style comments (C<< # I<text> >>) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1617 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1618 | As a nonstandard extension to the JSON syntax that is enabled by the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1619 | C<relaxed> setting, shell-style comments are allowed. They can start | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1620 | anywhere outside strings and go till the end of the line. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1621 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1622 | =item tagged values (C<< (I<tag>)I<value> >>). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1623 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1624 | Another nonstandard extension to the JSON syntax, enabled with the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1625 | C<allow_tags> setting, are tagged values. In this implementation, the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1626 | I<tag> must be a perl package/class name encoded as a JSON string, and the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1627 | I<value> must be a JSON array encoding optional constructor arguments. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1628 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1629 | See L<OBJECT SERIALIZATION>, below, for details. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1630 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1631 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1632 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1633 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1634 | =head2 PERL -> JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1635 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1636 | The mapping from Perl to JSON is slightly more difficult, as Perl is a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1637 | truly typeless language, so we can only guess which JSON type is meant by | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1638 | a Perl value. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1639 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1640 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1641 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1642 | =item hash references | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1643 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1644 | Perl hash references become JSON objects. As there is no inherent ordering | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1645 | in hash keys (or JSON objects), they will usually be encoded in a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1646 | pseudo-random order that can change between runs of the same program but | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1647 | stays generally the same within a single run of a program. Cpanel::JSON::XS can | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1648 | optionally sort the hash keys (determined by the I<canonical> flag), so | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1649 | the same datastructure will serialize to the same JSON text (given same | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1650 | settings and version of Cpanel::JSON::XS), but this incurs a runtime overhead | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1651 | and is only rarely useful, e.g. when you want to compare some JSON text | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1652 | against another for equality. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1653 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1654 | =item array references | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1655 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1656 | Perl array references become JSON arrays. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1657 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1658 | =item other references | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1659 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1660 | Other unblessed references are generally not allowed and will cause an | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1661 | exception to be thrown, except for references to the integers C<0> and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1662 | C<1>, which get turned into C<false> and C<true> atoms in JSON. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1663 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1664 | With the option C<allow_stringify>, you can ignore the exception and return | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1665 | the stringification of the perl value. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1666 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1667 | With the option C<allow_unknown>, you can ignore the exception and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1668 | return C<null> instead. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1669 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1670 | encode_json [\"x"] # => cannot encode reference to scalar 'SCALAR(0x..)' | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1671 | # unless the scalar is 0 or 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1672 | encode_json [\0, \1] # yields [false,true] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1673 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1674 | allow_stringify->encode_json [\"x"] # yields "x" unlike JSON::PP | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1675 | allow_unknown->encode_json [\"x"] # yields null as in JSON::PP | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1676 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1677 | =item Cpanel::JSON::XS::true, Cpanel::JSON::XS::false | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1678 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1679 | These special values become JSON true and JSON false values, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1680 | respectively. You can also use C<\1> and C<\0> or C<!0> and C<!1> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1681 | directly if you want. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1682 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1683 | encode_json [Cpanel::JSON::XS::false, Cpanel::JSON::XS::true] # yields [false,true] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1684 | encode_json [!1, !0], [JSON_TYPE_BOOL, JSON_TYPE_BOOL] # yields [false,true] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1685 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1686 | eq/ne comparisons with true, false: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1687 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1688 | false is eq to the empty string or the string 'false' or the special | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1689 | empty string C<!!0> or C<!1>, i.e. C<SV_NO>, or the numbers 0 or 0.0. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1690 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1691 | true is eq to the string 'true' or to the special string C<!0> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1692 | (i.e. C<SV_YES>) or to the numbers 1 or 1.0. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1693 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1694 | =item blessed objects | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1695 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1696 | Blessed objects are not directly representable in JSON, but | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1697 | C<Cpanel::JSON::XS> allows various optional ways of handling | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1698 | objects. See L<OBJECT SERIALIZATION>, below, for details. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1699 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1700 | See the C<allow_blessed> and C<convert_blessed> methods on various | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1701 | options on how to deal with this: basically, you can choose between | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1702 | throwing an exception, encoding the reference as if it weren't | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1703 | blessed, use the objects overloaded stringification method or provide | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1704 | your own serializer method. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1705 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1706 | =item simple scalars | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1707 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1708 | Simple Perl scalars (any scalar that is not a reference) are the most | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1709 | difficult objects to encode: Cpanel::JSON::XS will encode undefined | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1710 | scalars or inf/nan as JSON C<null> values and other scalars to either | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1711 | number or string in non-deterministic way which may be affected or | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1712 | changed by Perl version or any other loaded Perl module. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1713 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1714 | If you want to have stable and deterministic types in JSON encoder then | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1715 | use L<Cpanel::JSON::XS::Type>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1716 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1717 | Alternative way for deterministic types is to use C<type_all_string> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1718 | method when all perl scalars are encoded to JSON strings. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1719 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1720 | Non-deterministic behavior is following: scalars that have last been | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1721 | used in a string context before encoding as JSON strings, and anything | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1722 | else as number value: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1723 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1724 | # dump as number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1725 | encode_json [2] # yields [2] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1726 | encode_json [-3.0e17] # yields [-3e+17] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1727 | my $value = 5; encode_json [$value] # yields [5] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1728 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1729 | # used as string, but the two representations are for the same number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1730 | print $value; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1731 | encode_json [$value] # yields [5] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1732 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1733 | # used as different string (non-matching dual-var) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1734 | my $str = '0 but true'; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1735 | my $num = 1 + $str; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1736 | encode_json [$num, $str] # yields [1,"0 but true"] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1737 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1738 | # undef becomes null | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1739 | encode_json [undef] # yields [null] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1740 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1741 | # inf or nan becomes null, unless you answered | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1742 | # "Do you want to handle inf/nan as strings" with yes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1743 | encode_json [9**9**9] # yields [null] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1744 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1745 | You can force the type to be a JSON string by stringifying it: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1746 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1747 | my $x = 3.1; # some variable containing a number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1748 | "$x"; # stringified | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1749 | $x .= ""; # another, more awkward way to stringify | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1750 | print $x; # perl does it for you, too, quite often | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1751 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1752 | You can force the type to be a JSON number by numifying it: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1753 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1754 | my $x = "3"; # some variable containing a string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1755 | $x += 0; # numify it, ensuring it will be dumped as a number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1756 | $x *= 1; # same thing, the choice is yours. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1757 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1758 | Note that numerical precision has the same meaning as under Perl (so | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1759 | binary to decimal conversion follows the same rules as in Perl, which | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1760 | can differ to other languages). Also, your perl interpreter might expose | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1761 | extensions to the floating point numbers of your platform, such as | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1762 | infinities or NaN's - these cannot be represented in JSON, and thus | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1763 | null is returned instead. Optionally you can configure it to stringify | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1764 | inf and nan values. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1765 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1766 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1767 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1768 | =head2 OBJECT SERIALIZATION | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1769 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1770 | As JSON cannot directly represent Perl objects, you have to choose between | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1771 | a pure JSON representation (without the ability to deserialize the object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1772 | automatically again), and a nonstandard extension to the JSON syntax, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1773 | tagged values. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1774 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1775 | =head3 SERIALIZATION | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1776 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1777 | What happens when C<Cpanel::JSON::XS> encounters a Perl object depends | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1778 | on the C<allow_blessed>, C<convert_blessed> and C<allow_tags> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1779 | settings, which are used in this order: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1780 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1781 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1782 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1783 | =item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1784 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1785 | In this case, C<Cpanel::JSON::XS> uses the L<Types::Serialiser> object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1786 | serialization protocol to create a tagged JSON value, using a nonstandard | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1787 | extension to the JSON syntax. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1788 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1789 | This works by invoking the C<FREEZE> method on the object, with the first | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1790 | argument being the object to serialize, and the second argument being the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1791 | constant string C<JSON> to distinguish it from other serializers. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1792 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1793 | The C<FREEZE> method can return any number of values (i.e. zero or | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1794 | more). These values and the paclkage/classname of the object will then be | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1795 | encoded as a tagged JSON value in the following format: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1796 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1797 | ("classname")[FREEZE return values...] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1798 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1799 | e.g.: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1800 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1801 | ("URI")["http://www.google.com/"] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1802 | ("MyDate")[2013,10,29] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1803 | ("ImageData::JPEG")["Z3...VlCg=="] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1804 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1805 | For example, the hypothetical C<My::Object> C<FREEZE> method might use the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1806 | objects C<type> and C<id> members to encode the object: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1807 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1808 | sub My::Object::FREEZE { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1809 | my ($self, $serializer) = @_; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1810 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1811 | ($self->{type}, $self->{id}) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1812 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1813 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1814 | =item 2. C<convert_blessed> is enabled and the object has a C<TO_JSON> method. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1815 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1816 | In this case, the C<TO_JSON> method of the object is invoked in scalar | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1817 | context. It must return a single scalar that can be directly encoded into | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1818 | JSON. This scalar replaces the object in the JSON text. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1819 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1820 | For example, the following C<TO_JSON> method will convert all L<URI> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1821 | objects to JSON strings when serialized. The fact that these values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1822 | originally were L<URI> objects is lost. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1823 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1824 | sub URI::TO_JSON { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1825 | my ($uri) = @_; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1826 | $uri->as_string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1827 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1828 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1829 | =item 3. C<convert_blessed> is enabled and the object has a stringification overload. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1830 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1831 | In this case, the overloaded C<""> method of the object is invoked in scalar | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1832 | context. It must return a single scalar that can be directly encoded into | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1833 | JSON. This scalar replaces the object in the JSON text. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1834 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1835 | For example, the following C<""> method will convert all L<URI> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1836 | objects to JSON strings when serialized. The fact that these values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1837 | originally were L<URI> objects is lost. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1838 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1839 | package URI; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1840 | use overload '""' => sub { shift->as_string }; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1841 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1842 | =item 4. C<allow_blessed> is enabled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1843 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1844 | The object will be serialized as a JSON null value. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1845 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1846 | =item 5. none of the above | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1847 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1848 | If none of the settings are enabled or the respective methods are missing, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1849 | C<Cpanel::JSON::XS> throws an exception. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1850 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1851 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1852 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1853 | =head3 DESERIALIZATION | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1854 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1855 | For deserialization there are only two cases to consider: either | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1856 | nonstandard tagging was used, in which case C<allow_tags> decides, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1857 | or objects cannot be automatically be deserialized, in which | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1858 | case you can use postprocessing or the C<filter_json_object> or | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1859 | C<filter_json_single_key_object> callbacks to get some real objects our of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1860 | your JSON. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1861 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1862 | This section only considers the tagged value case: I a tagged JSON object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1863 | is encountered during decoding and C<allow_tags> is disabled, a parse | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1864 | error will result (as if tagged values were not part of the grammar). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1865 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1866 | If C<allow_tags> is enabled, C<Cpanel::JSON::XS> will look up the C<THAW> method | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1867 | of the package/classname used during serialization (it will not attempt | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1868 | to load the package as a Perl module). If there is no such method, the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1869 | decoding will fail with an error. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1870 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1871 | Otherwise, the C<THAW> method is invoked with the classname as first | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1872 | argument, the constant string C<JSON> as second argument, and all the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1873 | values from the JSON array (the values originally returned by the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1874 | C<FREEZE> method) as remaining arguments. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1875 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1876 | The method must then return the object. While technically you can return | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1877 | any Perl scalar, you might have to enable the C<enable_nonref> setting to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1878 | make that work in all cases, so better return an actual blessed reference. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1879 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1880 | As an example, let's implement a C<THAW> function that regenerates the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1881 | C<My::Object> from the C<FREEZE> example earlier: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1882 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1883 | sub My::Object::THAW { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1884 | my ($class, $serializer, $type, $id) = @_; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1885 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1886 | $class->new (type => $type, id => $id) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1887 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1888 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1889 | See the L</SECURITY CONSIDERATIONS> section below. Allowing external | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1890 | json objects being deserialized to perl objects is usually a very bad | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1891 | idea. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1892 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1893 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1894 | =head1 ENCODING/CODESET FLAG NOTES | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1895 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1896 | The interested reader might have seen a number of flags that signify | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1897 | encodings or codesets - C<utf8>, C<latin1>, C<binary> and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1898 | C<ascii>. There seems to be some confusion on what these do, so here | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1899 | is a short comparison: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1900 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1901 | C<utf8> controls whether the JSON text created by C<encode> (and expected | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1902 | by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1903 | control whether C<encode> escapes character values outside their respective | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1904 | codeset range. Neither of these flags conflict with each other, although | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1905 | some combinations make less sense than others. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1906 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1907 | Care has been taken to make all flags symmetrical with respect to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1908 | C<encode> and C<decode>, that is, texts encoded with any combination of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1909 | these flag values will be correctly decoded when the same flags are used | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1910 | - in general, if you use different flag settings while encoding vs. when | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1911 | decoding you likely have a bug somewhere. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1912 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1913 | Below comes a verbose discussion of these flags. Note that a "codeset" is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1914 | simply an abstract set of character-codepoint pairs, while an encoding | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1915 | takes those codepoint numbers and I<encodes> them, in our case into | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1916 | octets. Unicode is (among other things) a codeset, UTF-8 is an encoding, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1917 | and ISO-8859-1 (= latin 1) and ASCII are both codesets I<and> encodings at | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1918 | the same time, which can be confusing. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1919 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1920 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1921 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1922 | =item C<utf8> flag disabled | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1923 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1924 | When C<utf8> is disabled (the default), then C<encode>/C<decode> generate | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1925 | and expect Unicode strings, that is, characters with high ordinal Unicode | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1926 | values (> 255) will be encoded as such characters, and likewise such | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1927 | characters are decoded as-is, no changes to them will be done, except | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1928 | "(re-)interpreting" them as Unicode codepoints or Unicode characters, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1929 | respectively (to Perl, these are the same thing in strings unless you do | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1930 | funny/weird/dumb stuff). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1931 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1932 | This is useful when you want to do the encoding yourself (e.g. when you | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1933 | want to have UTF-16 encoded JSON texts) or when some other layer does | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1934 | the encoding for you (for example, when printing to a terminal using a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1935 | filehandle that transparently encodes to UTF-8 you certainly do NOT want | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1936 | to UTF-8 encode your data first and have Perl encode it another time). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1937 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1938 | =item C<utf8> flag enabled | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1939 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1940 | If the C<utf8>-flag is enabled, C<encode>/C<decode> will encode all | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1941 | characters using the corresponding UTF-8 multi-byte sequence, and will | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1942 | expect your input strings to be encoded as UTF-8, that is, no "character" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1943 | of the input string must have any value > 255, as UTF-8 does not allow | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1944 | that. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1945 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1946 | The C<utf8> flag therefore switches between two modes: disabled means you | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1947 | will get a Unicode string in Perl, enabled means you get an UTF-8 encoded | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1948 | octet/binary string in Perl. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1949 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1950 | =item C<latin1>, C<binary> or C<ascii> flags enabled | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1951 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1952 | With C<latin1> (or C<ascii>) enabled, C<encode> will escape | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1953 | characters with ordinal values > 255 (> 127 with C<ascii>) and encode | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1954 | the remaining characters as specified by the C<utf8> flag. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1955 | With C<binary> enabled, ordinal values > 255 are illegal. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1956 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1957 | If C<utf8> is disabled, then the result is also correctly encoded in those | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1958 | character sets (as both are proper subsets of Unicode, meaning that a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1959 | Unicode string with all character values < 256 is the same thing as a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1960 | ISO-8859-1 string, and a Unicode string with all character values < 128 is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1961 | the same thing as an ASCII string in Perl). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1962 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1963 | If C<utf8> is enabled, you still get a correct UTF-8-encoded string, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1964 | regardless of these flags, just some more characters will be escaped using | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1965 | C<\uXXXX> then before. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1966 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1967 | Note that ISO-8859-1-I<encoded> strings are not compatible with UTF-8 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1968 | encoding, while ASCII-encoded strings are. That is because the ISO-8859-1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1969 | encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I<codeset> being | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1970 | a subset of Unicode), while ASCII is. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1971 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1972 | Surprisingly, C<decode> will ignore these flags and so treat all input | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1973 | values as governed by the C<utf8> flag. If it is disabled, this allows you | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1974 | to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1975 | Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1976 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1977 | So neither C<latin1>, C<binary> nor C<ascii> are incompatible with the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1978 | C<utf8> flag - they only govern when the JSON output engine escapes a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1979 | character or not. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1980 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1981 | The main use for C<latin1> or C<binary> is to relatively efficiently | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1982 | store binary data as JSON, at the expense of breaking compatibility | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1983 | with most JSON decoders. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1984 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1985 | The main use for C<ascii> is to force the output to not contain characters | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1986 | with values > 127, which means you can interpret the resulting string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1987 | as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1988 | 8-bit-encoding, and still get the same data structure back. This is useful | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1989 | when your channel for JSON transfer is not 8-bit clean or the encoding | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1990 | might be mangled in between (e.g. in mail), and works because ASCII is a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1991 | proper subset of most 8-bit and multibyte encodings in use in the world. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1992 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1993 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1994 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1995 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1996 | =head2 JSON and ECMAscript | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1997 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1998 | JSON syntax is based on how literals are represented in javascript (the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 1999 | not-standardized predecessor of ECMAscript) which is presumably why it is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2000 | called "JavaScript Object Notation". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2001 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2002 | However, JSON is not a subset (and also not a superset of course) of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2003 | ECMAscript (the standard) or javascript (whatever browsers actually | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2004 | implement). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2005 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2006 | If you want to use javascript's C<eval> function to "parse" JSON, you | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2007 | might run into parse errors for valid JSON texts, or the resulting data | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2008 | structure might not be queryable: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2009 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2010 | One of the problems is that U+2028 and U+2029 are valid characters inside | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2011 | JSON strings, but are not allowed in ECMAscript string literals, so the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2012 | following Perl fragment will not output something that can be guaranteed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2013 | to be parsable by javascript's C<eval>: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2014 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2015 | use Cpanel::JSON::XS; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2016 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2017 | print encode_json [chr 0x2028]; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2018 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2019 | The right fix for this is to use a proper JSON parser in your javascript | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2020 | programs, and not rely on C<eval> (see for example Douglas Crockford's | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2021 | F<json2.js> parser). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2022 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2023 | If this is not an option, you can, as a stop-gap measure, simply encode to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2024 | ASCII-only JSON: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2025 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2026 | use Cpanel::JSON::XS; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2027 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2028 | print Cpanel::JSON::XS->new->ascii->encode ([chr 0x2028]); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2029 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2030 | Note that this will enlarge the resulting JSON text quite a bit if you | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2031 | have many non-ASCII characters. You might be tempted to run some regexes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2032 | to only escape U+2028 and U+2029, e.g.: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2033 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2034 | # DO NOT USE THIS! | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2035 | my $json = Cpanel::JSON::XS->new->utf8->encode ([chr 0x2028]); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2036 | $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2037 | $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2038 | print $json; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2039 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2040 | Note that I<this is a bad idea>: the above only works for U+2028 and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2041 | U+2029 and thus only for fully ECMAscript-compliant parsers. Many existing | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2042 | javascript implementations, however, have issues with other characters as | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2043 | well - using C<eval> naively simply I<will> cause problems. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2044 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2045 | Another problem is that some javascript implementations reserve | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2046 | some property names for their own purposes (which probably makes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2047 | them non-ECMAscript-compliant). For example, Iceweasel reserves the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2048 | C<__proto__> property name for its own purposes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2049 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2050 | If that is a problem, you could parse try to filter the resulting JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2051 | output for these property strings, e.g.: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2052 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2053 | $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2054 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2055 | This works because C<__proto__> is not valid outside of strings, so every | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2056 | occurrence of C<"__proto__"\s*:> must be a string used as property name. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2057 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2058 | Raw non-Unicode characters outside the valid unicode range fail now to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2059 | parse, because "A string is a sequence of zero or more Unicode | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2060 | characters" RFC 7159 section 1 and "JSON text SHALL be encoded in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2061 | Unicode RFC 7159 section 8.1. We use now the UTF8_DISALLOW_SUPER | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2062 | flag when parsing unicode. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2063 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2064 | Since RFC 3629, U+D800 through U+DFFF are not legal Unicode values and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2065 | their UTF-8 encodings must be treated as an invalid byte sequence. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2066 | RFC 8259 section 8.2 admits the spec allows string values that contain | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2067 | bit sequences that cannot encode Unicode characters and that the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2068 | behavior of software that receives such values is unpredictable. To | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2069 | avoid introducing non-Unicode strings into Perl we use the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2070 | UTF8_DISALLOW_SURROGATE flag when parsing Unicode and verify escaped | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2071 | surrogates form valid pairs. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2072 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2073 | If you know of other incompatibilities, please let me know. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2074 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2075 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2076 | =head2 JSON and YAML | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2077 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2078 | You often hear that JSON is a subset of YAML. I<in general, there is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2079 | no way to configure JSON::XS to output a data structure as valid YAML> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2080 | that works in all cases. If you really must use Cpanel::JSON::XS to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2081 | generate YAML, you should use this algorithm (subject to change in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2082 | future versions): | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2083 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2084 | my $to_yaml = Cpanel::JSON::XS->new->utf8->space_after (1); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2085 | my $yaml = $to_yaml->encode ($ref) . "\n"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2086 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2087 | This will I<usually> generate JSON texts that also parse as valid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2088 | YAML. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2089 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2090 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2091 | =head2 SPEED | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2092 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2093 | It seems that JSON::XS is surprisingly fast, as shown in the following | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2094 | tables. They have been generated with the help of the C<eg/bench> program | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2095 | in the JSON::XS distribution, to make it easy to compare on your own | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2096 | system. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2097 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2098 | JSON::XS is with L<Data::MessagePack> and L<Sereal> one of the fastest | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2099 | serializers, because JSON and JSON::XS do not support backrefs (no | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2100 | graph structures), only trees. Storable supports backrefs, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2101 | i.e. graphs. Data::MessagePack encodes its data binary (as Storable) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2102 | and supports only very simple subset of JSON. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2103 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2104 | First comes a comparison between various modules using | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2105 | a very short single-line JSON string (also available at | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2106 | L<http://dist.schmorp.de/misc/json/short.json>). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2107 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2108 | {"method": "handleMessage", "params": ["user1", | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2109 | "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2110 | 1, 0]} | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2111 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2112 | It shows the number of encodes/decodes per second (JSON::XS uses | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2113 | the functional interface, while Cpanel::JSON::XS/2 uses the OO interface | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2114 | with pretty-printing and hash key sorting enabled, Cpanel::JSON::XS/3 enables | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2115 | shrink. JSON::DWIW/DS uses the deserialize function, while JSON::DWIW::FJ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2116 | uses the from_json method). Higher is better: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2117 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2118 | module | encode | decode | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2119 | --------------|------------|------------| | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2120 | JSON::DWIW/DS | 86302.551 | 102300.098 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2121 | JSON::DWIW/FJ | 86302.551 | 75983.768 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2122 | JSON::PP | 15827.562 | 6638.658 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2123 | JSON::Syck | 63358.066 | 47662.545 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2124 | JSON::XS | 511500.488 | 511500.488 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2125 | JSON::XS/2 | 291271.111 | 388361.481 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2126 | JSON::XS/3 | 361577.931 | 361577.931 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2127 | Storable | 66788.280 | 265462.278 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2128 | --------------+------------+------------+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2129 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2130 | That is, JSON::XS is almost six times faster than JSON::DWIW on encoding, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2131 | about five times faster on decoding, and over thirty to seventy times | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2132 | faster than JSON's pure perl implementation. It also compares favourably | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2133 | to Storable for small amounts of data. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2134 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2135 | Using a longer test string (roughly 18KB, generated from Yahoo! Locals | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2136 | search API (L<http://dist.schmorp.de/misc/json/long.json>). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2137 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2138 | module | encode | decode | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2139 | --------------|------------|------------| | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2140 | JSON::DWIW/DS | 1647.927 | 2673.916 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2141 | JSON::DWIW/FJ | 1630.249 | 2596.128 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2142 | JSON::PP | 400.640 | 62.311 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2143 | JSON::Syck | 1481.040 | 1524.869 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2144 | JSON::XS | 20661.596 | 9541.183 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2145 | JSON::XS/2 | 10683.403 | 9416.938 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2146 | JSON::XS/3 | 20661.596 | 9400.054 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2147 | Storable | 19765.806 | 10000.725 | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2148 | --------------+------------+------------+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2149 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2150 | Again, JSON::XS leads by far (except for Storable which non-surprisingly | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2151 | decodes a bit faster). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2152 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2153 | On large strings containing lots of high Unicode characters, some modules | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2154 | (such as JSON::PC) seem to decode faster than JSON::XS, but the result | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2155 | will be broken due to missing (or wrong) Unicode handling. Others refuse | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2156 | to decode or encode properly, so it was impossible to prepare a fair | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2157 | comparison table for that case. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2158 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2159 | For updated graphs see L<https://github.com/Sereal/Sereal/wiki/Sereal-Comparison-Graphs> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2160 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2161 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2162 | =head1 INTEROP with JSON and JSON::XS and other JSON modules | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2163 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2164 | As long as you only serialize data that can be directly expressed in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2165 | JSON, C<Cpanel::JSON::XS> is incapable of generating invalid JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2166 | output (modulo bugs, but C<JSON::XS> has found more bugs in the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2167 | official JSON testsuite (1) than the official JSON testsuite has found | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2168 | in C<JSON::XS> (0)). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2169 | C<Cpanel::JSON::XS> is currently the only known JSON decoder which passes all | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2170 | L<http://seriot.ch/projects/parsing_json.html> tests, while being the fastest also. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2171 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2172 | When you have trouble decoding JSON generated by this module using other | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2173 | decoders, then it is very likely that you have an encoding mismatch or the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2174 | other decoder is broken. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2175 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2176 | When decoding, C<JSON::XS> is strict by default and will likely catch | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2177 | all errors. There are currently two settings that change this: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2178 | C<relaxed> makes C<JSON::XS> accept (but not generate) some | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2179 | non-standard extensions, and C<allow_tags> or C<allow_blessed> will | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2180 | allow you to encode and decode Perl objects, at the cost of being | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2181 | totally insecure and not outputting valid JSON anymore. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2182 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2183 | JSON-XS-3.01 broke interoperability with JSON-2.90 with booleans. See L<JSON>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2184 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2185 | Cpanel::JSON::XS needs to know the JSON and JSON::XS versions to be able work | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2186 | with those objects, especially when encoding a booleans like C<{"is_true":true}>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2187 | So you need to load these modules before. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2188 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2189 | true/false overloading and boolean representations are supported. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2190 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2191 | JSON::XS and JSON::PP representations are accepted and older JSON::XS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2192 | accepts Cpanel::JSON::XS booleans. All JSON modules JSON, JSON, PP, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2193 | JSON::XS, Cpanel::JSON::XS produce JSON::PP::Boolean objects, just | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2194 | Mojo and JSON::YAJL not. Mojo produces Mojo::JSON::_Bool and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2195 | JSON::YAJL::Parser just an unblessed IV. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2196 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2197 | Cpanel::JSON::XS accepts JSON::PP::Boolean and Mojo::JSON::_Bool | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2198 | objects as booleans. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2199 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2200 | I cannot think of any reason to still use JSON::XS anymore. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2201 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2202 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2203 | =head2 TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2204 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2205 | When you use C<allow_tags> to use the extended (and also nonstandard | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2206 | and invalid) JSON syntax for serialized objects, and you still want to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2207 | decode the generated serialize objects, you can run a regex to replace | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2208 | the tagged syntax by standard JSON arrays (it only works for "normal" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2209 | package names without comma, newlines or single colons). First, the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2210 | readable Perl version: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2211 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2212 | # if your FREEZE methods return no values, you need this replace first: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2213 | $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2214 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2215 | # this works for non-empty constructor arg lists: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2216 | $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[/[$1,/gx; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2217 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2218 | And here is a less readable version that is easy to adapt to other | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2219 | languages: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2220 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2221 | $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/[$1,/g; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2222 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2223 | Here is an ECMAScript version (same regex): | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2224 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2225 | json = json.replace (/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/g, "[$1,"); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2226 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2227 | Since this syntax converts to standard JSON arrays, it might be hard to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2228 | distinguish serialized objects from normal arrays. You can prepend a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2229 | "magic number" as first array element to reduce chances of a collision: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2230 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2231 | $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2232 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2233 | And after decoding the JSON text, you could walk the data | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2234 | structure looking for arrays with a first element of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2235 | C<XU1peReLzT4ggEllLanBYq4G9VzliwKF>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2236 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2237 | The same approach can be used to create the tagged format with another | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2238 | encoder. First, you create an array with the magic string as first member, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2239 | the classname as second, and constructor arguments last, encode it as part | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2240 | of your JSON structure, and then: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2241 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2242 | $json =~ s/\[\s*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s*,\s*("([^\\":,]+|\\.|::)*")\s*,/($1)[/g; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2243 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2244 | Again, this has some limitations - the magic string must not be encoded | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2245 | with character escapes, and the constructor arguments must be non-empty. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2246 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2247 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2248 | =head1 RFC7159 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2249 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2250 | Since this module was written, Google has written a new JSON RFC, RFC 7159 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2251 | (and RFC7158). Unfortunately, this RFC breaks compatibility with both the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2252 | original JSON specification on www.json.org and RFC4627. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2253 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2254 | As far as I can see, you can get partial compatibility when parsing by | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2255 | using C<< ->allow_nonref >>. However, consider the security implications | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2256 | of doing so. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2257 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2258 | I haven't decided yet when to break compatibility with RFC4627 by default | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2259 | (and potentially leave applications insecure) and change the default to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2260 | follow RFC7159, but application authors are well advised to call C<< | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2261 | ->allow_nonref(0) >> even if this is the current default, if they cannot | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2262 | handle non-reference values, in preparation for the day when the default | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2263 | will change. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2264 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2265 | =head1 SECURITY CONSIDERATIONS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2266 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2267 | JSON::XS and Cpanel::JSON::XS are not only fast. JSON is generally the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2268 | most secure serializing format, because it is the only one besides | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2269 | Data::MessagePack, which does not deserialize objects per default. For | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2270 | all languages, not just perl. The binary variant BSON (MongoDB) does | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2271 | more but is unsafe. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2272 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2273 | It is trivial for any attacker to create such serialized objects in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2274 | JSON and trick perl into expanding them, thereby triggering certain | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2275 | methods. Watch L<https://www.youtube.com/watch?v=Gzx6KlqiIZE> for an | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2276 | exploit demo for "CVE-2015-1592 SixApart MovableType Storable Perl | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2277 | Code Execution" for a deserializer which expands objects. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2278 | Deserializing even coderefs (methods, functions) or external | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2279 | data would be considered the most dangerous. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2280 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2281 | Security relevant overview of serializers regarding deserializing | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2282 | objects by default: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2283 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2284 | Objects Coderefs External Data | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2285 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2286 | Data::Dumper YES YES YES | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2287 | Storable YES NO (def) NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2288 | Sereal YES NO NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2289 | YAML YES NO NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2290 | B::C YES YES YES | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2291 | B::Bytecode YES YES YES | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2292 | BSON YES YES NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2293 | JSON::SL YES NO YES | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2294 | JSON NO (def) NO NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2295 | Data::MessagePack NO NO NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2296 | XML NO NO YES | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2297 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2298 | Pickle YES YES YES | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2299 | PHP Deserialize YES NO NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2300 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2301 | When you are using JSON in a protocol, talking to untrusted potentially | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2302 | hostile creatures requires relatively few measures. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2303 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2304 | First of all, your JSON decoder should be secure, that is, should not have | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2305 | any buffer overflows. Obviously, this module should ensure that. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2306 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2307 | Second, you need to avoid resource-starving attacks. That means you should | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2308 | limit the size of JSON texts you accept, or make sure then when your | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2309 | resources run out, that's just fine (e.g. by using a separate process that | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2310 | can crash safely). The size of a JSON text in octets or characters is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2311 | usually a good indication of the size of the resources required to decode | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2312 | it into a Perl structure. While JSON::XS can check the size of the JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2313 | text, it might be too late when you already have it in memory, so you | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2314 | might want to check the size before you accept the string. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2315 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2316 | Third, Cpanel::JSON::XS recurses using the C stack when decoding objects and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2317 | arrays. The C stack is a limited resource: for instance, on my amd64 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2318 | machine with 8MB of stack size I can decode around 180k nested arrays but | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2319 | only 14k nested JSON objects (due to perl itself recursing deeply on croak | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2320 | to free the temporary). If that is exceeded, the program crashes. To be | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2321 | conservative, the default nesting limit is set to 512. If your process | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2322 | has a smaller stack, you should adjust this setting accordingly with the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2323 | C<max_depth> method. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2324 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2325 | Also keep in mind that Cpanel::JSON::XS might leak contents of your Perl data | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2326 | structures in its error messages, so when you serialize sensitive | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2327 | information you might want to make sure that exceptions thrown by JSON::XS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2328 | will not end up in front of untrusted eyes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2329 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2330 | If you are using Cpanel::JSON::XS to return packets to consumption | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2331 | by JavaScript scripts in a browser you should have a look at | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2332 | L<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/> to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2333 | see whether you are vulnerable to some common attack vectors (which really | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2334 | are browser design bugs, but it is still you who will have to deal with | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2335 | it, as major browser developers care only for features, not about getting | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2336 | security right). You might also want to also look at L<Mojo::JSON> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2337 | special escape rules to prevent from XSS attacks. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2338 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2339 | =head1 "OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2340 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2341 | B<Note: Since version 4.42, Cpanel::JSON::XS defaults to the broken RFC | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2342 | 7159 behavior> (like JSON::XS 4.0+), accepting scalar top-level JSON values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2343 | without requiring C<allow_nonref>. This was done for compatibility with the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2344 | larger Perl JSON ecosystem, despite the security concerns outlined below. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2345 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2346 | If you rely on the old strict behavior, explicitly disable it: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2347 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2348 | my $json = Cpanel::JSON::XS->new->allow_nonref(0); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2349 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2350 | The rationale for the original (pre-4.42) default, and the reason you might | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2351 | want to keep it off, follows: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2352 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2353 | TL;DR: The original JSON RFC 4627 required JSON texts to be arrays or | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2354 | objects. The IETF later standardized a broken revision (RFC 7159) that | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2355 | allows bare scalars at top-level, opening a class of protocol confusion | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2356 | attacks. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2357 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2358 | The long version: JSON being an important and supposedly stable format, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2359 | the IETF standardized it as RFC 4627 in 2006. Unfortunately the inventor | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2360 | of JSON Douglas Crockford unilaterally changed the definition of JSON in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2361 | javascript. Rather than create a fork, the IETF decided to standardize the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2362 | new syntax (apparently, so I was told, without finding it very amusing). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2363 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2364 | The biggest difference between the original JSON and the new JSON is that | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2365 | the new JSON supports scalars (anything other than arrays and objects) at | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2366 | the top-level of a JSON text. While this is strictly backwards compatible | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2367 | the top-level of a JSON text. While this is supposedly backwards compatible | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2368 | to older versions, it breaks a number of protocols that relied on sending | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2369 | JSON back-to-back, and is a security concern. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2370 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2371 | For example, imagine you have two banks communicating, and on one side, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2372 | the JSON coder gets upgraded. Two messages, such as C<10> and C<1000> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2373 | might then be confused to mean C<101000>, something that could not happen | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2374 | in the original JSON, because neither of these messages would be valid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2375 | JSON. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2376 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2377 | If one side accepts these messages, then an upgrade in the coder on either | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2378 | side could result in this becoming exploitable. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2379 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2380 | The IETF's own I-JSON profile (RFC 7493, also edited by Tim Bray who | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2381 | authored RFC 7159) acknowledges this mistake: Section 4.1 states that | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2382 | "there are software implementations, coded to the older specification | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2383 | [RFC4627], which only accept JSON objects or JSON arrays at the top | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2384 | level of JSON texts. For maximum interoperability with such | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2385 | implementations, protocol designers SHOULD NOT use top-level JSON | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2386 | texts that are neither objects nor arrays." | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2387 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2388 | =head1 THREADS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2389 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2390 | Cpanel::JSON::XS has proper ithreads support, unlike JSON::XS. If you | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2391 | encounter any bugs with thread support please report them. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2392 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2393 | From Version 4.00 - 4.19 you couldn't encode true with threads::shared | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2394 | magic. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2395 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2396 | =head1 BUGS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2397 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2398 | While the goal of the Cpanel::JSON::XS module is to be correct, that | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2399 | unfortunately does not mean it's bug-free, only that the author thinks | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2400 | its design is bug-free. If you keep reporting bugs and tests they will | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2401 | be fixed swiftly, though. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2402 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2403 | Since the JSON::XS author refuses to use a public bugtracker and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2404 | prefers private emails, we use the tracker at B<github>, so you might want | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2405 | to report any issues twice. Once in private to MLEHMANN to be fixed in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2406 | JSON::XS and one to our the public tracker. Issues fixed by JSON::XS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2407 | with a new release will also be backported to Cpanel::JSON::XS and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2408 | 5.6.2, as long as cPanel relies on 5.6.2 and Cpanel::JSON::XS as our | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2409 | serializer of choice. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2410 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2411 | L<https://github.com/rurban/Cpanel-JSON-XS/issues> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2412 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2413 | =head1 LICENSE | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2414 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2415 | This module is available under the same licences as perl, the Artistic | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2416 | license and the GPL. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2417 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2418 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2419 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2420 | 0 | ▶ | sub allow_bigint { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
allow_bigint: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2421 | 0 | Carp::carp("allow_bigint() is obsoleted. use allow_bignum() instead."); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2422 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2423 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2424 | 3 | ▶ | sub decode_and_validate { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
decode_and_validate: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2425 | 3 | my ($self, $json_text, $schema) = @_; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2426 | 3 | require Cpanel::JSON::XS::Type; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2427 | 3 | my $data = $self->decode($json_text, my $found_type); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2428 | 3 | my @errors = Cpanel::JSON::XS::Type::check_type($data, $schema, $found_type); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2429 | 3 | ▶ | if (@errors) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2430 | 2 | require Carp; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2431 | 2 | Carp::croak("JSON does not match schema:\n " . join("\n ", @errors)); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2432 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2433 | 1 | return $data; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2434 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2435 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2436 | 69 | ▶ | BEGIN { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=3 SCAR=11.2
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2437 | package | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2438 | JSON::PP::Boolean; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2439 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2440 | 69 | require overload; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2441 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2442 | 69 | local $^W; # silence redefine warnings. no warnings 'redefine' does not help | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2443 | # These already come with JSON::PP::Boolean. Avoid redefine warning. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2444 | 69 | ▶ | if (!defined $JSON::PP::Boolean::VERSION or $JSON::PP::VERSION lt '4.00') { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
not defined $VERSION or $JSON::PP::VERSION lt "4.00"
MC/DC0%0/2
not defined $VERSION or $JSON::PP::VERSION lt "4.00"
not defined $VERSION
$JSON::PP::VERSION lt "4.00"
Truth table33%1/3
not(A) or B
A= not defined $VERSIONB= $JSON::PP::VERSION lt "4.00"
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2445 | 69 | &overload::unimport( 'overload', '0+', '++', '--' ); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2446 | &overload::import( 'overload', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2447 | 6 | ▶ | "0+" => sub { ${$_[0]} }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2448 | 0 | ▶ | "++" => sub { $_[0] = ${$_[0]} + 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2449 | 0 | ▶ | "--" => sub { $_[0] = ${$_[0]} - 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2450 | 69 | ); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2451 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2452 | # workaround 5.6 reserved keyword warning | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2453 | 69 | &overload::unimport( 'overload', '""', 'eq', 'ne' ); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2454 | &overload::import( 'overload', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2455 | 35 | ▶ | '""' => sub { ${$_[0]} == 1 ? '1' : '0' }, # GH 29 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=2 SCAR=6.9
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2456 | # NOTE: unlike JSON::PP::Boolean which relies on fallback and has no | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2457 | # explicit eq/ne overload, we provide semantic boolean matching: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2458 | # false eq "false", false eq "", false eq !!0, true eq "true". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2459 | # JSON::PP would return FALSE for all of these (plain string eq). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2460 | 36 | ▶ | 'eq' => sub { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=9 SCAR=22.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2461 | 36 | ▶ | my ($obj, $op) = $_[2] ? ($_[1], $_[0]) : ($_[0], $_[1]); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2462 | 36 | ▶ | if (ref $op) { # if 2nd also blessed might recurse endlessly | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2463 | 6 | ▶ | return $obj ? 1 == $op : 0 == $op; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2464 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2465 | # if string, only accept numbers or true|false or "" (e.g. !!0 / SV_NO) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2466 | elsif ($op !~ /^[0-9]+$/) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2467 | 18 | ▶ | return "$obj" eq '1' ? 'true' eq $op | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%6/6
"false" eq $op or defined $op and "" eq $op
defined $op and "" eq $op
MC/DC100%3/3
"false" eq $op or defined $op and "" eq $op
"false" eq $op
defined $op
"" eq $op
Truth table100%4/4
A or B and C
A= "false" eq $opB= defined $opC= "" eq $op
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2468 | : 'false' eq $op || (defined($op) && "" eq $op); # GH #207 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2469 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2470 | else { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2471 | 12 | ▶ | return $obj ? 1 == $op : 0 == $op; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2472 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2473 | }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2474 | 6 | ▶ | 'ne' => sub { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=2 SCAR=7.2
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2475 | 6 | ▶ | my ($obj, $op) = $_[2] ? ($_[1], $_[0]) : ($_[0], $_[1]); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2476 | #warn "ne obj:$obj op:$op"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2477 | 6 | return !($obj eq $op); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2478 | }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2479 | 69 | fallback => 1); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2480 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2481 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2482 | 69 | our ($true, $false); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2483 | 69 | ▶ | BEGIN { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=4 SCAR=17.3
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2484 | 69 | ▶ | if ($INC{'JSON/XS.pm'} | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%2/6
$INC{"JSON/XS.pm"} and $INC{"Types/Serialiser.pm"} and $JSON::XS::VERSION ge "3.00"
$INC{"JSON/XS.pm"} and $INC{"Types/Serialiser.pm"}
MC/DC0%0/3
$INC{"JSON/XS.pm"} and $INC{"Types/Serialiser.pm"} and $JSON::XS::VERSION ge "3.00"
$INC{"JSON/XS.pm"}
$INC{"Types/Serialiser.pm"}
$JSON::XS::VERSION ge "3.00"
Truth table25%1/4
A and B and C
A= $INC{"JSON/XS.pm"}B= $INC{"Types/Serialiser.pm"}C= $JSON::XS::VERSION ge "3.00"
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2485 | and $INC{'Types/Serialiser.pm'} | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2486 | and $JSON::XS::VERSION ge "3.00") { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2487 | 0 | $true = $Types::Serialiser::true; # readonly if loaded by JSON::XS | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2488 | 0 | $false = $Types::Serialiser::false; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2489 | } else { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2490 | 69 | $true = do { bless \(my $dummy = 1), "JSON::PP::Boolean" }; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2491 | 69 | $false = do { bless \(my $dummy = 0), "JSON::PP::Boolean" }; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2492 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2493 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2494 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2495 | 69 | ▶ | BEGIN { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.4
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2496 | 69 | my $const_true = $true; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2497 | 69 | my $const_false = $false; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2498 | 0 | ▶ | *true = sub () { $const_true }; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=1.2
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2499 | 0 | ▶ | *false = sub () { $const_false }; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=1.2
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2500 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2501 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2502 | 37 | ▶ | sub is_bool($) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
is_bool: called CC=5 SCAR=16.5
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2503 | 37 | ▶ | shift if @_ == 2; # as method call | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2504 | (ref($_[0]) and UNIVERSAL::isa( $_[0], JSON::PP::Boolean::)) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2505 | 37 | ▶ | or (exists $INC{'Types/Serialiser.pm'} and Types::Serialiser::is_bool($_[0])) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%6/9
ref $_[0] && UNIVERSAL::isa($_[0], 'JSON::PP::Boolean') || exists $INC{'Types/Serialiser.pm'} && Types::Serialiser::is_bool($_[0])
ref $_[0] and UNIVERSAL::isa($_[0], "JSON::PP::Boolean")
exists $INC{"Types/Serialiser.pm"} and Types::Serialiser::is_bool($_[0])
MC/DC50%2/4
ref $_[0] && UNIVERSAL::isa($_[0], 'JSON::PP::Boolean') || exists $INC{'Types/Serialiser.pm'} && Types::Serialiser::is_bool($_[0])
ref $_[0]
UNIVERSAL::isa($_[0], "JSON::PP::Boolean")
exists $INC{"Types/Serialiser.pm"}
Types::Serialiser::is_bool($_[0])
Truth table42%3/7
A and B || C and D
A= ref $_[0]B= UNIVERSAL::isa($_[0], "JSON::PP::Boolean")C= exists $INC{"Types/Serialiser.pm"}D= Types::Serialiser::is_bool($_[0])
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2506 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2507 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2508 | 69 | XSLoader::load 'Cpanel::JSON::XS', $XS_VERSION; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2509 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2510 | 69 | 1; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2511 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2512 | =head1 SEE ALSO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2513 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2514 | The F<cpanel_json_xs> command line utility for quick experiments. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2515 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2516 | L<JSON::PP>, L<JSON>, L<JSON::XS>, L<JSON::MaybeXS>, L<Mojo::JSON>, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2517 | L<Mojo::JSON::MaybeXS>, L<JSON::SL>, L<JSON::DWIW>, L<JSON::YAJL>, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2518 | L<JSON::Any>, L<Test::JSON>, L<Locale::Wolowitz>, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2519 | L<https://metacpan.org/search?q=JSON> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2520 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2521 | L<https://tools.ietf.org/html/rfc7159> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2522 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2523 | L<https://tools.ietf.org/html/rfc4627> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2524 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2525 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2526 | =head1 AUTHOR | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2527 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2528 | Reini Urban <reini.urban@gmail.com> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2529 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2530 | Marc Lehmann <schmorp@schmorp.de>, http://home.schmorp.de/ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2531 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2532 | =head1 MAINTAINER | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2533 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2534 | Reini Urban <reini.urban@gmail.com> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2535 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2536 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2537 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||