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"). In particular, it can be used to
35 automatically tie or bless typed lexicals.
37 It is not implemented with a source filter.
40 "import [ as => [ $prefix | $mangler ] ]"
41 Magically called when writing "use Lexical::Types". All the occurences
42 of "my Str $x" in the current lexical scope will be changed to call at
43 each run a given method in a given package. The method and package are
44 determined by the parameter 'as' :
46 * If it's left unspecified, the "TYPEDSCALAR" method in the "Str"
47 package will be called.
50 my Str $x; # calls Str->TYPEDSCALAR
52 * If a plain scalar $prefix is passed as the value, the "TYPEDSCALAR"
53 method in the "${prefix}::Str" package will be used.
55 use Lexical::Types as => 'My::'; # or "as => 'My'"
56 my Str $x; # calls My::Str->TYPEDSCALAR
58 * If the value given is a code reference $mangler, it will be called
59 at compile-time with arguments 'Str' and 'TYPEDSCALAR' and is
62 * either an empty list, in which case the current typed lexical
63 definition will be skipped (thus it won't be altered to trigger
66 use Lexical::Types as => sub { return $_[0] =~ /Str/ ? @_ : () };
67 my Str $y; # calls Str->TYPEDSCALAR
68 my Int $x; # nothing special
70 * or the desired package and method name, in that order (if any of
71 those is "undef", the default value will be used instead).
73 use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
74 my Str $x; # the coderef indicates to call My->new_str
76 The initializer method receives an alias to the pad entry of $x in $_[1]
77 and the original type name ("Str") in $_[2]. You can either edit $_[1]
78 in place, in which case you should return an empty list, or return a new
79 scalar that will be copied into $x.
82 Magically called when writing "no Lexical::Types". Turns the pragma off.
85 You can integrate Lexical::Types in your module so that using it will
86 provide types to your users without asking them to load either
87 Lexical::Types or the type classes manually.
91 BEGIN { require Lexical::Types; }
94 eval 'package Str; package Int'; # The types you want to support
95 Lexical::Types->import(
96 as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
101 Lexical::Types->unimport;
109 For "perl" to be able to parse "my Str $x", you need :
111 * either the "Str" package to be defined ;
113 * or for "Str" to be a constant sub returning a valid defined package.
115 Those restrictions apply even if you use the 'as' option to redirect to
116 another package, and are unlikely to find a workaround as this happens
117 deep inside the lexer - far from the reach of an extension.
119 Only one mangler or prefix can be in use at the same time in a given
131 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
133 You can contact me by mail or on "irc.perl.org" (vincent).
136 Please report any bugs or feature requests to "bug-lexical-types at
137 rt.cpan.org", or through the web interface at
138 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Lexical-Types>. I will
139 be notified, and then you'll automatically be notified of progress on
140 your bug as I make changes.
143 You can find documentation for this module with the perldoc command.
145 perldoc Lexical::Types
147 Tests code coverage report is available at
148 <http://www.profvince.com/perl/cover/Lexical-Types>.
151 Inspired by Ricardo Signes.
153 Thanks Florian Ragwitz for suggesting the use of constants for types.
156 Copyright 2009 Vincent Pit, all rights reserved.
158 This program is free software; you can redistribute it and/or modify it
159 under the same terms as Perl itself.