view release on metacpan or  search on metacpan

bundled/JSON-PP/JSON/PP.pm  view on Meta::CPAN

=back

=head1 FUNCTIONAL INTERFACE

Some documents are copied and modified from L<JSON::XS/FUNCTIONAL INTERFACE>.

=head2 encode_json

    $json_text = encode_json $perl_scalar

Converts the given Perl data structure to a UTF-8 encoded, binary string.

This function call is functionally identical to:

    $json_text = JSON::PP->new->utf8->encode($perl_scalar)

=head2 decode_json

    $perl_scalar = decode_json $json_text

The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
to parse that as an UTF-8 encoded JSON text, returning the resulting
reference.

This function call is functionally identical to:

    $perl_scalar = JSON::PP->new->utf8->decode($json_text)

=head2 JSON::PP::is_bool

    $is_boolean = JSON::PP::is_bool($scalar)

Returns true if the passed scalar represents either JSON::PP::true or
JSON::PP::false, two constants that act like C<1> and C<0> respectively
and are also used to represent JSON C<true> and C<false> in Perl strings.

=head2 JSON::PP::true

Returns JSON true value which is blessed object.
It C<isa> JSON::PP::Boolean object.

=head2 JSON::PP::false

Returns JSON false value which is blessed object.
It C<isa> JSON::PP::Boolean object.

=head2 JSON::PP::null

Returns C<undef>.

See L<MAPPING>, below, for more information on how JSON values are mapped to
Perl.


=head1 HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER

This section supposes that your perl vresion is 5.8 or later.

If you know a JSON text from an outer world - a network, a file content, and so on,
is encoded in UTF-8, you should use C<decode_json> or C<JSON> module object
with C<utf8> enable. And the decoded result will contain UNICODE characters.

  # from network
  my $json        = JSON::PP->new->utf8;
  my $json_text   = CGI->new->param( 'json_data' );
  my $perl_scalar = $json->decode( $json_text );
  
  # from file content
  local $/;
  open( my $fh, '<', 'json.data' );
  $json_text   = <$fh>;
  $perl_scalar = decode_json( $json_text );

If an outer data is not encoded in UTF-8, firstly you should C<decode> it.

  use Encode;
  local $/;
  open( my $fh, '<', 'json.data' );
  my $encoding = 'cp932';
  my $unicode_json_text = decode( $encoding, <$fh> ); # UNICODE
  
  # or you can write the below code.
  #
  # open( my $fh, "<:encoding($encoding)", 'json.data' );
  # $unicode_json_text = <$fh>;

In this case, C<$unicode_json_text> is of course UNICODE string.
So you B<cannot> use C<decode_json> nor C<JSON> module object with C<utf8> enable.
Instead of them, you use C<JSON> module object with C<utf8> disable.

  $perl_scalar = $json->utf8(0)->decode( $unicode_json_text );

Or C<encode 'utf8'> and C<decode_json>:

  $perl_scalar = decode_json( encode( 'utf8', $unicode_json_text ) );
  # this way is not efficient.

And now, you want to convert your C<$perl_scalar> into JSON data and
send it to an outer world - a network or a file content, and so on.

Your data usually contains UNICODE strings and you want the converted data to be encoded
in UTF-8, you should use C<encode_json> or C<JSON> module object with C<utf8> enable.

  print encode_json( $perl_scalar ); # to a network? file? or display?
  # or
  print $json->utf8->encode( $perl_scalar );

If C<$perl_scalar> does not contain UNICODE but C<$encoding>-encoded strings
for some reason, then its characters are regarded as B<latin1> for perl
(because it does not concern with your $encoding).
You B<cannot> use C<encode_json> nor C<JSON> module object with C<utf8> enable.
Instead of them, you use C<JSON> module object with C<utf8> disable.
Note that the resulted text is a UNICODE string but no problem to print it.

  # $perl_scalar contains $encoding encoded string values
  $unicode_json_text = $json->utf8(0)->encode( $perl_scalar );
  # $unicode_json_text consists of characters less than 0x100
  print $unicode_json_text;

Or C<decode $encoding> all string values and C<encode_json>: