README

   1 NAME
   2     Lexical::Types - Extend the semantics of typed lexicals.
   3
   4 VERSION
   5     Version 0.02
   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 Str $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 Str $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 "Str"
  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}::Str" 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 'Str' and 'TYPEDSCALAR' and is
  46         expected to return :
  47
  48         *   either an empty list, in which case the current typed lexical
  49             definition will be skipped (thus it won't be altered to trigger
  50             a run-time hook) ;
  51
  52                 use Lexical::Types as => sub { return $_[0] =~ /Str/ ? () : @_ };
  53                 my Str $x; # nothing special
  54                 my Int $y; # calls Int->TYPEDSCALAR
  55
  56         *   or the desired package and method name, in that order (if any of
  57             those is "undef", the default value will be used instead).
  58
  59                 use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
  60                 my Str $x; # the coderef indicates to call My->new_str
  61
  62     The initializer method receives an alias to the pad entry of $x in $_[1]
  63     and the original type name ("Str") in $_[2]. You can either edit $_[1]
  64     in place, in which case you should return an empty list, or return a new
  65     scalar that will be copied into $x.
  66
  67   "unimport"
  68     Magically called when writing "no Lexical::Types". Turns the module off.
  69
  70 INTEGRATION
  71     You can integrate Lexical::Types in your module so that using it will
  72     provide types to your users without asking them to load either
  73     Lexical::Types or the type classes manually.
  74
  75         package MyTypes;
  76
  77         BEGIN { require Lexical::Types; }
  78
  79         sub import {
  80          eval 'package Str; package Int'; # The types you want to support
  81          Lexical::Types->import(
  82           as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
  83          );
  84         }
  85
  86         sub unimport {
  87          Lexical::Types->unimport;
  88         }
  89
  90         sub new_str { ... }
  91
  92         sub new_int { ... }
  93
  94 CAVEATS
  95     For "perl" to be able to parse "my Str $x", the package "Str" must be
  96     defined somewhere, and this even if you use the 'as' option to redirect
  97     to another package. It's unlikely to find a workaround, as this happens
  98     deep inside the lexer, far from the reach of an extension.
  99
 100     Only one mangler or prefix can be in use at the same time in a given
 101     scope.
 102
 103 DEPENDENCIES
 104     perl 5.8, XSLoader.
 105
 106 SEE ALSO
 107     fields.
 108
 109     Attribute::Handlers.
 110
 111 AUTHOR
 112     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 113
 114     You can contact me by mail or on "irc.perl.org" (vincent).
 115
 116 BUGS
 117     Please report any bugs or feature requests to "bug-lexical-types at
 118     rt.cpan.org", or through the web interface at
 119     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Lexical-Types>. I will
 120     be notified, and then you'll automatically be notified of progress on
 121     your bug as I make changes.
 122
 123 SUPPORT
 124     You can find documentation for this module with the perldoc command.
 125
 126         perldoc Lexical::Types
 127
 128     Tests code coverage report is available at
 129     <http://www.profvince.com/perl/cover/Lexical-Types>.
 130
 131 ACKNOWLEDGEMENTS
 132     Inspired by Ricardo Signes.
 133
 134 COPYRIGHT & LICENSE
 135     Copyright 2009 Vincent Pit, all rights reserved.
 136
 137     This program is free software; you can redistribute it and/or modify it
 138     under the same terms as Perl itself.
 139