README

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