lib/Lexical/Types.pm

   1 package Lexical::Types;
   2
   3 use 5.008;
   4
   5 use strict;
   6 use warnings;
   7
   8 use Carp qw/croak/;
   9
  10 =head1 NAME
  11
  12 Lexical::Types - Extend the semantics of typed lexicals.
  13
  14 =head1 VERSION
  15
  16 Version 0.01
  17
  18 =cut
  19
  20 our $VERSION;
  21 BEGIN {
  22  $VERSION = '0.01';
  23 }
  24
  25 =head1 SYNOPSIS
  26
  27     {
  28      package Str;
  29
  30      sub TYPEDSCALAR { Some::String::Implementation->new }
  31     }
  32
  33     use Lexical::Types;
  34
  35     my Str $x; # $x is now a Some::String::Implementation object
  36
  37 =head1 DESCRIPTION
  38
  39 This module allows you to hook the execution of typed lexicals declarations (C<my Foo $x>).
  40 In particular, it can be used to automatically tie or bless typed lexicals.
  41
  42 It is B<not> implemented with a source filter.
  43
  44 =cut
  45
  46 BEGIN {
  47  require XSLoader;
  48  XSLoader::load(__PACKAGE__, $VERSION);
  49 }
  50
  51 =head1 FUNCTIONS
  52
  53 =head2 C<< import [ as => [ $prefix | $mangler ] ] >>
  54
  55 Magically called when writing C<use Lexical::Types>.
  56 All the occurences of C<my Foo $x> in the current lexical scope will be changed to call at each run a given method in a given package.
  57 The method and package are determined by the parameter C<as> :
  58
  59 =over 4
  60
  61 =item *
  62
  63 If it's left unspecified, the C<TYPEDSCALAR> method in the C<Foo> package will be called.
  64
  65     use Lexical::Types;
  66     my Str $x; # calls Str->TYPEDSCALAR
  67
  68 =item *
  69
  70 If a plain scalar C<$prefix> is passed as the value, the C<TYPEDSCALAR> method in the C<${prefix}::Foo> package will be used.
  71
  72     use Lexical::Types as => 'My::'; # or "as => 'My'"
  73     my Str $x; # calls My::Str->TYPEDSCALAR
  74
  75 =item *
  76
  77 If the value given is a code reference C<$mangler>, it will be called at compile-time with arguments C<'Foo'> and C<'TYPEDSCALAR'> and is expected to return the desired package and method name (in that order).
  78 If any of those is C<undef>, the default value will be used instead.
  79
  80     use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
  81     my Str $x; # the coderef indicates to call My->new_str
  82
  83 =back
  84
  85 The initializer method receives an alias to the pad entry of C<$x> in C<$_[1]> and the original type name (C<Foo>) in C<$_[2]>.
  86 You can either edit C<$_[1]> in place, in which case you should return an empty list, or return a new scalar that will be copied into C<$x>.
  87
  88 =cut
  89
  90 sub import {
  91  shift;
  92  my %args = @_;
  93
  94  my $hint;
  95
  96  my $as = delete $args{'as'};
  97  if ($as) {
  98   my $r = ref $as;
  99   if ($r eq 'CODE') {
 100    $hint = _tag($as);
 101   } elsif (!$r) {
 102    $as .= '::' if $as !~ /::$/;
 103    $hint = _tag(sub { $as . $_[0] });
 104   } else {
 105    croak "Invalid $r reference for 'as'";
 106   }
 107  } else {
 108   $hint = _tag(0);
 109  }
 110
 111  $^H |= 0x020000;
 112  # Yes, we store a coderef inside the hints hash, but that's just for compile
 113  # time.
 114  $^H{+(__PACKAGE__)} = $hint;
 115 }
 116
 117 =head2 C<unimport>
 118
 119 Magically called when writing C<no Lexical::Types>.
 120 Turns the module off.
 121
 122 =cut
 123
 124 sub unimport {
 125  $^H{+(__PACKAGE__)} = undef;
 126 }
 127
 128 =head1 INTEGRATION
 129
 130 You can integrate L<Lexical::Types> in your module so that using it will provide types to your users without asking them to load either L<Lexical::Types> or the type classes manually.
 131
 132     package MyTypes;
 133
 134     BEGIN { require Lexical::Types; }
 135
 136     sub import {
 137      eval 'package Str; package Int'; # The types you want to support
 138      Lexical::Types->import(
 139       as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
 140      );
 141     }
 142
 143     sub unimport {
 144      Lexical::Types->unimport;
 145     }
 146
 147     sub new_str { ... }
 148
 149     sub new_int { ... }
 150
 151 =head1 CAVEATS
 152
 153 For C<perl> to be able to parse C<my Foo $x>, the package C<Foo> must be defined somewhere, and this even if you use the C<as> option to redirect to another package.
 154 It's unlikely to find a workaround, as this happens deep inside the lexer, far from the reach of an extension.
 155
 156 Only one mangler or prefix can be in use at the same time in a given scope.
 157
 158 =head1 DEPENDENCIES
 159
 160 L<perl> 5.8, L<XSLoader>.
 161
 162 =head1 SEE ALSO
 163
 164 L<fields>.
 165
 166 L<Attribute::Handlers>.
 167
 168 =head1 AUTHOR
 169
 170 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 171
 172 You can contact me by mail or on C<irc.perl.org> (vincent).
 173
 174 =head1 BUGS
 175
 176 Please report any bugs or feature requests to C<bug-lexical-types at rt.cpan.org>, or through the web interface at L<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.
 177
 178 =head1 SUPPORT
 179
 180 You can find documentation for this module with the perldoc command.
 181
 182     perldoc Lexical::Types
 183
 184 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Lexical-Types>.
 185
 186 =head1 ACKNOWLEDGEMENTS
 187
 188 Inspired by Ricardo Signes.
 189
 190 =head1 COPYRIGHT & LICENSE
 191
 192 Copyright 2009 Vincent Pit, all rights reserved.
 193
 194 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
 195
 196 =cut
 197
 198 1; # End of Lexical::Types