NAME
JSON::Relaxed -- An extension of JSON that allows for better human-readability
Relaxed JSON?
There's been increasing support for the idea of expanding JSON to improve human-readability. "Relaxed" JSON (RJSON) is a term that has been used to describe a JSON-ish format that has some human-friendly features that JSON doesn't. Most notably, RJSON allows the use of JavaScript-like comments and eliminates the need to quote all keys and values. An (official) specification can be found on RelaxedJSON.org.
Note that by definition every valid JSON document is also a valid RJSON document.
SYNOPSIS
use JSON::Relaxed;
# Some raw RJSON data.
my $rjson = <<'RAW_DATA';
/* Javascript-like comments. */
{
// Keys do not require quotes.
// Single, double and backtick quotes.
a : 'Larry',
b : "Curly",
c : `Phoey`,
// Simple values do not require quotes.
d: unquoted
// Nested structures.
e: [
{ a:1, b:2 },
],
// Like Perl, trailing commas are allowed.
f: "more stuff",
}
RAW_DATA
# Functional parsing.
my $hash = decode_rjson($rjson);
# Object-oriented parsing.
my $parser = JSON::Relaxed->new();
$hash = $parser->decode($rjson);
DESCRIPTION
JSON::Relaxed is a lightweight parser and serializer for RJSON. It is fully compliant to the RelaxedJSON.org specification.
It does, however, have some additional extensions to make it even more relaxed.
LEGACY MODE
The old static method from_rjson
has been renamed to decode_rjson
, to conform to many other modules of this kind. For compatibility with pre-0.060 versions from_rjson
is kept as a synonym for decode_rjson
.
For the same reason, the old parser method parse
has been renamed to decode
. For compatibility parse
is kept as a synonym for decode
.
When called by one of the old names, JSON::Relaxed will operate in legacy mode. This changes the way errors are handled.
EXTENSIONS
Extensions are enabled unless the option strict
is set.
- Leading commas in lists are allowed
-
For example,
[ , 1 ]
- Hash keys without values
-
JSON::Relaxed supports object keys without a specified value. In that case the hash element is simply assigned the undefined value.
In the following example, a is assigned 1, and b is assigned undef:
{ a:1, b }
- String continuation
-
Long strings can be split over multiple lines by putting a backslash at the end of the line:
"this is a " \ "long string"
Note that this is different from
"this is a \ long string"
which embeds the newline into the string.
- Extended Unicode escapes
-
Unicode escapes in strings may contain an arbitrary number of hexadecimal digits enclosed in braces:
\u{1d10e}
This eliminates the need to use surrogates to obtain the same character:
\uD834\uDD0E
SUBROUTINES
decode_rjson
$structure = decode_rjson( $data, %options )
decode_rjson()
is the simple way to parse an RJSON string. It is exported by default. decode_rjson
takes a single parameter, the string to be parsed.
Optionally an additional hash with options can be passed to change the behaviour of the parser. See below.
$structure = decode_rjson( $rjson, %options );
OBJECT-ORIENTED PARSING
new
Create a JSON::Relaxed
object, suitable for one or many operations.
$parser = JSON::Relaxed->new( %options );
Options:
- strict
-
When set to a true value, enforces full compliance with the RelaxedJSON.org specification.
Default value is false, enabling JSON::Relaxed extensions.
- extra_tokens_ok
-
When set to a true value, allows (and ignores) trailing information after the first complete JSON structure.
Disabled by default.
- croak_on_error
-
Disabled by default in legacy mode, enabled otherwise.
Causes parsing error to be signalled with an exception.
See "ERROR HANDLING".
decode
This method parses the JSON string, passed as argument.
$structure = $parser->decode($rjson);
parse
This is the same as decode, but also enables legacy mode.
err_id
Fetches the error id of the last error, if any.
Error ids are simple short strings, like "multiple-structures"
.
For a full list, see JSON::Relaxed::ErrorCodes.
err_pos
Fetches the text position in the JSON string where the error occured. Returns -1 if this information is not available.
err_msg
Fetches the text of the last error message, if any.
For a full list, see JSON::Relaxed::ErrorCodes.
croak_on_error
Enables/disables exceptions on parse errors.
Note that the value must be assigned to:
$parser->croak_on_error = 1; # enable
extra_tokens_ok
Note that the value must be assigned to:
$parser->extra_tokens_ok = 0; # disable
strict
Enables/disables strict conformance to the official specification,
Note that the value must be assigned to:
$parser->strict = 1; # enable
ERROR HANDLING
If the document cannot be parsed, JSON::Relaxed will throw an exception.
In legacy mode, JSON::Relaxed returns an undefined value and sets error indicators in $JSON::Relaxed::err_id and $JSON::Relaxed::err_msg.
If parser property croak_on_error
is set to a false value, it will always behave as if in legacy mode.
For a full list of error codes, see JSON::Relaxed::ErrorCodes.
AUTHOR
Johan Vromans jv@cpan.org
Based on original code from Miko O'Sullivan miko@idocs.com.
SUPPORT
Development of this module takes place on GitHub: https://github.com/sciurius/perl-JSON-Relaxed.
You can find documentation for this module with the perldoc command.
perldoc JSON::Relaxed
Please report any bugs or feature requests using the issue tracker on GitHub.
LICENSE
Copyright (c) 2024 by Johan Vromans. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This software comes with NO WARRANTY of any kind.