1CGI::Ex::JSONDump(3)  User Contributed Perl Documentation CGI::Ex::JSONDump(3)
2
3
4

NAME

6       CGI::Ex::JSONDump - Comprehensive data to JSON dump.
7

VERSION

9       version 2.54
10

SYNOPSIS

12           use CGI::Ex::JSONDump;
13
14           my $js = JSONDump(\%complex_data, {pretty => 1});
15
16           ### OR
17
18           my $js = CGI::Ex::JSONDump->new({pretty => 1})->dump(\%complex_data);
19

DESCRIPTION

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
26       CGI::Ex::JSONDump has roughly the same output as JSON::objToJson, but
27       with the following differences:
28
29           - 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

METHODS

38       new Create a CGI::Ex::JSONDump object.  Takes arguments hashref as
39           single argument.
40
41               my $obj = CGI::Ex::JSONDump->new(\%args);
42
43           See the arguments section for a list of the possible arguments.
44
45       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
50       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

FUNCTIONS

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
60               JSONDump($data, $args);
61
62           Is the same as:
63
64               CGI::Ex::JSONDump->new($args)->dump($data);
65

ARGUMENTS

67       The following arguments may be passed to the new method or as the
68       second argument to the JSONDump function.
69
70       pretty
71           0 or 1.  Default 0 (false).  If true then dumped structures will
72           include whitespace to make them more readable.
73
74                JSONDump({a => [1, 2]}, {pretty => 0});
75                JSONDump({a => [1, 2]}, {pretty => 1});
76
77                Would print
78
79                {"a":[1,2]}
80                {
81                  "a" : [
82                    1,
83                    2
84                  ]
85                }
86
87       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
92                JSONDump("a", {single_quote => 0});
93                JSONDump("a", {single_quote => 1});
94
95                Would print
96
97                "a"
98                'a'
99
100       sort_keys
101           0 or 1.  Default 1 (true)
102
103           If true, then key/value pairs of hashrefs will be output in sorted
104           order.
105
106       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
110           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
115       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
123               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
128                       return $self->js_escape("Ref=" . ref $data);
129                   },
130                   pretty => 0,
131               });
132
133               Would print
134
135               {"a":"Ref=A","b":1}
136
137           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
141               JSONDump({a => bless({}, 'A'), b => 1}, {pretty => 0});
142
143               Would print
144
145               {"b":1}
146
147       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
153               JSONDump({a => 1, b => 1}, {skip_keys => ['a'], pretty => 0});
154
155               Would print
156
157               {"b":1}
158
159       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
164               JSONDump({a => 1, _b => 1}, {skip_keys_qr => qr/^_/, pretty => 0});
165
166               Would print
167
168               {"a":1}
169
170       indent
171           The level to indent each nested data structure level if pretty is
172           true.  Default is "  " (two spaces).
173
174       hash_nl
175           The whitespace to add after each hashref key/value pair if pretty
176           is true.  Default is "\n".
177
178       hash_sep
179           The separator and whitespace to put between each hashref key/value
180           pair if pretty is true.  Default is " : ".
181
182       array_nl
183           The whitespace to add after each arrayref entry if pretty is true.
184           Default is "\n".
185
186       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
191               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
195               Would print
196
197               "This is a long string\n"
198                 +"with plenty of embedded newlines\n"
199                 +"and is greater than 80 characters.\n"
200
201               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
205               Would print
206
207               "This is a long string\nwith plenty of embedded newlines\nand is greater than 80 characters.\n"
208
209           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
213       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
220           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
226               JSONDump("<html><!-- comment --><script></script></html>");
227
228               Would print
229
230               "<htm"+"l><!-"+"- comment --"+"><scrip"+"t></scrip"+"t></htm"+"l>"
231
232               With the flag
233
234               JSONDump("<html><!-- comment --><script></script></html>", {no_tag_splitting => 1});
235
236               Would print
237
238               "<html><!-- comment --><script></script></html>"
239

LICENSE

241       This module may distributed under the same terms as Perl itself.
242

AUTHORS

244       Paul Seamons <perl at seamons dot com>
245
246
247
248perl v5.38.0                      2023-07-20              CGI::Ex::JSONDump(3)
Impressum