README

   1 NAME
   2     Lexical::Types - Extend the semantics of typed lexicals.
   3
   4 VERSION
   5     Version 0.07
   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 CONSTANTS
 175   "LT_THREADSAFE"
 176     True iff the module could have been built with thread-safety features
 177     enabled.
 178
 179 CAVEATS
 180     The restrictions on the type (being either a defined package name or a
 181     constant) apply even if you use the 'as' option to redirect to another
 182     package, and are unlikely to find a workaround as this happens deep
 183     inside the lexer - far from the reach of an extension.
 184
 185     Only one mangler or prefix can be in use at the same time in a given
 186     scope.
 187
 188     The implementation was tweaked to work around several limitations of
 189     vanilla "perl" pragmas : it's thread safe, and doesn't suffer from a
 190     "perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into
 191     "require"d scopes.
 192
 193     With 5.8 perls, the pragma does not propagate into "eval STRING". This
 194     is due to a shortcoming in the way perl handles the hints hash, which is
 195     addressed in perl 5.10.
 196
 197 DEPENDENCIES
 198     perl 5.8, XSLoader.
 199
 200 SEE ALSO
 201     fields.
 202
 203     Attribute::Handlers.
 204
 205 AUTHOR
 206     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 207
 208     You can contact me by mail or on "irc.perl.org" (vincent).
 209
 210 BUGS
 211     Please report any bugs or feature requests to "bug-lexical-types at
 212     rt.cpan.org", or through the web interface at
 213     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Lexical-Types>. I will
 214     be notified, and then you'll automatically be notified of progress on
 215     your bug as I make changes.
 216
 217 SUPPORT
 218     You can find documentation for this module with the perldoc command.
 219
 220         perldoc Lexical::Types
 221
 222     Tests code coverage report is available at
 223     <http://www.profvince.com/perl/cover/Lexical-Types>.
 224
 225 ACKNOWLEDGEMENTS
 226     Inspired by Ricardo Signes.
 227
 228     Thanks Florian Ragwitz for suggesting the use of constants for types.
 229
 230 COPYRIGHT & LICENSE
 231     Copyright 2009 Vincent Pit, all rights reserved.
 232
 233     This program is free software; you can redistribute it and/or modify it
 234     under the same terms as Perl itself.
 235