Revamp the description so that the important discussion about what the type can be...

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

diff --git a/lib/Lexical/Types.pm b/lib/Lexical/Types.pm
index 85df03982bc19897735fa4cfbb50726a87db3a4f..36960d88603cac0621c2a7620332192b8990c93a 100644 (file)
--- a/lib/Lexical/Types.pm
+++ b/lib/Lexical/Types.pm
@@ -13,33 +13,63 @@ Lexical::Types - Extend the semantics of typed lexicals.
 
 =head1 VERSION
 
-Version 0.02
+Version 0.03
 
 =cut
 
 our $VERSION;
 BEGIN {
- $VERSION = '0.02';
+ $VERSION = '0.03';
 }
 
 =head1 SYNOPSIS
 
+    { package Str; }
+
     {
-     package Str;
+     package My::Types::Str;
 
-     sub TYPEDSCALAR { Some::String::Implementation->new }
+     sub new { bless { }, shift }
+    }
+
+    use Lexical::Types as => sub { 'My::Types::' . $_[0] => 'new' };
+
+    my Str $x; # $x is now a My::Types::Str object
+
+    {
+     package My::Types::Int;
+
+     sub TYPEDSCALAR { bless { }, shift }
     }
 
     use Lexical::Types;
 
-    my Str $x; # $x is now a Some::String::Implementation object
+    use constant Int => 'My::Types::Int';
+
+    my Int $y; # $y is now a My::Types::Int object
 
 =head1 DESCRIPTION
 
-This pragma allows you to hook the execution of typed lexicals declarations (C<my Str $x>).
-In particular, it can be used to automatically tie or bless typed lexicals.
+This pragma allows you to hook the execution of typed lexicals declarations (C<my Str $x>) by calling a configurable method in a configurable package at each run.
+In particular, it can be used to automatically tie or bless typed lexicals whenever they are initialized.
+
+Remind that for C<perl> to be able to parse C<my Str $x>, you need :
+
+=over 4
+
+=item *
+
+either the C<Str> package to be defined ;
+
+=item *
+
+or for C<Str> to be a constant sub returning a valid defined package.
+
+=back
+
+so make sure you follow one of those two strategies to define your types.
 
-It is B<not> implemented with a source filter.
+This pragma is B<not> implemented with a source filter.
 
 =cut
 
@@ -179,7 +209,7 @@ or for C<Str> to be a constant sub returning a valid defined package.
 
 =back
 
-Those restrictions apply even if you use the C<'as'> option to redirect to another package, and are unlikely to find a workaround as this happens deep inside the lexer - far from the reach of an extension.
+The restrictions on the type (being either a defined package name or a constant) apply even if you use the C<'as'> option to redirect to another package, and are unlikely to find a workaround as this happens deep inside the lexer - far from the reach of an extension.
 
 Only one mangler or prefix can be in use at the same time in a given scope.