<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from JSON/XS.rs. Do not edit. -->

```{index} single: JSON::XS
```

# JSON::XS

```{pperl-module-badges} JSON::XS
```

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

```perl
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

- [`JSON::XS::Boolean`](XS/Boolean.md) - dummy module providing JSON::XS::Boolean

## Functions

### Data serialisation

#### `new`

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

**Synopsis**

```perl
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`](XS/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**

```perl
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`](XS/encode)

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

#### [`decode`](XS/decode)

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

#### [`decode_prefix`](XS/decode_prefix)

Decode the JSON text at the start of a string.

#### [`incr_parse`](XS/incr_parse)

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

#### `encode_json`

Perl data to UTF-8 encoded JSON text.

**Synopsis**

```perl
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`](XS/decode_json)

UTF-8 encoded JSON text to Perl data.

```{toctree}
:hidden:
:maxdepth: 1

XS/Boolean
XS/allow_blessed
XS/encode
XS/decode
XS/decode_prefix
XS/incr_parse
XS/decode_json
```