README
1NAME
2 JSON::Any - Wrapper Class for the various JSON classes.
3
4VERSION
5 Version 1.29
6
7SYNOPSIS
8 This module tries to provide a coherent API to bring together the
9 various JSON modules currently on CPAN. This module will allow you to
10 code to any JSON API and have it work regardless of which JSON module is
11 actually installed.
12
13 use JSON::Any;
14
15 my $j = JSON::Any->new;
16
17 $json = $j->objToJson({foo=>'bar', baz=>'quux'});
18 $obj = $j->jsonToObj($json);
19
20 or
21
22 $json = $j->encode({foo=>'bar', baz=>'quux'});
23 $obj = $j->decode($json);
24
25 or
26
27 $json = $j->Dump({foo=>'bar', baz=>'quux'});
28 $obj = $j->Load($json);
29
30 or
31
32 $json = $j->to_json({foo=>'bar', baz=>'quux'});
33 $obj = $j->from_json($json);
34
35 or without creating an object:
36
37 $json = JSON::Any->objToJson({foo=>'bar', baz=>'quux'});
38 $obj = JSON::Any->jsonToObj($json);
39
40 On load, JSON::Any will find a valid JSON module in your @INC by looking
41 for them in this order:
42
43 JSON::XS
44 JSON
45 JSON::DWIW
46
47 And loading the first one it finds.
48
49 You may change the order by specifying it on the "use JSON::Any" line:
50
51 use JSON::Any qw(DWIW XS JSON);
52
53 Specifying an order that is missing one of the modules will prevent that
54 module from being used:
55
56 use JSON::Any qw(DWIW XS JSON);
57
58 This will check in that order, and will never attempt to load
59 JSON::Syck. This can also be set via the $ENV{JSON_ANY_ORDER}
60 environment variable.
61
62 JSON::Syck has been deprecated by it's author, but in the attempt to
63 still stay relevant as a "Compat Layer" JSON::Any still supports it.
64 This support however has been made optional starting with JSON::Any
65 1.19. In deference to a bug request starting with JSON 1.20 JSON::Syck
66 and other deprecated modules will still be installed, but only as a last
67 resort and will now include a warning.
68
69 use JSON::Any qw(Syck XS JSON);
70
71 or
72
73 $ENV{JSON_ANY_ORDER} = 'Syck XS JSON';
74
75 WARNING: If you call JSON::Any with an empty list
76
77 use JSON::Any ();
78
79 It will skip the JSON package detection routines and will die loudly
80 that it couldn't find a package.
81
82DEPRECATION
83 The original need for JSON::Any has been solved (quite some time ago
84 actually). If you're producing new code it is recommended to use JSON.pm
85 which will optionally use JSON::XS for speed purposes.
86
87 JSON::Any will continue to be maintained for compatibility with existing
88 code, and frankly because the maintainer prefers the JSON::Any API.
89
90METHODS
91 "new"
92 Will take any of the parameters for the underlying system and pass
93 them through. However these values don't map between JSON modules,
94 so, from a portability standpoint this is really only helpful for
95 those parameters that happen to have the same name. This will be
96 addressed in a future release.
97
98 The one parameter that is universally supported (to the extent that
99 is supported by the underlying JSON modules) is "utf8". When this
100 parameter is enabled all resulting JSON will be marked as unicode,
101 and all unicode strings in the input data structure will be
102 preserved as such.
103
104 Also note that the "allow_blessed" parameter is recognised by all
105 the modules that throw exceptions when a blessed reference is given
106 them meaning that setting it to true works for all modules. Of
107 course, that means that you cannot set it to false intentionally in
108 order to always get such exceptions.
109
110 The actual output will vary, for example JSON will encode and decode
111 unicode chars (the resulting JSON is not unicode) whereas JSON::XS
112 will emit unicode JSON.
113
114 "handlerType"
115 Takes no arguments, returns a string indicating which JSON Module is
116 in use.
117
118 "handler"
119 Takes no arguments, if called on an object returns the internal
120 JSON::* object in use. Otherwise returns the JSON::* package we are
121 using for class methods.
122
123 "true"
124 Takes no arguments, returns the special value that the internal JSON
125 object uses to map to a JSON "true" boolean.
126
127 "false"
128 Takes no arguments, returns the special value that the internal JSON
129 object uses to map to a JSON "false" boolean.
130
131 "objToJson"
132 Takes a single argument, a hashref to be converted into JSON. It
133 returns the JSON text in a scalar.
134
135 "to_json"
136 "Dump"
137 "encode"
138 Aliases for objToJson, can be used interchangeably, regardless of
139 the underlying JSON module.
140
141 "jsonToObj"
142 Takes a single argument, a string of JSON text to be converted back
143 into a hashref.
144
145 "from_json"
146 "Load"
147 "decode"
148 Aliases for jsonToObj, can be used interchangeably, regardless of
149 the underlying JSON module.
150
151AUTHORS
152 Chris Thompson "cthom at cpan.org"
153
154 Chris Prather "chris at prather.org"
155
156 Robin Berjon "robin at berjon.com"
157
158 Marc Mims "marc at questright.com"
159
160 Tomas Doran "bobtfish at bobtfish.net"
161
162BUGS
163 Please report any bugs or feature requests to "bug-json-any at
164 rt.cpan.org", or through the web interface at
165 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=JSON-Any>. I will be
166 notified, and then you'll automatically be notified of progress on your
167 bug as I make changes.
168
169ACKNOWLEDGEMENTS
170 This module came about after discussions on irc.perl.org about the fact
171 that there were now six separate JSON perl modules with different
172 interfaces.
173
174 In the spirit of Class::Any, JSON::Any was created with the considerable
175 help of Matt 'mst' Trout.
176
177 Simon Wistow graciously supplied a patch for backwards compat with
178 JSON::XS versions previous to 2.01
179
180 San Dimas High School Football Rules!
181
182COPYRIGHT & LICENSE
183 Copyright 2007-2009 Chris Thompson, some rights reserved.
184
185 This program is free software; you can redistribute it and/or modify it
186 under the same terms as Perl itself.
187
188