1 package Lexical::Types;
10 Lexical::Types - Extend the semantics of typed lexicals.
28 package My::Types::Str;
30 sub new { bless { }, shift }
33 use Lexical::Types as => sub { 'My::Types::' . $_[0] => 'new' };
35 my Str $x; # $x is now a My::Types::Str object
38 package My::Types::Int;
40 sub TYPEDSCALAR { bless { }, shift }
45 use constant Int => 'My::Types::Int';
47 my Int $y; # $y is now a My::Types::Int object
51 This pragma allows you to hook the execution of typed lexicals declarations (C<my Str $x>) by calling a configurable method in a configurable package at each run.
52 In particular, it can be used to automatically tie or bless typed lexicals whenever they are initialized.
54 Remind that for C<perl> to be able to parse C<my Str $x>, you need :
60 either the C<Str> package to be defined ;
64 or for C<Str> to be a constant sub returning a valid defined package.
68 so make sure you follow one of those two strategies to define your types.
70 This pragma is B<not> implemented with a source filter.
76 XSLoader::load(__PACKAGE__, $VERSION);
84 use Lexical::Types as => $prefix;
85 use Lexical::Types as => sub { ... }; # = $mangler
87 Magically called when C<use Lexical::Types> is encountered.
88 All the occurences of C<my Str $x> in the current lexical scope will be changed to call at each run a given method in a given package.
89 The method and package are determined by the parameter C<'as'> :
95 If it's left unspecified, the C<TYPEDSCALAR> method in the C<Str> package will be called.
98 my Str $x; # calls Str->TYPEDSCALAR
102 If a plain scalar C<$prefix> is passed as the value, the C<TYPEDSCALAR> method in the C<${prefix}::Str> package will be used.
104 use Lexical::Types as => 'My::'; # or "as => 'My'"
105 my Str $x; # calls My::Str->TYPEDSCALAR
109 If the value given is a code reference C<$mangler>, it will be called at compile-time with arguments C<'Str'> and C<'TYPEDSCALAR'> and is expected to return :
115 either an empty list, in which case the current typed lexical definition will be skipped (thus it won't be altered to trigger a run-time hook) ;
117 use Lexical::Types as => sub {
118 return $_[0] =~ /Str/ ? @_ : ()
120 my Str $y; # calls Str->TYPEDSCALAR
121 my Int $x; # nothing special
125 or the desired package and method name, in that order (if any of those is C<undef>, the default value will be used instead).
127 use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
128 my Str $x; # the coderef indicates to call My->new_str
132 Note that if the type is a constant, C<$_[0]> will be set to the I<value> of constant and not to its name.
134 use Lexical::Types as => sub { $_[0] => 'new' };
135 use constant Str => 'MyStr';
136 my Str $x; # calls MyStr->new
138 This means in particular that you can't both use constant types and redirect several types to different methods of the same package, because then you can't distinguish between the original types with C<$_[0]>.
150 my $as = delete $args{'as'};
156 $as .= '::' if $as !~ /::$/;
157 $hint = _tag(sub { $as . $_[0] });
160 Carp::croak("Invalid $r reference for 'as'");
163 $hint = _tag(sub { @_ });
167 $^H{+(__PACKAGE__)} = $hint;
176 Magically called when C<no Lexical::Types> is encountered.
177 Turns the pragma off.
183 $^H{+(__PACKAGE__)} = undef;
188 =head1 RUN-TIME INITIALIZER METHOD
190 The initializer method receives an alias to the pad slot of the initialized lexical in C<$_[1]> and the original type name in C<$_[2]>.
191 You can either edit C<$_[1]> in place, in which case you should return an empty list, or return a new scalar that will be copied into the pad slot.
193 use Lexical::Types as => 'My';
199 sub My::Str::TYPEDSCALAR {
200 # $_[1] is an alias to $x, and $_[2] is 'Str'
206 You can integrate L<Lexical::Types> in your module so that using it will provide types to your users without asking them to load either L<Lexical::Types> or the type classes manually.
210 BEGIN { require Lexical::Types; }
213 eval 'package Str; package Int'; # The types you want to support
214 Lexical::Types->import(
215 as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
220 Lexical::Types->unimport;
227 If you prefer to use constants rather than creating empty packages, you can replace the previous example with something like this :
231 BEGIN { require Lexical::Types; }
236 my $type = __PACKAGE__ . '::' . $_;
238 no warnings 'redefine';
239 *{$pkg.'::'.$_} = eval "sub () { '$type' }";
241 Lexical::Types->import(
242 as => sub { $_[0] => 'new' }
247 Lexical::Types->unimport;
250 package MyTypes::Str;
254 package MyTypes::Int;
260 =head2 C<LT_THREADSAFE>
262 True iff the module could have been built with thread-safety features enabled.
264 =head2 C<LT_FORKSAFE>
266 True iff this module could have been built with fork-safety features enabled.
267 This will always be true except on Windows where it's false for perl 5.10.0 and below .
271 Using this pragma will cause a slight global slowdown of any subsequent compilation phase that happens anywere in your code - even outside of the scope of use of C<use Lexical::Types> - which may become noticeable if you rely heavily on numerous calls to C<eval STRING>.
273 The restrictions on the type (being either a defined package name or a constant) apply even if you use the C<'as'> option to redirect to another package, and are unlikely to find a workaround as this happens deep inside the lexer - far from the reach of an extension.
275 Only one mangler or prefix can be in use at the same time in a given scope.
277 Typed lexicals declarations that appear in code C<eval>'d during the global destruction phase of a spawned thread or pseudo-fork (the processes used internally for the C<fork> emulation on Windows) are ignored.
279 The implementation was tweaked to work around several limitations of vanilla C<perl> pragmas : it's thread safe, and doesn't suffer from a C<perl 5.8.x-5.10.0> bug that causes all pragmas to propagate into C<require>d scopes.
281 With 5.8 perls, the pragma does not propagate into C<eval STRING>.
282 This is due to a shortcoming in the way perl handles the hints hash, which is addressed in perl 5.10.
289 This module may happen to build with a C++ compiler as well, but don't rely on it, as no guarantee is made in this regard.
291 L<XSLoader> (standard since perl 5.6.0).
297 L<Attribute::Handlers>.
301 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
303 You can contact me by mail or on C<irc.perl.org> (vincent).
307 Please report any bugs or feature requests to C<bug-lexical-types at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Lexical-Types>.
308 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
312 You can find documentation for this module with the perldoc command.
314 perldoc Lexical::Types
316 =head1 ACKNOWLEDGEMENTS
318 Inspired by Ricardo Signes.
320 Thanks Florian Ragwitz for suggesting the use of constants for types.
322 =head1 COPYRIGHT & LICENSE
324 Copyright 2009,2010,2011,2012,2013,2014,2015,2017 Vincent Pit, all rights reserved.
326 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
330 1; # End of Lexical::Types