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.
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' :
56 * If it's left unspecified, the "TYPEDSCALAR" method in the "Str"
57 package will be called.
60 my Str $x; # calls Str->TYPEDSCALAR
62 * If a plain scalar $prefix is passed as the value, the "TYPEDSCALAR"
63 method in the "${prefix}::Str" package will be used.
65 use Lexical::Types as => 'My::'; # or "as => 'My'"
66 my Str $x; # calls My::Str->TYPEDSCALAR
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
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
76 use Lexical::Types as => sub { return $_[0] =~ /Str/ ? @_ : () };
77 my Str $y; # calls Str->TYPEDSCALAR
78 my Int $x; # nothing special
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).
83 use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
84 my Str $x; # the coderef indicates to call My->new_str
86 Note that if the type is a constant, $_[0] will be set to the
87 *value* of constant and not to its name.
89 use Lexical::Types as => sub { $_[0] => 'new' };
90 use constant Str => 'MyStr';
91 my Str $x; # calls MyStr->new
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
99 Magically called when writing "no Lexical::Types". Turns the pragma off.
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.
107 use Lexical::Types as => 'My';
113 sub My::Str::TYPEDSCALAR {
114 # $_[1] is an alias to $x, and $_[2] is 'Str'
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.
125 BEGIN { require Lexical::Types; }
128 eval 'package Str; package Int'; # The types you want to support
129 Lexical::Types->import(
130 as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
135 Lexical::Types->unimport;
142 If you prefer to use constants rather than creating empty packages, you
143 can replace the previous example with something like this :
147 BEGIN { require Lexical::Types; }
152 my $type = __PACKAGE__ . '::' . $_;
154 no warnings 'redefine';
155 *{$pkg.'::'.$_} = eval "sub () { '$type' }";
157 Lexical::Types->import(
158 as => sub { $_[0] => 'new' }
163 Lexical::Types->unimport;
166 package MyTypes::Str;
170 package MyTypes::Int;
176 True iff the module could have been built with thread-safety features
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.
185 Only one mangler or prefix can be in use at the same time in a given
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
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.
206 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
208 You can contact me by mail or on "irc.perl.org" (vincent).
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.
218 You can find documentation for this module with the perldoc command.
220 perldoc Lexical::Types
222 Tests code coverage report is available at
223 <http://www.profvince.com/perl/cover/Lexical-Types>.
226 Inspired by Ricardo Signes.
228 Thanks Florian Ragwitz for suggesting the use of constants for types.
231 Copyright 2009 Vincent Pit, all rights reserved.
233 This program is free software; you can redistribute it and/or modify it
234 under the same terms as Perl itself.