JSON::XS#

📦 std

Encode Perl data as JSON text and decode JSON text into Perl data, in compiled code.

encode_json and decode_json convert between a Perl structure and UTF-8 encoded JSON. An object made with JSON::XS->new takes options

  • utf8, pretty, canonical, relaxed, allow_nonref, convert_blessed, allow_tags, max_depth, max_size, filter callbacks - and parses incrementally from a stream with incr_parse. JSON true and false decode to Types::Serialiser’s booleans.

This is a native implementation of JSON::XS 4.04’s XS.xs; its JSON/XS.pm is used unchanged.

Synopsis#

use JSON::XS;

my $text = encode_json { name => "caf\x{e9}", list => [1, 2.5, "x"] };
my $data = decode_json '{"a":[1,true,null]}';

my $json = JSON::XS->new->pretty->canonical;
print $json->encode($data);

$json->incr_parse('[1,2');
$json->incr_parse(',3]');
my $array = $json->incr_parse;           # [1, 2, 3]

Differences from upstream#

  • A method called on something blessed into JSON::XS that JSON::XS->new did not make - a hash, an array, a short string - dies “object is not of type JSON::XS”; perl crashes.

  • After JSON::XS::CLONE has been called by hand, new and the decoding of true and false work as they do in a perl built with threads; a perl without threads crashes.

Modules#

Functions#

Data serialisation#

new#

A new encoder/decoder with the defaults: allow_nonref on, a maximum depth of 512, everything else off.

Synopsis

my $json = JSON::XS->new->utf8->canonical;

What you get back

An object blessed into the class it was called on, whose option methods return it again, so that they chain.

allow_blessed#

The option setters: ascii, latin1, utf8, indent, canonical, space_before, space_after, pretty, allow_nonref, shrink, allow_blessed, convert_blessed, relaxed, allow_unknown and allow_tags.

Also available as JSON::XS::allow_nonref, JSON::XS::allow_tags, JSON::XS::allow_unknown, JSON::XS::ascii, JSON::XS::canonical, JSON::XS::convert_blessed, JSON::XS::indent, JSON::XS::latin1, JSON::XS::pretty, JSON::XS::relaxed, JSON::XS::shrink, JSON::XS::space_after, JSON::XS::space_before, JSON::XS::utf8.

get_allow_blessed#

The option getters: get_ascii, get_utf8, get_canonical and the others of each setter but pretty.

Also available as JSON::XS::get_allow_nonref, JSON::XS::get_allow_tags, JSON::XS::get_allow_unknown, JSON::XS::get_ascii, JSON::XS::get_canonical, JSON::XS::get_convert_blessed, JSON::XS::get_indent, JSON::XS::get_latin1, JSON::XS::get_relaxed, JSON::XS::get_shrink, JSON::XS::get_space_after, JSON::XS::get_space_before, JSON::XS::get_utf8.

Synopsis

print JSON::XS->new->get_allow_nonref ? "on\n" : "off\n";   # on

What you get back

True when the option is on, false otherwise.

encode#

Perl data to JSON text, with this object’s options.

decode#

JSON text to Perl data, with this object’s options.

decode_prefix#

Decode the JSON text at the start of a string.

incr_parse#

Parse JSON texts as they arrive, a piece at a time.

encode_json#

Perl data to UTF-8 encoded JSON text.

Synopsis

use JSON::XS;
my $bytes = encode_json { name => "caf\x{e9}" };   # {"name":"caf\xc3\xa9"}

What you get back

The JSON text as UTF-8 bytes: JSON::XS->new->utf8->encode($data).

decode_json#

UTF-8 encoded JSON text to Perl data.