README

   1 NAME
   2     Lexical::Types - Extend the semantics of typed lexicals.
   3
   4 VERSION
   5     Version 0.01
   6
   7 SYNOPSIS
   8         {
   9          package Str;
  10
  11          sub TYPEDSCALAR { Some::String::Implementation->new }
  12         }
  13
  14         use Lexical::Types;
  15
  16         my Str $x; # $x is now a Some::String::Implementation object
  17
  18 DESCRIPTION
  19     This module allows you to hook the execution of typed lexicals
  20     declarations ("my Foo $x"). In particular, it can be used to
  21     automatically tie or bless typed lexicals.
  22
  23     It is not implemented with a source filter.
  24
  25 FUNCTIONS
  26   "import [ as => [ $prefix | $mangler ] ]"
  27     Magically called when writing "use Lexical::Types". All the occurences
  28     of "my Foo $x" in the current lexical scope will be changed to call at
  29     each run a given method in a given package. The method and package are
  30     determined by the parameter "as" :
  31
  32     *   If it's left unspecified, the "TYPEDSCALAR" method in the "Foo"
  33         package will be called.
  34
  35             use Lexical::Types;
  36             my Str $x; # calls Str->TYPEDSCALAR
  37
  38     *   If a plain scalar $prefix is passed as the value, the "TYPEDSCALAR"
  39         method in the "${prefix}::Foo" package will be used.
  40
  41             use Lexical::Types as => 'My::'; # or "as => 'My'"
  42             my Str $x; # calls My::Str->TYPEDSCALAR
  43
  44     *   If the value given is a code reference $mangler, it will be called
  45         at compile-time with arguments 'Foo' and 'TYPEDSCALAR' and is
  46         expected to return the desired package and method name (in that
  47         order). If any of those is "undef", the default value will be used
  48         instead.
  49
  50             use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
  51             my Str $x; # the coderef indicates to call My->new_str
  52
  53     The initializer method receives an alias to the pad entry of $x in $_[1]
  54     and the original type name ("Foo") in $_[2]. You can either edit $_[1]
  55     in place, in which case you should return an empty list, or return a new
  56     scalar that will be copied into $x.
  57
  58   "unimport"
  59     Magically called when writing "no Lexical::Types". Turns the module off.
  60
  61 INTEGRATION
  62     You can integrate Lexical::Types in your module so that using it will
  63     provide types to your users without asking them to load either
  64     Lexical::Types or the type classes manually.
  65
  66         package MyTypes;
  67
  68         BEGIN { require Lexical::Types; }
  69
  70         sub import {
  71          eval 'package Str; package Int'; # The types you want to support
  72          Lexical::Types->import(
  73           as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
  74          );
  75         }
  76
  77         sub unimport {
  78          Lexical::Types->unimport;
  79         }
  80
  81         sub new_str { ... }
  82
  83         sub new_int { ... }
  84
  85 CAVEATS
  86     For "perl" to be able to parse "my Foo $x", the package "Foo" must be
  87     defined somewhere, and this even if you use the "as" option to redirect
  88     to another package. It's unlikely to find a workaround, as this happens
  89     deep inside the lexer, far from the reach of an extension.
  90
  91     Only one mangler or prefix can be in use at the same time in a given
  92     scope.
  93
  94 DEPENDENCIES
  95     perl 5.8, XSLoader.
  96
  97 SEE ALSO
  98     fields.
  99
 100     Attribute::Handlers.
 101
 102 AUTHOR
 103     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 104
 105     You can contact me by mail or on "irc.perl.org" (vincent).
 106
 107 BUGS
 108     Please report any bugs or feature requests to "bug-lexical-types at
 109     rt.cpan.org", or through the web interface at
 110     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Lexical-Types>. I will
 111     be notified, and then you'll automatically be notified of progress on
 112     your bug as I make changes.
 113
 114 SUPPORT
 115     You can find documentation for this module with the perldoc command.
 116
 117         perldoc Lexical::Types
 118
 119 ACKNOWLEDGEMENTS
 120     Inspired by Ricardo Signes.
 121
 122 COPYRIGHT & LICENSE
 123     Copyright 2009 Vincent Pit, all rights reserved.
 124
 125     This program is free software; you can redistribute it and/or modify it
 126     under the same terms as Perl itself.
 127