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>).
  54 In particular, it can be used to automatically tie or bless typed lexicals.
  55
  56 It is B<not> implemented with a source filter.
  57
  58 =cut
  59
  60 BEGIN {
  61  require XSLoader;
  62  XSLoader::load(__PACKAGE__, $VERSION);
  63 }
  64
  65 =head1 FUNCTIONS
  66
  67 =head2 C<< import [ as => [ $prefix | $mangler ] ] >>
  68
  69 Magically called when writing C<use Lexical::Types>.
  70 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.
  71 The method and package are determined by the parameter C<'as'> :
  72
  73 =over 4
  74
  75 =item *
  76
  77 If it's left unspecified, the C<TYPEDSCALAR> method in the C<Str> package will be called.
  78
  79     use Lexical::Types;
  80     my Str $x; # calls Str->TYPEDSCALAR
  81
  82 =item *
  83
  84 If a plain scalar C<$prefix> is passed as the value, the C<TYPEDSCALAR> method in the C<${prefix}::Str> package will be used.
  85
  86     use Lexical::Types as => 'My::'; # or "as => 'My'"
  87     my Str $x; # calls My::Str->TYPEDSCALAR
  88
  89 =item *
  90
  91 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 :
  92
  93 =over 4
  94
  95 =item *
  96
  97 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) ;
  98
  99     use Lexical::Types as => sub { return $_[0] =~ /Str/ ? @_ : () };
 100     my Str $y; # calls Str->TYPEDSCALAR
 101     my Int $x; # nothing special
 102
 103 =item *
 104
 105 or the desired package and method name, in that order (if any of those is C<undef>, the default value will be used instead).
 106
 107     use Lexical::Types as => sub { 'My', 'new_' . lc($_[0]) };
 108     my Str $x; # the coderef indicates to call My->new_str
 109
 110 =back
 111
 112 =back
 113
 114 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]>.
 115 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>.
 116
 117 =cut
 118
 119 sub import {
 120  shift;
 121  my %args = @_;
 122
 123  my $hint;
 124
 125  my $as = delete $args{'as'};
 126  if ($as) {
 127   my $r = ref $as;
 128   if ($r eq 'CODE') {
 129    $hint = _tag($as);
 130   } elsif (!$r) {
 131    $as .= '::' if $as !~ /::$/;
 132    $hint = _tag(sub { $as . $_[0] });
 133   } else {
 134    croak "Invalid $r reference for 'as'";
 135   }
 136  } else {
 137   $hint = _tag(0);
 138  }
 139
 140  $^H |= 0x020000;
 141  # Yes, we store a coderef inside the hints hash, but that's just for compile
 142  # time.
 143  $^H{+(__PACKAGE__)} = $hint;
 144 }
 145
 146 =head2 C<unimport>
 147
 148 Magically called when writing C<no Lexical::Types>.
 149 Turns the pragma off.
 150
 151 =cut
 152
 153 sub unimport {
 154  $^H{+(__PACKAGE__)} = undef;
 155 }
 156
 157 =head1 INTEGRATION
 158
 159 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.
 160
 161     package MyTypes;
 162
 163     BEGIN { require Lexical::Types; }
 164
 165     sub import {
 166      eval 'package Str; package Int'; # The types you want to support
 167      Lexical::Types->import(
 168       as => sub { __PACKAGE__, 'new_' . lc($_[0]) }
 169      );
 170     }
 171
 172     sub unimport {
 173      Lexical::Types->unimport;
 174     }
 175
 176     sub new_str { ... }
 177
 178     sub new_int { ... }
 179
 180 =head1 CAVEATS
 181
 182 For C<perl> to be able to parse C<my Str $x>, you need :
 183
 184 =over 4
 185
 186 =item *
 187
 188 either the C<Str> package to be defined ;
 189
 190 =item *
 191
 192 or for C<Str> to be a constant sub returning a valid defined package.
 193
 194 =back
 195
 196 Those restrictions 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.
 197
 198 Only one mangler or prefix can be in use at the same time in a given scope.
 199
 200 =head1 DEPENDENCIES
 201
 202 L<perl> 5.8, L<XSLoader>.
 203
 204 =head1 SEE ALSO
 205
 206 L<fields>.
 207
 208 L<Attribute::Handlers>.
 209
 210 =head1 AUTHOR
 211
 212 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 213
 214 You can contact me by mail or on C<irc.perl.org> (vincent).
 215
 216 =head1 BUGS
 217
 218 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.
 219
 220 =head1 SUPPORT
 221
 222 You can find documentation for this module with the perldoc command.
 223
 224     perldoc Lexical::Types
 225
 226 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Lexical-Types>.
 227
 228 =head1 ACKNOWLEDGEMENTS
 229
 230 Inspired by Ricardo Signes.
 231
 232 Thanks Florian Ragwitz for suggesting the use of constants for types.
 233
 234 =head1 COPYRIGHT & LICENSE
 235
 236 Copyright 2009 Vincent Pit, all rights reserved.
 237
 238 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
 239
 240 =cut
 241
 242 1; # End of Lexical::Types