NAME

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

SYNOPSIS

  use mb::JSON;

  # decode: JSON text -> Perl data
  my $data = mb::JSON::decode('{"name":"Alice","age":30,"active":true}');
  print $data->{name};    # Alice
  print $data->{age};     # 30
  print $data->{active};  # true (mb::JSON::Boolean object)

  # encode: Perl data -> JSON text
  my $json = mb::JSON::encode({
      name   => 'Alice',
      active => mb::JSON::true,
      score  => undef,
  });
  # -> {"active":true,"name":"Alice","score":null}

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

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

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 explicit
  Boolean type objects (mb::JSON::true and mb::JSON::false) to
  complement the existing decode()/parse().

FUNCTIONS

  mb::JSON::encode($data)
      Converts a Perl data structure to a JSON text string.
      Hash keys are sorted alphabetically for deterministic output.
      UTF-8 multibyte bytes are output as-is (not \uXXXX-escaped).

  mb::JSON::decode($json_text)
      Converts a JSON text string to a Perl data structure.
      If no argument is given, $_ is used.

  mb::JSON::parse($json_text)
      Alias for decode(). Retained for backward compatibility with 0.03.

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

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

ENCODING RULES

  undef                -> null
  mb::JSON::true       -> true
  mb::JSON::false      -> false
  number-like scalar   -> number (no quotes)
  other scalar         -> "string" (UTF-8 bytes kept as-is)
  ARRAY reference      -> [...]
  HASH reference       -> {...} (keys sorted alphabetically)

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

BOOLEAN VALUES

  Perl has no native boolean type. mb::JSON provides two singleton
  objects for unambiguous boolean encoding:

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

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

    encode({ count => 1 })           -> '{"count":1}'
    encode({ flag => mb::JSON::true }) -> '{"flag":true}'

INCLUDED DOCUMENTATION

  The doc/ directory contains JSON cheat sheets in 21 languages
  for use as quick reference materials.

INSTALLATION

  To install this module type the following:

    perl Makefile.PL
    make
    make test
    make install

  Or using pmake.bat (Windows):

    pmake.bat test
    pmake.bat install

COMPATIBILITY

  This module works with Perl 5.005_03 and later.

  WHY PERL 5.005_03 SPECIFICATION?

  This module adheres to the Perl 5.005_03 specification--not because we
  use the old interpreter, but because this specification represents the
  simple, original Perl programming model that makes programming enjoyable.

  THE STRENGTH OF MODERN TIMES

  Some people think the strength of modern times is the ability to use
  modern technology. That thinking is insufficient. The strength of modern
  times is the ability to use ALL technology up to the present day.

  By adhering to the Perl 5.005_03 specification, we gain access to the
  entire history of Perl--from 5.005_03 to 5.42 and beyond--rather than
  limiting ourselves to only the latest versions.

  Key reasons:

  - Simplicity: Original Perl approach keeps programming "raku" (easy/fun)
  - JPerl: Final version of JPerl (Japanese Perl)
  - Universal: Runs on ALL Perl versions (5.005_03 through 5.42+)
  - Philosophy: Programming should be enjoyable (Camel Book readers know!)

  Perl 5.6+ introduced character encoding complexity that made programming
  harder. By following the 5.005_03 specification, we maintain the joy of
  Perl programming.

TARGET USE CASES

  - Processing JSON data with UTF-8 multibyte strings
  - Environments where JSON::PP or JSON::XS cannot be installed
  - Legacy Perl environments (5.005_03 and later)
  - Lightweight scripts and utilities with no external dependencies

LIMITATIONS

  - Surrogate pairs (\uD800-\uDFFF) in \uXXXX sequences are not supported
  - Circular references in encode() are not detected (infinite recursion)
  - Numbers are not distinguished from strings if the value matches the
    number pattern

AUTHOR

  INABA Hitoshi <ina@cpan.org>

COPYRIGHT AND LICENSE

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