/ 
mb-JSON-0.06
/ mb::JSON

NAME

mb::JSON - JSON encode/decode for multibyte (UTF-8) strings

VERSION

Version 0.06

SYNOPSIS

use mb::JSON;

# decode: JSON text -> Perl data
my $data = mb::JSON::decode("{\"name\":\"\\u7530\\u4e2d\",\"age\":30}");
my $data = mb::JSON::decode("{\"name\":\"Tanaka\",\"age\":30}");

# parse: alias for decode()
my $data = mb::JSON::parse("{\"key\":\"value\"}");

# encode: Perl data -> JSON text
my $json = mb::JSON::encode({ name => 'Tanaka', age => 30 });
# -> '{"age":30,"name":"Tanaka"}'

# stringify: alias for encode()
my $json = mb::JSON::stringify({ name => 'Tanaka', age => 30 });
# -> '{"age":30,"name":"Tanaka"}'

# Boolean values
my $json = mb::JSON::encode({
    active => mb::JSON::true,
    locked => mb::JSON::false,
});
# -> '{"active":true,"locked":false}'

# null
my $json = mb::JSON::encode({ value => undef });
# -> '{"value":null}'

TABLE OF CONTENTS

DESCRIPTION

mb::JSON is a simple, dependency-free JSON encoder and decoder designed for Perl 5.005_03 and later. It handles UTF-8 multibyte strings correctly, making it suitable for environments where standard JSON modules requiring Perl 5.8+ are unavailable.

mb::JSON provides two pairs of symmetric functions: decode()/parse() convert JSON text to Perl data, and encode()/stringify() convert Perl data to JSON text. Within each pair, both names are aliases and produce identical output. Version 0.06 adds stringify() as an alias for encode(), mirror of parse() which is an alias for decode().

FUNCTIONS

decode( $json_text )

Converts a JSON text string to a Perl data structure. If no argument is given, $_ is used.

my $data = mb::JSON::decode($json_text);

parse( $json_text )

Alias for decode(). Both names are interchangeable.

my $data = mb::JSON::parse($json_text);

encode( $data )

Converts a Perl data structure to a JSON text string. Returns a byte string encoded in UTF-8.

my $json = mb::JSON::encode($data);

stringify( $data )

Alias for encode(). Both names are interchangeable. Mirrors the JSON.stringify() function in JavaScript.

my $json = mb::JSON::stringify($data);

true

Returns the singleton mb::JSON::Boolean object representing JSON true. Numifies to 1, stringifies to "true".

false

Returns the singleton mb::JSON::Boolean object representing JSON false. Numifies to 0, stringifies to "false".

BOOLEAN VALUES

Perl has no native boolean type. To represent JSON true and false unambiguously, mb::JSON provides two singleton objects:

mb::JSON::true   -- stringifies as "true",  numifies as 1
mb::JSON::false  -- stringifies as "false", numifies as 0

Use these when encoding a boolean value:

my $json = mb::JSON::encode({ flag => mb::JSON::true });
# -> '{"flag":true}'

A plain 1 or 0 encodes as a JSON number, not a boolean:

my $json = mb::JSON::encode({ count => 1 });
# -> '{"count":1}'

When decoding, JSON true and false are returned as mb::JSON::Boolean objects, which behave as 1 and 0 in numeric and boolean context.

stringify() behaves identically to encode() for boolean values.

ENCODING RULES

Applies to both encode() and stringify().

undef -> null
mb::JSON::true -> true, mb::JSON::false -> false
Number

A scalar matching the JSON number pattern is encoded as a bare number.

String

Encoded as a double-quoted JSON string. UTF-8 multibyte bytes are output as-is (not \uXXXX-escaped). Control characters U+0000-U+001F are escaped.

ARRAY reference -> JSON array [...]
HASH reference -> JSON object {...}

Hash keys are sorted alphabetically for deterministic output.

DECODING RULES

Applies to both decode() and parse().

null -> undef
true -> mb::JSON::Boolean (numifies to 1)
false -> mb::JSON::Boolean (numifies to 0)
Number -> Perl number
String -> Perl string (\uXXXX converted to UTF-8)
Object -> hash reference
Array -> array reference

LIMITATIONS

  • Surrogate pairs (\uD800-\uDFFF) in \uXXXX sequences are not supported.

  • Circular references in encode() and stringify() are not detected and will cause infinite recursion.

  • References other than ARRAY and HASH (e.g. code references, blessed objects other than mb::JSON::Boolean) are stringified rather than raising an error.

  • A scalar that matches the JSON number pattern (e.g. "1.0", "007") is encoded as a number if it looks like one, and as a string otherwise. Leading-zero strings such as "007" are preserved as strings because they do not match the JSON number pattern.

DIAGNOSTICS

mb::JSON::decode: unexpected end of input

The JSON text ended before a complete value was parsed.

mb::JSON::decode: unexpected token: <text>

An unrecognised token was encountered while parsing.

mb::JSON::decode: expected string key in object

An object key was not a quoted string.

mb::JSON::decode: expected ':' after key '<key>'

The colon separator was missing after an object key.

mb::JSON::decode: expected ',' or '}' in object

A JSON object was not properly terminated or separated.

mb::JSON::decode: expected ',' or ']' in array

A JSON array was not properly terminated or separated.

mb::JSON::decode: unterminated string

A JSON string was not closed with a double-quote.

mb::JSON::decode: trailing garbage: <text>

Extra text was found after a successfully parsed top-level value.

BUGS AND LIMITATIONS

Please report bugs to ina@cpan.org.

SEE ALSO

JSON::PP, JSON::XS

AUTHOR

INABA Hitoshi <ina@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2021, 2022, 2026 INABA Hitoshi <ina@cpan.org>

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