/ 
Lexical-Types-0.03
River stage one • 2 direct dependents • 2 total dependents
/ Lexical::Types

NAME

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

VERSION

Version 0.03

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). In particular, it can be used to automatically tie or bless typed lexicals.

It is not implemented with a source filter.

FUNCTIONS

import [ as => [ $prefix | $mangler ] ]

Magically called when writing use Lexical::Types. 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 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}::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 'Str' and 'TYPEDSCALAR' and is expected to return :

    • 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/ ? @_ : () };
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

The initializer method receives an alias to the pad entry of $x in $_[1] and the original type name (Str) 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.

unimport

Magically called when writing no Lexical::Types. Turns the pragma off.

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 { ... }

CAVEATS

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.

Those restrictions 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.

DEPENDENCIES

perl 5.8, XSLoader.

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