2 Lexical::Types - Extend the semantics of typed lexicals.
11 package My::Types::Str;
13 sub new { bless { }, shift }
16 use Lexical::Types as => sub { 'My::Types::' . $_[0] => 'new' };
18 my Str $x; # $x is now a My::Types::Str object
21 package My::Types::Int;
23 sub TYPEDSCALAR { bless { }, shift }
28 use constant Int => 'My::Types::Int';
30 my Int $y; # $y is now a My::Types::Int object
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.
38 Remind that for "perl" to be able to parse "my Str $x", you need :
40 * either the "Str" package to be defined ;
42 * or for "Str" to be a constant sub returning a valid defined package.
44 so make sure you follow one of those two strategies to define your
47 This pragma is not implemented with a source filter.
52 use Lexical::Types as => $prefix;
53 use Lexical::Types as => sub { ... }; # = $mangler
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' :
60 * If it's left unspecified, the "TYPEDSCALAR" method in the "Str"
61 package will be called.
64 my Str $x; # calls Str->TYPEDSCALAR
66 * If a plain scalar $prefix is passed as the value, the "TYPEDSCALAR"
67 method in the "${prefix}::Str" package will be used.
69 use Lexical::Types as => 'My::'; # or "as => 'My'"
70 my Str $x; # calls My::Str->TYPEDSCALAR
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
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
80 use Lexical::Types as => sub {
81 return $_[0] =~ /Str/ ? @_ : ()
83 my Str $y; # calls Str->TYPEDSCALAR
84 my Int $x; # nothing special
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).
89 use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
90 my Str $x; # the coderef indicates to call My->new_str
92 Note that if the type is a constant, $_[0] will be set to the
93 *value* of constant and not to its name.
95 use Lexical::Types as => sub { $_[0] => 'new' };
96 use constant Str => 'MyStr';
97 my Str $x; # calls MyStr->new
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
107 Magically called when "no Lexical::Types" is encountered. Turns the
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.
116 use Lexical::Types as => 'My';
122 sub My::Str::TYPEDSCALAR {
123 # $_[1] is an alias to $x, and $_[2] is 'Str'
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.
134 BEGIN { require Lexical::Types; }
137 eval 'package Str; package Int'; # The types you want to support
138 Lexical::Types->import(
139 as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
144 Lexical::Types->unimport;
151 If you prefer to use constants rather than creating empty packages, you
152 can replace the previous example with something like this :
156 BEGIN { require Lexical::Types; }
161 my $type = __PACKAGE__ . '::' . $_;
163 no warnings 'redefine';
164 *{$pkg.'::'.$_} = eval "sub () { '$type' }";
166 Lexical::Types->import(
167 as => sub { $_[0] => 'new' }
172 Lexical::Types->unimport;
175 package MyTypes::Str;
179 package MyTypes::Int;
185 True iff the module could have been built with thread-safety features
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 .
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".
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.
204 Only one mangler or prefix can be in use at the same time in a given
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
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
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.
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.
227 XSLoader (standard since perl 5.6.0).
235 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
237 You can contact me by mail or on "irc.perl.org" (vincent).
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.
247 You can find documentation for this module with the perldoc command.
249 perldoc Lexical::Types
251 Tests code coverage report is available at
252 <http://www.profvince.com/perl/cover/Lexical-Types>.
255 Inspired by Ricardo Signes.
257 Thanks Florian Ragwitz for suggesting the use of constants for types.
260 Copyright 2009,2010,2011,2012,2013,2014 Vincent Pit, all rights
263 This program is free software; you can redistribute it and/or modify it
264 under the same terms as Perl itself.