File Coverage

blib/lib/JSON/XS/ByteString.pm
Criterion Covered Total %
statement 8 8 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 11 11 100.0


line stmt bran cond sub pod time code
1             package JSON::XS::ByteString;
2              
3 1     1   74997 use 5.008;
  1         4  
4 1     1   5 use strict;
  1         2  
  1         19  
5 1     1   5 use warnings;
  1         2  
  1         108  
6              
7             require Exporter;
8              
9             our @ISA = qw(Exporter);
10             our @EXPORT_OK = qw(encode_json encode_json_unblessed decode_json decode_json_safe);
11             our $VERSION = 1.006000;
12              
13             require XSLoader;
14             XSLoader::load('JSON::XS::ByteString', $VERSION);
15              
16             =head1 NAME
17              
18             JSON::XS::ByteString - A more predictable and convenient XS implementation for JSON
19              
20             =head1 SYNOPSIS
21              
22             use JSON::XS::ByteString qw(encode_json encode_json_unblessed decode_json decode_json_safe);
23              
24             $json_string = encode_json($perl_data);
25             $json_string_pretty = encode_json_pretty($perl_data);
26             $perl_data = decode_json($json_string);
27             $perl_data = decode_json($json_string, 1); # die if $json_string is not valid JSON string
28              
29             $json_string = encode_json_unblessed($perl_data);
30             $json_string_pretty = encode_json_unblessed_pretty($perl_data);
31             # the same behavior as encode_json
32             # but encode blessed references as reference strings,
33             # like 'Object=HASH(0xffffffff)'
34              
35             =head1 DESCRIPTION
36              
37             This module is a XS implementation for JSON. It provide a more predictable behavior than L by always producing strings in JSON for normal scalars.
38             And you can force it to produce numbers in JSON by putting references to numbers.
39              
40             All the string data are treated as UTF-8 octets and just copy them in and out directly, except C<">, C<\> and characters that C<< ord($char) < 32 >>
41              
42             C will return an undef without exceptions with invalid json string.
43              
44             =head1 DESIGN CONSIDERATION
45              
46             =head2 I didn't transfer the numeric value from C back to string values
47              
48             Because in the pure Perl world, there's insignificant difference between numeric or string.
49             So I think we don't need to do it since the result will be used in Perl.
50              
51             =head2 I didn't transfer the numeric value from C back to reference values
52              
53             Let C preserve the identical structure as it received.
54              
55             =head1 FUNCTIONS
56              
57             =head2 $json_string = encode_json($perl_data)
58              
59             Get a JSON string from a perl data structure. Treat blessed objects as normal references.
60              
61             =head2 $json_string = encode_json_unblessed($perl_data)
62              
63             Get a JSON string from a perl data structure. Treat blessed objects as strings (such as C<'Object=HASH(0xffffffff)'>)
64              
65             =head2 $perl_data = decode_json($json_string, $warn2die=0)
66              
67             Get the perl data structure back from a JSON string.
68              
69             If the given string is not a valid JSON string, it will return an C.
70             If the C<$warn2die> is false or not specified, this function will not die but warns an offset where it encountered the unrecognized character.
71             If the C<$warn2die> is true, this function will die with the error message which is identical to the warning one.
72              
73             =head2 $perl_data = decode_json_safe($json_string)
74              
75             The same as C except that C will not warn at all.
76              
77             =head1 SEE ALSO
78              
79             L
80              
81             This mod's github repository L
82              
83             =head1 AUTHOR
84              
85             Cindy Wang (CindyLinz)
86              
87             =head1 COPYRIGHT AND LICENSE
88              
89             Copyright (C) 2014-2021 by Cindy Wang (CindyLinz)
90              
91             This library is free software; you can redistribute it and/or modify
92             it under the same terms as Perl itself, either Perl version 5.8 or,
93             at your option, any later version of Perl 5 you may have available.
94              
95             =cut
96              
97             1;