lib/Lexical/Types.pm

   1 package Lexical::Types;
   2
   3 use 5.008003;
   4
   5 use strict;
   6 use warnings;
   7
   8 =head1 NAME
   9
  10 Lexical::Types - Extend the semantics of typed lexicals.
  11
  12 =head1 VERSION
  13
  14 Version 0.12
  15
  16 =cut
  17
  18 our $VERSION;
  19 BEGIN {
  20  $VERSION = '0.12';
  21 }
  22
  23 =head1 SYNOPSIS
  24
  25     { package Str; }
  26
  27     {
  28      package My::Types::Str;
  29
  30      sub new { bless { }, shift }
  31     }
  32
  33     use Lexical::Types as => sub { 'My::Types::' . $_[0] => 'new' };
  34
  35     my Str $x; # $x is now a My::Types::Str object
  36
  37     {
  38      package My::Types::Int;
  39
  40      sub TYPEDSCALAR { bless { }, shift }
  41     }
  42
  43     use Lexical::Types;
  44
  45     use constant Int => 'My::Types::Int';
  46
  47     my Int $y; # $y is now a My::Types::Int object
  48
  49 =head1 DESCRIPTION
  50
  51 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.
  52 In particular, it can be used to automatically tie or bless typed lexicals whenever they are initialized.
  53
  54 Remind that for C<perl> to be able to parse C<my Str $x>, you need :
  55
  56 =over 4
  57
  58 =item *
  59
  60 either the C<Str> package to be defined ;
  61
  62 =item *
  63
  64 or for C<Str> to be a constant sub returning a valid defined package.
  65
  66 =back
  67
  68 so make sure you follow one of those two strategies to define your types.
  69
  70 This pragma is B<not> implemented with a source filter.
  71
  72 =cut
  73
  74 BEGIN {
  75  require XSLoader;
  76  XSLoader::load(__PACKAGE__, $VERSION);
  77 }
  78
  79 =head1 METHODS
  80
  81 =head2 C<import>
  82
  83     use Lexical::Types;
  84     use Lexical::Types as => $prefix;
  85     use Lexical::Types as => sub { ... }; # = $mangler
  86
  87 Magically called when C<use Lexical::Types> is encountered.
  88 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.
  89 The method and package are determined by the parameter C<'as'> :
  90
  91 =over 4
  92
  93 =item *
  94
  95 If it's left unspecified, the C<TYPEDSCALAR> method in the C<Str> package will be called.
  96
  97     use Lexical::Types;
  98     my Str $x; # calls Str->TYPEDSCALAR
  99
 100 =item *
 101
 102 If a plain scalar C<$prefix> is passed as the value, the C<TYPEDSCALAR> method in the C<${prefix}::Str> package will be used.
 103
 104     use Lexical::Types as => 'My::'; # or "as => 'My'"
 105     my Str $x; # calls My::Str->TYPEDSCALAR
 106
 107 =item *
 108
 109 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 :
 110
 111 =over 4
 112
 113 =item *
 114
 115 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) ;
 116
 117     use Lexical::Types as => sub { return $_[0] =~ /Str/ ? @_ : () };
 118     my Str $y; # calls Str->TYPEDSCALAR
 119     my Int $x; # nothing special
 120
 121 =item *
 122
 123 or the desired package and method name, in that order (if any of those is C<undef>, the default value will be used instead).
 124
 125     use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
 126     my Str $x; # the coderef indicates to call My->new_str
 127
 128 =back
 129
 130 Note that if the type is a constant, C<$_[0]> will be set to the I<value> of constant and not to its name.
 131
 132     use Lexical::Types as => sub { $_[0] => 'new' };
 133     use constant Str => 'MyStr';
 134     my Str $x; # calls MyStr->new
 135
 136 This means in particular that you can't both use constant types and redirect several types to different methods of the same package, because then you can't distinguish between the original types with C<$_[0]>.
 137
 138 =back
 139
 140 =cut
 141
 142 sub import {
 143  shift;
 144  my %args = @_;
 145
 146  my $hint;
 147
 148  my $as = delete $args{'as'};
 149  if ($as) {
 150   my $r = ref $as;
 151   if ($r eq 'CODE') {
 152    $hint = _tag($as);
 153   } elsif (!$r) {
 154    $as .= '::' if $as !~ /::$/;
 155    $hint = _tag(sub { $as . $_[0] });
 156   } else {
 157    require Carp;
 158    Carp::croak("Invalid $r reference for 'as'");
 159   }
 160  } else {
 161   $hint = _tag(sub { @_ });
 162  }
 163
 164  $^H |= 0x020000;
 165  # Yes, we store a coderef inside the hints hash, but that's just for compile
 166  # time.
 167  $^H{+(__PACKAGE__)} = $hint;
 168 }
 169
 170 =head2 C<unimport>
 171
 172     no Lexical::Types;
 173
 174 Magically called when C<no Lexical::Types> is encountered.
 175 Turns the pragma off.
 176
 177 =cut
 178
 179 sub unimport {
 180  $^H{+(__PACKAGE__)} = undef;
 181 }
 182
 183 =head1 RUN-TIME INITIALIZER METHOD
 184
 185 The initializer method receives an alias to the pad slot of the initialized lexical in C<$_[1]> and the original type name in C<$_[2]>.
 186 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 the pad slot.
 187
 188     use Lexical::Types as => 'My';
 189
 190     my Str $x;
 191
 192     ...
 193
 194     sub My::Str::TYPEDSCALAR {
 195      # $_[1] is an alias to $x, and $_[2] is 'Str'
 196      ...
 197     }
 198
 199 =head1 INTEGRATION
 200
 201 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.
 202
 203     package MyTypes;
 204
 205     BEGIN { require Lexical::Types; }
 206
 207     sub import {
 208      eval 'package Str; package Int'; # The types you want to support
 209      Lexical::Types->import(
 210       as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
 211      );
 212     }
 213
 214     sub unimport {
 215      Lexical::Types->unimport;
 216     }
 217
 218     sub new_str { ... }
 219
 220     sub new_int { ... }
 221
 222 If you prefer to use constants rather than creating empty packages, you can replace the previous example with something like this :
 223
 224     package MyTypes;
 225
 226     BEGIN { require Lexical::Types; }
 227
 228     sub import {
 229      my $pkg = caller;
 230      for (qw<Str Int>) {
 231       my $type = __PACKAGE__ . '::' . $_;
 232       no strict 'refs';
 233       no warnings 'redefine';
 234       *{$pkg.'::'.$_} = eval "sub () { '$type' }";
 235      }
 236      Lexical::Types->import(
 237       as => sub { $_[0] => 'new' }
 238      );
 239     }
 240
 241     sub unimport {
 242      Lexical::Types->unimport;
 243     }
 244
 245     package MyTypes::Str;
 246
 247     sub new { ... }
 248
 249     package MyTypes::Int;
 250
 251     sub new { ... }
 252
 253 =head1 CONSTANTS
 254
 255 =head2 C<LT_THREADSAFE>
 256
 257 True iff the module could have been built with thread-safety features enabled.
 258
 259 =head2 C<LT_FORKSAFE>
 260
 261 True iff this module could have been built with fork-safety features enabled.
 262 This will always be true except on Windows where it's false for perl 5.10.0 and below .
 263
 264 =head1 CAVEATS
 265
 266 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.
 267
 268 Only one mangler or prefix can be in use at the same time in a given scope.
 269
 270 The implementation was tweaked to work around several limitations of vanilla C<perl> pragmas : it's thread safe, and doesn't suffer from a C<perl 5.8.x-5.10.0> bug that causes all pragmas to propagate into C<require>d scopes.
 271
 272 With 5.8 perls, the pragma does not propagate into C<eval STRING>.
 273 This is due to a shortcoming in the way perl handles the hints hash, which is addressed in perl 5.10.
 274
 275 =head1 DEPENDENCIES
 276
 277 L<perl> 5.8.3.
 278
 279 A C compiler.
 280 This module may happen to build with a C++ compiler as well, but don't rely on it, as no guarantee is made in this regard.
 281
 282 L<XSLoader> (standard since perl 5.006).
 283
 284 =head1 SEE ALSO
 285
 286 L<fields>.
 287
 288 L<Attribute::Handlers>.
 289
 290 =head1 AUTHOR
 291
 292 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 293
 294 You can contact me by mail or on C<irc.perl.org> (vincent).
 295
 296 =head1 BUGS
 297
 298 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>.
 299 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
 300
 301 =head1 SUPPORT
 302
 303 You can find documentation for this module with the perldoc command.
 304
 305     perldoc Lexical::Types
 306
 307 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Lexical-Types>.
 308
 309 =head1 ACKNOWLEDGEMENTS
 310
 311 Inspired by Ricardo Signes.
 312
 313 Thanks Florian Ragwitz for suggesting the use of constants for types.
 314
 315 =head1 COPYRIGHT & LICENSE
 316
 317 Copyright 2009,2010,2011 Vincent Pit, all rights reserved.
 318
 319 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
 320
 321 =cut
 322
 323 1; # End of Lexical::Types