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