From: John SJ Anderson <genehack@genehack.org>
Date: Fri, 13 Mar 2015 22:53:07 +0000 (-0700)
Subject: Add CAVEAT section about type checking [RT#102733]
X-Git-Tag: v1.003004~3
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=06551ef5e477d0c227b70b0bd5be900a449175b6;p=p5sagit%2FJSON-MaybeXS.git

Add CAVEAT section about type checking [RT#102733]
---

diff --git a/lib/JSON/MaybeXS.pm b/lib/JSON/MaybeXS.pm
index 2f90001..cd20183 100644
--- a/lib/JSON/MaybeXS.pm
+++ b/lib/JSON/MaybeXS.pm
@@ -223,6 +223,27 @@ To include JSON-aware booleans (C<true>, C<false>) in your data, just do:
     my $true = JSON->true;
     my $false = JSON->false;
 
+=head1 CAVEATS
+
+The C<new()> method in this module is technically a factory, not a
+constructor, because the objects it returns will I<NOT> be blessed into the
+C<JSON::MaybeXS> class.
+
+If you are using an object returned by this module as a Moo(se) attribute,
+this type constraint code:
+
+    is 'json' => ( isa => 'JSON::MaybeXS' );
+
+will I<NOT> do what you expect. Instead, either rely on the C<JSON> class
+constant described above, as so:
+
+    is 'json' => ( isa => JSON::MaybeXS::JSON() );
+
+Alternatively, you can use duck typing:
+
+    use Moose::Util::TypeConstraints;
+    is 'json' => ( isa => Object , duck_type([qw/ encode decode /]));
+
 =head1 AUTHOR
 
 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>