CGI::Ex::JSONDump(3) User Contributed Perl Documentation CGI::Ex::JSONDump(3)NAMECGI::Ex::JSONDump - Comprehensive data to JSON dump.
SYNOPSIS
use CGI::Ex::JSONDump;
my $js = JSONDump(\%complex_data, {pretty => 1});
### OR
my $js = CGI::Ex::JSONDump->new({pretty => 1})->dump(\%complex_data);
DESCRIPTIONCGI::Ex::JSONDump is a very lightweight and fast perl data structure to
javascript object notation dumper. This is useful for AJAX style
methods, or dynamic page creation that needs to embed perl data in the
presented page.
CGI::Ex::JSONDump has roughly the same output as JSON::objToJson, but
with the following differences:
- CGI::Ex::JSONDump is much much lighter and smaller (a whopping 134 lines).
- It dumps Javascript in more browser friendly format (handling of </script> tags).
- It removes unknown key types by default instead of dying.
- It allows for a general handler to handle unknown key types.
- It allows for fine grain control of all whitespace.
- It allows for skipping keys by name or by regex.
- It dumps both data structures and scalar types.
METHODS
new Create a CGI::Ex::JSONDump object. Takes arguments hashref as
single argument.
my $obj = CGI::Ex::JSONDump->new(\%args);
See the arguments section for a list of the possible arguments.
dump
Takes a perl data structure or scalar string or number and returns
a string containing the javascript representation of that string
(in Javascript object notation - JSON).
js_escape
Takes a scalar string or number and returns a javascript escaped
string that will embed properly in javascript. All numbers and
strings of nested data structures are passed through this method.
FUNCTIONS
JSONDump
A wrapper around the new and dump methods. Takes a structure to
dump and optional args to pass to the new routine.
JSONDump($data, $args);
Is the same as:
CGI::Ex::JSONDump->new($args)->dump($data);
ARGUMENTS
The following arguments may be passed to the new method or as the
second argument to the JSONDump function.
pretty
0 or 1. Default 0 (false). If true then dumped structures will
include whitespace to make them more readable.
JSONDump({a => [1, 2]}, {pretty => 0});
JSONDump({a => [1, 2]}, {pretty => 1});
Would print
{"a":[1,2]}
{
"a" : [
1,
2
]
}
single_quote
0 or 1. Default 0 (false). If true then escaped values will be
quoted with single quotes. Otherwise values are quoted with double
quotes.
JSONDump("a", {single_quote => 0});
JSONDump("a", {single_quote => 1});
Would print
"a"
'a'
sort_keys
0 or 1. Default 1 (true)
If true, then key/value pairs of hashrefs will be output in sorted
order.
play_coderefs
0 or 1. Default 0 (false). If true, then any code refs will be
executed and the returned string will be dumped.
If false, then keys of hashrefs that contain coderefs will be
skipped (unless the handle_unknown_types property is set).
Coderefs that are in arrayrefs will show up as "CODE(0x814c648)"
unless the handle_unknown_types property is set.
handle_unknown_types
Default undef. If true it should contain a coderef that will be
called if any unknown types are encountered. The only default
known types are scalar string or number values, unblessed HASH refs
and ARRAY refs (and CODE refs if the play_coderefs property is
set). All other types will be passed to the handle_unknown_types
method call.
JSONDump({a => bless({}, 'A'), b => 1}, {
handle_unknown_types => sub {
my $self = shift; # a JSON object
my $data = shift; # the object to dump
return $self->js_escape("Ref=" . ref $data);
},
pretty => 0,
});
Would print
{"a":"Ref=A","b":1}
If the handle_unknown_types method is not set then keys hashrefs
that have values with unknown types will not be included in the
javascript output.
JSONDump({a => bless({}, 'A'), b => 1}, {pretty => 0});
Would print
{"b":1}
skip_keys
Should contain an arrayref of keys or a hashref whose keys are the
keys to skip. Default is unset. Any keys of hashrefs (including
nested hashrefs) that are listed in the skip_keys item will not be
included in the javascript output.
JSONDump({a => 1, b => 1}, {skip_keys => ['a'], pretty => 0});
Would print
{"b":1}
skip_keys_qr
Similar to skip_keys but should contain a regex. Any keys of
hashrefs (including nested hashrefs) that match the skip_keys_qr
regex will not be included in the javascript output.
JSONDump({a => 1, _b => 1}, {skip_keys_qr => qr/^_/, pretty => 0});
Would print
{"a":1}
indent
The level to indent each nested data structure level if pretty is
true. Default is " " (two spaces).
hash_nl
The whitespace to add after each hashref key/value pair if pretty
is true. Default is "\n".
hash_sep
The separator and whitespace to put between each hashref key/value
pair if pretty is true. Default is " : ".
array_nl
The whitespace to add after each arrayref entry if pretty is true.
Default is "\n".
str_nl
The whitespace to add in between newline separated strings if
pretty is true or the output line is greater than 80 characters.
Default is "\n" (if pretty is true).
JSONDump("This is a long string\n"
."with plenty of embedded newlines\n"
."and is greater than 80 characters.\n", {pretty => 1});
Would print
"This is a long string\n"
+"with plenty of embedded newlines\n"
+"and is greater than 80 characters.\n"
JSONDump("This is a long string\n"
."with plenty of embedded newlines\n"
."and is greater than 80 characters.\n", {pretty => 1, str_nl => ""});
Would print
"This is a long string\nwith plenty of embedded newlines\nand is greater than 80 characters.\n"
If the string is less than 80 characters, or if str_nl is set to
"", then the escaped string will be contained on a single line.
Setting pretty to 0 effectively sets str_nl equal to "".
no_tag_splitting
Default off. If JSON is embedded in an HTML document and the JSON
contains "<html>", "</html>", "<script>", "</script>", "<!--", or ,
"-->" tags, they are split apart with a quote, a +, and a quote.
This allows the embedded tags to not affect the currently playing
JavaScript.
However, if the JSON that is output is intended for deserialization
by another non-javascript-engine JSON parser, this splitting
behavior may cause errors when the JSON is imported. To avoid the
splitting behavior in these cases you can use the no_tag_splitting
flag to turn off the behavior.
JSONDump("<html><!-- comment --><script></script></html>");
Would print
"<htm"+"l><!-"+"- comment --"+"><scrip"+"t></scrip"+"t></htm"+"l>"
With the flag
JSONDump("<html><!-- comment --><script></script></html>", {no_tag_splitting => 1});
Would print
"<html><!-- comment --><script></script></html>"
LICENSE
This module may distributed under the same terms as Perl itself.
AUTHORS
Paul Seamons <perl at seamons dot com>
perl v5.14.1 2010-02-25 CGI::Ex::JSONDump(3)