--- JSON-XS/XS.pm	2013/10/29 00:19:08	1.147
+++ JSON-XS/XS.pm	2014/03/02 22:09:38	1.154
@@ -103,7 +103,7 @@
 
 use common::sense;
 
-our $VERSION = '3.0';
+our $VERSION = 3.01;
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_json decode_json);
@@ -485,7 +485,7 @@
 
 =item $enabled = $json->get_convert_blessed
 
-See "OBJECT SERIALISATION" for details.
+See L<OBJECT SERIALISATION> for details.
 
 If C<$enable> is true (or missing), then C<encode>, upon encountering a
 blessed object, will check for the availability of the C<TO_JSON> method
@@ -509,7 +509,7 @@
 
 =item $enabled = $json->allow_tags
 
-See "OBJECT SERIALISATION" for details.
+See L<OBJECT SERIALISATION> for details.
 
 If C<$enable> is true (or missing), then C<encode>, upon encountering a
 blessed object, will check for the availability of the C<FREEZE> method on
@@ -1019,7 +1019,7 @@
 I<tag> must be a perl package/class name encoded as a JSON string, and the
 I<value> must be a JSON array encoding optional constructor arguments.
 
-See "OBJECT SERIALISATION", below, for details.
+See L<OBJECT SERIALISATION>, below, for details.
 
 =back
 
@@ -1068,7 +1068,7 @@
 =item blessed objects
 
 Blessed objects are not directly representable in JSON, but C<JSON::XS>
-allows various ways of handling objects. See "OBJECT SERIALISATION",
+allows various ways of handling objects. See L<OBJECT SERIALISATION>,
 below, for details.
 
 =item simple scalars
@@ -1131,7 +1131,7 @@
 
 =over 4
 
-=item 1. C<allow_tags> is enabled and object has a C<FREEZE> method.
+=item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method.
 
 In this case, C<JSON::XS> uses the L<Types::Serialiser> object
 serialisation protocol to create a tagged JSON value, using a nonstandard
@@ -1147,6 +1147,12 @@
 
    ("classname")[FREEZE return values...]
 
+e.g.:
+
+   ("URI")["http://www.google.com/"]
+   ("MyDate")[2013,10,29]
+   ("ImageData::JPEG")["Z3...VlCg=="]
+
 For example, the hypothetical C<My::Object> C<FREEZE> method might use the
 objects C<type> and C<id> members to encode the object:
 
@@ -1156,7 +1162,7 @@
       ($self->{type}, $self->{id})
    }
 
-=item 2. C<convert_blessed> is enabled and object has a C<TO_JSON> method.
+=item 2. C<convert_blessed> is enabled and the object has a C<TO_JSON> method.
 
 In this case, the C<TO_JSON> method of the object is invoked in scalar
 context. It must return a single scalar that can be directly encoded into
@@ -1557,6 +1563,83 @@
 such as L<JSON::PP> and L<CBOR::XS>.
 
 
+=head1 INTEROPERABILITY WITH OTHER JSON DECODERS
+
+As long as you only serialise data that can be directly expressed in JSON,
+C<JSON::XS> is incapable of generating invalid JSON output (modulo bugs,
+but C<JSON::XS> has found more bugs in the official JSON testsuite (1)
+than the official JSON testsuite has found in C<JSON::XS> (0)).
+
+When you have trouble decoding JSON generated by this module using other
+decoders, then it is very likely that you have an encoding mismatch or the
+other decoder is broken.
+
+When decoding, C<JSON::XS> is strict by default and will likely catch all
+errors. There are currently two settings that change this: C<relaxed>
+makes C<JSON::XS> accept (but not generate) some non-standard extensions,
+and C<allow_tags> will allow you to encode and decode Perl objects, at the
+cost of not outputting valid JSON anymore.
+
+=head2 TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
+
+When you use C<allow_tags> to use the extended (and also nonstandard and
+invalid) JSON syntax for serialised objects, and you still want to decode
+the generated When you want to serialise objects, you can run a regex
+to replace the tagged syntax by standard JSON arrays (it only works for
+"normal" packagesnames without comma, newlines or single colons). First,
+the readable Perl version:
+
+   # if your FREEZE methods return no values, you need this replace first:
+   $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx;
+
+   # this works for non-empty constructor arg lists:
+   $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[/[$1,/gx;
+
+And here is a less readable version that is easy to adapt to other
+languages:
+
+   $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/[$1,/g;
+
+Here is an ECMAScript version (same regex):
+
+   json = json.replace (/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/g, "[$1,");
+
+Since this syntax converts to standard JSON arrays, it might be hard to
+distinguish serialised objects from normal arrays. You can prepend a
+"magic number" as first array element to reduce chances of a collision:
+
+   $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
+
+And after decoding the JSON text, you could walk the data
+structure looking for arrays with a first element of
+C<XU1peReLzT4ggEllLanBYq4G9VzliwKF>.
+
+The same approach can be used to create the tagged format with another
+encoder. First, you create an array with the magic string as first member,
+the classname as second, and constructor arguments last, encode it as part
+of your JSON structure, and then:
+
+   $json =~ s/\[\s*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s*,\s*("([^\\":,]+|\\.|::)*")\s*,/($1)[/g;
+
+Again, this has some limitations - the magic string must not be encoded
+with character escapes, and the constructor arguments must be non-empty.
+
+
+=head1 RFC7158
+
+Since this module was written, Google has written a new JSON RFC, RFC
+7158. Unfortunately, this RFC breaks compatibility with both the original
+JSON specification on www.json.org and RFC4627.
+
+As far as I can see, you can get partial compatibility when parsing by
+using C<< ->allow_nonref >>. However, consider thew security implications
+of doing so.
+
+I haven't decided yet whether to break compatibility with RFC4627 by
+default (and potentially leave applications insecure), or change the
+default to follow RFC7158.
+
+
 =head1 THREADS
 
 This module is I<not> guaranteed to be thread safe and there are no