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, from_json
77 See JSON for details. These are included to support legacy code only.
78 JSON
80 The "JSON" constant returns the selected implementation module's name
81 for use as a class name - so:
82 my $json_obj = JSON()->new; # returns a Cpanel::JSON::XS or JSON::PP object
84 and that object can then be used normally:
86 my $data_structure = $json_obj->decode($json_text); # etc.
88 The use of parentheses here is optional, and only used as a hint to the
90 reader that this use of "JSON" is a subroutine call, not a class name.
91 is_bool
93 $is_boolean = is_bool($scalar)
94 Returns true if the passed scalar represents either "true" or "false",
96 two constants that act like 1 and 0, respectively and are used to
97 represent JSON "true" and "false" values in Perl.
98 Since this is a bare sub in the various backend classes, it cannot be
100 called as a class method like the other interfaces; it must be called
101 as a function, with no invocant. It supports the representation used
102 in all JSON backends.
103 Available since version 1.002004.
105
107 new
108 With JSON::PP, JSON::XS and Cpanel::JSON::XS you are required to call
109 mutators to set options, such as:
110 my $json = $class->new->utf8(1)->pretty(1);
112 Since this is a trifle irritating and noticeably un-perlish, we also
114 offer:
115 my $json = JSON::MaybeXS->new(utf8 => 1, pretty => 1);
117 which works equivalently to the above (and in the usual tradition will
119 accept a hashref instead of a hash, should you so desire).
120 The resulting object is blessed into the underlying backend, which
122 offers (at least) the methods "encode" and "decode".
123
125 To include JSON-aware booleans ("true", "false") in your data, just do:
126 use JSON::MaybeXS;
128 my $true = JSON()->true;
129 my $false = JSON()->false;
130 The booleans are also available as subs or methods on JSON::MaybeXS.
132 use JSON::MaybeXS ();
134 my $true = JSON::MaybeXS::true;
135 my $true = JSON::MaybeXS->true;
136 my $false = JSON::MaybeXS::false;
137 my $false = JSON::MaybeXS->false;
138
140 JSON::Any used to be the favoured compatibility layer above the various
141 JSON backends, but over time has grown a lot of extra code to deal with
142 legacy backends (e.g. JSON::Syck) that are no longer needed. This is a
143 rough guide of translating such code:
144 Change code from:
146 use JSON::Any;
148 my $json = JSON::Any->new->objToJson($data); # or to_json($data), or Dump($data)
149 to:
151 use JSON::MaybeXS;
153 my $json = encode_json($data);
154 Change code from:
156 use JSON::Any;
158 my $data = JSON::Any->new->jsonToObj($json); # or from_json($json), or Load($json)
159 to:
161 use JSON::MaybeXS;
163 my $json = decode_json($data);
164
166 The new() method in this module is technically a factory, not a
167 constructor, because the objects it returns will NOT be blessed into
168 the "JSON::MaybeXS" class.
169 If you are using an object returned by this module as a Moo(se)
171 attribute, this type constraint code:
172 is 'json' => ( isa => 'JSON::MaybeXS' );
174 will NOT do what you expect. Instead, either rely on the "JSON" class
176 constant described above, as so:
177 is 'json' => ( isa => JSON::MaybeXS::JSON() );
179 Alternatively, you can use duck typing:
181 use Moose::Util::TypeConstraints 'duck_type';
183 is 'json' => ( isa => Object , duck_type([qw/ encode decode /]));
184
186 At installation time, Makefile.PL will attempt to determine if you have
187 a working compiler available, and therefore whether you are able to run
188 XS code. If so, Cpanel::JSON::XS will be added to the prerequisite
189 list, unless JSON::XS is already installed at a high enough version.
190 JSON::XS may also be upgraded to fix any incompatibility issues.
191 Because running XS code is not mandatory and JSON::PP (which is in perl
193 core) is used as a fallback backend, this module is safe to be used in
194 a suite of code that is fatpacked or installed into a restricted-
195 resource environment.
196 You can also prevent any XS dependencies from being installed by
198 setting "PUREPERL_ONLY=1" in Makefile.PL options (or in the
199 "PERL_MM_OPT" environment variable), or using the "--pp" or
200 "--pureperl" flags with the cpanminus client.
201
203 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
204
206 • Clinton Gormley <drtech@cpan.org>
207 • Karen Etheridge <ether@cpan.org>
209 • Kieren Diment <diment@gmail.com>
211
213 Copyright (c) 2013 the "JSON::MaybeXS" "AUTHOR" and "CONTRIBUTORS" as
214 listed above.
215
217 This library is free software and may be distributed under the same
218 terms as perl itself.
219perl v5.36.0 2023-01-20 JSON::MaybeXS(3)