Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CGI::Ex::JSONDump(3)  User Contributed Perl Documentation CGI::Ex::JSONDump(3)

NAME
       CGI::Ex::JSONDump - Comprehensive data to JSON dump.

VERSION
       version 2.50

SYNOPSIS
	   use CGI::Ex::JSONDump;

	   my $js = JSONDump(\%complex_data, {pretty =>	1});

	   ### OR

	   my $js = CGI::Ex::JSONDump->new({pretty => 1})->dump(\%complex_data);

DESCRIPTION
       CGI::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.32.0			  2020-07-08		  CGI::Ex::JSONDump(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | FUNCTIONS | ARGUMENTS | LICENSE | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CGI::Ex::JSONDump&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help