summaryrefslogtreecommitdiff
path: root/systems/texlive/tlnet/tlpkg/tlperl/site/lib/JSON/MaybeXS.pm
blob: 302b01cb65a3c7be80465ea0174372716592ae9b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
package JSON::MaybeXS;

use strict;
use warnings FATAL => 'all';
use base qw(Exporter);

our $VERSION = '1.004000';
$VERSION = eval $VERSION;

sub _choose_json_module {
    return 'Cpanel::JSON::XS' if $INC{'Cpanel/JSON/XS.pm'};
    return 'JSON::XS'         if $INC{'JSON/XS.pm'};

    my @err;

    return 'Cpanel::JSON::XS' if eval { require Cpanel::JSON::XS; 1; };
    push @err, "Error loading Cpanel::JSON::XS: $@";

    return 'JSON::XS' if eval { require JSON::XS; 1; };
    push @err, "Error loading JSON::XS: $@";

    return 'JSON::PP' if eval { require JSON::PP; 1 };
    push @err, "Error loading JSON::PP: $@";

    die join( "\n", "Couldn't load a JSON module:", @err );

}

BEGIN {
    our $JSON_Class = _choose_json_module();
    $JSON_Class->import(qw(encode_json decode_json));
    no strict 'refs';
    *$_ = $JSON_Class->can($_)
      for qw(true false);
}

our @EXPORT = qw(encode_json decode_json JSON);
my @EXPORT_ALL = qw(is_bool);
our @EXPORT_OK = qw(is_bool to_json from_json);
our %EXPORT_TAGS = ( all => [ @EXPORT, @EXPORT_ALL ],
                     legacy => [ @EXPORT, @EXPORT_OK ],
                   );

sub JSON () { our $JSON_Class }

sub new {
  shift;
  my %args = @_ == 1 ? %{$_[0]} : @_;
  my $new = (our $JSON_Class)->new;
  $new->$_($args{$_}) for keys %args;
  return $new;
}

use Scalar::Util ();

sub is_bool {
  die 'is_bool is not a method' if $_[1];

  Scalar::Util::blessed($_[0])
    and ($_[0]->isa('JSON::XS::Boolean')
      or $_[0]->isa('Cpanel::JSON::XS::Boolean')
      or $_[0]->isa('JSON::PP::Boolean'));
}

# (mostly) CopyPasta from JSON.pm version 2.90
use Carp ();

sub from_json ($@) {
    if ( ref($_[0]) =~ /^JSON/ or $_[0] =~ /^JSON/ ) {
        Carp::croak "from_json should not be called as a method.";
    }
    my $json = JSON()->new;

    if (@_ == 2 and ref $_[1] eq 'HASH') {
        my $opt  = $_[1];
        for my $method (keys %$opt) {
            $json->$method( $opt->{$method} );
        }
    }

    return $json->decode( $_[0] );
}

sub to_json ($@) {
    if (
        ref($_[0]) =~ /^JSON/
        or (@_ > 2 and $_[0] =~ /^JSON/)
          ) {
               Carp::croak "to_json should not be called as a method.";
    }
    my $json = JSON()->new;

    if (@_ == 2 and ref $_[1] eq 'HASH') {
        my $opt  = $_[1];
        for my $method (keys %$opt) {
            $json->$method( $opt->{$method} );
        }
    }

    $json->encode($_[0]);
}

1;

=head1 NAME

JSON::MaybeXS - Use L<Cpanel::JSON::XS> with a fallback to L<JSON::XS> and L<JSON::PP>

=head1 SYNOPSIS

  use JSON::MaybeXS;

  my $data_structure = decode_json($json_input);

  my $json_output = encode_json($data_structure);

  my $json = JSON()->new;

  my $json_with_args = JSON::MaybeXS->new(utf8 => 1); # or { utf8 => 1 }

=head1 DESCRIPTION

This module first checks to see if either L<Cpanel::JSON::XS> or
L<JSON::XS> is already loaded, in which case it uses that module. Otherwise
it tries to load L<Cpanel::JSON::XS>, then L<JSON::XS>, then L<JSON::PP>
in order, and either uses the first module it finds or throws an error.

It then exports the C<encode_json> and C<decode_json> functions from the
loaded module, along with a C<JSON> constant that returns the class name
for calling C<new> on.

If you're writing fresh code rather than replacing L<JSON.pm|JSON> usage, you might
want to pass options as constructor args rather than calling mutators, so
we provide our own C<new> method that supports that.

=head1 EXPORTS

C<encode_json>, C<decode_json> and C<JSON> are exported by default; C<is_bool>
is exported on request.

To import only some symbols, specify them on the C<use> line:

  use JSON::MaybeXS qw(encode_json decode_json is_bool); # functions only

  use JSON::MaybeXS qw(JSON); # JSON constant only

To import all available sensible symbols (C<encode_json>, C<decode_json>, and
C<is_bool>), use C<:all>:

  use JSON::MaybeXS ':all';

To import all symbols including those needed by legacy apps that use L<JSON::PP>:

  use JSON::MaybeXS ':legacy';

This imports the C<to_json> and C<from_json> symbols as well as everything in
C<:all>.  NOTE: This is to support legacy code that makes extensive
use of C<to_json> and C<from_json> which you are not yet in a position to
refactor.  DO NOT use this import tag in new code, in order to avoid
the crawling horrors of getting UTF-8 support subtly wrong.  See the
documentation for L<JSON> for further details.

=head2 encode_json

This is the C<encode_json> function provided by the selected implementation
module, and takes a perl data structure which is serialised to JSON text.

  my $json_text = encode_json($data_structure);

=head2 decode_json

This is the C<decode_json> function provided by the selected implementation
module, and takes a string of JSON text to deserialise to a perl data structure.

  my $data_structure = decode_json($json_text);

=head2 to_json, from_json

See L<JSON> for details.  These are included to support legacy code
B<only>.

=head2 JSON

The C<JSON> constant returns the selected implementation module's name for
use as a class name - so:

  my $json_obj = JSON()->new; # returns a Cpanel::JSON::XS or JSON::PP object

and that object can then be used normally:

  my $data_structure = $json_obj->decode($json_text); # etc.

The use of parentheses here is optional, and only used as a hint to the reader
that this use of C<JSON> is a I<subroutine> call, I<not> a class name.

=head2 is_bool

  $is_boolean = is_bool($scalar)

Returns true if the passed scalar represents either C<true> or
C<false>, two constants that act like C<1> and C<0>, respectively
and are used to represent JSON C<true> and C<false> values in Perl.

Since this is a bare sub in the various backend classes, it cannot be called as
a class method like the other interfaces; it must be called as a function, with
no invocant.  It supports the representation used in all JSON backends.

=head1 CONSTRUCTOR

=head2 new

With L<JSON::PP>, L<JSON::XS> and L<Cpanel::JSON::XS> you are required to call
mutators to set options, such as:

  my $json = $class->new->utf8(1)->pretty(1);

Since this is a trifle irritating and noticeably un-perlish, we also offer:

  my $json = JSON::MaybeXS->new(utf8 => 1, pretty => 1);

which works equivalently to the above (and in the usual tradition will accept
a hashref instead of a hash, should you so desire).

The resulting object is blessed into the underlying backend, which offers (at
least) the methods C<encode> and C<decode>.

=head1 BOOLEANS

To include JSON-aware booleans (C<true>, C<false>) in your data, just do:

    use JSON::MaybeXS;
    my $true = JSON()->true;
    my $false = JSON()->false;

The booleans are also available as subs or methods on JSON::MaybeXS.

    use JSON::MaybeXS ();
    my $true = JSON::MaybeXS::true;
    my $true = JSON::MaybeXS->true;
    my $false = JSON::MaybeXS::false;
    my $false = JSON::MaybeXS->false;

=head1 CONVERTING FROM JSON::Any

L<JSON::Any> used to be the favoured compatibility layer above the various
JSON backends, but over time has grown a lot of extra code to deal with legacy
backends (e.g. L<JSON::Syck>) that are no longer needed.  This is a rough guide of translating such code:

Change code from:

    use JSON::Any;
    my $json = JSON::Any->new->objToJson($data);    # or to_json($data), or Dump($data)

to:

    use JSON::MaybeXS;
    my $json = encode_json($data);


Change code from:

    use JSON::Any;
    my $data = JSON::Any->new->jsonToObj($json);    # or from_json($json), or Load($json)

to:

    use JSON::MaybeXS;
    my $json = decode_json($data);

=head1 CAVEATS

The C<new()> method in this module is technically a factory, not a
constructor, because the objects it returns will I<NOT> be blessed into the
C<JSON::MaybeXS> class.

If you are using an object returned by this module as a Moo(se) attribute,
this type constraint code:

    is 'json' => ( isa => 'JSON::MaybeXS' );

will I<NOT> do what you expect. Instead, either rely on the C<JSON> class
constant described above, as so:

    is 'json' => ( isa => JSON::MaybeXS::JSON() );

Alternatively, you can use duck typing:

    use Moose::Util::TypeConstraints 'duck_type';
    is 'json' => ( isa => Object , duck_type([qw/ encode decode /]));

=head1 INSTALLATION

At installation time, F<Makefile.PL> will attempt to determine if you have a
working compiler available, and therefore whether you are able to run XS code.
If so, L<Cpanel::JSON::XS> will be added to the prerequisite list, unless
L<JSON::XS> is already installed at a high enough version. L<JSON::XS> may
also be upgraded to fix any incompatibility issues.

Because running XS code is not mandatory and L<JSON::PP> (which is in perl
core) is used as a fallback backend, this module is safe to be used in a suite
of code that is fatpacked or installed into a restricted-resource environment.

You can also prevent any XS dependencies from being installed by setting
C<PUREPERL_ONLY=1> in F<Makefile.PL> options (or in the C<PERL_MM_OPT>
environment variable), or using the C<--pp> or C<--pureperl> flags with the
L<cpanminus client|cpanm>.

=head1 AUTHOR

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

=head1 CONTRIBUTORS

=over 4

=item * Clinton Gormley <drtech@cpan.org>

=item * Karen Etheridge <ether@cpan.org>

=item * Kieren Diment <diment@gmail.com>

=back

=head1 COPYRIGHT

Copyright (c) 2013 the C<JSON::MaybeXS> L</AUTHOR> and L</CONTRIBUTORS>
as listed above.

=head1 LICENSE

This library is free software and may be distributed under the same terms
as perl itself.

=cut