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       is already loaded, in which case it uses that module. Otherwise it
23       tries to load Cpanel::JSON::XS, then JSON::XS, then JSON::PP in order,
24       and either uses the first module it finds or throws an error.
25
26       It then exports the "encode_json" and "decode_json" functions from the
27       loaded module, along with a "JSON" constant that returns the class name
28       for calling "new" on.
29
30       If you're writing fresh code rather than replacing JSON.pm usage, you
31       might want to pass options as constructor args rather than calling
32       mutators, so we provide our own "new" method that supports that.
33

EXPORTS

35       "encode_json", "decode_json" and "JSON" are exported by default;
36       "is_bool" is exported on request.
37
38       To import only some symbols, specify them on the "use" line:
39
40         use JSON::MaybeXS qw(encode_json decode_json is_bool); # functions only
41
42         use JSON::MaybeXS qw(JSON); # JSON constant only
43
44       To import all available sensible symbols ("encode_json", "decode_json",
45       and "is_bool"), use ":all":
46
47         use JSON::MaybeXS ':all';
48
49       To import all symbols including those needed by legacy apps that use
50       JSON::PP:
51
52         use JSON::MaybeXS ':legacy';
53
54       This imports the "to_json" and "from_json" symbols as well as
55       everything in ":all".  NOTE: This is to support legacy code that makes
56       extensive use of "to_json" and "from_json" which you are not yet in a
57       position to refactor.  DO NOT use this import tag in new code, in order
58       to avoid the crawling horrors of getting UTF-8 support subtly wrong.
59       See the documentation for JSON for further details.
60
61   encode_json
62       This is the "encode_json" function provided by the selected
63       implementation module, and takes a perl data structure which is
64       serialised to JSON text.
65
66         my $json_text = encode_json($data_structure);
67
68   decode_json
69       This is the "decode_json" function provided by the selected
70       implementation module, and takes a string of JSON text to deserialise
71       to a perl data structure.
72
73         my $data_structure = decode_json($json_text);
74
75   to_json, from_json
76       See JSON for details.  These are included to support legacy code only.
77
78   JSON
79       The "JSON" constant returns the selected implementation module's name
80       for use as a class name - so:
81
82         my $json_obj = JSON()->new; # returns a Cpanel::JSON::XS or JSON::PP object
83
84       and that object can then be used normally:
85
86         my $data_structure = $json_obj->decode($json_text); # etc.
87
88       The use of parentheses here is optional, and only used as a hint to the
89       reader that this use of "JSON" is a subroutine call, not a class name.
90
91   is_bool
92         $is_boolean = is_bool($scalar)
93
94       Returns true if the passed scalar represents either "true" or "false",
95       two constants that act like 1 and 0, respectively and are used to
96       represent JSON "true" and "false" values in Perl.
97
98       Since this is a bare sub in the various backend classes, it cannot be
99       called as a class method like the other interfaces; it must be called
100       as a function, with no invocant.  It supports the representation used
101       in all JSON backends.
102

CONSTRUCTOR

104   new
105       With JSON::PP, JSON::XS and Cpanel::JSON::XS you are required to call
106       mutators to set options, such as:
107
108         my $json = $class->new->utf8(1)->pretty(1);
109
110       Since this is a trifle irritating and noticeably un-perlish, we also
111       offer:
112
113         my $json = JSON::MaybeXS->new(utf8 => 1, pretty => 1);
114
115       which works equivalently to the above (and in the usual tradition will
116       accept a hashref instead of a hash, should you so desire).
117
118       The resulting object is blessed into the underlying backend, which
119       offers (at least) the methods "encode" and "decode".
120

BOOLEANS

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

CONVERTING FROM JSON::Any

137       JSON::Any used to be the favoured compatibility layer above the various
138       JSON backends, but over time has grown a lot of extra code to deal with
139       legacy backends (e.g. JSON::Syck) that are no longer needed.  This is a
140       rough guide of translating such code:
141
142       Change code from:
143
144           use JSON::Any;
145           my $json = JSON::Any->new->objToJson($data);    # or to_json($data), or Dump($data)
146
147       to:
148
149           use JSON::MaybeXS;
150           my $json = encode_json($data);
151
152       Change code from:
153
154           use JSON::Any;
155           my $data = JSON::Any->new->jsonToObj($json);    # or from_json($json), or Load($json)
156
157       to:
158
159           use JSON::MaybeXS;
160           my $json = decode_json($data);
161

CAVEATS

163       The "new()" method in this module is technically a factory, not a
164       constructor, because the objects it returns will NOT be blessed into
165       the "JSON::MaybeXS" class.
166
167       If you are using an object returned by this module as a Moo(se)
168       attribute, this type constraint code:
169
170           is 'json' => ( isa => 'JSON::MaybeXS' );
171
172       will NOT do what you expect. Instead, either rely on the "JSON" class
173       constant described above, as so:
174
175           is 'json' => ( isa => JSON::MaybeXS::JSON() );
176
177       Alternatively, you can use duck typing:
178
179           use Moose::Util::TypeConstraints 'duck_type';
180           is 'json' => ( isa => Object , duck_type([qw/ encode decode /]));
181

INSTALLATION

183       At installation time, Makefile.PL will attempt to determine if you have
184       a working compiler available, and therefore whether you are able to run
185       XS code.  If so, Cpanel::JSON::XS will be added to the prerequisite
186       list, unless JSON::XS is already installed at a high enough version.
187       JSON::XS may also be upgraded to fix any incompatibility issues.
188
189       Because running XS code is not mandatory and JSON::PP (which is in perl
190       core) is used as a fallback backend, this module is safe to be used in
191       a suite of code that is fatpacked or installed into a restricted-
192       resource environment.
193
194       You can also prevent any XS dependencies from being installed by
195       setting "PUREPERL_ONLY=1" in Makefile.PL options (or in the
196       "PERL_MM_OPT" environment variable), or using the "--pp" or
197       "--pureperl" flags with the cpanminus client.
198

AUTHOR

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

CONTRIBUTORS

203       ·   Clinton Gormley <drtech@cpan.org>
204
205       ·   Karen Etheridge <ether@cpan.org>
206
207       ·   Kieren Diment <diment@gmail.com>
208

COPYRIGHT

210       Copyright (c) 2013 the "JSON::MaybeXS" "AUTHOR" and "CONTRIBUTORS" as
211       listed above.
212

LICENSE

214       This library is free software and may be distributed under the same
215       terms as perl itself.
216
217
218
219perl v5.30.1                      2020-01-30                  JSON::MaybeXS(3)