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.03
  17
  18 =cut
  19
  20 our $VERSION;
  21 BEGIN {
  22  $VERSION = '0.03';
  23 }
  24
  25 =head1 SYNOPSIS
  26
  27     { package Str; }
  28
  29     {
  30      package My::Types::Str;
  31
  32      sub new { bless { }, shift }
  33     }
  34
  35     use Lexical::Types as => sub { 'My::Types::' . $_[0] => 'new' };
  36
  37     my Str $x; # $x is now a My::Types::Str object
  38
  39     {
  40      package My::Types::Int;
  41
  42      sub TYPEDSCALAR { bless { }, shift }
  43     }
  44
  45     use Lexical::Types;
  46
  47     use constant Int => 'My::Types::Int';
  48
  49     my Int $y; # $y is now a My::Types::Int object
  50
  51 =head1 DESCRIPTION
  52
  53 This pragma allows you to hook the execution of typed lexicals declarations (C<my Str $x>) by calling a configurable method in a configurable package at each run.
  54 In particular, it can be used to automatically tie or bless typed lexicals whenever they are initialized.
  55
  56 Remind that for C<perl> to be able to parse C<my Str $x>, you need :
  57
  58 =over 4
  59
  60 =item *
  61
  62 either the C<Str> package to be defined ;
  63
  64 =item *
  65
  66 or for C<Str> to be a constant sub returning a valid defined package.
  67
  68 =back
  69
  70 so make sure you follow one of those two strategies to define your types.
  71
  72 This pragma is B<not> implemented with a source filter.
  73
  74 =cut
  75
  76 BEGIN {
  77  require XSLoader;
  78  XSLoader::load(__PACKAGE__, $VERSION);
  79 }
  80
  81 =head1 FUNCTIONS
  82
  83 =head2 C<< import [ as => [ $prefix | $mangler ] ] >>
  84
  85 Magically called when writing C<use Lexical::Types>.
  86 All the occurences of C<my Str $x> in the current lexical scope will be changed to call at each run a given method in a given package.
  87 The method and package are determined by the parameter C<'as'> :
  88
  89 =over 4
  90
  91 =item *
  92
  93 If it's left unspecified, the C<TYPEDSCALAR> method in the C<Str> package will be called.
  94
  95     use Lexical::Types;
  96     my Str $x; # calls Str->TYPEDSCALAR
  97
  98 =item *
  99
 100 If a plain scalar C<$prefix> is passed as the value, the C<TYPEDSCALAR> method in the C<${prefix}::Str> package will be used.
 101
 102     use Lexical::Types as => 'My::'; # or "as => 'My'"
 103     my Str $x; # calls My::Str->TYPEDSCALAR
 104
 105 =item *
 106
 107 If the value given is a code reference C<$mangler>, it will be called at compile-time with arguments C<'Str'> and C<'TYPEDSCALAR'> and is expected to return :
 108
 109 =over 4
 110
 111 =item *
 112
 113 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) ;
 114
 115     use Lexical::Types as => sub { return $_[0] =~ /Str/ ? @_ : () };
 116     my Str $y; # calls Str->TYPEDSCALAR
 117     my Int $x; # nothing special
 118
 119 =item *
 120
 121 or the desired package and method name, in that order (if any of those is C<undef>, the default value will be used instead).
 122
 123     use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
 124     my Str $x; # the coderef indicates to call My->new_str
 125
 126 =back
 127
 128 =back
 129
 130 The initializer method receives an alias to the pad entry of C<$x> in C<$_[1]> and the original type name (C<Str>) in C<$_[2]>.
 131 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>.
 132
 133 =cut
 134
 135 sub import {
 136  shift;
 137  my %args = @_;
 138
 139  my $hint;
 140
 141  my $as = delete $args{'as'};
 142  if ($as) {
 143   my $r = ref $as;
 144   if ($r eq 'CODE') {
 145    $hint = _tag($as);
 146   } elsif (!$r) {
 147    $as .= '::' if $as !~ /::$/;
 148    $hint = _tag(sub { $as . $_[0] });
 149   } else {
 150    croak "Invalid $r reference for 'as'";
 151   }
 152  } else {
 153   $hint = _tag(0);
 154  }
 155
 156  $^H |= 0x020000;
 157  # Yes, we store a coderef inside the hints hash, but that's just for compile
 158  # time.
 159  $^H{+(__PACKAGE__)} = $hint;
 160 }
 161
 162 =head2 C<unimport>
 163
 164 Magically called when writing C<no Lexical::Types>.
 165 Turns the pragma off.
 166
 167 =cut
 168
 169 sub unimport {
 170  $^H{+(__PACKAGE__)} = undef;
 171 }
 172
 173 =head1 INTEGRATION
 174
 175 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.
 176
 177     package MyTypes;
 178
 179     BEGIN { require Lexical::Types; }
 180
 181     sub import {
 182      eval 'package Str; package Int'; # The types you want to support
 183      Lexical::Types->import(
 184       as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
 185      );
 186     }
 187
 188     sub unimport {
 189      Lexical::Types->unimport;
 190     }
 191
 192     sub new_str { ... }
 193
 194     sub new_int { ... }
 195
 196 =head1 CAVEATS
 197
 198 For C<perl> to be able to parse C<my Str $x>, you need :
 199
 200 =over 4
 201
 202 =item *
 203
 204 either the C<Str> package to be defined ;
 205
 206 =item *
 207
 208 or for C<Str> to be a constant sub returning a valid defined package.
 209
 210 =back
 211
 212 The restrictions on the type (being either a defined package name or a constant) apply even if you use the C<'as'> option to redirect to another package, and are unlikely to find a workaround as this happens deep inside the lexer - far from the reach of an extension.
 213
 214 Only one mangler or prefix can be in use at the same time in a given scope.
 215
 216 =head1 DEPENDENCIES
 217
 218 L<perl> 5.8, L<XSLoader>.
 219
 220 =head1 SEE ALSO
 221
 222 L<fields>.
 223
 224 L<Attribute::Handlers>.
 225
 226 =head1 AUTHOR
 227
 228 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 229
 230 You can contact me by mail or on C<irc.perl.org> (vincent).
 231
 232 =head1 BUGS
 233
 234 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.
 235
 236 =head1 SUPPORT
 237
 238 You can find documentation for this module with the perldoc command.
 239
 240     perldoc Lexical::Types
 241
 242 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Lexical-Types>.
 243
 244 =head1 ACKNOWLEDGEMENTS
 245
 246 Inspired by Ricardo Signes.
 247
 248 Thanks Florian Ragwitz for suggesting the use of constants for types.
 249
 250 =head1 COPYRIGHT & LICENSE
 251
 252 Copyright 2009 Vincent Pit, all rights reserved.
 253
 254 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
 255
 256 =cut
 257
 258 1; # End of Lexical::Types