This is 0.03

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

diff --git a/lib/Lexical/Types.pm b/lib/Lexical/Types.pm
index 4eed8beb189f610fbf8b54f62b5d3a1e52bd4f8b..841c3aad3393d64ab2117ba0b1e606479c4a1761 100644 (file)
--- a/lib/Lexical/Types.pm
+++ b/lib/Lexical/Types.pm
@@ -1,5 +1,7 @@
 package Lexical::Types;
 
+use 5.008;
+
 use strict;
 use warnings;
 
@@ -11,30 +13,44 @@ Lexical::Types - Extend the semantics of typed lexicals.
 
 =head1 VERSION
 
-Version 0.01
+Version 0.03
 
 =cut
 
 our $VERSION;
 BEGIN {
- $VERSION = '0.01';
+ $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 module allows you to hook the execution of typed lexicals declarations (C<my Foo $x>).
+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.
 
 It is B<not> implemented with a source filter.
@@ -51,36 +67,51 @@ BEGIN {
 =head2 C<< import [ as => [ $prefix | $mangler ] ] >>
 
 Magically called when writing C<use Lexical::Types>.
-All the occurences of C<my Foo $x> in the current lexical scope will be changed to call at each run a given method in a given package.
-The method and package are determined by the parameter C<as> :
+All the occurences of C<my Str $x> in the current lexical scope will be changed to call at each run a given method in a given package.
+The method and package are determined by the parameter C<'as'> :
 
 =over 4
 
 =item *
 
-If it's left unspecified, the C<TYPEDSCALAR> method in the C<Foo> package will be called.
+If it's left unspecified, the C<TYPEDSCALAR> method in the C<Str> package will be called.
 
     use Lexical::Types;
     my Str $x; # calls Str->TYPEDSCALAR
 
 =item *
 
-If a plain scalar C<$prefix> is passed as the value, the C<TYPEDSCALAR> method in the C<${prefix}::Foo> package will be used.
+If a plain scalar C<$prefix> is passed as the value, the C<TYPEDSCALAR> method in the C<${prefix}::Str> package will be used.
 
     use Lexical::Types as => 'My::'; # or "as => 'My'"
     my Str $x; # calls My::Str->TYPEDSCALAR
 
 =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<'Str'> 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 $y; # calls Str->TYPEDSCALAR
+    my Int $x; # nothing special
+
+=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
 
-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]>.
+=back
+
+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>.
 
 =cut
@@ -115,7 +146,7 @@ sub import {
 =head2 C<unimport>
 
 Magically called when writing C<no Lexical::Types>.
-Turns the module off.
+Turns the pragma off.
 
 =cut
 
@@ -148,8 +179,21 @@ You can integrate L<Lexical::Types> in your module so that using it will provide
 
 =head1 CAVEATS
 
-For C<perl> to be able to parse C<my Foo $x>, the package C<Foo> must be defined somewhere, and this even if you use the C<as> option to redirect to another package.
-It's unlikely to find a workaround, as this happens deep inside the lexer, far from the reach of an extension.
+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
+
+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.
 
 Only one mangler or prefix can be in use at the same time in a given scope.
 
@@ -179,10 +223,14 @@ You can find documentation for this module with the perldoc command.
 
     perldoc Lexical::Types
 
+Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Lexical-Types>.
+
 =head1 ACKNOWLEDGEMENTS
 
 Inspired by Ricardo Signes.
 
+Thanks Florian Ragwitz for suggesting the use of constants for types.
+
 =head1 COPYRIGHT & LICENSE
 
 Copyright 2009 Vincent Pit, all rights reserved.