.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 .\" .\" Standard preamble: .\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. | will give a .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' .\" expand to `' in nroff, nothing in troff, for use with C<>. .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "JSON::DWIW 3" .TH JSON::DWIW 3 "2007-09-07" "perl v5.8.8" "User Contributed Perl Documentation" .SH "NAME" JSON::DWIW \- JSON converter that Does What I Want .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& use JSON::DWIW; \& my $json_obj = JSON::DWIW->new; \& my $data = $json_obj->from_json($json_str); \& my $str = $json_obj->to_json($data); .Ve .PP .Vb 3 \& my $error_string = $json_obj->get_error_string; \& my $error_data = $json_obj->get_error_data; \& my $stats = $json_obj->get_stats; .Ve .PP .Vb 2 \& my $data = $json_obj->from_json_file($file) \& my $ok = $json_obj->to_json_file($data, $file); .Ve .PP .Vb 2 \& my $data = JSON::DWIW->from_json($json_str); \& my $str = JSON:DWIW->to_json($data); .Ve .PP .Vb 2 \& my $data = JSON::DWIW->from_json($json_str, \e%options); \& my $str = JSON::DWIW->to_json($data, \e%options); .Ve .PP .Vb 5 \& 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); .Ve .PP .Vb 3 \& use JSON::DWIW qw(:all); \& my $data = from_json($json_str); \& my $str = to_json($data); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Other \s-1JSON\s0 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 \s-1JSON\s0 in Perl. This module also encodes and decodes faster than \s-1JSON\s0.pm and JSON::Syck in my benchmarks. .PP This means that any piece of data in Perl (assuming it's valid unicode) will get converted to something in \s-1JSON\s0 instead of throwing an exception. It also means that output will be strict \&\s-1JSON\s0, while accepted input will be flexible, without having to set any options. .Sh "Encoding" .IX Subsection "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 \fItrue()\fR and \fIfalse()\fR methods). For example, a blessed hash ref will be represented as an object in \s-1JSON\s0, 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. .PP 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. .Sh "Decoding" .IX Subsection "Decoding" 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. .PP The parser is flexible in what it accepts and handles some things not in the \s-1JSON\s0 spec: .IP "quotes" 4 .IX Item "quotes" .Vb 1 \& Both single and double quotes are allowed for quoting a string, e.g., .Ve .Sp .Vb 1 \& [ "string1", 'string2' ] .Ve .IP "bare keys" 4 .IX Item "bare keys" .Vb 1 \& Object/hash keys can be bare if they look like an identifier, e.g., .Ve .Sp .Vb 1 \& { var1: "myval1", var2: "myval2" } .Ve .IP "extra commas" 4 .IX Item "extra commas" .Vb 1 \& Extra commas in objects/hashes and arrays are ignored, e.g., .Ve .Sp .Vb 1 \& [1,2,3,,,4,] .Ve .Sp .Vb 1 \& becomes a 4 element array containing 1, 2, 3, and 4. .Ve .SH "METHODS" .IX Header "METHODS" .Sh "new(\e%options)" .IX Subsection "new(%options)" .Vb 1 \& Create a new JSON::DWIW object. .Ve .PP .Vb 4 \& %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: .Ve .PP \fIbare_keys\fR .IX Subsection "bare_keys" .PP .Vb 3 \& 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. .Ve .PP \fIuse_exceptions\fR .IX Subsection "use_exceptions" .PP .Vb 3 \& 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. .Ve .PP \fIbad_char_policy\fR .IX Subsection "bad_char_policy" .PP .Vb 3 \& 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. .Ve .PP .Vb 1 \& The following values for bad_char_policy are supported: .Ve .PP error .IX Subsection "error" .PP .Vb 1 \& default action, i.e., drop any output built up and return an error .Ve .PP convert .IX Subsection "convert" .PP .Vb 3 \& 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. .Ve .PP pass_through .IX Subsection "pass_through" .PP .Vb 1 \& Ignore the error and pass through the raw bytes (invalid JSON) .Ve .PP \fIescape_multi_byte\fR .IX Subsection "escape_multi_byte" .PP .Vb 2 \& If set to a true value, escape all multi-byte characters (e.g., \& \eu00e9) when converting to JSON. .Ve .PP \fIpretty\fR .IX Subsection "pretty" .PP .Vb 2 \& Add white space to the output when calling to_json() to make the \& output easier for humans to read. .Ve .PP \fIconvert_bool\fR .IX Subsection "convert_bool" .PP .Vb 7 \& 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". .Ve .Sh "to_json" .IX Subsection "to_json" .Vb 2 \& Returns the JSON representation of $data (arbitrary \& datastructure). See http://www.json.org/ for details. .Ve .PP .Vb 6 \& 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(). .Ve .PP .Vb 1 \& my $json_str = JSON::DWIW->to_json($data); .Ve .PP .Vb 1 \& my ($json_str, $error_msg) = JSON::DWIW->to_json($data); .Ve .PP .Vb 1 \& my $json_str = JSON::DWIW->to_json($data, { use_exceptions => 1 }); .Ve .PP .Vb 1 \& Aliases: toJson, toJSON, objToJson .Ve .Sh "from_json" .IX Subsection "from_json" .Vb 3 \& 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. .Ve .PP .Vb 6 \& 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(). .Ve .PP .Vb 1 \& my $data = from_json($json_str) .Ve .PP .Vb 1 \& my ($data, $error_msg) = from_json($json_str) .Ve .PP .Vb 1 \& my $data = from_json($json_str, { use_exceptions => 1 }) .Ve .PP .Vb 1 \& Aliases: fromJson, fromJSON, jsonToObj .Ve .Sh "from_json_file" .IX Subsection "from_json_file" .Vb 3 \& Returns the Perl data structure for the JSON object in the given \& file. Currently, this method slurps in the whole file, then \& parses it. .Ve .PP my ($data, \f(CW$error_msg\fR) = \f(CW$json\fR\->from_json_file($file, \e%options) .Sh "to_json_file" .IX Subsection "to_json_file" .Vb 3 \& 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. .Ve .PP my ($ok, \f(CW$error\fR) = \f(CW$json\fR\->to_json_file($data, \f(CW$file\fR, \e%options); .Sh "get_error_string" .IX Subsection "get_error_string" .Vb 1 \& Returns the error message from the last call, if there was one, e.g., .Ve .PP .Vb 2 \& my $data = JSON::DWIW->from_json($json_str) \& or die "JSON error: " . JSON::DWIW->get_error_string; .Ve .PP .Vb 2 \& my $data = $json_obj->from_json($json_str) \& or die "JSON error: " . $json_obj->get_error_string; .Ve .PP .Vb 1 \& Aliases: get_err_str(), errstr() .Ve .Sh "get_error_data" .IX Subsection "get_error_data" .Vb 1 \& Returns the error details from the last call, in a hash ref, e.g., .Ve .PP .Vb 8 \& $error_data = { \& 'byte' => 23, \& 'byte_col' => 23, \& 'col' => 22, \& 'char' => 22, \& 'version' => '0.15a', \& 'line' => 1 \& }; .Ve .PP .Vb 1 \& This is really only useful when decoding JSON. .Ve .PP .Vb 1 \& Aliases: get_error(), error() .Ve .Sh "get_stats" .IX Subsection "get_stats" .Vb 2 \& Returns statistics from the last method called to encode or \& decode. E.g., for an encoding (to_json() or to_json_file()), .Ve .PP .Vb 14 \& $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 \& }; .Ve .Sh "true" .IX Subsection "true" .Vb 1 \& Returns an object that will get output as a true value when encoding to JSON. .Ve .Sh "false" .IX Subsection "false" .Vb 1 \& Returns an object that will get output as a false value when encoding to JSON. .Ve .SH "BENCHMARKS" .IX Header "BENCHMARKS" .Vb 2 \& Latest benchmarks against JSON and JSON::Syck run on my MacBook \& Pro: .Ve .PP .Vb 1 \& Using a small data set: .Ve .PP .Vb 6 \& Encode (50000 iterations): \& ========================== \& Rate JSON JSON::Syck JSON::DWIW \& JSON 2648/s -- -72% -86% \& JSON::Syck 9416/s 256% -- -51% \& JSON::DWIW 19380/s 632% 106% -- .Ve .PP .Vb 6 \& Decode (50000 iterations): \& ========================== \& Rate JSON JSON::Syck JSON::DWIW \& JSON 2288/s -- -81% -93% \& JSON::Syck 12195/s 433% -- -60% \& JSON::DWIW 30675/s 1240% 152% -- .Ve .PP .Vb 2 \& Using a larger data set (8KB JSON string) generated from Yahoo! \& Local's search API (http://nanoref.com/yahooapis/mgPdGg) .Ve .PP .Vb 6 \& Encode (1000 iterations): \& ========================= \& Rate JSON JSON::Syck JSON::DWIW \& JSON 133/s -- -54% -66% \& JSON::Syck 289/s 118% -- -26% \& JSON::DWIW 389/s 193% 35% -- .Ve .PP .Vb 6 \& Decode (1000 iterations): \& ========================= \& Rate JSON JSON::Syck JSON::DWIW \& JSON 35.5/s -- -92% -94% \& JSON::Syck 427/s 1103% -- -25% \& JSON::DWIW 571/s 1508% 34% -- .Ve .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" Perl 5.6 or later .SH "BUGS/LIMITATIONS" .IX Header "BUGS/LIMITATIONS" If you find a bug, please file a tracker request at . .PP When decoding a \s-1JSON\s0 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. .SH "AUTHOR" .IX Header "AUTHOR" Don Owens .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Thanks to Asher Blum for help with testing. .PP Thanks to Nigel Bowden for helping with compilation on Windows. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (c) 2007 Don Owens . All rights reserved. .PP This is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \&\s-1PURPOSE\s0. .SH "SEE ALSO" .IX Header "SEE ALSO" .Vb 3 \& The JSON home page: L \& The JSON spec: L \& The JSON-RPC spec: L .Ve .PP .Vb 2 \& L \& L (included in L) .Ve .SH "VERSION" .IX Header "VERSION" 0.19