1JSON::MaybeXS(3) User Contributed Perl Documentation JSON::MaybeXS(3)
2
6 JSON::MaybeXS - Use Cpanel::JSON::XS with a fallback to JSON::XS and
7 JSON::PP
8
10 use JSON::MaybeXS;
11 my $data_structure = decode_json($json_input);
13 my $json_output = encode_json($data_structure);
15 my $json = JSON()->new;
17 my $json_with_args = JSON::MaybeXS->new(utf8 => 1); # or { utf8 => 1 }
19
21 This module first checks to see if either Cpanel::JSON::XS or JSON::XS
22 (at at least version 3.0) is already loaded, in which case it uses that
23 module. Otherwise it tries to load Cpanel::JSON::XS, then JSON::XS,
24 then JSON::PP in order, and either uses the first module it finds or
25 throws an error.
26 It then exports the "encode_json" and "decode_json" functions from the
28 loaded module, along with a "JSON" constant that returns the class name
29 for calling "new" on.
30 If you're writing fresh code rather than replacing JSON.pm usage, you
32 might want to pass options as constructor args rather than calling
33 mutators, so we provide our own "new" method that supports that.
34
36 "encode_json", "decode_json" and "JSON" are exported by default;
37 "is_bool" is exported on request.
38 To import only some symbols, specify them on the "use" line:
40 use JSON::MaybeXS qw(encode_json decode_json is_bool); # functions only
42 use JSON::MaybeXS qw(JSON); # JSON constant only
44 To import all available sensible symbols ("encode_json", "decode_json",
46 and "is_bool"), use ":all":
47 use JSON::MaybeXS ':all';
49 To import all symbols including those needed by legacy apps that use
51 JSON::PP:
52 use JSON::MaybeXS ':legacy';
54 This imports the "to_json" and "from_json" symbols as well as
56 everything in ":all". NOTE: This is to support legacy code that makes
57 extensive use of "to_json" and "from_json" which you are not yet in a
58 position to refactor. DO NOT use this import tag in new code, in order
59 to avoid the crawling horrors of getting UTF-8 support subtly wrong.
60 See the documentation for JSON for further details.
61 encode_json
63 This is the "encode_json" function provided by the selected
64 implementation module, and takes a perl data structure which is
65 serialised to JSON text.
66 my $json_text = encode_json($data_structure);
68 decode_json
70 This is the "decode_json" function provided by the selected
71 implementation module, and takes a string of JSON text to deserialise
72 to a perl data structure.
73 my $data_structure = decode_json($json_text);
75 to_json
77 This function is equivalent to calling
78 "JSON()->new->encode($data_structure)". It takes a perl data structure
79 which is serialised to JSON text without encoding it to UTF-8. You
80 should only use this function if you expect another layer to handle the
81 UTF-8 encoding of the resulting JSON text.
82 my $json_text = to_json($data_structure);
84 Additional arguments can be passed and will be handled as in "to_json"
86 in JSON, this is included to support legacy code only.
87 from_json
89 This function is equivalent to calling
90 "JSON()->new->decode($json_text)". It takes a string of unencoded JSON
91 text to deserialise to a perl data structure. You should only use this
92 function if another layer is already handling the UTF-8 decoding of the
93 input JSON text.
94 my $data_structure = from_json($json_text);
96 Additional arguments can be passed and will be handled as in
98 "from_json" in JSON, this is included to support legacy code only.
99 JSON
101 The "JSON" constant returns the selected implementation module's name
102 for use as a class name - so:
103 my $json_obj = JSON()->new; # returns a Cpanel::JSON::XS or JSON::PP object
105 and that object can then be used normally:
107 my $data_structure = $json_obj->decode($json_text); # etc.
109 The use of parentheses here is optional, and only used as a hint to the
111 reader that this use of "JSON" is a subroutine call, not a class name.
112 is_bool
114 $is_boolean = is_bool($scalar)
115 Returns true if the passed scalar represents either "true" or "false",
117 two constants that act like 1 and 0, respectively and are used to
118 represent JSON "true" and "false" values in Perl.
119 Since this is a bare sub in the various backend classes, it cannot be
121 called as a class method like the other interfaces; it must be called
122 as a function, with no invocant. It supports the representation used
123 in all JSON backends.
124 Available since version 1.002004.
126
128 new
129 With JSON::PP, JSON::XS and Cpanel::JSON::XS you are required to call
130 mutators to set options, such as:
131 my $json = $class->new->utf8(1)->pretty(1);
133 Since this is a trifle irritating and noticeably un-perlish, we also
135 offer:
136 my $json = JSON::MaybeXS->new(utf8 => 1, pretty => 1);
138 which works equivalently to the above (and in the usual tradition will
140 accept a hashref instead of a hash, should you so desire).
141 The resulting object is blessed into the underlying backend, which
143 offers (at least) the methods "encode" and "decode".
144
146 To include JSON-aware booleans ("true", "false") in your data, just do:
147 use JSON::MaybeXS;
149 my $true = JSON()->true;
150 my $false = JSON()->false;
151 The booleans are also available as subs or methods on JSON::MaybeXS.
153 use JSON::MaybeXS ();
155 my $true = JSON::MaybeXS::true;
156 my $true = JSON::MaybeXS->true;
157 my $false = JSON::MaybeXS::false;
158 my $false = JSON::MaybeXS->false;
159
161 JSON::Any used to be the favoured compatibility layer above the various
162 JSON backends, but over time has grown a lot of extra code to deal with
163 legacy backends (e.g. JSON::Syck) that are no longer needed. This is a
164 rough guide of translating such code:
165 Change code from:
167 use JSON::Any;
169 my $json = JSON::Any->new->objToJson($data); # or to_json($data), or Dump($data)
170 to:
172 use JSON::MaybeXS;
174 my $json = encode_json($data);
175 Change code from:
177 use JSON::Any;
179 my $data = JSON::Any->new->jsonToObj($json); # or from_json($json), or Load($json)
180 to:
182 use JSON::MaybeXS;
184 my $json = decode_json($data);
185
187 The new() method in this module is technically a factory, not a
188 constructor, because the objects it returns will NOT be blessed into
189 the "JSON::MaybeXS" class.
190 If you are using an object returned by this module as a Moo(se)
192 attribute, this type constraint code:
193 is 'json' => ( isa => 'JSON::MaybeXS' );
195 will NOT do what you expect. Instead, either rely on the "JSON" class
197 constant described above, as so:
198 is 'json' => ( isa => JSON::MaybeXS::JSON() );
200 Alternatively, you can use duck typing:
202 use Moose::Util::TypeConstraints 'duck_type';
204 is 'json' => ( isa => Object , duck_type([qw/ encode decode /]));
205
207 At installation time, Makefile.PL will attempt to determine if you have
208 a working compiler available, and therefore whether you are able to run
209 XS code. If so, Cpanel::JSON::XS will be added to the prerequisite
210 list, unless JSON::XS is already installed at a high enough version.
211 JSON::XS may also be upgraded to fix any incompatibility issues.
212 Because running XS code is not mandatory and JSON::PP (which is in perl
214 core) is used as a fallback backend, this module is safe to be used in
215 a suite of code that is fatpacked or installed into a restricted-
216 resource environment.
217 You can also prevent any XS dependencies from being installed by
219 setting "PUREPERL_ONLY=1" in Makefile.PL options (or in the
220 "PERL_MM_OPT" environment variable), or using the "--pp" or
221 "--pureperl" flags with the cpanminus client.
222
224 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
225
227 • Clinton Gormley <drtech@cpan.org>
228 • Karen Etheridge <ether@cpan.org>
230 • Kieren Diment <diment@gmail.com>
232
234 Copyright (c) 2013 the "JSON::MaybeXS" "AUTHOR" and "CONTRIBUTORS" as
235 listed above.
236
238 This library is free software and may be distributed under the same
239 terms as perl itself.
240perl v5.38.0 2023-07-20 JSON::MaybeXS(3)