Allow skipping declarations by returning an empty list from the mangler

[perl/modules/Lexical-Types.git] / lib / Lexical / Types.pm

diff --git a/lib/Lexical/Types.pm b/lib/Lexical/Types.pm
index 29a5a0dbad80267ddc640ee17b7ec817dcd74aec..138fcf588cb0187cc61da5646fd8a6997ae5ceab 100644 (file)
--- a/lib/Lexical/Types.pm
+++ b/lib/Lexical/Types.pm
@@ -74,14 +74,29 @@ If a plain scalar C<$prefix> is passed as the value, the C<TYPEDSCALAR> method i
 
 =item *
 
-If the value given is a code reference C<$mangler>, it will be called at compile-time with arguments C<'Foo'> and C<'TYPEDSCALAR'> and is expected to return the desired package and method name (in that order).
-If any of those is C<undef>, the default value will be used instead.
+If the value given is a code reference C<$mangler>, it will be called at compile-time with arguments C<'Foo'> and C<'TYPEDSCALAR'> and is expected to return :
+
+=over 4
+
+=item *
+
+either an empty list, in which case the current typed lexical definition will be skipped (thus it won't be altered to trigger a run-time hook) ;
+
+    use Lexical::Types as => sub { return $_[0] =~ /Str/ ? () : @_ };
+    my Str $x; # nothing special
+    my Int $y; # calls Int->TYPEDSCALAR
+
+=item *
+
+or the desired package and method name, in that order (if any of those is C<undef>, the default value will be used instead).
 
     use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
     my Str $x; # the coderef indicates to call My->new_str
 
 =back
 
+=back
+
 The initializer method receives an alias to the pad entry of C<$x> in C<$_[1]> and the original type name (C<Foo>) in C<$_[2]>.
 You can either edit C<$_[1]> in place, in which case you should return an empty list, or return a new scalar that will be copied into C<$x>.