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

FreeBSD Manual Pages

  
 
  

home | help
JSON::DWIW(3)	      User Contributed Perl Documentation	 JSON::DWIW(3)

NAME
       JSON::DWIW - JSON converter that	Does What I Want

SYNOPSIS
	use JSON::DWIW;
	my $json_obj = JSON::DWIW->new;
	my $data = $json_obj->from_json($json_str);
	my $str	= $json_obj->to_json($data);

	my ($data, $error_string) = $json_obj->from_json($json_str);

	my $data = JSON::DWIW::deserialize($json_str);
	my $error_str =	JSON::DWIW::get_error_string();

	use JSON::DWIW qw/deserialize_json from_json/
	my $data = deserialize_json($json_str);
	my $error_str =	JSON::DWIW::get_error_string();

	my $error_string = $json_obj->get_error_string;
	my $error_data = $json_obj->get_error_data;
	my $stats = $json_obj->get_stats;

	my $data = $json_obj->from_json_file($file)
	my $ok = $json_obj->to_json_file($data,	$file);

	my $data = JSON::DWIW->from_json($json_str);
	my $str	= JSON::DWIW->to_json($data);

	my $data = JSON::DWIW->from_json($json_str, \%options);
	my $str	= JSON::DWIW->to_json($data, \%options);

	my $true_value = JSON::DWIW->true;
	my $false_value	= JSON::DWIW->false;
	my $data = { var1 => "stuff", var2 => $true_value,
		     var3 => $false_value, };
	my $str	= JSON::DWIW->to_json($data);

	my $data = JSON::DWIW::deserialize($str, { start_depth => 1,
						   start_depth_handler => $handler });

DESCRIPTION
       Other JSON modules require setting several parameters before calling
       the conversion methods to do what I want.  This module does things by
       default that I think should be done when	working	with JSON in Perl.
       This module also	encodes	and decodes faster than	JSON.pm	and JSON::Syck
       in my benchmarks.

       This means that any piece of data in Perl (assuming it's	valid unicode)
       will get	converted to something in JSON instead of throwing an
       exception.  It also means that output will be strict JSON, while
       accepted	input will be flexible,	without	having to set any options.

       For a list of changes in	recent versions, see the documentation for
       JSON::DWIW::Changes.

       This module can be downloaded from
       <http://www.cpan.org/authors/id/D/DO/DOWENS/>.

   Encoding
       Perl objects get	encoded	as their underlying data structure, with the
       exception of Math::BigInt and Math::BigFloat, which will	be output as
       numbers,	and JSON::DWIW::Boolean, which will get	output as a true or
       false value (see	the true() and false() methods).  For example, a
       blessed hash ref	will be	represented as an object in JSON, a blessed
       array will be represented as an array. etc.  A reference	to a scalar is
       dereferenced and	represented as the scalar itself.  Globs, Code refs,
       etc., get stringified, and undef	becomes	null.

       Scalars that have been used as both a string and	a number will be
       output as a string.  A reference	to a reference is currently output as
       an empty	string,	but this may change.

       You may notice there is a deserialize function, but not a serialize
       one.  The deserialize function was written as a full rewrite (the
       parsing is in a separate, event-based library now) of from_json (now
       from_json calls deserialize).  In the future, there will	be a serialize
       function	that is	a rewrite of to_json.

   Decoding
       Input is	expected to utf-8.  When decoding, null, true, and false
       become undef, 1,	and 0, repectively.  Numbers that appear to be too
       long to be supported natively are converted to Math::BigInt or
       Math::BigFloat objects, if you have them	installed.  Otherwise, long
       numbers are turned into strings to prevent data loss.

       The parser is flexible in what it accepts and handles some things not
       in the JSON spec:

       quotes
	   Both	single and double quotes are allowed for quoting a string,
	   e.g.,

	       [ "string1", 'string2' ]

       bare keys
	   Object/hash keys can	be bare	if they	look like an identifier, e.g.,

	       { var1: "myval1", var2: "myval2"	}

       extra commas
	   Extra commas	in objects/hashes and arrays are ignored, e.g.,

	       [1,2,3,,,4,]

	   becomes a 4 element array containing	1, 2, 3, and 4.

       escape sequences
	   Latin1 hexadecimal escape sequences (\xHH) are accepted, as in
	   Javascript.	Also, the vertical tab escape \v is recognized
	   (\u000b).

       comments
	   C, C++, and shell-style comments are	accepted.  That	is

	    /* this is a comment */
	    // this is a comment

	    # this is also a comment

METHODS
   "new(\%options)"
       Create a	new JSON::DWIW object.

       %options	is an optional hash of parameters that will change the
       bahavior	of this	module when encoding to	JSON.  You may also pass these
       options as the second argument to "to_json()" and "from_json()".	 The
       following options are supported:

       bare_keys

       If set to a true	value, keys in hashes will not be quoted when
       converted to JSON if they look like identifiers.	 This is valid
       Javascript in current browsers, but not in JSON.

       use_exceptions

       If set to a true	value, errors found when converting to or from JSON
       will result in "die()" being called with	the error message.  The
       default is to not use exceptions.

       bad_char_policy

       This options indicates what should be done if bad characters are	found,
       e.g., bad utf-8 sequence.  The default is to return an error and	drop
       all the output.

       The following values for	bad_char_policy	are supported:

       error

       default action, i.e., drop any output built up and return an error

       convert

       Convert to a utf-8 char using the value of the byte as a	code point.
       This is basically the same as assuming the bad character	is in latin-1
       and converting it to utf-8.

       pass_through

       Ignore the error	and pass through the raw bytes (invalid	JSON)

       escape_multi_byte

       If set to a true	value, escape all multi-byte characters	(e.g., \u00e9)
       when converting to JSON.

       ascii

       Synonym for escape_multi_byte

       pretty

       Add white space to the output when calling to_json() to make the	output
       easier for humans to read.

       convert_bool

       When converting from JSON, return objects for booleans so that "true"
       and "false" can be maintained when encoding and decoding.  If this flag
       is set, then "true" becomes a JSON::DWIW::Boolean object	that evaluates
       to true in a boolean context, and "false" becomes an object that
       evaluates to false in a boolean context.	 These objects are recognized
       by the to_json()	method,	so they	will be	output as "true" or "false"
       instead of "1" or "0".

       bare_solidus

       Don't escape solidus characters ("/") in	strings.  The output is	still
       legal JSON with this option turned on.

       minimal_escaping

       Only do required	escaping in strings (solidus and quote).  Tabs,
       newlines, backspaces, etc., will	not be escaped with this optioned
       turned on (but the output will still be valid JSON).

       sort_keys

       Set to a	true value to sort hash	keys (alphabetically) when converting
       to JSON.

       parse_number

       A subroutine reference to call when parsing a number.  The subroutine
       will be provided	one string that	is the number being parsed.  The
       return value from the subroutine	will be	used to	populate the return
       data instead of converting to a number.

       E.g.,

	 my $json = '{ "a": 6.3e-10 }';
	 my $cb	= sub {	my ($val) = @_;	return "I got the number '$val'"; };

	 my $data = JSON::DWIW::deserialize($json, { parse_number => $cb });

       parse_constant

       A subroutine reference to call when parsing a constant (true, false, or
       null).  The subroutine will be provided one string that is the constant
       being parsed.  The return value from the	subroutine will	be used	to
       populate	the return data	instead	of converting to a boolean or undef.
       See the "parse_number" option.

       start_depth

       Depth at	which "start_depth_handler" should be called.  See
       "start_depth_handler".

       start_depth_handler

       A reference to a	subroutine to called when parsing and at level
       start_depth in the data structure.  When	specified along	with
       start_depth, the	parser does not	return the entire data structure.
       Instead,	it calls start_depth_handler for each element in the array
       when the	parser is at level start_depth.	 This is useful	for parsing a
       very large array	without	loading	all the	data into memory (especially
       when using "deserialize_file").

       E.g., with start_depth set to 1 and start_depth_handler set to
       $handler:

	   my $str = '[	{ "foo": "bar",	"cat": 1 }, { "concat":	1, "lambda" : [	"one", 2, 3 ] }	]';

	   my $foo = { foo => [	] };
	   my $handler = sub { push @{$foo->{foo}}, $_[0]; return 1; };

	   my $data = JSON::DWIW::deserialize($str, { start_depth => 1,
						      start_depth_handler => $handler });
	   print STDERR	Data::Dumper->Dump([ $foo ], [ 'foo' ])	. "\n";
	   print STDERR	Data::Dumper->Dump([ $data ], [	'leftover_data'	]) . "\n";

	   # Output
	   $foo	= {
		    'foo' => [
			       {
				 'cat' => 1,
				 'foo' => 'bar'
			       },
			       {
				 'lambda' => [
					     'one',
					     2,
					     3
					   ],
				 'concat' => 1
			       }
			     ]
		  };

	   $leftover_data = [];

   "to_json"
       Returns the JSON	representation of $data	(arbitrary datastructure).
       See http://www.json.org/	for details.

       Called in list context, this method returns a list whose	first element
       is the encoded JSON string and the second element is an error message,
       if any.	If $error_msg is defined, there	was a problem converting to
       JSON.  You may also pass	a second argument to to_json() that is a
       reference to a hash of options -- see new().

	    my $json_str = JSON::DWIW->to_json($data);

	    my ($json_str, $error_msg) = JSON::DWIW->to_json($data);

	    my $json_str = JSON::DWIW->to_json($data, {	use_exceptions => 1 });

       Aliases:	toJson,	toJSON,	objToJson

   "deserialize($json_str, \%options)"
       Returns the Perl	data structure for the given JSON string.  The value
       for true	becomes	1, false becomes 0, and	null gets converted to undef.

       This function should not	be called as a method (for performance
       reasons).  Unlike "from_json()",	it returns a single value, the data
       structure resulting from	the conversion.	 If the	return value is	undef,
       check the result	of the "get_error_string()" function/method to see if
       an error	is defined.

   "deserialize_file($file, \%options)"
       Same as deserialize, except that	it takes a file	as an argument.	 On
       Unix, this mmap's the file, so it does not load a big file into memory
       all at once, and	does less buffer copying.

   "from_json"
       Similar to "deserialize()", but expects to be called as a method.

       Called in list context, this method returns a list whose	first element
       is the data and the second element is the error message,	if any.	 If
       $error_msg is defined, there was	a problem parsing the JSON string, and
       $data will be undef.  You may also pass a second	argument to
       "from_json()" that is a reference to a hash of options -- see "new()".

	    my $data = from_json($json_str)

	    my ($data, $error_msg) = from_json($json_str)

       Aliases:	fromJson, fromJSON, jsonToObj

   "from_json_file"
       Similar to "deserialize_file()",	except that it expects to be called a
       a method, and it	also returns the error,	if any,	when called in list
       context.

       my ($data, $error_msg) =	$json->from_json_file($file, \%options)

   "to_json_file"
       Converts	$data to JSON and writes the result to the file	$file.
       Currently, this is simply a convenience routine that converts the data
       to a JSON string	and then writes	it to the file.

	my ($ok, $error) = $json->to_json_file($data, $file, \%options);

   "get_error_string"
       Returns the error message from the last call, if	there was one, e.g.,

	my $data = JSON::DWIW->from_json($json_str)
	    or die "JSON error:	" . JSON::DWIW->get_error_string;

	my $data = $json_obj->from_json($json_str)
	    or die "JSON error:	" . $json_obj->get_error_string;

       Aliases:	get_err_str(), errstr()

   "get_error_data"
       Returns the error details from the last call, in	a hash ref, e.g.,

	$error_data = {
		       'byte' => 23,
		       'byte_col' => 23,
		       'col' =>	22,
		       'char' => 22,
		       'version' => '0.15a',
		       'line' => 1
		     };

       This is really only useful when decoding	JSON.

       Aliases:	get_error(), error()

   "get_stats"
       Returns statistics from the last	method called to encode	or decode.
       E.g., for an encoding ("to_json()" or "to_json_file()"),

	   $stats = {
		      'bytes' => 78,
		      'nulls' => 1,
		      'max_string_bytes' => 5,
		      'max_depth' => 2,
		      'arrays' => 1,
		      'numbers'	=> 6,
		      'lines' => 1,
		      'max_string_chars' => 5,
		      'strings'	=> 6,
		      'bools' => 1,
		      'chars' => 78,
		      'hashes' => 1
		    };

   "true"
       Returns an object that will get output as a true	value when encoding to
       JSON.

   "false"
       Returns an object that will get output as a false value when encoding
       to JSON.

   "json_to_xml($json, \%params)"
       This function (not a method) converts the given JSON to XML.
       Hash/object keys	become tag names.  Arrays that are hash	values are
       output as multiple tags with the	hash key as the	tag name.

       Any characters in hash keys not in "[\w-]" (i.e., letters, numbers,
       underscore, or dash), get converted to underscore ("_") when output as
       XML tags.

       Valid parameters	in "\%params" are the same as for passing to
       "deserialize()" or "from_json()", plus the "pretty" option, which will
       add newlines and	indentation to the XML to make it more human-readable.

Utilities
       Following are some methods I use	for debugging and testing.

   "flagged_as_utf8($str)"
       Returns true if the given string	is flagged as utf-8.

   "flag_as_utf8($str)"
       Flags the given string as utf-8.

   "unflag_as_utf8($str)"
       Clears the flag that tells Perl the string is utf-8.

   "is_valid_utf8($str)"
       Returns true if the given string	is valid utf-8 (regardless of the
       flag).

   "upgrade_to_utf8($str)"
       Converts	the string to utf-8, assuming it is latin1.  This effects $str
       itself in place,	but also returns $str.

   "code_point_to_utf8_str($cp)"
       Returns a utf8 string containing	the byte sequence for the given	code
       point.

   "code_point_to_hex_bytes($cp)"
       Returns a string	representing the byte sequence for $cp encoding	in
       utf-8.  E.g.,

	my $hex_bytes =	JSON::DWIW->code_point_to_hex_bytes(0xe9);
	print "$hex_bytes\n"; #	\xc3\xa9

   "bytes_to_code_points($str)"
       Returns a reference to an array of code points from the given string,
       assuming	the string is encoded in utf-8.

   "peek_scalar($scalar)"
       Dumps the internal structure of the given scalar.

BENCHMARKS
       Need new	benchmarks here.

DEPENDENCIES
       Perl 5.6	or later

BUGS/LIMITATIONS
       If you find a bug, please file a	tracker	request	at
       <http://rt.cpan.org/Public/Dist/Display.html?Name=JSON-DWIW>.

       When decoding a JSON string, it is a assumed to be utf-8	encoded.  The
       module should detect whether the	input is utf-8,	utf-16,	or utf-32.

AUTHOR
       Don Owens <don@regexguy.com>

ACKNOWLEDGEMENTS
       Thanks to Asher Blum for	help with testing.

       Thanks to Nigel Bowden for helping with compilation on Windows.

       Thanks to Robert	Peters for discovering and tracking down the source of
       a number	parsing	bug.

       Thanks to Mark Phillips for helping with	a bug under Solaris on Sparc.

       Thanks to Josh for helping debug	[rt.cpan.org #47344].

LICENSE	AND COPYRIGHT
       Copyright (c) 2007-2010 Don Owens <don@regexguy.com>.  All rights
       reserved.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as Perl itself.  See perlartistic.

       This program is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A	PARTICULAR PURPOSE.

SEE ALSO
       The JSON	home page: <http://json.org/>
       The JSON	spec: <http://www.ietf.org/rfc/rfc4627.txt>
       The JSON-RPC spec:
       <http://json-rpc.org/wd/JSON-RPC-1-1-WD-20060807.html>
       JSON
       JSON::Syck (included in YAML::Syck)

perl v5.24.1			  2010-09-29			 JSON::DWIW(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | Utilities | BENCHMARKS | DEPENDENCIES | BUGS/LIMITATIONS | AUTHOR | ACKNOWLEDGEMENTS | LICENSE AND COPYRIGHT | SEE ALSO

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

home | help