Commit | Line | Data |
3be1e192 |
1 | package JSON::MaybeXS; |
2 | |
3 | use strict; |
4 | use warnings FATAL => 'all'; |
5 | use base qw(Exporter); |
6 | |
0975ef16 |
7 | our $VERSION = '1.002000'; |
44459f01 |
8 | |
16205c4a |
9 | sub _choose_json_module { |
10 | return 'Cpanel::JSON::XS' if $INC{'Cpanel/JSON/XS.pm'}; |
11 | return 'JSON::XS' if $INC{'JSON/XS.pm'}; |
3be1e192 |
12 | |
16205c4a |
13 | my @err; |
3be1e192 |
14 | |
16205c4a |
15 | return 'Cpanel::JSON::XS' if eval { require Cpanel::JSON::XS; 1; }; |
3be1e192 |
16 | push @err, "Error loading Cpanel::JSON::XS: $@"; |
16205c4a |
17 | |
18 | return 'JSON::XS' if eval { require JSON::XS; 1; }; |
19 | push @err, "Error loading JSON::XS: $@"; |
20 | |
21 | return 'JSON::PP' if eval { require JSON::PP; 1 }; |
22 | push @err, "Error loading JSON::PP: $@"; |
23 | |
24 | die join( "\n", "Couldn't load a JSON module:", @err ); |
25 | |
26 | } |
27 | |
28 | BEGIN { |
29 | our $JSON_Class = _choose_json_module(); |
30 | $JSON_Class->import(qw(encode_json decode_json)); |
3be1e192 |
31 | } |
32 | |
33 | our @EXPORT = qw(encode_json decode_json JSON); |
34 | |
35 | sub JSON () { our $JSON_Class } |
36 | |
939f9a29 |
37 | sub new { |
38 | shift; |
39 | my %args = @_ == 1 ? %{$_[0]} : @_; |
40 | my $new = (our $JSON_Class)->new; |
41 | $new->$_($args{$_}) for keys %args; |
42 | return $new; |
43 | } |
44 | |
3be1e192 |
45 | 1; |
44459f01 |
46 | |
47 | =head1 NAME |
48 | |
16205c4a |
49 | JSON::MaybeXS - use L<Cpanel::JSON::XS> with a fallback to L<JSON::XS> and L<JSON::PP> |
44459f01 |
50 | |
51 | =head1 SYNOPSIS |
52 | |
53 | use JSON::MaybeXS; |
54 | |
55 | my $data_structure = decode_json($json_input); |
56 | |
57 | my $json_output = encode_json($data_structure); |
58 | |
59 | my $json = JSON->new; |
60 | |
939f9a29 |
61 | my $json_with_args = JSON::MaybeXS->new(utf8 => 1); # or { utf8 => 1 } |
62 | |
44459f01 |
63 | =head1 DESCRIPTION |
64 | |
16205c4a |
65 | This module first checks to see if either L<Cpanel::JSON::XS> or |
66 | L<JSON::XS> is already loaded, in which case it uses that module. Otherwise |
67 | it tries to load L<Cpanel::JSON::XS>, then L<JSON::XS>, then L<JSON::PP> |
68 | in order, and either uses the first module it finds or throws an error. |
44459f01 |
69 | |
70 | It then exports the C<encode_json> and C<decode_json> functions from the |
71 | loaded module, along with a C<JSON> constant that returns the class name |
72 | for calling C<new> on. |
73 | |
939f9a29 |
74 | If you're writing fresh code rather than replacing JSON.pm usage, you might |
75 | want to pass options as constructor args rather than calling mutators, so |
76 | we provide our own C<new> method that supports that. |
77 | |
44459f01 |
78 | =head1 EXPORTS |
79 | |
80 | All of C<encode_json>, C<decode_json> and C<JSON> are exported by default. |
81 | |
82 | To import only some symbols, specify them on the C<use> line: |
83 | |
84 | use JSON::MaybeXS qw(encode_json decode_json); # functions only |
85 | |
86 | use JSON::MaybeXS qw(JSON); # JSON constant only |
87 | |
88 | =head2 encode_json |
89 | |
90 | This is the C<encode_json> function provided by the selected implementation |
0629a8af |
91 | module, and takes a perl data structure which is serialised to JSON text. |
44459f01 |
92 | |
93 | my $json_text = encode_json($data_structure); |
94 | |
95 | =head2 decode_json |
96 | |
97 | This is the C<decode_json> function provided by the selected implementation |
98 | module, and takes a string of JSON text to deserialise to a perl data structure. |
99 | |
100 | my $data_structure = decode_json($json_text); |
101 | |
102 | =head2 JSON |
103 | |
104 | The C<JSON> constant returns the selected implementation module's name for |
105 | use as a class name - so: |
106 | |
107 | my $json_obj = JSON->new; # returns a Cpanel::JSON::XS or JSON::PP object |
108 | |
109 | and that object can then be used normally: |
110 | |
111 | my $data_structure = $json_obj->decode($json_text); # etc. |
112 | |
939f9a29 |
113 | =head1 CONSTRUCTOR |
114 | |
115 | =head2 new |
116 | |
16205c4a |
117 | With L<JSON::PP>, L<JSON::XS> and L<Cpanel::JSON::XS> you are required to call |
118 | mutators to set options, i.e. |
939f9a29 |
119 | |
120 | my $json = $class->new->utf8(1)->pretty(1); |
121 | |
122 | Since this is a trifle irritating and noticeably un-perlish, we also offer: |
123 | |
124 | my $json = JSON::MaybeXS->new(utf8 => 1, pretty => 1); |
125 | |
126 | which works equivalently to the above (and in the usual tradition will accept |
127 | a hashref instead of a hash, should you so desire). |
128 | |
44459f01 |
129 | =head1 AUTHOR |
130 | |
131 | mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk> |
132 | |
133 | =head1 CONTRIBUTORS |
134 | |
135 | None yet. Well volunteered? :) |
136 | |
137 | =head1 COPYRIGHT |
138 | |
139 | Copyright (c) 2013 the C<JSON::MaybeXS> L</AUTHOR> and L</CONTRIBUTORS> |
140 | as listed above. |
141 | |
142 | =head1 LICENSE |
143 | |
144 | This library is free software and may be distributed under the same terms |
145 | as perl itself. |
146 | |
147 | =cut |