1JSON::MaybeXS(3)      User Contributed Perl Documentation     JSON::MaybeXS(3)
2
3
4

NAME

6       JSON::MaybeXS - Use Cpanel::JSON::XS with a fallback to JSON::XS and
7       JSON::PP
8

SYNOPSIS

10         use JSON::MaybeXS;
11
12         my $data_structure = decode_json($json_input);
13
14         my $json_output = encode_json($data_structure);
15
16         my $json = JSON()->new;
17
18         my $json_with_args = JSON::MaybeXS->new(utf8 => 1); # or { utf8 => 1 }
19

DESCRIPTION

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
27       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
31       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

EXPORTS

36       "encode_json", "decode_json" and "JSON" are exported by default;
37       "is_bool" is exported on request.
38
39       To import only some symbols, specify them on the "use" line:
40
41         use JSON::MaybeXS qw(encode_json decode_json is_bool); # functions only
42
43         use JSON::MaybeXS qw(JSON); # JSON constant only
44
45       To import all available sensible symbols ("encode_json", "decode_json",
46       and "is_bool"), use ":all":
47
48         use JSON::MaybeXS ':all';
49
50       To import all symbols including those needed by legacy apps that use
51       JSON::PP:
52
53         use JSON::MaybeXS ':legacy';
54
55       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
62   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
67         my $json_text = encode_json($data_structure);
68
69   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
74         my $data_structure = decode_json($json_text);
75
76   to_json, from_json
77       See JSON for details.  These are included to support legacy code only.
78
79   JSON
80       The "JSON" constant returns the selected implementation module's name
81       for use as a class name - so:
82
83         my $json_obj = JSON()->new; # returns a Cpanel::JSON::XS or JSON::PP object
84
85       and that object can then be used normally:
86
87         my $data_structure = $json_obj->decode($json_text); # etc.
88
89       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
92   is_bool
93         $is_boolean = is_bool($scalar)
94
95       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
99       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
104       Available since version 1.002004.
105

CONSTRUCTOR

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
111         my $json = $class->new->utf8(1)->pretty(1);
112
113       Since this is a trifle irritating and noticeably un-perlish, we also
114       offer:
115
116         my $json = JSON::MaybeXS->new(utf8 => 1, pretty => 1);
117
118       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
121       The resulting object is blessed into the underlying backend, which
122       offers (at least) the methods "encode" and "decode".
123

BOOLEANS

125       To include JSON-aware booleans ("true", "false") in your data, just do:
126
127           use JSON::MaybeXS;
128           my $true = JSON()->true;
129           my $false = JSON()->false;
130
131       The booleans are also available as subs or methods on JSON::MaybeXS.
132
133           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

CONVERTING FROM JSON::Any

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
145       Change code from:
146
147           use JSON::Any;
148           my $json = JSON::Any->new->objToJson($data);    # or to_json($data), or Dump($data)
149
150       to:
151
152           use JSON::MaybeXS;
153           my $json = encode_json($data);
154
155       Change code from:
156
157           use JSON::Any;
158           my $data = JSON::Any->new->jsonToObj($json);    # or from_json($json), or Load($json)
159
160       to:
161
162           use JSON::MaybeXS;
163           my $json = decode_json($data);
164

CAVEATS

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
170       If you are using an object returned by this module as a Moo(se)
171       attribute, this type constraint code:
172
173           is 'json' => ( isa => 'JSON::MaybeXS' );
174
175       will NOT do what you expect. Instead, either rely on the "JSON" class
176       constant described above, as so:
177
178           is 'json' => ( isa => JSON::MaybeXS::JSON() );
179
180       Alternatively, you can use duck typing:
181
182           use Moose::Util::TypeConstraints 'duck_type';
183           is 'json' => ( isa => Object , duck_type([qw/ encode decode /]));
184

INSTALLATION

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
192       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
197       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

AUTHOR

203       mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
204

CONTRIBUTORS

206       •   Clinton Gormley <drtech@cpan.org>
207
208       •   Karen Etheridge <ether@cpan.org>
209
210       •   Kieren Diment <diment@gmail.com>
211
213       Copyright (c) 2013 the "JSON::MaybeXS" "AUTHOR" and "CONTRIBUTORS" as
214       listed above.
215

LICENSE

217       This library is free software and may be distributed under the same
218       terms as perl itself.
219
220
221
222perl v5.34.0                      2021-07-22                  JSON::MaybeXS(3)
Impressum