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

VERSION
    Version 0.01

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 Foo $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 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" :

    *   If it's left unspecified, the "TYPEDSCALAR" method in the "Foo"
        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.

            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.

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

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

    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

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.