README

   1 NAME
   2     Lexical::Types - Extend the semantics of typed lexicals.
   3
   4 VERSION
   5     Version 0.16
   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 METHODS
  50   "import"
  51         use Lexical::Types;
  52         use Lexical::Types as => $prefix;
  53         use Lexical::Types as => sub { ... }; # = $mangler
  54
  55     Magically called when "use Lexical::Types" is encountered. All the
  56     occurences of "my Str $x" in the current lexical scope will be changed
  57     to call at each run a given method in a given package. The method and
  58     package are determined by the parameter 'as' :
  59
  60     *   If it's left unspecified, the "TYPEDSCALAR" method in the "Str"
  61         package will be called.
  62
  63             use Lexical::Types;
  64             my Str $x; # calls Str->TYPEDSCALAR
  65
  66     *   If a plain scalar $prefix is passed as the value, the "TYPEDSCALAR"
  67         method in the "${prefix}::Str" package will be used.
  68
  69             use Lexical::Types as => 'My::'; # or "as => 'My'"
  70             my Str $x; # calls My::Str->TYPEDSCALAR
  71
  72     *   If the value given is a code reference $mangler, it will be called
  73         at compile-time with arguments 'Str' and 'TYPEDSCALAR' and is
  74         expected to return :
  75
  76         *   either an empty list, in which case the current typed lexical
  77             definition will be skipped (thus it won't be altered to trigger
  78             a run-time hook) ;
  79
  80                 use Lexical::Types as => sub {
  81                  return $_[0] =~ /Str/ ? @_ : ()
  82                 };
  83                 my Str $y; # calls Str->TYPEDSCALAR
  84                 my Int $x; # nothing special
  85
  86         *   or the desired package and method name, in that order (if any of
  87             those is "undef", the default value will be used instead).
  88
  89                 use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
  90                 my Str $x; # the coderef indicates to call My->new_str
  91
  92         Note that if the type is a constant, $_[0] will be set to the
  93         *value* of constant and not to its name.
  94
  95             use Lexical::Types as => sub { $_[0] => 'new' };
  96             use constant Str => 'MyStr';
  97             my Str $x; # calls MyStr->new
  98
  99         This means in particular that you can't both use constant types and
 100         redirect several types to different methods of the same package,
 101         because then you can't distinguish between the original types with
 102         $_[0].
 103
 104   "unimport"
 105         no Lexical::Types;
 106
 107     Magically called when "no Lexical::Types" is encountered. Turns the
 108     pragma off.
 109
 110 RUN-TIME INITIALIZER METHOD
 111     The initializer method receives an alias to the pad slot of the
 112     initialized lexical in $_[1] and the original type name in $_[2]. You
 113     can either edit $_[1] in place, in which case you should return an empty
 114     list, or return a new scalar that will be copied into the pad slot.
 115
 116         use Lexical::Types as => 'My';
 117
 118         my Str $x;
 119
 120         ...
 121
 122         sub My::Str::TYPEDSCALAR {
 123          # $_[1] is an alias to $x, and $_[2] is 'Str'
 124          ...
 125         }
 126
 127 INTEGRATION
 128     You can integrate Lexical::Types in your module so that using it will
 129     provide types to your users without asking them to load either
 130     Lexical::Types or the type classes manually.
 131
 132         package MyTypes;
 133
 134         BEGIN { require Lexical::Types; }
 135
 136         sub import {
 137          eval 'package Str; package Int'; # The types you want to support
 138          Lexical::Types->import(
 139           as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
 140          );
 141         }
 142
 143         sub unimport {
 144          Lexical::Types->unimport;
 145         }
 146
 147         sub new_str { ... }
 148
 149         sub new_int { ... }
 150
 151     If you prefer to use constants rather than creating empty packages, you
 152     can replace the previous example with something like this :
 153
 154         package MyTypes;
 155
 156         BEGIN { require Lexical::Types; }
 157
 158         sub import {
 159          my $pkg = caller;
 160          for (qw<Str Int>) {
 161           my $type = __PACKAGE__ . '::' . $_;
 162           no strict 'refs';
 163           no warnings 'redefine';
 164           *{$pkg.'::'.$_} = eval "sub () { '$type' }";
 165          }
 166          Lexical::Types->import(
 167           as => sub { $_[0] => 'new' }
 168          );
 169         }
 170
 171         sub unimport {
 172          Lexical::Types->unimport;
 173         }
 174
 175         package MyTypes::Str;
 176
 177         sub new { ... }
 178
 179         package MyTypes::Int;
 180
 181         sub new { ... }
 182
 183 CONSTANTS
 184   "LT_THREADSAFE"
 185     True iff the module could have been built with thread-safety features
 186     enabled.
 187
 188   "LT_FORKSAFE"
 189     True iff this module could have been built with fork-safety features
 190     enabled. This will always be true except on Windows where it's false for
 191     perl 5.10.0 and below .
 192
 193 CAVEATS
 194     Using this pragma will cause a slight global slowdown of any subsequent
 195     compilation phase that happens anywere in your code - even outside of
 196     the scope of use of "use Lexical::Types" - which may become noticeable
 197     if you rely heavily on numerous calls to "eval STRING".
 198
 199     The restrictions on the type (being either a defined package name or a
 200     constant) apply even if you use the 'as' option to redirect to another
 201     package, and are unlikely to find a workaround as this happens deep
 202     inside the lexer - far from the reach of an extension.
 203
 204     Only one mangler or prefix can be in use at the same time in a given
 205     scope.
 206
 207     Typed lexicals declarations that appear in code "eval"'d during the
 208     global destruction phase of a spawned thread or pseudo-fork (the
 209     processes used internally for the "fork" emulation on Windows) are
 210     ignored.
 211
 212     The implementation was tweaked to work around several limitations of
 213     vanilla "perl" pragmas : it's thread safe, and doesn't suffer from a
 214     "perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into
 215     "require"d scopes.
 216
 217     With 5.8 perls, the pragma does not propagate into "eval STRING". This
 218     is due to a shortcoming in the way perl handles the hints hash, which is
 219     addressed in perl 5.10.
 220
 221 DEPENDENCIES
 222     perl 5.8.4.
 223
 224     A C compiler. This module may happen to build with a C++ compiler as
 225     well, but don't rely on it, as no guarantee is made in this regard.
 226
 227     XSLoader (standard since perl 5.6.0).
 228
 229 SEE ALSO
 230     fields.
 231
 232     Attribute::Handlers.
 233
 234 AUTHOR
 235     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 236
 237     You can contact me by mail or on "irc.perl.org" (vincent).
 238
 239 BUGS
 240     Please report any bugs or feature requests to "bug-lexical-types at
 241     rt.cpan.org", or through the web interface at
 242     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Lexical-Types>. I will
 243     be notified, and then you'll automatically be notified of progress on
 244     your bug as I make changes.
 245
 246 SUPPORT
 247     You can find documentation for this module with the perldoc command.
 248
 249         perldoc Lexical::Types
 250
 251 ACKNOWLEDGEMENTS
 252     Inspired by Ricardo Signes.
 253
 254     Thanks Florian Ragwitz for suggesting the use of constants for types.
 255
 256 COPYRIGHT & LICENSE
 257     Copyright 2009,2010,2011,2012,2013,2014,2015,2017 Vincent Pit, all
 258     rights reserved.
 259
 260     This program is free software; you can redistribute it and/or modify it
 261     under the same terms as Perl itself.
 262