Vincent Pit > Lexical-Types-0.13 > Lexical::Types

Download:
Lexical-Types-0.13.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.13   Source  

NAME ^

Lexical::Types - Extend the semantics of typed lexicals.

VERSION ^

Version 0.13

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 My::Types::Int;

     sub TYPEDSCALAR { bless { }, shift }
    }

    use Lexical::Types;

    use constant Int => 'My::Types::Int';

    my Int $y; # $y is now a My::Types::Int object

DESCRIPTION ^

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 :

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

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' :

unimport

    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 provide types to your users without asking them to load either Lexical::Types or the type classes manually.

    package MyTypes;

    BEGIN { require Lexical::Types; }

    sub import {
     eval 'package Str; package Int'; # The types you want to support
     Lexical::Types->import(
      as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
     );
    }

    sub unimport {
     Lexical::Types->unimport;
    }

    sub new_str { ... }

    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 ^

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 required 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.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.

XSLoader (standard since perl 5.6.0).

SEE ALSO ^

fields.

Attribute::Handlers.

AUTHOR ^

Vincent Pit, <perl at profvince.com>, http://www.profvince.com.

You can contact me by mail or on irc.perl.org (vincent).

BUGS ^

Please report any bugs or feature requests to bug-lexical-types at rt.cpan.org, or through the web interface at 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.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc Lexical::Types

Tests code coverage report is available at http://www.profvince.com/perl/cover/Lexical-Types.

ACKNOWLEDGEMENTS ^

Inspired by Ricardo Signes.

Thanks Florian Ragwitz for suggesting the use of constants for types.

COPYRIGHT & LICENSE ^

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.

syntax highlighting: