diff options
Diffstat (limited to 'third_party/JSON/JSON-2.59/blib/man3/JSON.3pm')
| -rw-r--r-- | third_party/JSON/JSON-2.59/blib/man3/JSON.3pm | 1876 |
1 files changed, 1876 insertions, 0 deletions
diff --git a/third_party/JSON/JSON-2.59/blib/man3/JSON.3pm b/third_party/JSON/JSON-2.59/blib/man3/JSON.3pm new file mode 100644 index 0000000..4a73a04 --- /dev/null +++ b/third_party/JSON/JSON-2.59/blib/man3/JSON.3pm @@ -0,0 +1,1876 @@ +.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "JSON 3pm" +.TH JSON 3pm "2013-06-05" "perl v5.14.2" "User Contributed Perl Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +JSON \- JSON (JavaScript Object Notation) encoder/decoder +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& use JSON; # imports encode_json, decode_json, to_json and from_json. +\& +\& # simple and fast interfaces (expect/generate UTF\-8) +\& +\& $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; +\& $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; +\& +\& # OO\-interface +\& +\& $json = JSON\->new\->allow_nonref; +\& +\& $json_text = $json\->encode( $perl_scalar ); +\& $perl_scalar = $json\->decode( $json_text ); +\& +\& $pretty_printed = $json\->pretty\->encode( $perl_scalar ); # pretty\-printing +\& +\& # If you want to use PP only support features, call with \*(Aq\-support_by_pp\*(Aq +\& # When XS unsupported feature is enable, using PP (de|en)code instead of XS ones. +\& +\& use JSON \-support_by_pp; +\& +\& # option\-acceptable interfaces (expect/generate UNICODE by default) +\& +\& $json_text = to_json( $perl_scalar, { ascii => 1, pretty => 1 } ); +\& $perl_scalar = from_json( $json_text, { utf8 => 1 } ); +\& +\& # Between (en|de)code_json and (to|from)_json, if you want to write +\& # a code which communicates to an outer world (encoded in UTF\-8), +\& # recommend to use (en|de)code_json. +.Ve +.SH "VERSION" +.IX Header "VERSION" +.Vb 1 +\& 2.59 +.Ve +.PP +This version is compatible with \s-1JSON::XS\s0 \fB2.34\fR and later. +.SH "NOTE" +.IX Header "NOTE" +\&\s-1JSON::PP\s0 was earlier included in the \f(CW\*(C`JSON\*(C'\fR distribution, but +has since Perl 5.14 been a core module. For this reason, +\&\s-1JSON::PP\s0 was removed from the \s-1JSON\s0 distribution and can now +be found also in the Perl5 repository at +.IP "\(bu" 4 +<http://perl5.git.perl.org/perl.git> +.PP +(The newest \s-1JSON::PP\s0 version still exists in \s-1CPAN\s0.) +.PP +Instead, the \f(CW\*(C`JSON\*(C'\fR distribution will include JSON::backportPP +for backwards computability. \s-1JSON\s0.pm should thus work as it did +before. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +.Vb 6 +\& ************************** CAUTION ******************************** +\& * This is \*(AqJSON module version 2\*(Aq and there are many differences * +\& * to version 1.xx * +\& * Please check your applications using old version. * +\& * See to \*(AqINCOMPATIBLE CHANGES TO OLD VERSION\*(Aq * +\& ******************************************************************* +.Ve +.PP +\&\s-1JSON\s0 (JavaScript Object Notation) is a simple data format. +See to <http://www.json.org/> and \f(CW\*(C`RFC4627\*(C'\fR(<http://www.ietf.org/rfc/rfc4627.txt>). +.PP +This module converts Perl data structures to \s-1JSON\s0 and vice versa using either +\&\s-1JSON::XS\s0 or \s-1JSON::PP\s0. +.PP +\&\s-1JSON::XS\s0 is the fastest and most proper \s-1JSON\s0 module on \s-1CPAN\s0 which must be +compiled and installed in your environment. +\&\s-1JSON::PP\s0 is a pure-Perl module which is bundled in this distribution and +has a strong compatibility to \s-1JSON::XS\s0. +.PP +This module try to use \s-1JSON::XS\s0 by default and fail to it, use \s-1JSON::PP\s0 instead. +So its features completely depend on \s-1JSON::XS\s0 or \s-1JSON::PP\s0. +.PP +See to \*(L"\s-1BACKEND\s0 \s-1MODULE\s0 \s-1DECISION\s0\*(R". +.PP +To distinguish the module name '\s-1JSON\s0' and the format type \s-1JSON\s0, +the former is quoted by C<> (its results vary with your using media), +and the latter is left just as it is. +.PP +Module name : \f(CW\*(C`JSON\*(C'\fR +.PP +Format type : \s-1JSON\s0 +.SS "\s-1FEATURES\s0" +.IX Subsection "FEATURES" +.IP "\(bu" 4 +correct unicode handling +.Sp +This module (i.e. backend modules) knows how to handle Unicode, documents +how and when it does so, and even documents what \*(L"correct\*(R" means. +.Sp +Even though there are limitations, this feature is available since Perl version 5.6. +.Sp +\&\s-1JSON::XS\s0 requires Perl 5.8.2 (but works correctly in 5.8.8 or later), so in older versions +\&\f(CW\*(C`JSON\*(C'\fR should call \s-1JSON::PP\s0 as the backend which can be used since Perl 5.005. +.Sp +With Perl 5.8.x \s-1JSON::PP\s0 works, but from 5.8.0 to 5.8.2, because of a Perl side problem, +\&\s-1JSON::PP\s0 works slower in the versions. And in 5.005, the Unicode handling is not available. +See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R" in \s-1JSON::PP\s0 for more information. +.Sp +See also to \*(L"A \s-1FEW\s0 \s-1NOTES\s0 \s-1ON\s0 \s-1UNICODE\s0 \s-1AND\s0 \s-1PERL\s0\*(R" in \s-1JSON::XS\s0 +and \*(L"\s-1ENCODING/CODESET_FLAG_NOTES\s0\*(R" in \s-1JSON::XS\s0. +.IP "\(bu" 4 +round-trip integrity +.Sp +When you serialise a perl data structure using only data types supported +by \s-1JSON\s0 and Perl, the deserialised data structure is identical on the Perl +level. (e.g. the string \*(L"2.0\*(R" doesn't suddenly become \*(L"2\*(R" just because +it looks like a number). There \fIare\fR minor exceptions to this, read the +\&\*(L"\s-1MAPPING\s0\*(R" section below to learn about those. +.IP "\(bu" 4 +strict checking of \s-1JSON\s0 correctness +.Sp +There is no guessing, no generating of illegal \s-1JSON\s0 texts by default, +and only \s-1JSON\s0 is accepted as input by default (the latter is a security +feature). +.Sp +See to \*(L"\s-1FEATURES\s0\*(R" in \s-1JSON::XS\s0 and \*(L"\s-1FEATURES\s0\*(R" in \s-1JSON::PP\s0. +.IP "\(bu" 4 +fast +.Sp +This module returns a \s-1JSON::XS\s0 object itself if available. +Compared to other \s-1JSON\s0 modules and other serialisers such as Storable, +\&\s-1JSON::XS\s0 usually compares favorably in terms of speed, too. +.Sp +If not available, \f(CW\*(C`JSON\*(C'\fR returns a \s-1JSON::PP\s0 object instead of \s-1JSON::XS\s0 and +it is very slow as pure-Perl. +.IP "\(bu" 4 +simple to use +.Sp +This module has both a simple functional interface as well as an +object oriented interface interface. +.IP "\(bu" 4 +reasonably versatile output formats +.Sp +You can choose between the most compact guaranteed-single-line format possible +(nice for simple line-based protocols), a pure-ASCII format (for when your transport +is not 8\-bit clean, still supports the whole Unicode range), or a pretty-printed +format (for when you want to read that stuff). Or you can combine those features +in whatever way you like. +.SH "FUNCTIONAL INTERFACE" +.IX Header "FUNCTIONAL INTERFACE" +Some documents are copied and modified from \*(L"\s-1FUNCTIONAL\s0 \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0. +\&\f(CW\*(C`to_json\*(C'\fR and \f(CW\*(C`from_json\*(C'\fR are additional functions. +.SS "encode_json" +.IX Subsection "encode_json" +.Vb 1 +\& $json_text = encode_json $perl_scalar +.Ve +.PP +Converts the given Perl data structure to a \s-1UTF\-8\s0 encoded, binary string. +.PP +This function call is functionally identical to: +.PP +.Vb 1 +\& $json_text = JSON\->new\->utf8\->encode($perl_scalar) +.Ve +.SS "decode_json" +.IX Subsection "decode_json" +.Vb 1 +\& $perl_scalar = decode_json $json_text +.Ve +.PP +The opposite of \f(CW\*(C`encode_json\*(C'\fR: expects an \s-1UTF\-8\s0 (binary) string and tries +to parse that as an \s-1UTF\-8\s0 encoded \s-1JSON\s0 text, returning the resulting +reference. +.PP +This function call is functionally identical to: +.PP +.Vb 1 +\& $perl_scalar = JSON\->new\->utf8\->decode($json_text) +.Ve +.SS "to_json" +.IX Subsection "to_json" +.Vb 1 +\& $json_text = to_json($perl_scalar) +.Ve +.PP +Converts the given Perl data structure to a json string. +.PP +This function call is functionally identical to: +.PP +.Vb 1 +\& $json_text = JSON\->new\->encode($perl_scalar) +.Ve +.PP +Takes a hash reference as the second. +.PP +.Vb 1 +\& $json_text = to_json($perl_scalar, $flag_hashref) +.Ve +.PP +So, +.PP +.Vb 1 +\& $json_text = to_json($perl_scalar, {utf8 => 1, pretty => 1}) +.Ve +.PP +equivalent to: +.PP +.Vb 1 +\& $json_text = JSON\->new\->utf8(1)\->pretty(1)\->encode($perl_scalar) +.Ve +.PP +If you want to write a modern perl code which communicates to outer world, +you should use \f(CW\*(C`encode_json\*(C'\fR (supposed that \s-1JSON\s0 data are encoded in \s-1UTF\-8\s0). +.SS "from_json" +.IX Subsection "from_json" +.Vb 1 +\& $perl_scalar = from_json($json_text) +.Ve +.PP +The opposite of \f(CW\*(C`to_json\*(C'\fR: expects a json string and tries +to parse it, returning the resulting reference. +.PP +This function call is functionally identical to: +.PP +.Vb 1 +\& $perl_scalar = JSON\->decode($json_text) +.Ve +.PP +Takes a hash reference as the second. +.PP +.Vb 1 +\& $perl_scalar = from_json($json_text, $flag_hashref) +.Ve +.PP +So, +.PP +.Vb 1 +\& $perl_scalar = from_json($json_text, {utf8 => 1}) +.Ve +.PP +equivalent to: +.PP +.Vb 1 +\& $perl_scalar = JSON\->new\->utf8(1)\->decode($json_text) +.Ve +.PP +If you want to write a modern perl code which communicates to outer world, +you should use \f(CW\*(C`decode_json\*(C'\fR (supposed that \s-1JSON\s0 data are encoded in \s-1UTF\-8\s0). +.SS "JSON::is_bool" +.IX Subsection "JSON::is_bool" +.Vb 1 +\& $is_boolean = JSON::is_bool($scalar) +.Ve +.PP +Returns true if the passed scalar represents either JSON::true or +JSON::false, two constants that act like \f(CW1\fR and \f(CW0\fR respectively +and are also used to represent \s-1JSON\s0 \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR in Perl strings. +.SS "JSON::true" +.IX Subsection "JSON::true" +Returns \s-1JSON\s0 true value which is blessed object. +It \f(CW\*(C`isa\*(C'\fR JSON::Boolean object. +.SS "JSON::false" +.IX Subsection "JSON::false" +Returns \s-1JSON\s0 false value which is blessed object. +It \f(CW\*(C`isa\*(C'\fR JSON::Boolean object. +.SS "JSON::null" +.IX Subsection "JSON::null" +Returns \f(CW\*(C`undef\*(C'\fR. +.PP +See \s-1MAPPING\s0, below, for more information on how \s-1JSON\s0 values are mapped to +Perl. +.SH "HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER" +.IX Header "HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER" +This section supposes that your perl version is 5.8 or later. +.PP +If you know a \s-1JSON\s0 text from an outer world \- a network, a file content, and so on, +is encoded in \s-1UTF\-8\s0, you should use \f(CW\*(C`decode_json\*(C'\fR or \f(CW\*(C`JSON\*(C'\fR module object +with \f(CW\*(C`utf8\*(C'\fR enable. And the decoded result will contain \s-1UNICODE\s0 characters. +.PP +.Vb 4 +\& # from network +\& my $json = JSON\->new\->utf8; +\& my $json_text = CGI\->new\->param( \*(Aqjson_data\*(Aq ); +\& my $perl_scalar = $json\->decode( $json_text ); +\& +\& # from file content +\& local $/; +\& open( my $fh, \*(Aq<\*(Aq, \*(Aqjson.data\*(Aq ); +\& $json_text = <$fh>; +\& $perl_scalar = decode_json( $json_text ); +.Ve +.PP +If an outer data is not encoded in \s-1UTF\-8\s0, firstly you should \f(CW\*(C`decode\*(C'\fR it. +.PP +.Vb 5 +\& use Encode; +\& local $/; +\& open( my $fh, \*(Aq<\*(Aq, \*(Aqjson.data\*(Aq ); +\& my $encoding = \*(Aqcp932\*(Aq; +\& my $unicode_json_text = decode( $encoding, <$fh> ); # UNICODE +\& +\& # or you can write the below code. +\& # +\& # open( my $fh, "<:encoding($encoding)", \*(Aqjson.data\*(Aq ); +\& # $unicode_json_text = <$fh>; +.Ve +.PP +In this case, \f(CW$unicode_json_text\fR is of course \s-1UNICODE\s0 string. +So you \fBcannot\fR use \f(CW\*(C`decode_json\*(C'\fR nor \f(CW\*(C`JSON\*(C'\fR module object with \f(CW\*(C`utf8\*(C'\fR enable. +Instead of them, you use \f(CW\*(C`JSON\*(C'\fR module object with \f(CW\*(C`utf8\*(C'\fR disable or \f(CW\*(C`from_json\*(C'\fR. +.PP +.Vb 3 +\& $perl_scalar = $json\->utf8(0)\->decode( $unicode_json_text ); +\& # or +\& $perl_scalar = from_json( $unicode_json_text ); +.Ve +.PP +Or \f(CW\*(C`encode \*(Aqutf8\*(Aq\*(C'\fR and \f(CW\*(C`decode_json\*(C'\fR: +.PP +.Vb 2 +\& $perl_scalar = decode_json( encode( \*(Aqutf8\*(Aq, $unicode_json_text ) ); +\& # this way is not efficient. +.Ve +.PP +And now, you want to convert your \f(CW$perl_scalar\fR into \s-1JSON\s0 data and +send it to an outer world \- a network or a file content, and so on. +.PP +Your data usually contains \s-1UNICODE\s0 strings and you want the converted data to be encoded +in \s-1UTF\-8\s0, you should use \f(CW\*(C`encode_json\*(C'\fR or \f(CW\*(C`JSON\*(C'\fR module object with \f(CW\*(C`utf8\*(C'\fR enable. +.PP +.Vb 3 +\& print encode_json( $perl_scalar ); # to a network? file? or display? +\& # or +\& print $json\->utf8\->encode( $perl_scalar ); +.Ve +.PP +If \f(CW$perl_scalar\fR does not contain \s-1UNICODE\s0 but \f(CW$encoding\fR\-encoded strings +for some reason, then its characters are regarded as \fBlatin1\fR for perl +(because it does not concern with your \f(CW$encoding\fR). +You \fBcannot\fR use \f(CW\*(C`encode_json\*(C'\fR nor \f(CW\*(C`JSON\*(C'\fR module object with \f(CW\*(C`utf8\*(C'\fR enable. +Instead of them, you use \f(CW\*(C`JSON\*(C'\fR module object with \f(CW\*(C`utf8\*(C'\fR disable or \f(CW\*(C`to_json\*(C'\fR. +Note that the resulted text is a \s-1UNICODE\s0 string but no problem to print it. +.PP +.Vb 6 +\& # $perl_scalar contains $encoding encoded string values +\& $unicode_json_text = $json\->utf8(0)\->encode( $perl_scalar ); +\& # or +\& $unicode_json_text = to_json( $perl_scalar ); +\& # $unicode_json_text consists of characters less than 0x100 +\& print $unicode_json_text; +.Ve +.PP +Or \f(CW\*(C`decode $encoding\*(C'\fR all string values and \f(CW\*(C`encode_json\*(C'\fR: +.PP +.Vb 3 +\& $perl_scalar\->{ foo } = decode( $encoding, $perl_scalar\->{ foo } ); +\& # ... do it to each string values, then encode_json +\& $json_text = encode_json( $perl_scalar ); +.Ve +.PP +This method is a proper way but probably not efficient. +.PP +See to Encode, perluniintro. +.SH "COMMON OBJECT-ORIENTED INTERFACE" +.IX Header "COMMON OBJECT-ORIENTED INTERFACE" +.SS "new" +.IX Subsection "new" +.Vb 1 +\& $json = JSON\->new +.Ve +.PP +Returns a new \f(CW\*(C`JSON\*(C'\fR object inherited from either \s-1JSON::XS\s0 or \s-1JSON::PP\s0 +that can be used to de/encode \s-1JSON\s0 strings. +.PP +All boolean flags described below are by default \fIdisabled\fR. +.PP +The mutators for flags all return the \s-1JSON\s0 object again and thus calls can +be chained: +.PP +.Vb 2 +\& my $json = JSON\->new\->utf8\->space_after\->encode({a => [1,2]}) +\& => {"a": [1, 2]} +.Ve +.SS "ascii" +.IX Subsection "ascii" +.Vb 1 +\& $json = $json\->ascii([$enable]) +\& +\& $enabled = $json\->get_ascii +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then the encode method will not generate characters outside +the code range 0..127. Any Unicode characters outside that range will be escaped using either +a single \euXXXX or a double \euHHHH\euLLLLL escape sequence, as per \s-1RFC4627\s0. +.PP +If \f(CW$enable\fR is false, then the encode method will not escape Unicode characters unless +required by the \s-1JSON\s0 syntax or other flags. This results in a faster and more compact format. +.PP +This feature depends on the used Perl version and environment. +.PP +See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R" in \s-1JSON::PP\s0 if the backend is \s-1PP\s0. +.PP +.Vb 2 +\& JSON\->new\->ascii(1)\->encode([chr 0x10401]) +\& => ["\eud801\eudc01"] +.Ve +.SS "latin1" +.IX Subsection "latin1" +.Vb 1 +\& $json = $json\->latin1([$enable]) +\& +\& $enabled = $json\->get_latin1 +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then the encode method will encode the resulting \s-1JSON\s0 +text as latin1 (or iso\-8859\-1), escaping any characters outside the code range 0..255. +.PP +If \f(CW$enable\fR is false, then the encode method will not escape Unicode characters +unless required by the \s-1JSON\s0 syntax or other flags. +.PP +.Vb 2 +\& JSON\->new\->latin1\->encode (["\ex{89}\ex{abc}"] +\& => ["\ex{89}\e\eu0abc"] # (perl syntax, U+abc escaped, U+89 not) +.Ve +.SS "utf8" +.IX Subsection "utf8" +.Vb 1 +\& $json = $json\->utf8([$enable]) +\& +\& $enabled = $json\->get_utf8 +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then the encode method will encode the \s-1JSON\s0 result +into \s-1UTF\-8\s0, as required by many protocols, while the decode method expects to be handled +an UTF\-8\-encoded string. Please note that UTF\-8\-encoded strings do not contain any +characters outside the range 0..255, they are thus useful for bytewise/binary I/O. +.PP +In future versions, enabling this option might enable autodetection of the \s-1UTF\-16\s0 and \s-1UTF\-32\s0 +encoding families, as described in \s-1RFC4627\s0. +.PP +If \f(CW$enable\fR is false, then the encode method will return the \s-1JSON\s0 string as a (non-encoded) +Unicode string, while decode expects thus a Unicode string. Any decoding or encoding +(e.g. to \s-1UTF\-8\s0 or \s-1UTF\-16\s0) needs to be done yourself, e.g. using the Encode module. +.PP +Example, output UTF\-16BE\-encoded \s-1JSON:\s0 +.PP +.Vb 2 +\& use Encode; +\& $jsontext = encode "UTF\-16BE", JSON::XS\->new\->encode ($object); +.Ve +.PP +Example, decode UTF\-32LE\-encoded \s-1JSON:\s0 +.PP +.Vb 2 +\& use Encode; +\& $object = JSON::XS\->new\->decode (decode "UTF\-32LE", $jsontext); +.Ve +.PP +See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R" in \s-1JSON::PP\s0 if the backend is \s-1PP\s0. +.SS "pretty" +.IX Subsection "pretty" +.Vb 1 +\& $json = $json\->pretty([$enable]) +.Ve +.PP +This enables (or disables) all of the \f(CW\*(C`indent\*(C'\fR, \f(CW\*(C`space_before\*(C'\fR and +\&\f(CW\*(C`space_after\*(C'\fR (and in the future possibly more) flags in one call to +generate the most readable (or most compact) form possible. +.PP +Equivalent to: +.PP +.Vb 1 +\& $json\->indent\->space_before\->space_after +.Ve +.PP +The indent space length is three and \s-1JSON::XS\s0 cannot change the indent +space length. +.SS "indent" +.IX Subsection "indent" +.Vb 1 +\& $json = $json\->indent([$enable]) +\& +\& $enabled = $json\->get_indent +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will use a multiline +format as output, putting every array member or object/hash key-value pair +into its own line, identifying them properly. +.PP +If \f(CW$enable\fR is false, no newlines or indenting will be produced, and the +resulting \s-1JSON\s0 text is guaranteed not to contain any \f(CW\*(C`newlines\*(C'\fR. +.PP +This setting has no effect when decoding \s-1JSON\s0 texts. +.PP +The indent space length is three. +With \s-1JSON::PP\s0, you can also access \f(CW\*(C`indent_length\*(C'\fR to change indent space length. +.SS "space_before" +.IX Subsection "space_before" +.Vb 1 +\& $json = $json\->space_before([$enable]) +\& +\& $enabled = $json\->get_space_before +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra +optional space before the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1JSON\s0 objects. +.PP +If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra +space at those places. +.PP +This setting has no effect when decoding \s-1JSON\s0 texts. +.PP +Example, space_before enabled, space_after and indent disabled: +.PP +.Vb 1 +\& {"key" :"value"} +.Ve +.SS "space_after" +.IX Subsection "space_after" +.Vb 1 +\& $json = $json\->space_after([$enable]) +\& +\& $enabled = $json\->get_space_after +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra +optional space after the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1JSON\s0 objects +and extra whitespace after the \f(CW\*(C`,\*(C'\fR separating key-value pairs and array +members. +.PP +If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra +space at those places. +.PP +This setting has no effect when decoding \s-1JSON\s0 texts. +.PP +Example, space_before and indent disabled, space_after enabled: +.PP +.Vb 1 +\& {"key": "value"} +.Ve +.SS "relaxed" +.IX Subsection "relaxed" +.Vb 1 +\& $json = $json\->relaxed([$enable]) +\& +\& $enabled = $json\->get_relaxed +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept some +extensions to normal \s-1JSON\s0 syntax (see below). \f(CW\*(C`encode\*(C'\fR will not be +affected in anyway. \fIBe aware that this option makes you accept invalid +\&\s-1JSON\s0 texts as if they were valid!\fR. I suggest only to use this option to +parse application-specific files written by humans (configuration files, +resource files etc.) +.PP +If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept +valid \s-1JSON\s0 texts. +.PP +Currently accepted extensions are: +.IP "\(bu" 4 +list items can have an end-comma +.Sp +\&\s-1JSON\s0 \fIseparates\fR array elements and key-value pairs with commas. This +can be annoying if you write \s-1JSON\s0 texts manually and want to be able to +quickly append elements, so this extension accepts comma at the end of +such items not just between them: +.Sp +.Vb 8 +\& [ +\& 1, +\& 2, <\- this comma not normally allowed +\& ] +\& { +\& "k1": "v1", +\& "k2": "v2", <\- this comma not normally allowed +\& } +.Ve +.IP "\(bu" 4 +shell-style '#'\-comments +.Sp +Whenever \s-1JSON\s0 allows whitespace, shell-style comments are additionally +allowed. They are terminated by the first carriage-return or line-feed +character, after which more white-space and comments are allowed. +.Sp +.Vb 4 +\& [ +\& 1, # this comment not allowed in JSON +\& # neither this one... +\& ] +.Ve +.SS "canonical" +.IX Subsection "canonical" +.Vb 1 +\& $json = $json\->canonical([$enable]) +\& +\& $enabled = $json\->get_canonical +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will output \s-1JSON\s0 objects +by sorting their keys. This is adding a comparatively high overhead. +.PP +If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will output key-value +pairs in the order Perl stores them (which will likely change between runs +of the same script). +.PP +This option is useful if you want the same data structure to be encoded as +the same \s-1JSON\s0 text (given the same overall settings). If it is disabled, +the same hash might be encoded differently even if contains the same data, +as key-value pairs have no inherent ordering in Perl. +.PP +This setting has no effect when decoding \s-1JSON\s0 texts. +.SS "allow_nonref" +.IX Subsection "allow_nonref" +.Vb 1 +\& $json = $json\->allow_nonref([$enable]) +\& +\& $enabled = $json\->get_allow_nonref +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method can convert a +non-reference into its corresponding string, number or null \s-1JSON\s0 value, +which is an extension to \s-1RFC4627\s0. Likewise, \f(CW\*(C`decode\*(C'\fR will accept those \s-1JSON\s0 +values instead of croaking. +.PP +If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will croak if it isn't +passed an arrayref or hashref, as \s-1JSON\s0 texts must either be an object +or array. Likewise, \f(CW\*(C`decode\*(C'\fR will croak if given something that is not a +\&\s-1JSON\s0 object or array. +.PP +.Vb 2 +\& JSON\->new\->allow_nonref\->encode ("Hello, World!") +\& => "Hello, World!" +.Ve +.SS "allow_unknown" +.IX Subsection "allow_unknown" +.Vb 1 +\& $json = $json\->allow_unknown ([$enable]) +\& +\& $enabled = $json\->get_allow_unknown +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then \*(L"encode\*(R" will *not* throw an +exception when it encounters values it cannot represent in \s-1JSON\s0 (for +example, filehandles) but instead will encode a \s-1JSON\s0 \*(L"null\*(R" value. +Note that blessed objects are not included here and are handled +separately by c<allow_nonref>. +.PP +If \f(CW$enable\fR is false (the default), then \*(L"encode\*(R" will throw an +exception when it encounters anything it cannot encode as \s-1JSON\s0. +.PP +This option does not affect \*(L"decode\*(R" in any way, and it is +recommended to leave it off unless you know your communications +partner. +.SS "allow_blessed" +.IX Subsection "allow_blessed" +.Vb 1 +\& $json = $json\->allow_blessed([$enable]) +\& +\& $enabled = $json\->get_allow_blessed +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not +barf when it encounters a blessed reference. Instead, the value of the +\&\fBconvert_blessed\fR option will decide whether \f(CW\*(C`null\*(C'\fR (\f(CW\*(C`convert_blessed\*(C'\fR +disabled or no \f(CW\*(C`TO_JSON\*(C'\fR method found) or a representation of the +object (\f(CW\*(C`convert_blessed\*(C'\fR enabled and \f(CW\*(C`TO_JSON\*(C'\fR method found) is being +encoded. Has no effect on \f(CW\*(C`decode\*(C'\fR. +.PP +If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an +exception when it encounters a blessed object. +.SS "convert_blessed" +.IX Subsection "convert_blessed" +.Vb 1 +\& $json = $json\->convert_blessed([$enable]) +\& +\& $enabled = $json\->get_convert_blessed +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a +blessed object, will check for the availability of the \f(CW\*(C`TO_JSON\*(C'\fR method +on the object's class. If found, it will be called in scalar context +and the resulting scalar will be encoded instead of the object. If no +\&\f(CW\*(C`TO_JSON\*(C'\fR method is found, the value of \f(CW\*(C`allow_blessed\*(C'\fR will decide what +to do. +.PP +The \f(CW\*(C`TO_JSON\*(C'\fR method may safely call die if it wants. If \f(CW\*(C`TO_JSON\*(C'\fR +returns other blessed objects, those will be handled in the same +way. \f(CW\*(C`TO_JSON\*(C'\fR must take care of not causing an endless recursion cycle +(== crash) in this case. The name of \f(CW\*(C`TO_JSON\*(C'\fR was chosen because other +methods called by the Perl core (== not by the user of the object) are +usually in upper case letters and to avoid collisions with the \f(CW\*(C`to_json\*(C'\fR +function or method. +.PP +This setting does not yet influence \f(CW\*(C`decode\*(C'\fR in any way. +.PP +If \f(CW$enable\fR is false, then the \f(CW\*(C`allow_blessed\*(C'\fR setting will decide what +to do when a blessed object is found. +.IP "convert_blessed_universally mode" 4 +.IX Item "convert_blessed_universally mode" +If use \f(CW\*(C`JSON\*(C'\fR with \f(CW\*(C`\-convert_blessed_universally\*(C'\fR, the \f(CW\*(C`UNIVERSAL::TO_JSON\*(C'\fR +subroutine is defined as the below code: +.Sp +.Vb 7 +\& *UNIVERSAL::TO_JSON = sub { +\& my $b_obj = B::svref_2object( $_[0] ); +\& return $b_obj\->isa(\*(AqB::HV\*(Aq) ? { %{ $_[0] } } +\& : $b_obj\->isa(\*(AqB::AV\*(Aq) ? [ @{ $_[0] } ] +\& : undef +\& ; +\& } +.Ve +.Sp +This will cause that \f(CW\*(C`encode\*(C'\fR method converts simple blessed objects into +\&\s-1JSON\s0 objects as non-blessed object. +.Sp +.Vb 2 +\& JSON \-convert_blessed_universally; +\& $json\->allow_blessed\->convert_blessed\->encode( $blessed_object ) +.Ve +.Sp +This feature is experimental and may be removed in the future. +.SS "filter_json_object" +.IX Subsection "filter_json_object" +.Vb 1 +\& $json = $json\->filter_json_object([$coderef]) +.Ve +.PP +When \f(CW$coderef\fR is specified, it will be called from \f(CW\*(C`decode\*(C'\fR each +time it decodes a \s-1JSON\s0 object. The only argument passed to the coderef +is a reference to the newly-created hash. If the code references returns +a single scalar (which need not be a reference), this value +(i.e. a copy of that scalar to avoid aliasing) is inserted into the +deserialised data structure. If it returns an empty list +(\s-1NOTE:\s0 \fInot\fR \f(CW\*(C`undef\*(C'\fR, which is a valid scalar), the original deserialised +hash will be inserted. This setting can slow down decoding considerably. +.PP +When \f(CW$coderef\fR is omitted or undefined, any existing callback will +be removed and \f(CW\*(C`decode\*(C'\fR will not change the deserialised hash in any +way. +.PP +Example, convert all \s-1JSON\s0 objects into the integer 5: +.PP +.Vb 6 +\& my $js = JSON\->new\->filter_json_object (sub { 5 }); +\& # returns [5] +\& $js\->decode (\*(Aq[{}]\*(Aq); # the given subroutine takes a hash reference. +\& # throw an exception because allow_nonref is not enabled +\& # so a lone 5 is not allowed. +\& $js\->decode (\*(Aq{"a":1, "b":2}\*(Aq); +.Ve +.SS "filter_json_single_key_object" +.IX Subsection "filter_json_single_key_object" +.Vb 1 +\& $json = $json\->filter_json_single_key_object($key [=> $coderef]) +.Ve +.PP +Works remotely similar to \f(CW\*(C`filter_json_object\*(C'\fR, but is only called for +\&\s-1JSON\s0 objects having a single key named \f(CW$key\fR. +.PP +This \f(CW$coderef\fR is called before the one specified via +\&\f(CW\*(C`filter_json_object\*(C'\fR, if any. It gets passed the single value in the \s-1JSON\s0 +object. If it returns a single value, it will be inserted into the data +structure. If it returns nothing (not even \f(CW\*(C`undef\*(C'\fR but the empty list), +the callback from \f(CW\*(C`filter_json_object\*(C'\fR will be called next, as if no +single-key callback were specified. +.PP +If \f(CW$coderef\fR is omitted or undefined, the corresponding callback will be +disabled. There can only ever be one callback for a given key. +.PP +As this callback gets called less often then the \f(CW\*(C`filter_json_object\*(C'\fR +one, decoding speed will not usually suffer as much. Therefore, single-key +objects make excellent targets to serialise Perl objects into, especially +as single-key \s-1JSON\s0 objects are as close to the type-tagged value concept +as \s-1JSON\s0 gets (it's basically an \s-1ID/VALUE\s0 tuple). Of course, \s-1JSON\s0 does not +support this in any way, so you need to make sure your data never looks +like a serialised Perl hash. +.PP +Typical names for the single object key are \f(CW\*(C`_\|_class_whatever_\|_\*(C'\fR, or +\&\f(CW\*(C`$_\|_dollars_are_rarely_used_\|_$\*(C'\fR or \f(CW\*(C`}ugly_brace_placement\*(C'\fR, or even +things like \f(CW\*(C`_\|_class_md5sum(classname)_\|_\*(C'\fR, to reduce the risk of clashing +with real hashes. +.PP +Example, decode \s-1JSON\s0 objects of the form \f(CW\*(C`{ "_\|_widget_\|_" => <id> }\*(C'\fR +into the corresponding \f(CW$WIDGET{<id>}\fR object: +.PP +.Vb 7 +\& # return whatever is in $WIDGET{5}: +\& JSON +\& \->new +\& \->filter_json_single_key_object (_\|_widget_\|_ => sub { +\& $WIDGET{ $_[0] } +\& }) +\& \->decode (\*(Aq{"_\|_widget_\|_": 5\*(Aq) +\& +\& # this can be used with a TO_JSON method in some "widget" class +\& # for serialisation to json: +\& sub WidgetBase::TO_JSON { +\& my ($self) = @_; +\& +\& unless ($self\->{id}) { +\& $self\->{id} = ..get..some..id..; +\& $WIDGET{$self\->{id}} = $self; +\& } +\& +\& { _\|_widget_\|_ => $self\->{id} } +\& } +.Ve +.SS "shrink" +.IX Subsection "shrink" +.Vb 1 +\& $json = $json\->shrink([$enable]) +\& +\& $enabled = $json\->get_shrink +.Ve +.PP +With \s-1JSON::XS\s0, this flag resizes strings generated by either +\&\f(CW\*(C`encode\*(C'\fR or \f(CW\*(C`decode\*(C'\fR to their minimum size possible. This can save +memory when your \s-1JSON\s0 texts are either very very long or you have many +short strings. It will also try to downgrade any strings to octet-form +if possible: perl stores strings internally either in an encoding called +UTF-X or in octet-form. The latter cannot store everything but uses less +space in general (and some buggy Perl or C code might even rely on that +internal representation being used). +.PP +With \s-1JSON::PP\s0, it is noop about resizing strings but tries +\&\f(CW\*(C`utf8::downgrade\*(C'\fR to the returned string by \f(CW\*(C`encode\*(C'\fR. See to utf8. +.PP +See to \*(L"OBJECT-ORIENTED \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0 and \*(L"\s-1METHODS\s0\*(R" in \s-1JSON::PP\s0. +.SS "max_depth" +.IX Subsection "max_depth" +.Vb 1 +\& $json = $json\->max_depth([$maximum_nesting_depth]) +\& +\& $max_depth = $json\->get_max_depth +.Ve +.PP +Sets the maximum nesting level (default \f(CW512\fR) accepted while encoding +or decoding. If a higher nesting level is detected in \s-1JSON\s0 text or a Perl +data structure, then the encoder and decoder will stop and croak at that +point. +.PP +Nesting level is defined by number of hash\- or arrayrefs that the encoder +needs to traverse to reach a given point or the number of \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`[\*(C'\fR +characters without their matching closing parenthesis crossed to reach a +given character in a string. +.PP +If no argument is given, the highest possible setting will be used, which +is rarely useful. +.PP +Note that nesting is implemented by recursion in C. The default value has +been chosen to be as large as typical operating systems allow without +crashing. (\s-1JSON::XS\s0) +.PP +With \s-1JSON::PP\s0 as the backend, when a large value (100 or more) was set and +it de/encodes a deep nested object/text, it may raise a warning +\&'Deep recursion on subroutine' at the perl runtime phase. +.PP +See \*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0 for more info on why this is useful. +.SS "max_size" +.IX Subsection "max_size" +.Vb 1 +\& $json = $json\->max_size([$maximum_string_size]) +\& +\& $max_size = $json\->get_max_size +.Ve +.PP +Set the maximum length a \s-1JSON\s0 text may have (in bytes) where decoding is +being attempted. The default is \f(CW0\fR, meaning no limit. When \f(CW\*(C`decode\*(C'\fR +is called on a string that is longer then this many bytes, it will not +attempt to decode the string but throw an exception. This setting has no +effect on \f(CW\*(C`encode\*(C'\fR (yet). +.PP +If no argument is given, the limit check will be deactivated (same as when +\&\f(CW0\fR is specified). +.PP +See \*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0, below, for more info on why this is useful. +.SS "encode" +.IX Subsection "encode" +.Vb 1 +\& $json_text = $json\->encode($perl_scalar) +.Ve +.PP +Converts the given Perl data structure (a simple scalar or a reference +to a hash or array) to its \s-1JSON\s0 representation. Simple scalars will be +converted into \s-1JSON\s0 string or number sequences, while references to arrays +become \s-1JSON\s0 arrays and references to hashes become \s-1JSON\s0 objects. Undefined +Perl values (e.g. \f(CW\*(C`undef\*(C'\fR) become \s-1JSON\s0 \f(CW\*(C`null\*(C'\fR values. +References to the integers \f(CW0\fR and \f(CW1\fR are converted into \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR. +.SS "decode" +.IX Subsection "decode" +.Vb 1 +\& $perl_scalar = $json\->decode($json_text) +.Ve +.PP +The opposite of \f(CW\*(C`encode\*(C'\fR: expects a \s-1JSON\s0 text and tries to parse it, +returning the resulting simple scalar or reference. Croaks on error. +.PP +\&\s-1JSON\s0 numbers and strings become simple Perl scalars. \s-1JSON\s0 arrays become +Perl arrayrefs and \s-1JSON\s0 objects become Perl hashrefs. \f(CW\*(C`true\*(C'\fR becomes +\&\f(CW1\fR (\f(CW\*(C`JSON::true\*(C'\fR), \f(CW\*(C`false\*(C'\fR becomes \f(CW0\fR (\f(CW\*(C`JSON::false\*(C'\fR) and +\&\f(CW\*(C`null\*(C'\fR becomes \f(CW\*(C`undef\*(C'\fR. +.SS "decode_prefix" +.IX Subsection "decode_prefix" +.Vb 1 +\& ($perl_scalar, $characters) = $json\->decode_prefix($json_text) +.Ve +.PP +This works like the \f(CW\*(C`decode\*(C'\fR method, but instead of raising an exception +when there is trailing garbage after the first \s-1JSON\s0 object, it will +silently stop parsing there and return the number of characters consumed +so far. +.PP +.Vb 2 +\& JSON\->new\->decode_prefix ("[1] the tail") +\& => ([], 3) +.Ve +.PP +See to \*(L"OBJECT-ORIENTED \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0 +.SS "property" +.IX Subsection "property" +.Vb 1 +\& $boolean = $json\->property($property_name) +.Ve +.PP +Returns a boolean value about above some properties. +.PP +The available properties are \f(CW\*(C`ascii\*(C'\fR, \f(CW\*(C`latin1\*(C'\fR, \f(CW\*(C`utf8\*(C'\fR, +\&\f(CW\*(C`indent\*(C'\fR,\f(CW\*(C`space_before\*(C'\fR, \f(CW\*(C`space_after\*(C'\fR, \f(CW\*(C`relaxed\*(C'\fR, \f(CW\*(C`canonical\*(C'\fR, +\&\f(CW\*(C`allow_nonref\*(C'\fR, \f(CW\*(C`allow_unknown\*(C'\fR, \f(CW\*(C`allow_blessed\*(C'\fR, \f(CW\*(C`convert_blessed\*(C'\fR, +\&\f(CW\*(C`shrink\*(C'\fR, \f(CW\*(C`max_depth\*(C'\fR and \f(CW\*(C`max_size\*(C'\fR. +.PP +.Vb 5 +\& $boolean = $json\->property(\*(Aqutf8\*(Aq); +\& => 0 +\& $json\->utf8; +\& $boolean = $json\->property(\*(Aqutf8\*(Aq); +\& => 1 +.Ve +.PP +Sets the property with a given boolean value. +.PP +.Vb 1 +\& $json = $json\->property($property_name => $boolean); +.Ve +.PP +With no argument, it returns all the above properties as a hash reference. +.PP +.Vb 1 +\& $flag_hashref = $json\->property(); +.Ve +.SH "INCREMENTAL PARSING" +.IX Header "INCREMENTAL PARSING" +Most of this section are copied and modified from \*(L"\s-1INCREMENTAL\s0 \s-1PARSING\s0\*(R" in \s-1JSON::XS\s0. +.PP +In some cases, there is the need for incremental parsing of \s-1JSON\s0 texts. +This module does allow you to parse a \s-1JSON\s0 stream incrementally. +It does so by accumulating text until it has a full \s-1JSON\s0 object, which +it then can decode. This process is similar to using \f(CW\*(C`decode_prefix\*(C'\fR +to see if a full \s-1JSON\s0 object is available, but is much more efficient +(and can be implemented with a minimum of method calls). +.PP +The backend module will only attempt to parse the \s-1JSON\s0 text once it is sure it +has enough text to get a decisive result, using a very simple but +truly incremental parser. This means that it sometimes won't stop as +early as the full parser, for example, it doesn't detect parenthesis +mismatches. The only thing it guarantees is that it starts decoding as +soon as a syntactically valid \s-1JSON\s0 text has been seen. This means you need +to set resource limits (e.g. \f(CW\*(C`max_size\*(C'\fR) to ensure the parser will stop +parsing in the presence if syntax errors. +.PP +The following methods implement this incremental parser. +.SS "incr_parse" +.IX Subsection "incr_parse" +.Vb 1 +\& $json\->incr_parse( [$string] ) # void context +\& +\& $obj_or_undef = $json\->incr_parse( [$string] ) # scalar context +\& +\& @obj_or_empty = $json\->incr_parse( [$string] ) # list context +.Ve +.PP +This is the central parsing function. It can both append new text and +extract objects from the stream accumulated so far (both of these +functions are optional). +.PP +If \f(CW$string\fR is given, then this string is appended to the already +existing \s-1JSON\s0 fragment stored in the \f(CW$json\fR object. +.PP +After that, if the function is called in void context, it will simply +return without doing anything further. This can be used to add more text +in as many chunks as you want. +.PP +If the method is called in scalar context, then it will try to extract +exactly \fIone\fR \s-1JSON\s0 object. If that is successful, it will return this +object, otherwise it will return \f(CW\*(C`undef\*(C'\fR. If there is a parse error, +this method will croak just as \f(CW\*(C`decode\*(C'\fR would do (one can then use +\&\f(CW\*(C`incr_skip\*(C'\fR to skip the erroneous part). This is the most common way of +using the method. +.PP +And finally, in list context, it will try to extract as many objects +from the stream as it can find and return them, or the empty list +otherwise. For this to work, there must be no separators between the \s-1JSON\s0 +objects or arrays, instead they must be concatenated back-to-back. If +an error occurs, an exception will be raised as in the scalar context +case. Note that in this case, any previously-parsed \s-1JSON\s0 texts will be +lost. +.PP +Example: Parse some \s-1JSON\s0 arrays/objects in a given string and return them. +.PP +.Vb 1 +\& my @objs = JSON\->new\->incr_parse ("[5][7][1,2]"); +.Ve +.SS "incr_text" +.IX Subsection "incr_text" +.Vb 1 +\& $lvalue_string = $json\->incr_text +.Ve +.PP +This method returns the currently stored \s-1JSON\s0 fragment as an lvalue, that +is, you can manipulate it. This \fIonly\fR works when a preceding call to +\&\f(CW\*(C`incr_parse\*(C'\fR in \fIscalar context\fR successfully returned an object. Under +all other circumstances you must not call this function (I mean it. +although in simple tests it might actually work, it \fIwill\fR fail under +real world conditions). As a special exception, you can also call this +method before having parsed anything. +.PP +This function is useful in two cases: a) finding the trailing text after a +\&\s-1JSON\s0 object or b) parsing multiple \s-1JSON\s0 objects separated by non-JSON text +(such as commas). +.PP +.Vb 1 +\& $json\->incr_text =~ s/\es*,\es*//; +.Ve +.PP +In Perl 5.005, \f(CW\*(C`lvalue\*(C'\fR attribute is not available. +You must write codes like the below: +.PP +.Vb 3 +\& $string = $json\->incr_text; +\& $string =~ s/\es*,\es*//; +\& $json\->incr_text( $string ); +.Ve +.SS "incr_skip" +.IX Subsection "incr_skip" +.Vb 1 +\& $json\->incr_skip +.Ve +.PP +This will reset the state of the incremental parser and will remove the +parsed text from the input buffer. This is useful after \f(CW\*(C`incr_parse\*(C'\fR +died, in which case the input buffer and incremental parser state is left +unchanged, to skip the text parsed so far and to reset the parse state. +.SS "incr_reset" +.IX Subsection "incr_reset" +.Vb 1 +\& $json\->incr_reset +.Ve +.PP +This completely resets the incremental parser, that is, after this call, +it will be as if the parser had never parsed anything. +.PP +This is useful if you want to repeatedly parse \s-1JSON\s0 objects and want to +ignore any trailing data, which means you have to reset the parser after +each successful decode. +.PP +See to \*(L"\s-1INCREMENTAL\s0 \s-1PARSING\s0\*(R" in \s-1JSON::XS\s0 for examples. +.SH "JSON::PP SUPPORT METHODS" +.IX Header "JSON::PP SUPPORT METHODS" +The below methods are \s-1JSON::PP\s0 own methods, so when \f(CW\*(C`JSON\*(C'\fR works +with \s-1JSON::PP\s0 (i.e. the created object is a \s-1JSON::PP\s0 object), available. +See to \*(L"\s-1JSON::PP\s0 \s-1OWN\s0 \s-1METHODS\s0\*(R" in \s-1JSON::PP\s0 in detail. +.PP +If you use \f(CW\*(C`JSON\*(C'\fR with additional \f(CW\*(C`\-support_by_pp\*(C'\fR, some methods +are available even with \s-1JSON::XS\s0. See to \*(L"\s-1USE\s0 \s-1PP\s0 \s-1FEATURES\s0 \s-1EVEN\s0 \s-1THOUGH\s0 \s-1XS\s0 \s-1BACKEND\s0\*(R". +.PP +.Vb 1 +\& BEING { $ENV{PERL_JSON_BACKEND} = \*(AqJSON::XS\*(Aq } +\& +\& use JSON \-support_by_pp; +\& +\& my $json = JSON\->new; +\& $json\->allow_nonref\->escape_slash\->encode("/"); +\& +\& # functional interfaces too. +\& print to_json(["/"], {escape_slash => 1}); +\& print from_json(\*(Aq["foo"]\*(Aq, {utf8 => 1}); +.Ve +.PP +If you do not want to all functions but \f(CW\*(C`\-support_by_pp\*(C'\fR, +use \f(CW\*(C`\-no_export\*(C'\fR. +.PP +.Vb 2 +\& use JSON \-support_by_pp, \-no_export; +\& # functional interfaces are not exported. +.Ve +.SS "allow_singlequote" +.IX Subsection "allow_singlequote" +.Vb 1 +\& $json = $json\->allow_singlequote([$enable]) +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept +any \s-1JSON\s0 strings quoted by single quotations that are invalid \s-1JSON\s0 +format. +.PP +.Vb 3 +\& $json\->allow_singlequote\->decode({"foo":\*(Aqbar\*(Aq}); +\& $json\->allow_singlequote\->decode({\*(Aqfoo\*(Aq:"bar"}); +\& $json\->allow_singlequote\->decode({\*(Aqfoo\*(Aq:\*(Aqbar\*(Aq}); +.Ve +.PP +As same as the \f(CW\*(C`relaxed\*(C'\fR option, this option may be used to parse +application-specific files written by humans. +.SS "allow_barekey" +.IX Subsection "allow_barekey" +.Vb 1 +\& $json = $json\->allow_barekey([$enable]) +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept +bare keys of \s-1JSON\s0 object that are invalid \s-1JSON\s0 format. +.PP +As same as the \f(CW\*(C`relaxed\*(C'\fR option, this option may be used to parse +application-specific files written by humans. +.PP +.Vb 1 +\& $json\->allow_barekey\->decode(\*(Aq{foo:"bar"}\*(Aq); +.Ve +.SS "allow_bignum" +.IX Subsection "allow_bignum" +.Vb 1 +\& $json = $json\->allow_bignum([$enable]) +.Ve +.PP +If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will convert +the big integer Perl cannot handle as integer into a Math::BigInt +object and convert a floating number (any) into a Math::BigFloat. +.PP +On the contrary, \f(CW\*(C`encode\*(C'\fR converts \f(CW\*(C`Math::BigInt\*(C'\fR objects and \f(CW\*(C`Math::BigFloat\*(C'\fR +objects into \s-1JSON\s0 numbers with \f(CW\*(C`allow_blessed\*(C'\fR enable. +.PP +.Vb 4 +\& $json\->allow_nonref\->allow_blessed\->allow_bignum; +\& $bigfloat = $json\->decode(\*(Aq2.000000000000000000000000001\*(Aq); +\& print $json\->encode($bigfloat); +\& # => 2.000000000000000000000000001 +.Ve +.PP +See to \s-1MAPPING\s0 about the conversion of \s-1JSON\s0 number. +.SS "loose" +.IX Subsection "loose" +.Vb 1 +\& $json = $json\->loose([$enable]) +.Ve +.PP +The unescaped [\ex00\-\ex1f\ex22\ex2f\ex5c] strings are invalid in \s-1JSON\s0 strings +and the module doesn't allow to \f(CW\*(C`decode\*(C'\fR to these (except for \ex2f). +If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept these +unescaped strings. +.PP +.Vb 2 +\& $json\->loose\->decode(qq|["abc +\& def"]|); +.Ve +.PP +See to \*(L"\s-1JSON::PP\s0 \s-1OWN\s0 \s-1METHODS\s0\*(R" in \s-1JSON::PP\s0. +.SS "escape_slash" +.IX Subsection "escape_slash" +.Vb 1 +\& $json = $json\->escape_slash([$enable]) +.Ve +.PP +According to \s-1JSON\s0 Grammar, \fIslash\fR (U+002F) is escaped. But by default +\&\s-1JSON\s0 backend modules encode strings without escaping slash. +.PP +If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will escape slashes. +.SS "indent_length" +.IX Subsection "indent_length" +.Vb 1 +\& $json = $json\->indent_length($length) +.Ve +.PP +With \s-1JSON::XS\s0, The indent space length is 3 and cannot be changed. +With \s-1JSON::PP\s0, it sets the indent space length with the given \f(CW$length\fR. +The default is 3. The acceptable range is 0 to 15. +.SS "sort_by" +.IX Subsection "sort_by" +.Vb 2 +\& $json = $json\->sort_by($function_name) +\& $json = $json\->sort_by($subroutine_ref) +.Ve +.PP +If \f(CW$function_name\fR or \f(CW$subroutine_ref\fR are set, its sort routine are used. +.PP +.Vb 2 +\& $js = $pc\->sort_by(sub { $JSON::PP::a cmp $JSON::PP::b })\->encode($obj); +\& # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|); +\& +\& $js = $pc\->sort_by(\*(Aqown_sort\*(Aq)\->encode($obj); +\& # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|); +\& +\& sub JSON::PP::own_sort { $JSON::PP::a cmp $JSON::PP::b } +.Ve +.PP +As the sorting routine runs in the \s-1JSON::PP\s0 scope, the given +subroutine name and the special variables \f(CW$a\fR, \f(CW$b\fR will begin +with '\s-1JSON::PP::\s0'. +.PP +If \f(CW$integer\fR is set, then the effect is same as \f(CW\*(C`canonical\*(C'\fR on. +.PP +See to \*(L"\s-1JSON::PP\s0 \s-1OWN\s0 \s-1METHODS\s0\*(R" in \s-1JSON::PP\s0. +.SH "MAPPING" +.IX Header "MAPPING" +This section is copied from \s-1JSON::XS\s0 and modified to \f(CW\*(C`JSON\*(C'\fR. +\&\s-1JSON::XS\s0 and \s-1JSON::PP\s0 mapping mechanisms are almost equivalent. +.PP +See to \*(L"\s-1MAPPING\s0\*(R" in \s-1JSON::XS\s0. +.SS "\s-1JSON\s0 \-> \s-1PERL\s0" +.IX Subsection "JSON -> PERL" +.IP "object" 4 +.IX Item "object" +A \s-1JSON\s0 object becomes a reference to a hash in Perl. No ordering of object +keys is preserved (\s-1JSON\s0 does not preserver object key ordering itself). +.IP "array" 4 +.IX Item "array" +A \s-1JSON\s0 array becomes a reference to an array in Perl. +.IP "string" 4 +.IX Item "string" +A \s-1JSON\s0 string becomes a string scalar in Perl \- Unicode codepoints in \s-1JSON\s0 +are represented by the same codepoints in the Perl string, so no manual +decoding is necessary. +.IP "number" 4 +.IX Item "number" +A \s-1JSON\s0 number becomes either an integer, numeric (floating point) or +string scalar in perl, depending on its range and any fractional parts. On +the Perl level, there is no difference between those as Perl handles all +the conversion details, but an integer may take slightly less memory and +might represent more values exactly than floating point numbers. +.Sp +If the number consists of digits only, \f(CW\*(C`JSON\*(C'\fR will try to represent +it as an integer value. If that fails, it will try to represent it as +a numeric (floating point) value if that is possible without loss of +precision. Otherwise it will preserve the number as a string value (in +which case you lose roundtripping ability, as the \s-1JSON\s0 number will be +re-encoded to a \s-1JSON\s0 string). +.Sp +Numbers containing a fractional or exponential part will always be +represented as numeric (floating point) values, possibly at a loss of +precision (in which case you might lose perfect roundtripping ability, but +the \s-1JSON\s0 number will still be re-encoded as a \s-1JSON\s0 number). +.Sp +Note that precision is not accuracy \- binary floating point values cannot +represent most decimal fractions exactly, and when converting from and to +floating point, \f(CW\*(C`JSON\*(C'\fR only guarantees precision up to but not including +the least significant bit. +.Sp +If the backend is \s-1JSON::PP\s0 and \f(CW\*(C`allow_bignum\*(C'\fR is enable, the big integers +and the numeric can be optionally converted into Math::BigInt and +Math::BigFloat objects. +.IP "true, false" 4 +.IX Item "true, false" +These \s-1JSON\s0 atoms become \f(CW\*(C`JSON::true\*(C'\fR and \f(CW\*(C`JSON::false\*(C'\fR, +respectively. They are overloaded to act almost exactly like the numbers +\&\f(CW1\fR and \f(CW0\fR. You can check whether a scalar is a \s-1JSON\s0 boolean by using +the \f(CW\*(C`JSON::is_bool\*(C'\fR function. +.Sp +If \f(CW\*(C`JSON::true\*(C'\fR and \f(CW\*(C`JSON::false\*(C'\fR are used as strings or compared as strings, +they represent as \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR respectively. +.Sp +.Vb 4 +\& print JSON::true . "\en"; +\& => true +\& print JSON::true + 1; +\& => 1 +\& +\& ok(JSON::true eq \*(Aqtrue\*(Aq); +\& ok(JSON::true eq \*(Aq1\*(Aq); +\& ok(JSON::true == 1); +.Ve +.Sp +\&\f(CW\*(C`JSON\*(C'\fR will install these missing overloading features to the backend modules. +.IP "null" 4 +.IX Item "null" +A \s-1JSON\s0 null atom becomes \f(CW\*(C`undef\*(C'\fR in Perl. +.Sp +\&\f(CW\*(C`JSON::null\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR. +.SS "\s-1PERL\s0 \-> \s-1JSON\s0" +.IX Subsection "PERL -> JSON" +The mapping from Perl to \s-1JSON\s0 is slightly more difficult, as Perl is a +truly typeless language, so we can only guess which \s-1JSON\s0 type is meant by +a Perl value. +.IP "hash references" 4 +.IX Item "hash references" +Perl hash references become \s-1JSON\s0 objects. As there is no inherent ordering +in hash keys (or \s-1JSON\s0 objects), they will usually be encoded in a +pseudo-random order that can change between runs of the same program but +stays generally the same within a single run of a program. \f(CW\*(C`JSON\*(C'\fR +optionally sort the hash keys (determined by the \fIcanonical\fR flag), so +the same data structure will serialise to the same \s-1JSON\s0 text (given same +settings and version of \s-1JSON::XS\s0), but this incurs a runtime overhead +and is only rarely useful, e.g. when you want to compare some \s-1JSON\s0 text +against another for equality. +.Sp +In future, the ordered object feature will be added to \s-1JSON::PP\s0 using \f(CW\*(C`tie\*(C'\fR mechanism. +.IP "array references" 4 +.IX Item "array references" +Perl array references become \s-1JSON\s0 arrays. +.IP "other references" 4 +.IX Item "other references" +Other unblessed references are generally not allowed and will cause an +exception to be thrown, except for references to the integers \f(CW0\fR and +\&\f(CW1\fR, which get turned into \f(CW\*(C`false\*(C'\fR and \f(CW\*(C`true\*(C'\fR atoms in \s-1JSON\s0. You can +also use \f(CW\*(C`JSON::false\*(C'\fR and \f(CW\*(C`JSON::true\*(C'\fR to improve readability. +.Sp +.Vb 1 +\& to_json [\e0,JSON::true] # yields [false,true] +.Ve +.IP "JSON::true, JSON::false, JSON::null" 4 +.IX Item "JSON::true, JSON::false, JSON::null" +These special values become \s-1JSON\s0 true and \s-1JSON\s0 false values, +respectively. You can also use \f(CW\*(C`\e1\*(C'\fR and \f(CW\*(C`\e0\*(C'\fR directly if you want. +.Sp +JSON::null returns \f(CW\*(C`undef\*(C'\fR. +.IP "blessed objects" 4 +.IX Item "blessed objects" +Blessed objects are not directly representable in \s-1JSON\s0. See the +\&\f(CW\*(C`allow_blessed\*(C'\fR and \f(CW\*(C`convert_blessed\*(C'\fR methods on various options on +how to deal with this: basically, you can choose between throwing an +exception, encoding the reference as if it weren't blessed, or provide +your own serialiser method. +.Sp +With \f(CW\*(C`convert_blessed_universally\*(C'\fR mode, \f(CW\*(C`encode\*(C'\fR converts blessed +hash references or blessed array references (contains other blessed references) +into \s-1JSON\s0 members and arrays. +.Sp +.Vb 2 +\& use JSON \-convert_blessed_universally; +\& JSON\->new\->allow_blessed\->convert_blessed\->encode( $blessed_object ); +.Ve +.Sp +See to convert_blessed. +.IP "simple scalars" 4 +.IX Item "simple scalars" +Simple Perl scalars (any scalar that is not a reference) are the most +difficult objects to encode: \s-1JSON::XS\s0 and \s-1JSON::PP\s0 will encode undefined scalars as +\&\s-1JSON\s0 \f(CW\*(C`null\*(C'\fR values, scalars that have last been used in a string context +before encoding as \s-1JSON\s0 strings, and anything else as number value: +.Sp +.Vb 4 +\& # dump as number +\& encode_json [2] # yields [2] +\& encode_json [\-3.0e17] # yields [\-3e+17] +\& my $value = 5; encode_json [$value] # yields [5] +\& +\& # used as string, so dump as string +\& print $value; +\& encode_json [$value] # yields ["5"] +\& +\& # undef becomes null +\& encode_json [undef] # yields [null] +.Ve +.Sp +You can force the type to be a string by stringifying it: +.Sp +.Vb 4 +\& my $x = 3.1; # some variable containing a number +\& "$x"; # stringified +\& $x .= ""; # another, more awkward way to stringify +\& print $x; # perl does it for you, too, quite often +.Ve +.Sp +You can force the type to be a number by numifying it: +.Sp +.Vb 3 +\& my $x = "3"; # some variable containing a string +\& $x += 0; # numify it, ensuring it will be dumped as a number +\& $x *= 1; # same thing, the choice is yours. +.Ve +.Sp +You can not currently force the type in other, less obscure, ways. +.Sp +Note that numerical precision has the same meaning as under Perl (so +binary to decimal conversion follows the same rules as in Perl, which +can differ to other languages). Also, your perl interpreter might expose +extensions to the floating point numbers of your platform, such as +infinities or NaN's \- these cannot be represented in \s-1JSON\s0, and it is an +error to pass those in. +.IP "Big Number" 4 +.IX Item "Big Number" +If the backend is \s-1JSON::PP\s0 and \f(CW\*(C`allow_bignum\*(C'\fR is enable, +\&\f(CW\*(C`encode\*(C'\fR converts \f(CW\*(C`Math::BigInt\*(C'\fR objects and \f(CW\*(C`Math::BigFloat\*(C'\fR +objects into \s-1JSON\s0 numbers. +.SH "JSON and ECMAscript" +.IX Header "JSON and ECMAscript" +See to \*(L"\s-1JSON\s0 and ECMAscript\*(R" in \s-1JSON::XS\s0. +.SH "JSON and YAML" +.IX Header "JSON and YAML" +\&\s-1JSON\s0 is not a subset of \s-1YAML\s0. +See to \*(L"\s-1JSON\s0 and \s-1YAML\s0\*(R" in \s-1JSON::XS\s0. +.SH "BACKEND MODULE DECISION" +.IX Header "BACKEND MODULE DECISION" +When you use \f(CW\*(C`JSON\*(C'\fR, \f(CW\*(C`JSON\*(C'\fR tries to \f(CW\*(C`use\*(C'\fR \s-1JSON::XS\s0. If this call failed, it will +\&\f(CW\*(C`uses\*(C'\fR \s-1JSON::PP\s0. The required \s-1JSON::XS\s0 version is \fI2.2\fR or later. +.PP +The \f(CW\*(C`JSON\*(C'\fR constructor method returns an object inherited from the backend module, +and \s-1JSON::XS\s0 object is a blessed scalar reference while \s-1JSON::PP\s0 is a blessed hash +reference. +.PP +So, your program should not depend on the backend module, especially +returned objects should not be modified. +.PP +.Vb 2 +\& my $json = JSON\->new; # XS or PP? +\& $json\->{stash} = \*(Aqthis is xs object\*(Aq; # this code may raise an error! +.Ve +.PP +To check the backend module, there are some methods \- \f(CW\*(C`backend\*(C'\fR, \f(CW\*(C`is_pp\*(C'\fR and \f(CW\*(C`is_xs\*(C'\fR. +.PP +.Vb 1 +\& JSON\->backend; # \*(AqJSON::XS\*(Aq or \*(AqJSON::PP\*(Aq +\& +\& JSON\->backend\->is_pp: # 0 or 1 +\& +\& JSON\->backend\->is_xs: # 1 or 0 +\& +\& $json\->is_xs; # 1 or 0 +\& +\& $json\->is_pp; # 0 or 1 +.Ve +.PP +If you set an environment variable \f(CW\*(C`PERL_JSON_BACKEND\*(C'\fR, the calling action will be changed. +.IP "\s-1PERL_JSON_BACKEND\s0 = 0 or \s-1PERL_JSON_BACKEND\s0 = '\s-1JSON::PP\s0'" 4 +.IX Item "PERL_JSON_BACKEND = 0 or PERL_JSON_BACKEND = 'JSON::PP'" +Always use \s-1JSON::PP\s0 +.IP "\s-1PERL_JSON_BACKEND\s0 == 1 or \s-1PERL_JSON_BACKEND\s0 = '\s-1JSON::XS\s0,JSON::PP'" 4 +.IX Item "PERL_JSON_BACKEND == 1 or PERL_JSON_BACKEND = 'JSON::XS,JSON::PP'" +(The default) Use compiled \s-1JSON::XS\s0 if it is properly compiled & installed, +otherwise use \s-1JSON::PP\s0. +.IP "\s-1PERL_JSON_BACKEND\s0 == 2 or \s-1PERL_JSON_BACKEND\s0 = '\s-1JSON::XS\s0'" 4 +.IX Item "PERL_JSON_BACKEND == 2 or PERL_JSON_BACKEND = 'JSON::XS'" +Always use compiled \s-1JSON::XS\s0, die if it isn't properly compiled & installed. +.IP "\s-1PERL_JSON_BACKEND\s0 = 'JSON::backportPP'" 4 +.IX Item "PERL_JSON_BACKEND = 'JSON::backportPP'" +Always use JSON::backportPP. +JSON::backportPP is \s-1JSON::PP\s0 back port module. +\&\f(CW\*(C`JSON\*(C'\fR includes JSON::backportPP instead of \s-1JSON::PP\s0. +.PP +These ideas come from DBI::PurePerl mechanism. +.PP +example: +.PP +.Vb 2 +\& BEGIN { $ENV{PERL_JSON_BACKEND} = \*(AqJSON::PP\*(Aq } +\& use JSON; # always uses JSON::PP +.Ve +.PP +In future, it may be able to specify another module. +.SH "USE PP FEATURES EVEN THOUGH XS BACKEND" +.IX Header "USE PP FEATURES EVEN THOUGH XS BACKEND" +Many methods are available with either \s-1JSON::XS\s0 or \s-1JSON::PP\s0 and +when the backend module is \s-1JSON::XS\s0, if any \s-1JSON::PP\s0 specific (i.e. \s-1JSON::XS\s0 unsupported) +method is called, it will \f(CW\*(C`warn\*(C'\fR and be noop. +.PP +But If you \f(CW\*(C`use\*(C'\fR \f(CW\*(C`JSON\*(C'\fR passing the optional string \f(CW\*(C`\-support_by_pp\*(C'\fR, +it makes a part of those unsupported methods available. +This feature is achieved by using \s-1JSON::PP\s0 in \f(CW\*(C`de/encode\*(C'\fR. +.PP +.Vb 4 +\& BEGIN { $ENV{PERL_JSON_BACKEND} = 2 } # with JSON::XS +\& use JSON \-support_by_pp; +\& my $json = JSON\->new; +\& $json\->allow_nonref\->escape_slash\->encode("/"); +.Ve +.PP +At this time, the returned object is a \f(CW\*(C`JSON::Backend::XS::Supportable\*(C'\fR +object (re-blessed \s-1XS\s0 object), and by checking \s-1JSON::XS\s0 unsupported flags +in de/encoding, can support some unsupported methods \- \f(CW\*(C`loose\*(C'\fR, \f(CW\*(C`allow_bignum\*(C'\fR, +\&\f(CW\*(C`allow_barekey\*(C'\fR, \f(CW\*(C`allow_singlequote\*(C'\fR, \f(CW\*(C`escape_slash\*(C'\fR and \f(CW\*(C`indent_length\*(C'\fR. +.PP +When any unsupported methods are not enable, \f(CW\*(C`XS de/encode\*(C'\fR will be +used as is. The switch is achieved by changing the symbolic tables. +.PP +\&\f(CW\*(C`\-support_by_pp\*(C'\fR is effective only when the backend module is \s-1JSON::XS\s0 +and it makes the de/encoding speed down a bit. +.PP +See to \*(L"\s-1JSON::PP\s0 \s-1SUPPORT\s0 \s-1METHODS\s0\*(R". +.SH "INCOMPATIBLE CHANGES TO OLD VERSION" +.IX Header "INCOMPATIBLE CHANGES TO OLD VERSION" +There are big incompatibility between new version (2.00) and old (1.xx). +If you use old \f(CW\*(C`JSON\*(C'\fR 1.xx in your code, please check it. +.PP +See to \*(L"Transition ways from 1.xx to 2.xx.\*(R" +.IP "jsonToObj and objToJson are obsoleted." 4 +.IX Item "jsonToObj and objToJson are obsoleted." +Non Perl-style name \f(CW\*(C`jsonToObj\*(C'\fR and \f(CW\*(C`objToJson\*(C'\fR are obsoleted +(but not yet deleted from the source). +If you use these functions in your code, please replace them +with \f(CW\*(C`from_json\*(C'\fR and \f(CW\*(C`to_json\*(C'\fR. +.IP "Global variables are no longer available." 4 +.IX Item "Global variables are no longer available." +\&\f(CW\*(C`JSON\*(C'\fR class variables \- \f(CW$JSON::AUTOCONVERT\fR, \f(CW$JSON::BareKey\fR, etc... +\&\- are not available any longer. +Instead, various features can be used through object methods. +.IP "Package JSON::Converter and JSON::Parser are deleted." 4 +.IX Item "Package JSON::Converter and JSON::Parser are deleted." +Now \f(CW\*(C`JSON\*(C'\fR bundles with \s-1JSON::PP\s0 which can handle \s-1JSON\s0 more properly than them. +.IP "Package JSON::NotString is deleted." 4 +.IX Item "Package JSON::NotString is deleted." +There was \f(CW\*(C`JSON::NotString\*(C'\fR class which represents \s-1JSON\s0 value \f(CW\*(C`true\*(C'\fR, \f(CW\*(C`false\*(C'\fR, \f(CW\*(C`null\*(C'\fR +and numbers. It was deleted and replaced by \f(CW\*(C`JSON::Boolean\*(C'\fR. +.Sp +\&\f(CW\*(C`JSON::Boolean\*(C'\fR represents \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR. +.Sp +\&\f(CW\*(C`JSON::Boolean\*(C'\fR does not represent \f(CW\*(C`null\*(C'\fR. +.Sp +\&\f(CW\*(C`JSON::null\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR. +.Sp +\&\f(CW\*(C`JSON\*(C'\fR makes JSON::XS::Boolean and JSON::PP::Boolean is-a relation +to JSON::Boolean. +.IP "function JSON::Number is obsoleted." 4 +.IX Item "function JSON::Number is obsoleted." +\&\f(CW\*(C`JSON::Number\*(C'\fR is now needless because \s-1JSON::XS\s0 and \s-1JSON::PP\s0 have +round-trip integrity. +.IP "\s-1JSONRPC\s0 modules are deleted." 4 +.IX Item "JSONRPC modules are deleted." +Perl implementation of JSON-RPC protocol \- \f(CW\*(C`JSONRPC \*(C'\fR, \f(CW\*(C`JSONRPC::Transport::HTTP\*(C'\fR +and \f(CW\*(C`Apache::JSONRPC \*(C'\fR are deleted in this distribution. +Instead of them, there is \s-1JSON::RPC\s0 which supports JSON-RPC protocol version 1.1. +.SS "Transition ways from 1.xx to 2.xx." +.IX Subsection "Transition ways from 1.xx to 2.xx." +You should set \f(CW\*(C`suport_by_pp\*(C'\fR mode firstly, because +it is always successful for the below codes even with \s-1JSON::XS\s0. +.PP +.Vb 1 +\& use JSON \-support_by_pp; +.Ve +.IP "Exported jsonToObj (simple)" 4 +.IX Item "Exported jsonToObj (simple)" +.Vb 1 +\& from_json($json_text); +.Ve +.IP "Exported objToJson (simple)" 4 +.IX Item "Exported objToJson (simple)" +.Vb 1 +\& to_json($perl_scalar); +.Ve +.IP "Exported jsonToObj (advanced)" 4 +.IX Item "Exported jsonToObj (advanced)" +.Vb 2 +\& $flags = {allow_barekey => 1, allow_singlequote => 1}; +\& from_json($json_text, $flags); +.Ve +.Sp +equivalent to: +.Sp +.Vb 3 +\& $JSON::BareKey = 1; +\& $JSON::QuotApos = 1; +\& jsonToObj($json_text); +.Ve +.IP "Exported objToJson (advanced)" 4 +.IX Item "Exported objToJson (advanced)" +.Vb 2 +\& $flags = {allow_blessed => 1, allow_barekey => 1}; +\& to_json($perl_scalar, $flags); +.Ve +.Sp +equivalent to: +.Sp +.Vb 2 +\& $JSON::BareKey = 1; +\& objToJson($perl_scalar); +.Ve +.IP "jsonToObj as object method" 4 +.IX Item "jsonToObj as object method" +.Vb 1 +\& $json\->decode($json_text); +.Ve +.IP "objToJson as object method" 4 +.IX Item "objToJson as object method" +.Vb 1 +\& $json\->encode($perl_scalar); +.Ve +.IP "new method with parameters" 4 +.IX Item "new method with parameters" +The \f(CW\*(C`new\*(C'\fR method in 2.x takes any parameters no longer. +You can set parameters instead; +.Sp +.Vb 1 +\& $json = JSON\->new\->pretty; +.Ve +.ie n .IP "$JSON::Pretty, $JSON::Indent, $JSON::Delimiter" 4 +.el .IP "\f(CW$JSON::Pretty\fR, \f(CW$JSON::Indent\fR, \f(CW$JSON::Delimiter\fR" 4 +.IX Item "$JSON::Pretty, $JSON::Indent, $JSON::Delimiter" +If \f(CW\*(C`indent\*(C'\fR is enable, that means \f(CW$JSON::Pretty\fR flag set. And +\&\f(CW$JSON::Delimiter\fR was substituted by \f(CW\*(C`space_before\*(C'\fR and \f(CW\*(C`space_after\*(C'\fR. +In conclusion: +.Sp +.Vb 1 +\& $json\->indent\->space_before\->space_after; +.Ve +.Sp +Equivalent to: +.Sp +.Vb 1 +\& $json\->pretty; +.Ve +.Sp +To change indent length, use \f(CW\*(C`indent_length\*(C'\fR. +.Sp +(Only with \s-1JSON::PP\s0, if \f(CW\*(C`\-support_by_pp\*(C'\fR is not used.) +.Sp +.Vb 1 +\& $json\->pretty\->indent_length(2)\->encode($perl_scalar); +.Ve +.ie n .IP "$JSON::BareKey" 4 +.el .IP "\f(CW$JSON::BareKey\fR" 4 +.IX Item "$JSON::BareKey" +(Only with \s-1JSON::PP\s0, if \f(CW\*(C`\-support_by_pp\*(C'\fR is not used.) +.Sp +.Vb 1 +\& $json\->allow_barekey\->decode($json_text) +.Ve +.ie n .IP "$JSON::ConvBlessed" 4 +.el .IP "\f(CW$JSON::ConvBlessed\fR" 4 +.IX Item "$JSON::ConvBlessed" +use \f(CW\*(C`\-convert_blessed_universally\*(C'\fR. See to convert_blessed. +.ie n .IP "$JSON::QuotApos" 4 +.el .IP "\f(CW$JSON::QuotApos\fR" 4 +.IX Item "$JSON::QuotApos" +(Only with \s-1JSON::PP\s0, if \f(CW\*(C`\-support_by_pp\*(C'\fR is not used.) +.Sp +.Vb 1 +\& $json\->allow_singlequote\->decode($json_text) +.Ve +.ie n .IP "$JSON::SingleQuote" 4 +.el .IP "\f(CW$JSON::SingleQuote\fR" 4 +.IX Item "$JSON::SingleQuote" +Disable. \f(CW\*(C`JSON\*(C'\fR does not make such a invalid \s-1JSON\s0 string any longer. +.ie n .IP "$JSON::KeySort" 4 +.el .IP "\f(CW$JSON::KeySort\fR" 4 +.IX Item "$JSON::KeySort" +.Vb 1 +\& $json\->canonical\->encode($perl_scalar) +.Ve +.Sp +This is the ascii sort. +.Sp +If you want to use with your own sort routine, check the \f(CW\*(C`sort_by\*(C'\fR method. +.Sp +(Only with \s-1JSON::PP\s0, even if \f(CW\*(C`\-support_by_pp\*(C'\fR is used currently.) +.Sp +.Vb 1 +\& $json\->sort_by($sort_routine_ref)\->encode($perl_scalar) +\& +\& $json\->sort_by(sub { $JSON::PP::a <=> $JSON::PP::b })\->encode($perl_scalar) +.Ve +.Sp +Can't access \f(CW$a\fR and \f(CW$b\fR but \f(CW$JSON::PP::a\fR and \f(CW$JSON::PP::b\fR. +.ie n .IP "$JSON::SkipInvalid" 4 +.el .IP "\f(CW$JSON::SkipInvalid\fR" 4 +.IX Item "$JSON::SkipInvalid" +.Vb 1 +\& $json\->allow_unknown +.Ve +.ie n .IP "$JSON::AUTOCONVERT" 4 +.el .IP "\f(CW$JSON::AUTOCONVERT\fR" 4 +.IX Item "$JSON::AUTOCONVERT" +Needless. \f(CW\*(C`JSON\*(C'\fR backend modules have the round-trip integrity. +.ie n .IP "$JSON::UTF8" 4 +.el .IP "\f(CW$JSON::UTF8\fR" 4 +.IX Item "$JSON::UTF8" +Needless because \f(CW\*(C`JSON\*(C'\fR (\s-1JSON::XS/JSON::PP\s0) sets +the \s-1UTF8\s0 flag on properly. +.Sp +.Vb 1 +\& # With UTF8\-flagged strings +\& +\& $json\->allow_nonref; +\& $str = chr(1000); # UTF8\-flagged +\& +\& $json_text = $json\->utf8(0)\->encode($str); +\& utf8::is_utf8($json_text); +\& # true +\& $json_text = $json\->utf8(1)\->encode($str); +\& utf8::is_utf8($json_text); +\& # false +\& +\& $str = \*(Aq"\*(Aq . chr(1000) . \*(Aq"\*(Aq; # UTF8\-flagged +\& +\& $perl_scalar = $json\->utf8(0)\->decode($str); +\& utf8::is_utf8($perl_scalar); +\& # true +\& $perl_scalar = $json\->utf8(1)\->decode($str); +\& # died because of \*(AqWide character in subroutine\*(Aq +.Ve +.Sp +See to \*(L"A \s-1FEW\s0 \s-1NOTES\s0 \s-1ON\s0 \s-1UNICODE\s0 \s-1AND\s0 \s-1PERL\s0\*(R" in \s-1JSON::XS\s0. +.ie n .IP "$JSON::UnMapping" 4 +.el .IP "\f(CW$JSON::UnMapping\fR" 4 +.IX Item "$JSON::UnMapping" +Disable. See to \s-1MAPPING\s0. +.ie n .IP "$JSON::SelfConvert" 4 +.el .IP "\f(CW$JSON::SelfConvert\fR" 4 +.IX Item "$JSON::SelfConvert" +This option was deleted. +Instead of it, if a given blessed object has the \f(CW\*(C`TO_JSON\*(C'\fR method, +\&\f(CW\*(C`TO_JSON\*(C'\fR will be executed with \f(CW\*(C`convert_blessed\*(C'\fR. +.Sp +.Vb 2 +\& $json\->convert_blessed\->encode($blessed_hashref_or_arrayref) +\& # if need, call allow_blessed +.Ve +.Sp +Note that it was \f(CW\*(C`toJson\*(C'\fR in old version, but now not \f(CW\*(C`toJson\*(C'\fR but \f(CW\*(C`TO_JSON\*(C'\fR. +.SH "TODO" +.IX Header "TODO" +.IP "example programs" 4 +.IX Item "example programs" +.SH "THREADS" +.IX Header "THREADS" +No test with \s-1JSON::PP\s0. If with \s-1JSON::XS\s0, See to \*(L"\s-1THREADS\s0\*(R" in \s-1JSON::XS\s0. +.SH "BUGS" +.IX Header "BUGS" +Please report bugs relevant to \f(CW\*(C`JSON\*(C'\fR to <makamaka[at]cpan.org>. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Most of the document is copied and modified from \s-1JSON::XS\s0 doc. +.PP +\&\s-1JSON::XS\s0, \s-1JSON::PP\s0 +.PP +\&\f(CW\*(C`RFC4627\*(C'\fR(<http://www.ietf.org/rfc/rfc4627.txt>) +.SH "AUTHOR" +.IX Header "AUTHOR" +Makamaka Hannyaharamitu, <makamaka[at]cpan.org> +.PP +\&\s-1JSON::XS\s0 was written by Marc Lehmann <schmorp[at]schmorp.de> +.PP +The release of this new version owes to the courtesy of Marc Lehmann. +.SH "COPYRIGHT AND LICENSE" +.IX Header "COPYRIGHT AND LICENSE" +Copyright 2005\-2013 by Makamaka Hannyaharamitu +.PP +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. |