NAME

JSON::Functions::XS - Easy-to-use functional JSON-Perl convertions

SYNOPSIS

use JSON::Functions::XS qw(json_bytes2perl perl2json_bytes);

print perl2json_bytes $obj;
print json_bytes2perl $json;

DESCRIPTION

The JSON::Functions::XS module provides various useful functions to decode or encode JSON data. These functions are wrappers; actual conversion is enforced by the JSON::XS module.

Strictly speaking, JSON::Functions::XS is not just a wrapper for JSON::XS, but it adds some modifications to improve interoperability, namely:

- Support for scalar literal values

According to ECMA-404 JSON specification, a number, string, boolean, or null value can be recognized as valid input.

- Silent error recovery from fatal errors

In many use cases of JSON parsing, the application don't have to know what is exatly wrong with the JSON input but rather the entire operation should not die just because the input is invalid. In such an application, ill-formed input is as bad as wrongly-constructed well-formed JSON data, such that it has to check the result data structure anyway to be error tolerant. Therefore this module does not raise when the input is invalid. If you'd like to distinguish parse errors from application-dependent structural errors, this module would not be a choice for you.

- Avoiding HTML XSS

To prevent from HTML XSS attacks when the JSON output is poorly-labelled, or for legacy-browser users, this module replaces < characters in JSON output into its escaped form.

- Avoiding UTF-7 XSS

To avoid UTF-7 XSS attacks for legacy-browser users, this module replaces + characters in JSON output into its escaped form.

- JavaScript/JSONP compatbility

To improve JavaScript/JSONP compatibility, this module replaces U+2028 and U+2029 characters in JSON output, which are not allowed in JavaScript string literals, into their escaped forms.

FUNCTIONS

Functions are exposed by default. Instead, you can specify one or more functions to use after the module name:

use JSON::Functions::XS qw(json_bytes2perl json_chars2perl);

$perl_obj = json_bytes2perl $json_byte_string

Converts a JSON data represented as a byte string encoded in utf8 into Perl data structure.

$perl_obj = json_chars2perl $json_char_string

Converts a JSON data represented as a character string into Perl data structure.

$perl_obj = file2perl $path_class_file

Converts a JSON contained in a file encoded in utf8 specified by the Path::Class::File object into Perl data structure.

$json_byte_string = perl2json_bytes $perl_obj

Converts a Perl data into JSON represented as a byte string encoded in utf8.

$json_byte_string = perl2json_bytes_for_record $perl_obj

Converts a Perl data into JSON represented as a byte string encoded in utf8, pretty-printed.

$json_char_string = perl2json_chars $perl_obj

Converts a Perl data into JSON represented as a character string.

$json_char_string = perl2json_chars_for_record $perl_obj

Converts a Perl data into JSON represented as a character string, pretty-printed.

DEPENDENCY

The module requires Perl 5.14 or later and modules JSON::XS and Encode.

SEE ALSO

ECMA-404 The JSON Data Interchange Format <http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf>.

JSON::PS <https://github.com/wakaba/perl-json-ps> - A pure Perl JSON/Perl convertion functions, whose API is fully compatible with this module.

AUTHOR

Wakaba <[email protected]>.

HISTORY

This repository was located at <https://github.com/wakaba/perl-json-functions-xs> until 18 April 2023, then transferred to <https://github.com/pawjy/perl-json-functions-xs>.

LICENSE

Copyright 2009-2011 Hatena <https://www.hatena.ne.jp/>.

Copyright 2012-2016 Wakaba <[email protected]>.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.