Lexical::Types - Extend the semantics of typed lexicals.
VERSION
- Version 0.01
+ Version 0.16
SYNOPSIS
+ { package Str; }
+
+ {
+ package My::Types::Str;
+
+ sub new { bless { }, shift }
+ }
+
+ use Lexical::Types as => sub { 'My::Types::' . $_[0] => 'new' };
+
+ my Str $x; # $x is now a My::Types::Str object
+
{
- package Str;
+ package My::Types::Int;
- sub TYPEDSCALAR { Some::String::Implementation->new }
+ sub TYPEDSCALAR { bless { }, shift }
}
use Lexical::Types;
- my Str $x; # $x is now a Some::String::Implementation object
+ use constant Int => 'My::Types::Int';
+
+ my Int $y; # $y is now a My::Types::Int object
DESCRIPTION
- This module allows you to hook the execution of typed lexicals
- declarations ("my Foo $x"). In particular, it can be used to
- automatically tie or bless typed lexicals.
+ This pragma allows you to hook the execution of typed lexicals
+ declarations ("my Str $x") by calling a configurable method in a
+ configurable package at each run. In particular, it can be used to
+ automatically tie or bless typed lexicals whenever they are initialized.
+
+ Remind that for "perl" to be able to parse "my Str $x", you need :
+
+ * either the "Str" package to be defined ;
+
+ * or for "Str" to be a constant sub returning a valid defined package.
- It is not implemented with a source filter.
+ so make sure you follow one of those two strategies to define your
+ types.
+
+ This pragma is not implemented with a source filter.
+
+METHODS
+ "import"
+ use Lexical::Types;
+ use Lexical::Types as => $prefix;
+ use Lexical::Types as => sub { ... }; # = $mangler
-FUNCTIONS
- "import [ as => [ $prefix | $mangler ] ]"
- Magically called when writing "use Lexical::Types". All the occurences
- of "my Foo $x" in the current lexical scope will be changed to call at
- each run a given method in a given package. The method and package are
- determined by the parameter "as" :
+ Magically called when "use Lexical::Types" is encountered. All the
+ occurences of "my Str $x" in the current lexical scope will be changed
+ to call at each run a given method in a given package. The method and
+ package are determined by the parameter 'as' :
- * If it's left unspecified, the "TYPEDSCALAR" method in the "Foo"
+ * If it's left unspecified, the "TYPEDSCALAR" method in the "Str"
package will be called.
use Lexical::Types;
my Str $x; # calls Str->TYPEDSCALAR
* If a plain scalar $prefix is passed as the value, the "TYPEDSCALAR"
- method in the "${prefix}::Foo" package will be used.
+ method in the "${prefix}::Str" package will be used.
use Lexical::Types as => 'My::'; # or "as => 'My'"
my Str $x; # calls My::Str->TYPEDSCALAR
* If the value given is a code reference $mangler, it will be called
- at compile-time with arguments 'Foo' and 'TYPEDSCALAR' and is
- expected to return the desired package and method name (in that
- order). If any of those is "undef", the default value will be used
- instead.
+ at compile-time with arguments 'Str' and 'TYPEDSCALAR' and is
+ expected to return :
- use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
- my Str $x; # the coderef indicates to call My->new_str
+ * 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) ;
- The initializer method receives an alias to the pad entry of $x in $_[1]
- and the original type name ("Foo") in $_[2]. You can either edit $_[1]
- in place, in which case you should return an empty list, or return a new
- scalar that will be copied into $x.
+ use Lexical::Types as => sub {
+ return $_[0] =~ /Str/ ? @_ : ()
+ };
+ my Str $y; # calls Str->TYPEDSCALAR
+ my Int $x; # nothing special
+
+ * or the desired package and method name, in that order (if any of
+ those is "undef", the default value will be used instead).
+
+ use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
+ my Str $x; # the coderef indicates to call My->new_str
+
+ Note that if the type is a constant, $_[0] will be set to the
+ *value* of constant and not to its name.
+
+ use Lexical::Types as => sub { $_[0] => 'new' };
+ use constant Str => 'MyStr';
+ my Str $x; # calls MyStr->new
+
+ 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
+ $_[0].
"unimport"
- Magically called when writing "no Lexical::Types". Turns the module off.
+ no Lexical::Types;
+
+ Magically called when "no Lexical::Types" is encountered. Turns the
+ pragma off.
+
+RUN-TIME INITIALIZER METHOD
+ The initializer method receives an alias to the pad slot of the
+ initialized lexical in $_[1] and the original type name in $_[2]. You
+ can either edit $_[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.
+
+ use Lexical::Types as => 'My';
+
+ my Str $x;
+
+ ...
+
+ sub My::Str::TYPEDSCALAR {
+ # $_[1] is an alias to $x, and $_[2] is 'Str'
+ ...
+ }
INTEGRATION
You can integrate Lexical::Types in your module so that using it will
sub new_int { ... }
+ If you prefer to use constants rather than creating empty packages, you
+ can replace the previous example with something like this :
+
+ package MyTypes;
+
+ BEGIN { require Lexical::Types; }
+
+ sub import {
+ my $pkg = caller;
+ for (qw<Str Int>) {
+ my $type = __PACKAGE__ . '::' . $_;
+ no strict 'refs';
+ no warnings 'redefine';
+ *{$pkg.'::'.$_} = eval "sub () { '$type' }";
+ }
+ Lexical::Types->import(
+ as => sub { $_[0] => 'new' }
+ );
+ }
+
+ sub unimport {
+ Lexical::Types->unimport;
+ }
+
+ package MyTypes::Str;
+
+ sub new { ... }
+
+ package MyTypes::Int;
+
+ sub new { ... }
+
+CONSTANTS
+ "LT_THREADSAFE"
+ True iff the module could have been built with thread-safety features
+ enabled.
+
+ "LT_FORKSAFE"
+ True iff this module could have been built with fork-safety features
+ enabled. This will always be true except on Windows where it's false for
+ perl 5.10.0 and below .
+
CAVEATS
- For "perl" to be able to parse "my Foo $x", the package "Foo" must be
- defined somewhere, and this even if you use the "as" option to redirect
- to another package. It's unlikely to find a workaround, as this happens
- deep inside the lexer, far from the reach of an extension.
+ 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 "use Lexical::Types" - which may become noticeable
+ if you rely heavily on numerous calls to "eval STRING".
+
+ The restrictions on the type (being either a defined package name or a
+ constant) apply even if you use the '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.
Only one mangler or prefix can be in use at the same time in a given
scope.
+ Typed lexicals declarations that appear in code "eval"'d during the
+ global destruction phase of a spawned thread or pseudo-fork (the
+ processes used internally for the "fork" emulation on Windows) are
+ ignored.
+
+ The implementation was tweaked to work around several limitations of
+ vanilla "perl" pragmas : it's thread safe, and doesn't suffer from a
+ "perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into
+ "require"d scopes.
+
+ With 5.8 perls, the pragma does not propagate into "eval STRING". This
+ is due to a shortcoming in the way perl handles the hints hash, which is
+ addressed in perl 5.10.
+
DEPENDENCIES
- perl 5.8, XSLoader.
+ perl 5.8.4.
+
+ A C compiler. 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.
+
+ XSLoader (standard since perl 5.6.0).
SEE ALSO
fields.
ACKNOWLEDGEMENTS
Inspired by Ricardo Signes.
+ Thanks Florian Ragwitz for suggesting the use of constants for types.
+
COPYRIGHT & LICENSE
- Copyright 2009 Vincent Pit, all rights reserved.
+ Copyright 2009,2010,2011,2012,2013,2014,2015,2017 Vincent Pit, all
+ rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
projects / perl / modules / Lexical-Types.git / blobdiff