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