README

   1 NAME
   2     Lexical::Types - Extend the semantics of typed lexicals.
   3
   4 VERSION
   5     Version 0.03
   6
   7 SYNOPSIS
   8         { package Str; }
   9
  10         {
  11          package My::Types::Str;
  12
  13          sub new { bless { }, shift }
  14         }
  15
  16         use Lexical::Types as => sub { 'My::Types::' . $_[0] => 'new' };
  17
  18         my Str $x; # $x is now a My::Types::Str object
  19
  20         {
  21          package My::Types::Int;
  22
  23          sub TYPEDSCALAR { bless { }, shift }
  24         }
  25
  26         use Lexical::Types;
  27
  28         use constant Int => 'My::Types::Int';
  29
  30         my Int $y; # $y is now a My::Types::Int object
  31
  32 DESCRIPTION
  33     This pragma allows you to hook the execution of typed lexicals
  34     declarations ("my Str $x"). In particular, it can be used to
  35     automatically tie or bless typed lexicals.
  36
  37     It is not implemented with a source filter.
  38
  39 FUNCTIONS
  40   "import [ as => [ $prefix | $mangler ] ]"
  41     Magically called when writing "use Lexical::Types". All the occurences
  42     of "my Str $x" in the current lexical scope will be changed to call at
  43     each run a given method in a given package. The method and package are
  44     determined by the parameter 'as' :
  45
  46     *   If it's left unspecified, the "TYPEDSCALAR" method in the "Str"
  47         package will be called.
  48
  49             use Lexical::Types;
  50             my Str $x; # calls Str->TYPEDSCALAR
  51
  52     *   If a plain scalar $prefix is passed as the value, the "TYPEDSCALAR"
  53         method in the "${prefix}::Str" package will be used.
  54
  55             use Lexical::Types as => 'My::'; # or "as => 'My'"
  56             my Str $x; # calls My::Str->TYPEDSCALAR
  57
  58     *   If the value given is a code reference $mangler, it will be called
  59         at compile-time with arguments 'Str' and 'TYPEDSCALAR' and is
  60         expected to return :
  61
  62         *   either an empty list, in which case the current typed lexical
  63             definition will be skipped (thus it won't be altered to trigger
  64             a run-time hook) ;
  65
  66                 use Lexical::Types as => sub { return $_[0] =~ /Str/ ? @_ : () };
  67                 my Str $y; # calls Str->TYPEDSCALAR
  68                 my Int $x; # nothing special
  69
  70         *   or the desired package and method name, in that order (if any of
  71             those is "undef", the default value will be used instead).
  72
  73                 use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
  74                 my Str $x; # the coderef indicates to call My->new_str
  75
  76     The initializer method receives an alias to the pad entry of $x in $_[1]
  77     and the original type name ("Str") in $_[2]. You can either edit $_[1]
  78     in place, in which case you should return an empty list, or return a new
  79     scalar that will be copied into $x.
  80
  81   "unimport"
  82     Magically called when writing "no Lexical::Types". Turns the pragma off.
  83
  84 INTEGRATION
  85     You can integrate Lexical::Types in your module so that using it will
  86     provide types to your users without asking them to load either
  87     Lexical::Types or the type classes manually.
  88
  89         package MyTypes;
  90
  91         BEGIN { require Lexical::Types; }
  92
  93         sub import {
  94          eval 'package Str; package Int'; # The types you want to support
  95          Lexical::Types->import(
  96           as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
  97          );
  98         }
  99
 100         sub unimport {
 101          Lexical::Types->unimport;
 102         }
 103
 104         sub new_str { ... }
 105
 106         sub new_int { ... }
 107
 108 CAVEATS
 109     For "perl" to be able to parse "my Str $x", you need :
 110
 111     *   either the "Str" package to be defined ;
 112
 113     *   or for "Str" to be a constant sub returning a valid defined package.
 114
 115     Those restrictions apply even if you use the 'as' option to redirect to
 116     another package, and are unlikely to find a workaround as this happens
 117     deep inside the lexer - far from the reach of an extension.
 118
 119     Only one mangler or prefix can be in use at the same time in a given
 120     scope.
 121
 122 DEPENDENCIES
 123     perl 5.8, XSLoader.
 124
 125 SEE ALSO
 126     fields.
 127
 128     Attribute::Handlers.
 129
 130 AUTHOR
 131     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 132
 133     You can contact me by mail or on "irc.perl.org" (vincent).
 134
 135 BUGS
 136     Please report any bugs or feature requests to "bug-lexical-types at
 137     rt.cpan.org", or through the web interface at
 138     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Lexical-Types>. I will
 139     be notified, and then you'll automatically be notified of progress on
 140     your bug as I make changes.
 141
 142 SUPPORT
 143     You can find documentation for this module with the perldoc command.
 144
 145         perldoc Lexical::Types
 146
 147     Tests code coverage report is available at
 148     <http://www.profvince.com/perl/cover/Lexical-Types>.
 149
 150 ACKNOWLEDGEMENTS
 151     Inspired by Ricardo Signes.
 152
 153     Thanks Florian Ragwitz for suggesting the use of constants for types.
 154
 155 COPYRIGHT & LICENSE
 156     Copyright 2009 Vincent Pit, all rights reserved.
 157
 158     This program is free software; you can redistribute it and/or modify it
 159     under the same terms as Perl itself.
 160