1CGI::Ex::JSONDump(3) User Contributed Perl Documentation CGI::Ex::JSONDump(3)
2
6 CGI::Ex::JSONDump - Comprehensive data to JSON dump.
7
9 use CGI::Ex::JSONDump;
10 my $js = JSONDump(\%complex_data, {pretty => 1});
12 ### OR
14 my $js = CGI::Ex::JSONDump->new({pretty => 1})->dump(\%complex_data);
16
18 CGI::Ex::JSONDump is a very lightweight and fast perl data structure to
19 javascript object notation dumper. This is useful for AJAX style
20 methods, or dynamic page creation that needs to embed perl data in the
21 presented page.
22 CGI::Ex::JSONDump has roughly the same output as JSON::objToJson, but
24 with the following differences:
25 - CGI::Ex::JSONDump is much much lighter and smaller (a whopping 134 lines).
27 - It dumps Javascript in more browser friendly format (handling of </script> tags).
28 - It removes unknown key types by default instead of dying.
29 - It allows for a general handler to handle unknown key types.
30 - It allows for fine grain control of all whitespace.
31 - It allows for skipping keys by name or by regex.
32 - It dumps both data structures and scalar types.
33
35 new Create a CGI::Ex::JSONDump object. Takes arguments hashref as
36 single argument.
37 my $obj = CGI::Ex::JSONDump->new(\%args);
39 See the arguments section for a list of the possible arguments.
41 dump
43 Takes a perl data structure or scalar string or number and returns
44 a string containing the javascript representation of that string
45 (in Javascript object notation - JSON).
46 js_escape
48 Takes a scalar string or number and returns a javascript escaped
49 string that will embed properly in javascript. All numbers and
50 strings of nested data structures are passed through this method.
51
53 JSONDump
54 A wrapper around the new and dump methods. Takes a structure to
55 dump and optional args to pass to the new routine.
56 JSONDump($data, $args);
58 Is the same as:
60 CGI::Ex::JSONDump->new($args)->dump($data);
62
64 The following arguments may be passed to the new method or as the
65 second argument to the JSONDump function.
66 pretty
68 0 or 1. Default 0 (false). If true then dumped structures will
69 include whitespace to make them more readable.
70 JSONDump({a => [1, 2]}, {pretty => 0});
72 JSONDump({a => [1, 2]}, {pretty => 1});
73 Would print
75 {"a":[1,2]}
77 {
78 "a" : [
79 1,
80 2
81 ]
82 }
83 single_quote
85 0 or 1. Default 0 (false). If true then escaped values will be
86 quoted with single quotes. Otherwise values are quoted with double
87 quotes.
88 JSONDump("a", {single_quote => 0});
90 JSONDump("a", {single_quote => 1});
91 Would print
93 "a"
95 'a'
96 sort_keys
98 0 or 1. Default 1 (true)
99 If true, then key/value pairs of hashrefs will be output in sorted
101 order.
102 play_coderefs
104 0 or 1. Default 0 (false). If true, then any code refs will be
105 executed and the returned string will be dumped.
106 If false, then keys of hashrefs that contain coderefs will be
108 skipped (unless the handle_unknown_types property is set).
109 Coderefs that are in arrayrefs will show up as "CODE(0x814c648)"
110 unless the handle_unknown_types property is set.
111 handle_unknown_types
113 Default undef. If true it should contain a coderef that will be
114 called if any unknown types are encountered. The only default
115 known types are scalar string or number values, unblessed HASH refs
116 and ARRAY refs (and CODE refs if the play_coderefs property is
117 set). All other types will be passed to the handle_unknown_types
118 method call.
119 JSONDump({a => bless({}, 'A'), b => 1}, {
121 handle_unknown_types => sub {
122 my $self = shift; # a JSON object
123 my $data = shift; # the object to dump
124 return $self->js_escape("Ref=" . ref $data);
126 },
127 pretty => 0,
128 });
129 Would print
131 {"a":"Ref=A","b":1}
133 If the handle_unknown_types method is not set then keys hashrefs
135 that have values with unknown types will not be included in the
136 javascript output.
137 JSONDump({a => bless({}, 'A'), b => 1}, {pretty => 0});
139 Would print
141 {"b":1}
143 skip_keys
145 Should contain an arrayref of keys or a hashref whose keys are the
146 keys to skip. Default is unset. Any keys of hashrefs (including
147 nested hashrefs) that are listed in the skip_keys item will not be
148 included in the javascript output.
149 JSONDump({a => 1, b => 1}, {skip_keys => ['a'], pretty => 0});
151 Would print
153 {"b":1}
155 skip_keys_qr
157 Similar to skip_keys but should contain a regex. Any keys of
158 hashrefs (including nested hashrefs) that match the skip_keys_qr
159 regex will not be included in the javascript output.
160 JSONDump({a => 1, _b => 1}, {skip_keys_qr => qr/^_/, pretty => 0});
162 Would print
164 {"a":1}
166 indent
168 The level to indent each nested data structure level if pretty is
169 true. Default is " " (two spaces).
170 hash_nl
172 The whitespace to add after each hashref key/value pair if pretty
173 is true. Default is "\n".
174 hash_sep
176 The separator and whitespace to put between each hashref key/value
177 pair if pretty is true. Default is " : ".
178 array_nl
180 The whitespace to add after each arrayref entry if pretty is true.
181 Default is "\n".
182 str_nl
184 The whitespace to add in between newline separated strings if
185 pretty is true or the output line is greater than 80 characters.
186 Default is "\n" (if pretty is true).
187 JSONDump("This is a long string\n"
189 ."with plenty of embedded newlines\n"
190 ."and is greater than 80 characters.\n", {pretty => 1});
191 Would print
193 "This is a long string\n"
195 +"with plenty of embedded newlines\n"
196 +"and is greater than 80 characters.\n"
197 JSONDump("This is a long string\n"
199 ."with plenty of embedded newlines\n"
200 ."and is greater than 80 characters.\n", {pretty => 1, str_nl => ""});
201 Would print
203 "This is a long string\nwith plenty of embedded newlines\nand is greater than 80 characters.\n"
205 If the string is less than 80 characters, or if str_nl is set to
207 "", then the escaped string will be contained on a single line.
208 Setting pretty to 0 effectively sets str_nl equal to "".
209 no_tag_splitting
211 Default off. If JSON is embedded in an HTML document and the JSON
212 contains "<html>", "</html>", "<script>", "</script>", "<!--", or ,
213 "-->" tags, they are split apart with a quote, a +, and a quote.
214 This allows the embedded tags to not affect the currently playing
215 JavaScript.
216 However, if the JSON that is output is intended for deserialization
218 by another non-javascript-engine JSON parser, this splitting
219 behavior may cause errors when the JSON is imported. To avoid the
220 splitting behavior in these cases you can use the no_tag_splitting
221 flag to turn off the behavior.
222 JSONDump("<html><!-- comment --><script></script></html>");
224 Would print
226 "<htm"+"l><!-"+"- comment --"+"><scrip"+"t></scrip"+"t></htm"+"l>"
228 With the flag
230 JSONDump("<html><!-- comment --><script></script></html>", {no_tag_splitting => 1});
232 Would print
234 "<html><!-- comment --><script></script></html>"
236
238 This module may distributed under the same terms as Perl itself.
239
241 Paul Seamons <perl at seamons dot com>
242perl v5.12.1 2010-02-25 CGI::Ex::JSONDump(3)