This is 0.07

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

diff --git a/lib/Lexical/Types.pm b/lib/Lexical/Types.pm
index 36960d88603cac0621c2a7620332192b8990c93a..112c04236baa6956ca9fe48215b7e82f33178e1f 100644 (file)
--- a/lib/Lexical/Types.pm
+++ b/lib/Lexical/Types.pm
@@ -13,13 +13,13 @@ Lexical::Types - Extend the semantics of typed lexicals.
 
 =head1 VERSION
 
-Version 0.03
+Version 0.07
 
 =cut
 
 our $VERSION;
 BEGIN {
- $VERSION = '0.03';
+ $VERSION = '0.07';
 }
 
 =head1 SYNOPSIS
@@ -125,10 +125,15 @@ or the desired package and method name, in that order (if any of those is C<unde
 
 =back
 
-=back
+Note that if the type is a constant, C<$_[0]> will be set to the I<value> of constant and not to its name.
+
+    use Lexical::Types as => sub { $_[0] => 'new' };
+    use constant Str => 'MyStr';
+    my Str $x; # calls MyStr->new
 
-The initializer method receives an alias to the pad entry of C<$x> in C<$_[1]> and the original type name (C<Str>) 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>.
+This means in particular that you can't both use constant types and redirect several types to different methods of the same package, because then you can't distinguish between the original types with C<$_[0]>.
+
+=back
 
 =cut
 
@@ -150,7 +155,7 @@ sub import {
    croak "Invalid $r reference for 'as'";
   }
  } else {
-  $hint = _tag(0);
+  $hint = _tag(sub { @_ });
  }
 
  $^H |= 0x020000;
@@ -170,6 +175,22 @@ sub unimport {
  $^H{+(__PACKAGE__)} = undef;
 }
 
+=head1 RUN-TIME INITIALIZER METHOD
+
+The initializer method receives an alias to the pad slot of the initialized lexical in C<$_[1]> and the original type name 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 the pad slot.
+
+    use Lexical::Types as => 'My';
+
+    my Str $x;
+
+    ...
+
+    sub My::Str::TYPEDSCALAR {
+     # $_[1] is an alias to $x, and $_[2] is 'Str'
+     ...
+    }
+
 =head1 INTEGRATION
 
 You can integrate L<Lexical::Types> in your module so that using it will provide types to your users without asking them to load either L<Lexical::Types> or the type classes manually.
@@ -193,26 +214,54 @@ You can integrate L<Lexical::Types> in your module so that using it will provide
 
     sub new_int { ... }
 
-=head1 CAVEATS
+If you prefer to use constants rather than creating empty packages, you can replace the previous example with something like this :
 
-For C<perl> to be able to parse C<my Str $x>, you need :
+    package MyTypes;
 
-=over 4
+    BEGIN { require Lexical::Types; }
 
-=item *
+    sub import {
+     my $pkg = caller;
+     for (qw/Str Int/) {
+      my $type = __PACKAGE__ . '::' . $_;
+      no strict 'refs';
+      no warnings 'redefine';
+      *{$pkg.'::'.$_} = eval "sub () { '$type' }";
+     }
+     Lexical::Types->import(
+      as => sub { $_[0] => 'new' }
+     );
+    }
 
-either the C<Str> package to be defined ;
+    sub unimport {
+     Lexical::Types->unimport;
+    }
 
-=item *
+    package MyTypes::Str;
 
-or for C<Str> to be a constant sub returning a valid defined package.
+    sub new { ... }
 
-=back
+    package MyTypes::Int;
+
+    sub new { ... }
+
+=head1 CONSTANTS
+
+=head2 C<LT_THREADSAFE>
+
+True iff the module could have been built with thread-safety features enabled.
+
+=head1 CAVEATS
 
 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.
 
+The implementation was tweaked to work around several limitations of vanilla C<perl> pragmas : it's thread safe, and doesn't suffer from a C<perl 5.8.x-5.10.0> bug that causes all pragmas to propagate into C<require>d scopes.
+
+With 5.8 perls, the pragma does not propagate into C<eval STRING>.
+This is due to a shortcoming in the way perl handles the hints hash, which is addressed in perl 5.10.
+
 =head1 DEPENDENCIES
 
 L<perl> 5.8, L<XSLoader>.