| Index: trunk/src/third_party/JSON/JSON-2.59/blib/man3/JSON.3pm
|
| ===================================================================
|
| --- trunk/src/third_party/JSON/JSON-2.59/blib/man3/JSON.3pm (revision 205060)
|
| +++ trunk/src/third_party/JSON/JSON-2.59/blib/man3/JSON.3pm (working copy)
|
| @@ -1,1876 +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 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.
|
|
|
Chromium Code Reviews
Issue 16539003:
Revert 205057 "Add JSON.pm to third_party" (Closed)
Base URL: svn://svn.chromium.org/chrome/