README

   1 NAME
   2     Lexical::Types - Extend the semantics of typed lexicals.
   3
   4 VERSION
   5     Version 0.04
   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") by calling a configurable method in a
  35     configurable package at each run. In particular, it can be used to
  36     automatically tie or bless typed lexicals whenever they are initialized.
  37
  38     Remind that for "perl" to be able to parse "my Str $x", you need :
  39
  40     *   either the "Str" package to be defined ;
  41
  42     *   or for "Str" to be a constant sub returning a valid defined package.
  43
  44     so make sure you follow one of those two strategies to define your
  45     types.
  46
  47     This pragma is not implemented with a source filter.
  48
  49 FUNCTIONS
  50   "import [ as => [ $prefix | $mangler ] ]"
  51     Magically called when writing "use Lexical::Types". All the occurences
  52     of "my Str $x" in the current lexical scope will be changed to call at
  53     each run a given method in a given package. The method and package are
  54     determined by the parameter 'as' :
  55
  56     *   If it's left unspecified, the "TYPEDSCALAR" method in the "Str"
  57         package will be called.
  58
  59             use Lexical::Types;
  60             my Str $x; # calls Str->TYPEDSCALAR
  61
  62     *   If a plain scalar $prefix is passed as the value, the "TYPEDSCALAR"
  63         method in the "${prefix}::Str" package will be used.
  64
  65             use Lexical::Types as => 'My::'; # or "as => 'My'"
  66             my Str $x; # calls My::Str->TYPEDSCALAR
  67
  68     *   If the value given is a code reference $mangler, it will be called
  69         at compile-time with arguments 'Str' and 'TYPEDSCALAR' and is
  70         expected to return :
  71
  72         *   either an empty list, in which case the current typed lexical
  73             definition will be skipped (thus it won't be altered to trigger
  74             a run-time hook) ;
  75
  76                 use Lexical::Types as => sub { return $_[0] =~ /Str/ ? @_ : () };
  77                 my Str $y; # calls Str->TYPEDSCALAR
  78                 my Int $x; # nothing special
  79
  80         *   or the desired package and method name, in that order (if any of
  81             those is "undef", the default value will be used instead).
  82
  83                 use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
  84                 my Str $x; # the coderef indicates to call My->new_str
  85
  86         Note that if the type is a constant, $_[0] will be set to the
  87         *value* of constant and not to its name.
  88
  89             use Lexical::Types as => sub { $_[0] => 'new' };
  90             use constant Str => 'MyStr';
  91             my Str $x; # calls MyStr->new
  92
  93         This means in particular that you can't both use constant types and
  94         redirect several types to different methods of the same package,
  95         because then you can't distinguish between the original types with
  96         $_[0].
  97
  98   "unimport"
  99     Magically called when writing "no Lexical::Types". Turns the pragma off.
 100
 101 RUN-TIME INITIALIZER METHOD
 102     The initializer method receives an alias to the pad slot of the
 103     initialized lexical in $_[1] and the original type name in $_[2]. You
 104     can either edit $_[1] in place, in which case you should return an empty
 105     list, or return a new scalar that will be copied into the pad slot.
 106
 107         use Lexical::Types as => 'My';
 108
 109         my Str $x;
 110
 111         ...
 112
 113         sub My::Str::TYPEDSCALAR {
 114          # $_[1] is an alias to $x, and $_[2] is 'Str'
 115          ...
 116         }
 117
 118 INTEGRATION
 119     You can integrate Lexical::Types in your module so that using it will
 120     provide types to your users without asking them to load either
 121     Lexical::Types or the type classes manually.
 122
 123         package MyTypes;
 124
 125         BEGIN { require Lexical::Types; }
 126
 127         sub import {
 128          eval 'package Str; package Int'; # The types you want to support
 129          Lexical::Types->import(
 130           as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
 131          );
 132         }
 133
 134         sub unimport {
 135          Lexical::Types->unimport;
 136         }
 137
 138         sub new_str { ... }
 139
 140         sub new_int { ... }
 141
 142     If you prefer to use constants rather than creating empty packages, you
 143     can replace the previous example with something like this :
 144
 145         package MyTypes;
 146
 147         BEGIN { require Lexical::Types; }
 148
 149         sub import {
 150          my $pkg = caller;
 151          for (qw/Str Int/) {
 152           my $type = __PACKAGE__ . '::' . $_;
 153           no strict 'refs';
 154           no warnings 'redefine';
 155           *{$pkg.'::'.$_} = eval "sub () { '$type' }";
 156          }
 157          Lexical::Types->import(
 158           as => sub { $_[0] => 'new' }
 159          );
 160         }
 161
 162         sub unimport {
 163          Lexical::Types->unimport;
 164         }
 165
 166         package MyTypes::Str;
 167
 168         sub new { ... }
 169
 170         package MyTypes::Int;
 171
 172         sub new { ... }
 173
 174 CAVEATS
 175     For "perl" to be able to parse "my Str $x", you need :
 176
 177     *   either the "Str" package to be defined ;
 178
 179     *   or for "Str" to be a constant sub returning a valid defined package.
 180
 181     The restrictions on the type (being either a defined package name or a
 182     constant) apply even if you use the 'as' option to redirect to another
 183     package, and are unlikely to find a workaround as this happens deep
 184     inside the lexer - far from the reach of an extension.
 185
 186     Only one mangler or prefix can be in use at the same time in a given
 187     scope.
 188
 189 DEPENDENCIES
 190     perl 5.8, XSLoader.
 191
 192 SEE ALSO
 193     fields.
 194
 195     Attribute::Handlers.
 196
 197 AUTHOR
 198     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 199
 200     You can contact me by mail or on "irc.perl.org" (vincent).
 201
 202 BUGS
 203     Please report any bugs or feature requests to "bug-lexical-types at
 204     rt.cpan.org", or through the web interface at
 205     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Lexical-Types>. I will
 206     be notified, and then you'll automatically be notified of progress on
 207     your bug as I make changes.
 208
 209 SUPPORT
 210     You can find documentation for this module with the perldoc command.
 211
 212         perldoc Lexical::Types
 213
 214     Tests code coverage report is available at
 215     <http://www.profvince.com/perl/cover/Lexical-Types>.
 216
 217 ACKNOWLEDGEMENTS
 218     Inspired by Ricardo Signes.
 219
 220     Thanks Florian Ragwitz for suggesting the use of constants for types.
 221
 222 COPYRIGHT & LICENSE
 223     Copyright 2009 Vincent Pit, all rights reserved.
 224
 225     This program is free software; you can redistribute it and/or modify it
 226     under the same terms as Perl itself.
 227