NAME
JSON::Parse - Convert JSON into a Perl variable
SYNOPSIS
use JSON::Parse 'parse_json';
my $json = '["golden", "fleece"]';
my $perl = parse_json ($json);
# Same effect as $perl = ['golden', 'fleece'];Convert JSON into Perl.
DESCRIPTION
JSON::Parse converts JSON into equivalent Perl. The function "parse_json" takes one argument, a string containing JSON, and returns a Perl reference. The input to parse_json must be a complete JSON structure.
The module differs from the standard JSON module by simplifying the handling of Unicode. If its input is marked as Unicode characters, the strings in its output are also marked as Unicode characters.
JSON::Parse also provides a high speed validation function, "valid_json".
JSON means "JavaScript Object Notation" and it is specified in "RFC 4627".
FUNCTIONS
parse_json
use JSON::Parse 'parse_json';
my $perl = parse_json ('{"x":1, "y":2}');This function converts JSON into a Perl structure, either an array reference or a hash reference.
If the first argument does not contain a valid JSON text, parse_json throws a fatal error. See "DIAGNOSTICS" for the possible error messages.
If the argument contains valid JSON, the return value is either a hash or an array reference. If the input JSON text is a serialized object, a hash reference is returned:
my $perl = parse_json ('{"a":1, "b":2}');
print ref $perl, "\n";
# Prints "HASH".If the input JSON text is a serialized array, an array reference is returned:
my $perl = parse_json ('["a", "b", "c"]');
print ref $perl, "\n";
# Prints "ARRAY".json_file_to_perl
use JSON::Parse 'json_file_to_perl';
my $p = json_file_to_perl ('filename');This is exactly the same as "parse_json" except that it works on a file name. The file must be in UTF-8.
valid_json
use JSON::Parse 'valid_json';
if (valid_json ($json)) {
# do something
}Valid_json returns 1 if its argument is valid JSON and 0 if not.
Mapping from JSON to Perl
JSON elements are mapped to Perl as follows:
JSON numbers
JSON numbers become Perl numbers, either integers or double-precision floating point numbers.
JSON strings
JSON strings become Perl strings. The JSON escape characters such as \t for the tab character (see section 2.5 of "RFC 4627") are mapped to the equivalent ASCII character. Unicode escape characters of the form \uXXXX (see page three of "RFC 4627") are mapped to UTF-8 octets. This is done regardless of what input encoding might be used in the JSON text.
Handling of Unicode
If the input to "parse_json" is marked as Unicode characters, the output strings will be marked as Unicode characters. If the input is not marked as Unicode characters, the output strings will not be marked as Unicode characters. Thus,
# The scalar $sasori looks like Unicode to Perl
use utf8;
my $sasori = '["蠍"]';
my $p = parse_json ($sasori);
print utf8::is_utf8 ($p->[0]);
# Prints 1.but
# The scalar $ebi does not look like Unicode to Perl
no utf8;
my $ebi = '["海老"]';
my $p = parse_json ($ebi);
print utf8::is_utf8 ($p->[0]);
# Prints nothing.JSON arrays
JSON arrays become Perl array references. The elements of the Perl array are in the same order as they appear in the JSON.
Thus
my $p = parse_json ('["monday", "tuesday", "wednesday"]');has the same result as a Perl declaration of the form
my $p = [ 'monday', 'tuesday', 'wednesday' ];JSON objects
JSON objects become Perl hashes. The members of the JSON object become key and value pairs in the Perl hash. The string part of each object member becomes the key of the Perl hash. The value part of each member is mapped to the value of the Perl hash.
Thus
my $j = <<EOF;
{"monday":["blue", "black"],
"tuesday":["grey", "heart attack"],
"friday":"Gotta get down on Friday"}
EOF
my $p = parse_json ($j);has the same result as a Perl declaration of the form
my $p = {
monday => ['blue', 'black'],
tuesday => ['grey', 'heart attack'],
friday => 'Gotta get down on Friday',
};null
The JSON null literal is mapped to a scalar $JSON::Parse::null containing the undefined value.
true
The JSON true literal is mapped to a scalar $JSON::Parse::true containing the value 1.
false
The JSON false literal is mapped to a scalar $JSON::Parse::false containing the value 0.
RESTRICTIONS
This module imposes the following restrictions on its input.
- JSON only
-
JSON::Parse is a strict parser. It only parses JSON which exactly meets the criteria of "RFC 4627". That means, for example, JSON::Parse does not accept single quotes (') instead of double quotes ("), or numbers with leading zeros, like 0123.
- No incremental parsing
-
JSON::Parse does not do incremental parsing. JSON::Parse only parses fully-formed JSON strings which include opening and closing brackets.
- UTF-8 only
-
Although JSON may come in various encodings of Unicode, JSON::Parse only parses the UTF-8 format. If input is in a different Unicode encoding than UTF-8, convert the input before handing it to this module. For example, for the UTF-16 format,
use Encode 'decode'; my $input_utf8 = decode ('UTF-16', $input); my $perl = parse_json ($input_utf8);or, for a file,
open my $input, "<:encoding(UTF-16)", 'some-json-file';This module does not attempt to do the determination of the nature of the octet stream, as described in part 3 of "RFC 4627".
DIAGNOSTICS
"valid_json" does not produce error messages. "parse_json" dies on encountering invalid input.
Error messages have the line number and the byte number of the input which caused the problem.
Parsing errors are fatal, so to continue after an error occurs, put the parsing into an eval block:
my $p;
eval {
$p = parse_json ($j);
};
if ($@) {
# handle error
}SEE ALSO
- RFC 4627
-
JSON is specified in http://www.ietf.org/rfc/rfc4627.txt.
- JSON, JSON::XS
-
These modules allow both reading and writing of JSON.
TEST RESULTS
The ActiveState test results are at http://code.activestate.com/ppm/JSON-Parse/.
EXPORTS
The module exports nothing by default. Functions "parse_json" and "valid_json" can be exported on request.
AUTHOR
Ben Bullock, <bkb@cpan.org>
LICENSE
JSON::Parse can be used, copied, modified and redistributed under the same terms as Perl itself.