package Lexical::Types;
-use 5.008;
+use 5.008_003;
use strict;
use warnings;
-use Carp qw/croak/;
-
=head1 NAME
Lexical::Types - Extend the semantics of typed lexicals.
=head1 VERSION
-Version 0.03
+Version 0.12
=cut
our $VERSION;
BEGIN {
- $VERSION = '0.03';
+ $VERSION = '0.12';
}
=head1 SYNOPSIS
XSLoader::load(__PACKAGE__, $VERSION);
}
-=head1 FUNCTIONS
+=head1 METHODS
+
+=head2 C<import>
-=head2 C<< import [ as => [ $prefix | $mangler ] ] >>
+ use Lexical::Types;
+ use Lexical::Types as => $prefix;
+ use Lexical::Types as => sub { ... }; # = $mangler
-Magically called when writing C<use Lexical::Types>.
+Magically called when C<use Lexical::Types> is encountered.
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.
The method and package are determined by the parameter C<'as'> :
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) ;
- use Lexical::Types as => sub { return $_[0] =~ /Str/ ? @_ : () };
+ use Lexical::Types as => sub {
+ return $_[0] =~ /Str/ ? @_ : ()
+ };
my Str $y; # calls Str->TYPEDSCALAR
my Int $x; # nothing special
=back
-=back
+Note that if the type is a constant, C<$_[0]> will be set to the I<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 C<$_[0]>.
-The initializer method receives an alias to the pad entry of C<$x> in C<$_[1]> and the original type name (C<Str>) in C<$_[2]>.
-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 C<$x>.
+=back
=cut
$as .= '::' if $as !~ /::$/;
$hint = _tag(sub { $as . $_[0] });
} else {
- croak "Invalid $r reference for 'as'";
+ require Carp;
+ Carp::croak("Invalid $r reference for 'as'");
}
} else {
- $hint = _tag(0);
+ $hint = _tag(sub { @_ });
}
$^H |= 0x020000;
=head2 C<unimport>
-Magically called when writing C<no Lexical::Types>.
+ no Lexical::Types;
+
+Magically called when C<no Lexical::Types> is encountered.
Turns the pragma off.
=cut
$^H{+(__PACKAGE__)} = undef;
}
+=head1 RUN-TIME INITIALIZER METHOD
+
+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]>.
+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.
+
+ use Lexical::Types as => 'My';
+
+ my Str $x;
+
+ ...
+
+ sub My::Str::TYPEDSCALAR {
+ # $_[1] is an alias to $x, and $_[2] is 'Str'
+ ...
+ }
+
=head1 INTEGRATION
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.
sub new_int { ... }
-=head1 CAVEATS
+If you prefer to use constants rather than creating empty packages, you can replace the previous example with something like this :
-For C<perl> to be able to parse C<my Str $x>, you need :
+ package MyTypes;
-=over 4
+ BEGIN { require Lexical::Types; }
-=item *
+ 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' }
+ );
+ }
-either the C<Str> package to be defined ;
+ sub unimport {
+ Lexical::Types->unimport;
+ }
-=item *
+ package MyTypes::Str;
-or for C<Str> to be a constant sub returning a valid defined package.
+ sub new { ... }
-=back
+ package MyTypes::Int;
+
+ sub new { ... }
+
+=head1 CONSTANTS
+
+=head2 C<LT_THREADSAFE>
+
+True iff the module could have been built with thread-safety features enabled.
+
+=head2 C<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 .
+
+=head1 CAVEATS
+
+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>.
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.
Only one mangler or prefix can be in use at the same time in a given scope.
+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.
+
+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.
+
+With 5.8 perls, the pragma does not propagate into C<eval STRING>.
+This is due to a shortcoming in the way perl handles the hints hash, which is addressed in perl 5.10.
+
=head1 DEPENDENCIES
-L<perl> 5.8, L<XSLoader>.
+L<perl> 5.8.3.
+
+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.
+
+L<XSLoader> (standard since perl 5.6.0).
=head1 SEE ALSO
=head1 BUGS
-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>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
+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>.
+I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
=head1 SUPPORT
=head1 COPYRIGHT & LICENSE
-Copyright 2009 Vincent Pit, all rights reserved.
+Copyright 2009,2010,2011,2012,2013,2014 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