/ 
mb-JSON-0.04
River stage zero No dependents
/ mb::JSON

NAME

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

VERSION

Version 0.04

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}');

# encode: Perl data -> JSON text
my $json = mb::JSON::encode({ 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}'

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

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.

Version 0.04 adds encode() (Perl data to JSON text) and the Boolean type objects mb::JSON::true and mb::JSON::false, complementing the existing decode()/parse().

FUNCTIONS

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);

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(). Retained for backward compatibility with 0.03.

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

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.

ENCODING RULES

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

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() 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.