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 | |
34 | 1; |
44459f01 |
35 | |
36 | =head1 NAME |
37 | |
38 | JSON::MaybeXS - use L<Cpanel::JSON::XS> with a fallback to L<JSON::PP> |
39 | |
40 | =head1 SYNOPSIS |
41 | |
42 | use JSON::MaybeXS; |
43 | |
44 | my $data_structure = decode_json($json_input); |
45 | |
46 | my $json_output = encode_json($data_structure); |
47 | |
48 | my $json = JSON->new; |
49 | |
50 | =head1 DESCRIPTION |
51 | |
52 | This module tries to load L<Cpanel::JSON::XS>, and if that fails instead |
53 | tries to load L<JSON::PP>. If neither is available, an exception will be |
54 | thrown. |
55 | |
56 | It then exports the C<encode_json> and C<decode_json> functions from the |
57 | loaded module, along with a C<JSON> constant that returns the class name |
58 | for calling C<new> on. |
59 | |
60 | =head1 EXPORTS |
61 | |
62 | All of C<encode_json>, C<decode_json> and C<JSON> are exported by default. |
63 | |
64 | To import only some symbols, specify them on the C<use> line: |
65 | |
66 | use JSON::MaybeXS qw(encode_json decode_json); # functions only |
67 | |
68 | use JSON::MaybeXS qw(JSON); # JSON constant only |
69 | |
70 | =head2 encode_json |
71 | |
72 | This is the C<encode_json> function provided by the selected implementation |
73 | module, and takes a perl data stucture which is serialised to JSON text. |
74 | |
75 | my $json_text = encode_json($data_structure); |
76 | |
77 | =head2 decode_json |
78 | |
79 | This is the C<decode_json> function provided by the selected implementation |
80 | module, and takes a string of JSON text to deserialise to a perl data structure. |
81 | |
82 | my $data_structure = decode_json($json_text); |
83 | |
84 | =head2 JSON |
85 | |
86 | The C<JSON> constant returns the selected implementation module's name for |
87 | use as a class name - so: |
88 | |
89 | my $json_obj = JSON->new; # returns a Cpanel::JSON::XS or JSON::PP object |
90 | |
91 | and that object can then be used normally: |
92 | |
93 | my $data_structure = $json_obj->decode($json_text); # etc. |
94 | |
95 | =head1 AUTHOR |
96 | |
97 | mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk> |
98 | |
99 | =head1 CONTRIBUTORS |
100 | |
101 | None yet. Well volunteered? :) |
102 | |
103 | =head1 COPYRIGHT |
104 | |
105 | Copyright (c) 2013 the C<JSON::MaybeXS> L</AUTHOR> and L</CONTRIBUTORS> |
106 | as listed above. |
107 | |
108 | =head1 LICENSE |
109 | |
110 | This library is free software and may be distributed under the same terms |
111 | as perl itself. |
112 | |
113 | =cut |