diff options
Diffstat (limited to 'chromium/third_party/JSON/JSON-2.59/blib/man3/JSON__backportPP.3pm')
-rw-r--r-- | chromium/third_party/JSON/JSON-2.59/blib/man3/JSON__backportPP.3pm | 1379 |
1 files changed, 0 insertions, 1379 deletions
diff --git a/chromium/third_party/JSON/JSON-2.59/blib/man3/JSON__backportPP.3pm b/chromium/third_party/JSON/JSON-2.59/blib/man3/JSON__backportPP.3pm deleted file mode 100644 index 60015fbcf00..00000000000 --- a/chromium/third_party/JSON/JSON-2.59/blib/man3/JSON__backportPP.3pm +++ /dev/null @@ -1,1379 +0,0 @@ -.\" 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::backportPP 3pm" -.TH JSON::backportPP 3pm "2013-05-23" "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::PP \- JSON::XS compatible pure\-Perl module. -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& use JSON::PP; -\& -\& # exported functions, they croak on error -\& # and expect/generate UTF\-8 -\& -\& $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; -\& $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; -\& -\& # OO\-interface -\& -\& $coder = JSON::PP\->new\->ascii\->pretty\->allow_nonref; -\& -\& $json_text = $json\->encode( $perl_scalar ); -\& $perl_scalar = $json\->decode( $json_text ); -\& -\& $pretty_printed = $json\->pretty\->encode( $perl_scalar ); # pretty\-printing -\& -\& # Note that JSON version 2.0 and above will automatically use -\& # JSON::XS or JSON::PP, so you should be able to just: -\& -\& use JSON; -.Ve -.SH "VERSION" -.IX Header "VERSION" -.Vb 1 -\& 2.27200 -.Ve -.PP -\&\s-1JSON::XS\s0 2.27 (~2.30) compatible. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -This module is \s-1JSON::XS\s0 compatible pure Perl module. -(Perl 5.8 or later is recommended) -.PP -\&\s-1JSON::XS\s0 is the fastest and most proper \s-1JSON\s0 module on \s-1CPAN\s0. -It is written by Marc Lehmann in C, so must be compiled and -installed in the used environment. -.PP -\&\s-1JSON::PP\s0 is a pure-Perl module and has compatibility to \s-1JSON::XS\s0. -.SS "\s-1FEATURES\s0" -.IX Subsection "FEATURES" -.IP "\(bu" 4 -correct unicode handling -.Sp -This module knows how to handle Unicode (depending on Perl version). -.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 and -\&\*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R". -.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 \s-1MAPPING\s0 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). But when some options are set, loose checking -features are available. -.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. -.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::PP\->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::PP\->new\->utf8\->decode($json_text) -.Ve -.SS "JSON::PP::is_bool" -.IX Subsection "JSON::PP::is_bool" -.Vb 1 -\& $is_boolean = JSON::PP::is_bool($scalar) -.Ve -.PP -Returns true if the passed scalar represents either JSON::PP::true or -JSON::PP::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::PP::true" -.IX Subsection "JSON::PP::true" -Returns \s-1JSON\s0 true value which is blessed object. -It \f(CW\*(C`isa\*(C'\fR JSON::PP::Boolean object. -.SS "JSON::PP::false" -.IX Subsection "JSON::PP::false" -Returns \s-1JSON\s0 false value which is blessed object. -It \f(CW\*(C`isa\*(C'\fR JSON::PP::Boolean object. -.SS "JSON::PP::null" -.IX Subsection "JSON::PP::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::PP\->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. -.PP -.Vb 1 -\& $perl_scalar = $json\->utf8(0)\->decode( $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. -Note that the resulted text is a \s-1UNICODE\s0 string but no problem to print it. -.PP -.Vb 4 -\& # $perl_scalar contains $encoding encoded string values -\& $unicode_json_text = $json\->utf8(0)\->encode( $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 "METHODS" -.IX Header "METHODS" -Basically, check to \s-1JSON\s0 or \s-1JSON::XS\s0. -.SS "new" -.IX Subsection "new" -.Vb 1 -\& $json = JSON::PP\->new -.Ve -.PP -Returns a new \s-1JSON::PP\s0 object 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::PP\->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. -(See to \*(L"OBJECT-ORIENTED \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0). -.PP -In Perl 5.005, there is no character having high value (more than 255). -See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R". -.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 -.Vb 2 -\& JSON::PP\->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::XS\->new\->latin1\->encode (["\ex{89}\ex{abc}"] -\& => ["\ex{89}\e\eu0abc"] # (perl syntax, U+abc escaped, U+89 not) -.Ve -.PP -See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R". -.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 Perl 5.005, any character outside the range 0..255 does not exist. -See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R".) -.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::PP\->new\->encode ($object); -.Ve -.PP -Example, decode UTF\-32LE\-encoded \s-1JSON:\s0 -.PP -.Vb 2 -\& use Encode; -\& $object = JSON::PP\->new\->decode (decode "UTF\-32LE", $jsontext); -.Ve -.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 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 -.SS "indent" -.IX Subsection "indent" -.Vb 1 -\& $json = $json\->indent([$enable]) -\& -\& $enabled = $json\->get_indent -.Ve -.PP -The default indent space length is three. -You can use \f(CW\*(C`indent_length\*(C'\fR to change the 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. -.PP -If you want your own sorting routine, you can give a code reference -or a subroutine name to \f(CW\*(C`sort_by\*(C'\fR. See to \f(CW\*(C`JSON::PP OWN METHODS\*(C'\fR. -.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::PP\->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. -.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::PP\->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::PP -\& \->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 -In \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. -It will also try to downgrade any strings to octet-form if possible. -.PP -In \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 -.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 -See \*(L"\s-1SSECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0 for more info on why this is useful. -.PP -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. -.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 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 -.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 -This 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 OWN METHODS" -.IX Header "JSON::PP OWN METHODS" -.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 -\&\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 \*(L"\s-1MAPPING\s0\*(R" in \s-1JSON::XS\s0 about the normal 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 \*(L"\s-1SSECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\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 default -\&\s-1JSON::PP\s0 (as same as \s-1JSON::XS\s0) encodes 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 -\&\s-1JSON::XS\s0 indent space length is 3 and cannot be changed. -\&\s-1JSON::PP\s0 set 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 -in encoding \s-1JSON\s0 objects. -.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 -\&'\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. -.SH "INTERNAL" -.IX Header "INTERNAL" -For developers. -.IP "PP_encode_box" 4 -.IX Item "PP_encode_box" -Returns -.Sp -.Vb 4 -\& { -\& depth => $depth, -\& indent_count => $indent_count, -\& } -.Ve -.IP "PP_decode_box" 4 -.IX Item "PP_decode_box" -Returns -.Sp -.Vb 9 -\& { -\& text => $text, -\& at => $at, -\& ch => $ch, -\& len => $len, -\& depth => $depth, -\& encoding => $encoding, -\& is_valid_utf8 => $is_valid_utf8, -\& }; -.Ve -.SH "MAPPING" -.IX Header "MAPPING" -This section is copied from \s-1JSON::XS\s0 and modified to \f(CW\*(C`JSON::PP\*(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 -When \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::PP::true\*(C'\fR and \f(CW\*(C`JSON::PP::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 -.Vb 4 -\& print JSON::PP::true . "\en"; -\& => true -\& print JSON::PP::true + 1; -\& => 1 -\& -\& 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::PP::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. -.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::PP::true] # yields [false,true] -.Ve -.IP "JSON::PP::true, JSON::PP::false, JSON::PP::null" 4 -.IX Item "JSON::PP::true, JSON::PP::false, JSON::PP::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::PP::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 -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" -When \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 "UNICODE HANDLING ON PERLS" -.IX Header "UNICODE HANDLING ON PERLS" -If you do not know about Unicode on Perl well, -please check \*(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. -.SS "Perl 5.8 and later" -.IX Subsection "Perl 5.8 and later" -Perl can handle Unicode and the \s-1JSON::PP\s0 de/encode methods also work properly. -.PP -.Vb 2 -\& $json\->allow_nonref\->encode(chr hex 3042); -\& $json\->allow_nonref\->encode(chr hex 12345); -.Ve -.PP -Returns \f(CW"\eu3042"\fR and \f(CW"\eud808\eudf45"\fR respectively. -.PP -.Vb 2 -\& $json\->allow_nonref\->decode(\*(Aq"\eu3042"\*(Aq); -\& $json\->allow_nonref\->decode(\*(Aq"\eud808\eudf45"\*(Aq); -.Ve -.PP -Returns \s-1UTF\-8\s0 encoded strings with \s-1UTF8\s0 flag, regarded as \f(CW\*(C`U+3042\*(C'\fR and \f(CW\*(C`U+12345\*(C'\fR. -.PP -Note that the versions from Perl 5.8.0 to 5.8.2, Perl built-in \f(CW\*(C`join\*(C'\fR was broken, -so \s-1JSON::PP\s0 wraps the \f(CW\*(C`join\*(C'\fR with a subroutine. Thus \s-1JSON::PP\s0 works slow in the versions. -.SS "Perl 5.6" -.IX Subsection "Perl 5.6" -Perl can handle Unicode and the \s-1JSON::PP\s0 de/encode methods also work. -.SS "Perl 5.005" -.IX Subsection "Perl 5.005" -Perl 5.005 is a byte semantics world \*(-- all strings are sequences of bytes. -That means the unicode handling is not available. -.PP -In encoding, -.PP -.Vb 2 -\& $json\->allow_nonref\->encode(chr hex 3042); # hex 3042 is 12354. -\& $json\->allow_nonref\->encode(chr hex 12345); # hex 12345 is 74565. -.Ve -.PP -Returns \f(CW\*(C`B\*(C'\fR and \f(CW\*(C`E\*(C'\fR, as \f(CW\*(C`chr\*(C'\fR takes a value more than 255, it treats -as \f(CW\*(C`$value % 256\*(C'\fR, so the above codes are equivalent to : -.PP -.Vb 2 -\& $json\->allow_nonref\->encode(chr 66); -\& $json\->allow_nonref\->encode(chr 69); -.Ve -.PP -In decoding, -.PP -.Vb 1 -\& $json\->decode(\*(Aq"\eu00e3\eu0081\eu0082"\*(Aq); -.Ve -.PP -The returned is a byte sequence \f(CW\*(C`0xE3 0x81 0x82\*(C'\fR for \s-1UTF\-8\s0 encoded -japanese character (\f(CW\*(C`HIRAGANA LETTER A\*(C'\fR). -And if it is represented in Unicode code point, \f(CW\*(C`U+3042\*(C'\fR. -.PP -Next, -.PP -.Vb 1 -\& $json\->decode(\*(Aq"\eu3042"\*(Aq); -.Ve -.PP -We ordinary expect the returned value is a Unicode character \f(CW\*(C`U+3042\*(C'\fR. -But here is 5.005 world. This is \f(CW\*(C`0xE3 0x81 0x82\*(C'\fR. -.PP -.Vb 1 -\& $json\->decode(\*(Aq"\eud808\eudf45"\*(Aq); -.Ve -.PP -This is not a character \f(CW\*(C`U+12345\*(C'\fR but bytes \- \f(CW\*(C`0xf0 0x92 0x8d 0x85\*(C'\fR. -.SH "TODO" -.IX Header "TODO" -.IP "speed" 4 -.IX Item "speed" -.PD 0 -.IP "memory saving" 4 -.IX Item "memory saving" -.PD -.SH "SEE ALSO" -.IX Header "SEE ALSO" -Most of the document are copied and modified from \s-1JSON::XS\s0 doc. -.PP -\&\s-1JSON::XS\s0 -.PP -\&\s-1RFC4627\s0 (<http://www.ietf.org/rfc/rfc4627.txt>) -.SH "AUTHOR" -.IX Header "AUTHOR" -Makamaka Hannyaharamitu, <makamaka[at]cpan.org> -.SH "COPYRIGHT AND LICENSE" -.IX Header "COPYRIGHT AND LICENSE" -Copyright 2007\-2012 by Makamaka Hannyaharamitu -.PP -This library is free software; you can redistribute it and/or modify -it under the same terms as Perl itself. |