1CGI::Ex::JSONDump(3) User Contributed Perl Documentation CGI::Ex::JSONDump(3)
2
6 CGI::Ex::JSONDump - Comprehensive data to JSON dump.
7
9 version 2.54
10
12 use CGI::Ex::JSONDump;
13 my $js = JSONDump(\%complex_data, {pretty => 1});
15 ### OR
17 my $js = CGI::Ex::JSONDump->new({pretty => 1})->dump(\%complex_data);
19
21 CGI::Ex::JSONDump is a very lightweight and fast perl data structure to
22 javascript object notation dumper. This is useful for AJAX style
23 methods, or dynamic page creation that needs to embed perl data in the
24 presented page.
25 CGI::Ex::JSONDump has roughly the same output as JSON::objToJson, but
27 with the following differences:
28 - CGI::Ex::JSONDump is much much lighter and smaller (a whopping 134 lines).
30 - It dumps Javascript in more browser friendly format (handling of </script> tags).
31 - It removes unknown key types by default instead of dying.
32 - It allows for a general handler to handle unknown key types.
33 - It allows for fine grain control of all whitespace.
34 - It allows for skipping keys by name or by regex.
35 - It dumps both data structures and scalar types.
36
38 new Create a CGI::Ex::JSONDump object. Takes arguments hashref as
39 single argument.
40 my $obj = CGI::Ex::JSONDump->new(\%args);
42 See the arguments section for a list of the possible arguments.
44 dump
46 Takes a perl data structure or scalar string or number and returns
47 a string containing the javascript representation of that string
48 (in Javascript object notation - JSON).
49 js_escape
51 Takes a scalar string or number and returns a javascript escaped
52 string that will embed properly in javascript. All numbers and
53 strings of nested data structures are passed through this method.
54
56 JSONDump
57 A wrapper around the new and dump methods. Takes a structure to
58 dump and optional args to pass to the new routine.
59 JSONDump($data, $args);
61 Is the same as:
63 CGI::Ex::JSONDump->new($args)->dump($data);
65
67 The following arguments may be passed to the new method or as the
68 second argument to the JSONDump function.
69 pretty
71 0 or 1. Default 0 (false). If true then dumped structures will
72 include whitespace to make them more readable.
73 JSONDump({a => [1, 2]}, {pretty => 0});
75 JSONDump({a => [1, 2]}, {pretty => 1});
76 Would print
78 {"a":[1,2]}
80 {
81 "a" : [
82 1,
83 2
84 ]
85 }
86 single_quote
88 0 or 1. Default 0 (false). If true then escaped values will be
89 quoted with single quotes. Otherwise values are quoted with double
90 quotes.
91 JSONDump("a", {single_quote => 0});
93 JSONDump("a", {single_quote => 1});
94 Would print
96 "a"
98 'a'
99 sort_keys
101 0 or 1. Default 1 (true)
102 If true, then key/value pairs of hashrefs will be output in sorted
104 order.
105 play_coderefs
107 0 or 1. Default 0 (false). If true, then any code refs will be
108 executed and the returned string will be dumped.
109 If false, then keys of hashrefs that contain coderefs will be
111 skipped (unless the handle_unknown_types property is set).
112 Coderefs that are in arrayrefs will show up as "CODE(0x814c648)"
113 unless the handle_unknown_types property is set.
114 handle_unknown_types
116 Default undef. If true it should contain a coderef that will be
117 called if any unknown types are encountered. The only default
118 known types are scalar string or number values, unblessed HASH refs
119 and ARRAY refs (and CODE refs if the play_coderefs property is
120 set). All other types will be passed to the handle_unknown_types
121 method call.
122 JSONDump({a => bless({}, 'A'), b => 1}, {
124 handle_unknown_types => sub {
125 my $self = shift; # a JSON object
126 my $data = shift; # the object to dump
127 return $self->js_escape("Ref=" . ref $data);
129 },
130 pretty => 0,
131 });
132 Would print
134 {"a":"Ref=A","b":1}
136 If the handle_unknown_types method is not set then keys hashrefs
138 that have values with unknown types will not be included in the
139 javascript output.
140 JSONDump({a => bless({}, 'A'), b => 1}, {pretty => 0});
142 Would print
144 {"b":1}
146 skip_keys
148 Should contain an arrayref of keys or a hashref whose keys are the
149 keys to skip. Default is unset. Any keys of hashrefs (including
150 nested hashrefs) that are listed in the skip_keys item will not be
151 included in the javascript output.
152 JSONDump({a => 1, b => 1}, {skip_keys => ['a'], pretty => 0});
154 Would print
156 {"b":1}
158 skip_keys_qr
160 Similar to skip_keys but should contain a regex. Any keys of
161 hashrefs (including nested hashrefs) that match the skip_keys_qr
162 regex will not be included in the javascript output.
163 JSONDump({a => 1, _b => 1}, {skip_keys_qr => qr/^_/, pretty => 0});
165 Would print
167 {"a":1}
169 indent
171 The level to indent each nested data structure level if pretty is
172 true. Default is " " (two spaces).
173 hash_nl
175 The whitespace to add after each hashref key/value pair if pretty
176 is true. Default is "\n".
177 hash_sep
179 The separator and whitespace to put between each hashref key/value
180 pair if pretty is true. Default is " : ".
181 array_nl
183 The whitespace to add after each arrayref entry if pretty is true.
184 Default is "\n".
185 str_nl
187 The whitespace to add in between newline separated strings if
188 pretty is true or the output line is greater than 80 characters.
189 Default is "\n" (if pretty is true).
190 JSONDump("This is a long string\n"
192 ."with plenty of embedded newlines\n"
193 ."and is greater than 80 characters.\n", {pretty => 1});
194 Would print
196 "This is a long string\n"
198 +"with plenty of embedded newlines\n"
199 +"and is greater than 80 characters.\n"
200 JSONDump("This is a long string\n"
202 ."with plenty of embedded newlines\n"
203 ."and is greater than 80 characters.\n", {pretty => 1, str_nl => ""});
204 Would print
206 "This is a long string\nwith plenty of embedded newlines\nand is greater than 80 characters.\n"
208 If the string is less than 80 characters, or if str_nl is set to
210 "", then the escaped string will be contained on a single line.
211 Setting pretty to 0 effectively sets str_nl equal to "".
212 no_tag_splitting
214 Default off. If JSON is embedded in an HTML document and the JSON
215 contains "<html>", "</html>", "<script>", "</script>", "<!--", or ,
216 "-->" tags, they are split apart with a quote, a +, and a quote.
217 This allows the embedded tags to not affect the currently playing
218 JavaScript.
219 However, if the JSON that is output is intended for deserialization
221 by another non-javascript-engine JSON parser, this splitting
222 behavior may cause errors when the JSON is imported. To avoid the
223 splitting behavior in these cases you can use the no_tag_splitting
224 flag to turn off the behavior.
225 JSONDump("<html><!-- comment --><script></script></html>");
227 Would print
229 "<htm"+"l><!-"+"- comment --"+"><scrip"+"t></scrip"+"t></htm"+"l>"
231 With the flag
233 JSONDump("<html><!-- comment --><script></script></html>", {no_tag_splitting => 1});
235 Would print
237 "<html><!-- comment --><script></script></html>"
239
241 This module may distributed under the same terms as Perl itself.
242
244 Paul Seamons <perl at seamons dot com>
245perl v5.36.0 2023-01-20 CGI::Ex::JSONDump(3)