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

VERSION
    Version 0.02

SYNOPSIS
        {
         package Str;

         sub TYPEDSCALAR { Some::String::Implementation->new }
        }

        use Lexical::Types;

        my Str $x; # $x is now a Some::String::Implementation object

DESCRIPTION
    This module 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 $x; # nothing special
                my Int $y; # calls Int->TYPEDSCALAR

        *   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 module 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", the package "Str" 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.

    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.

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.