package Sub::Prototype::Util;
+use 5.006;
+
use strict;
use warnings;
-use Carp qw/croak/;
-use Scalar::Util qw/reftype/;
+use Carp qw<croak>;
+use Scalar::Util qw<reftype>;
=head1 NAME
=head1 VERSION
-Version 0.06
+Version 0.10
=cut
-use vars qw/$VERSION/;
+use vars qw<$VERSION>;
-$VERSION = '0.06';
+$VERSION = '0.10';
=head1 SYNOPSIS
- use Sub::Prototype::Util qw/flatten recall/;
+ use Sub::Prototype::Util qw<flatten wrap recall>;
- my @a = qw/a b c/;
+ my @a = qw<a b c>;
my @args = ( \@a, 1, { d => 2 }, undef, 3 );
my @flat = flatten '\@$;$', @args; # ('a', 'b', 'c', 1, { d => 2 })
recall 'CORE::push', @args; # @a contains 'a', 'b', 'c', 1, { d => 2 }, undef, 3
+ my $splice = wrap 'CORE::splice';
+ my @b = $splice->(\@a, 4, 2); # @a is now ('a', 'b', 'c', 1, 3) and @b is ({ d => 2 }, undef)
=head1 DESCRIPTION
-Prototypes are evil, but sometimes you just have to bear with them, especially when messing with core functions. This module provides several utilities aimed at facilitating "overloading" of prototyped functions.
+Prototypes are evil, but sometimes you just have to bear with them, especially when messing with core functions.
+This module provides several utilities aimed at facilitating "overloading" of prototyped functions.
They all handle C<5.10>'s C<_> prototype.
=cut
-my %sigils = qw/SCALAR $ ARRAY @ HASH % GLOB * CODE &/;
+my %sigils = qw<SCALAR $ ARRAY @ HASH % GLOB * CODE &>;
my %reftypes = reverse %sigils;
sub _check_ref {
- my ($a, $p) = @_;
- my $r;
- if (!defined $a || !defined($r = reftype $a)) { # not defined or plain scalar
- croak 'Got ' . ((defined $a) ? 'a plain scalar' : 'undef')
- . ' where a reference was expected';
+ my ($arg, $sigil) = @_;
+
+ my $reftype;
+ if (not defined $arg or not defined($reftype = reftype $arg)) {
+ # not defined or plain scalar
+ my $that = (defined $arg) ? 'a plain scalar' : 'undef';
+ croak "Got $that where a reference was expected";
}
- croak 'Unexpected ' . $r . ' reference' unless exists $sigils{$r}
- and $p =~ /\Q$sigils{$r}\E/;
- return $r;
+
+ croak "Unexpected $reftype reference" unless exists $sigils{$reftype}
+ and $sigil =~ /\Q$sigils{$reftype}\E/;
+
+ $reftype;
+}
+
+sub _clean_msg {
+ my ($msg) = @_;
+
+ $msg =~ s/(?:\s+called)?\s+at\s+.*$//s;
+
+ $msg;
}
=head2 C<flatten $proto, @args>
-Flattens the array C<@args> according to the prototype C<$proto>. When C<@args> is what C<@_> is after calling a subroutine with prototype C<$proto>, C<flatten> returns the list of what C<@_> would have been if there were no prototype.
+Flattens the array C<@args> according to the prototype C<$proto>.
+When C<@args> is what C<@_> is after calling a subroutine with prototype C<$proto>, C<flatten> returns the list of what C<@_> would have been if there were no prototype.
+It croaks if the arguments can't possibly match the required prototype, e.g. when a reference type is wrong or when not enough elements were provided.
=cut
sub flatten {
my $proto = shift;
+
return @_ unless defined $proto;
- my @args;
+
+ my @args;
while ($proto =~ /(\\?)(\[[^\]]+\]|[^\];])/g) {
- my $p = $2;
+ my $sigil = $2;
+
if ($1) {
- my $a = shift;
- my $r = _check_ref $a, $p;
- my %deref = (
- SCALAR => sub { push @args, $$a },
- ARRAY => sub { push @args, @$a },
- HASH => sub { push @args, %$a },
- GLOB => sub { push @args, *$a },
- CODE => sub { push @args, &$a }
- );
- $deref{$r}->();
- } elsif ($p =~ /[\@\%]/) {
+ my $arg = shift;
+ my $reftype = _check_ref $arg, $sigil;
+
+ push @args, $reftype eq 'SCALAR'
+ ? $$arg
+ : ($reftype eq 'ARRAY'
+ ? @$arg
+ : ($reftype eq 'HASH'
+ ? %$arg
+ : ($reftype eq 'GLOB'
+ ? *$arg
+ : &$arg # _check_ref ensures this must be a code ref
+ )
+ )
+ );
+
+ } elsif ($sigil =~ /[\@\%]/) {
push @args, @_;
last;
- } elsif ($p eq '_' && @_ == 0) {
- push @args, $_;
} else {
+ croak 'Not enough arguments to match this prototype' unless @_;
push @args, shift;
}
}
+
return @args;
}
-=head2 C<recall $name, @args>
-
-Calls the function C<$name> with the prototyped argument list C<@args>. That is, C<@args> should be what C<@_> is when you define a subroutine with the same prototype as C<$name>. For example,
-
- my $a = [ ];
- recall 'CORE::push', $a, 1, 2, 3;
-
-will call C<push @$a, 1, 2, 3> and so fill the arrayref C<$a> with C<1, 2, 3>. This is especially needed for core functions because you can't C<goto> into them.
+=head2 C<wrap $name, %opts>
-You can also force the use of a specific prototype. In this case, C<$name> must be a hash reference that holds exactly one key/value pair, the key being the function name and the value the prototpye that should be used to call it.
+Generates a wrapper that calls the function C<$name> with a prototyped argument list.
+That is, the wrapper's arguments should be what C<@_> is when you define a subroutine with the same prototype as C<$name>.
- recall { 'CORE::push' => '\@$' }, $a, 1, 2, 3; # will only push 1
+ my $a = [ 0 .. 2 ];
+ my $push = wrap 'CORE::push';
+ $push->($a, 3, 4); # returns 3 + 2 = 5 and $a now contains 0 .. 4
-This allows you to recall into C<CORE::grep> and C<CORE::map> by using the C<\&@> prototype :
+You can force the use of a specific prototype.
+In this case, C<$name> must be a hash reference that holds exactly one key / value pair, the key being the function name and the value the prototpye that should be used to call it.
- sub mygrep (&@) { recall { 'CORE::grep' => '\&@' }, @_ } # the prototypes are intentionally different
+ my $push = wrap { 'CORE::push' => '\@$' }; # only pushes 1 arg
-=cut
-
-sub _check_name {
- my $name = $_[0];
- croak 'No subroutine specified' unless $name;
- my $proto;
- my $r = ref $name;
- if ($r eq 'HASH') {
- croak 'Forced prototype hash reference must contain exactly one key/value pair' unless keys %$name == 1;
- ($name, $proto) = %$name;
- } elsif (length $r) {
- croak 'Unhandled ' . $r . ' reference as first argument';
- }
- $name =~ s/^\s+//;
- $name =~ s/[\s\$\@\%\*\&;].*//;
- $proto = prototype $name unless $proto;
- return $name, $proto;
-}
-
-sub recall {
- my ($name, $proto) = _check_name shift;
- my $call = $name . '(';
- my @cr;
- if (defined $proto) {
- my $i = 0;
- while ($proto =~ /(\\?)(\[[^\]]+\]|[^\];])/g) {
- my $p = $2;
- if ($1) {
- my $r = _check_ref $_[$i], $p;
- $call .= $sigils{$r} . '{$_[' . $i . ']},';
- } elsif ($p =~ /[\@\%]/) {
- $call .= '@_[' . $i . '..' . (@_ - 1) . ']';
- last;
- } elsif ($p =~ /\&/) {
- push @cr, $_[$i];
- $call .= 'sub{&{$cr[' . $#cr . ']}},';
- } elsif ($p eq '_' && $i >= @_) {
- $call .= '$_,';
- } else {
- $call .= '$_[' . $i . '],';
- }
- ++$i;
- }
- $call =~ s/,$//;
- } else {
- $call .= join ',', map '$_[' . $_ . ']', 0 .. @_ - 1;
- }
- $call .= ');';
- my @ret = eval $call;
- croak $@ if $@;
- return @ret;
-}
-
-=head2 C<wrap $name, %opts>
-
-Generates a wrapper that does the same thing as L</recall>, but specialized for a given function. This wrapper can be compiled once for all to avoid calling C<eval> at each run (like L</recall> does). You can still force the prototype by passing C<< { $name => $proto } >> as the first argument. Others arguments are seen as key / value pairs and tune the code generated by L</wrap>. Valid keys are :
+The remaining arguments C<%opts> are treated as key / value pairs that are meant to tune the code generated by L</wrap>.
+Valid keys are :
=over 4
=item C<< ref => $func >>
-Specifies the function used in the generated code to test the reference type of scalars. Defaults to C<'ref'>. You may also want to use C<Scalar::Util::reftype>.
+Specifies the function used in the generated code to test the reference type of scalars.
+Defaults to C<'ref'>.
+You may also want to use L<Scalar::Util/reftype>.
=item C<< wrong_ref => $code >>
-The code executed when a reference of incorrect type is encountered. The result of this snippet is also the result of the generated code, hence it defaults to C<'undef'>. It's a good place to C<croak> or C<die> too.
+The code executed when a reference of incorrect type is encountered.
+The result of this snippet is also the result of the generated code, hence it defaults to C<'undef'>.
+It's a good place to C<croak> or C<die> too.
=item C<< sub => $bool >>
-Encloses the code into a C<sub { }> block. Default is true.
+Encloses the code into a C<sub { }> block.
+Default is true.
=item C<< compile => $bool >>
-Makes L</wrap> compile the code generated and return the resulting code reference. Implies C<< sub => 1 >>. Be careful that in this case C<ref> must be a fully qualified function name. Defaults to false.
+Makes L</wrap> compile the code generated and return the resulting code reference.
+Be careful that in this case C<ref> must be a fully qualified function name.
+Defaults to true, but turned off when C<sub> is false.
=back
-This is how you make your own C<push> that pushes into array references :
+For example, this allows you to recall into C<CORE::grep> and C<CORE::map> by using the C<\&@> prototype :
- my @a = (0 .. 2);
- my $push = wrap 'CORE::push', compile => 1;
- $push->(\@a, 3 .. 7); # returns 3 + 5 = 8, and @a now contains 0 .. 7
+ my $grep = wrap { 'CORE::grep' => '\&@' };
+ sub mygrep (&@) { $grep->(@_) } # the prototypes are intentionally different
=cut
sub _wrap {
- my ($name, $proto, $i, $args, $cr, $opts) = @_;
- if ($proto =~ /(\\?)(\[[^\]]+\]|[^\];])(.*)/g) {
- my ($ref, $p) = ($1, $2);
- $proto = $3;
- $p = $1 if $p =~ /^\[([^\]]+)\]/;
+ my ($name, $proto, $i, $args, $coderefs, $opts) = @_;
+
+ while ($proto =~ s/(\\?)(\[[^\]]+\]|[^\];])//) {
+ my ($ref, $sigil) = ($1, $2);
+ $sigil = $1 if $sigil =~ /^\[([^\]]+)\]/;
+
+ my $cur = "\$_[$i]";
+
if ($ref) {
- if (length $p > 1) {
- return 'my $r = ' . $opts->{ref} . '($_[' . $i . ']); '
- . join ' els',
- map( {
- "if (\$r eq '" . $reftypes{$_} ."') { "
- . _wrap($name, $proto, ($i + 1),
- $args . $_ . '{$_[' . $i . ']}, ',
- $cr, $opts)
- . ' }'
- } split //, $p),
- 'e { ' . $opts->{wrong_ref} . ' }'
+ if (length $sigil > 1) {
+ my $code = "my \$r = $opts->{ref}($cur); ";
+ my @branches = map {
+ my $subcall = _wrap(
+ $name, $proto, ($i + 1), $args . "$_\{$cur}, ", $coderefs, $opts
+ );
+ "if (\$r eq '$reftypes{$_}') { $subcall }";
+ } split //, $sigil;
+ $code .= join ' els', @branches, "e { $opts->{wrong_ref} }";
+ return $code;
} else {
- $args .= $p . '{$_[' . $i . ']}, ';
+ $args .= "$sigil\{$cur}, ";
}
- } elsif ($p =~ /[\@\%]/) {
+ } elsif ($sigil =~ /[\@\%]/) {
$args .= '@_[' . $i . '..$#_]';
- } elsif ($p =~ /\&/) {
- my %h = do { my $c; map { $_ => $c++ } @$cr };
+ } elsif ($sigil =~ /\&/) {
+ my %h = do { my $c; map { $_ => $c++ } @$coderefs };
my $j;
- if (not exists $h{$i}) {
- push @$cr, $i;
- $j = $#{$cr};
- } else {
+ if (exists $h{$i}) {
$j = int $h{$i};
+ } else {
+ push @$coderefs, $i;
+ $j = $#{$coderefs};
}
- $args .= 'sub{&{$c[' . $j . ']}}, ';
- } elsif ($p eq '_') {
- $args .= '((@_ > ' . $i . ') ? $_[' . $i . '] : $_), ';
+ $args .= "sub{&{\$c[$j]}}, ";
+ } elsif ($sigil eq '_') {
+ $args .= "((\@_ > $i) ? $cur : \$_), ";
} else {
- $args .= '$_[' . $i . '], ';
+ $args .= "$cur, ";
}
- return _wrap($name, $proto, ($i + 1), $args, $cr, $opts);
+ } continue {
+ ++$i;
+ }
+
+ $args =~ s/,\s*$//;
+
+ return "$name($args)";
+}
+
+sub _check_name {
+ my ($name) = @_;
+ croak 'No subroutine specified' unless $name;
+
+ my $proto;
+ my $r = ref $name;
+ if (!$r) {
+ $proto = prototype $name;
+ } elsif ($r eq 'HASH') {
+ croak 'Forced prototype hash reference must contain exactly one key/value pair' unless keys %$name == 1;
+ ($name, $proto) = %$name;
} else {
- $args =~ s/,\s*$//;
- return $name . '(' . $args . ')';
+ croak 'Unhandled ' . $r . ' reference as first argument';
}
+
+ $name =~ s/^\s+//;
+ $name =~ s/[\s\$\@\%\*\&;].*//;
+
+ return $name, $proto;
}
sub wrap {
my ($name, $proto) = _check_name shift;
croak 'Optional arguments must be passed as key => value pairs' if @_ % 2;
my %opts = @_;
+
$opts{ref} ||= 'ref';
- $opts{sub} = 1 if not exists $opts{sub} or $opts{compile};
- $opts{wrong_ref} = 'undef' if not defined $opts{wrong_ref};
- my @cr;
+ $opts{sub} = 1 unless defined $opts{sub};
+ $opts{compile} = 1 if not defined $opts{compile} and $opts{sub};
+ $opts{wrong_ref} = 'undef' unless defined $opts{wrong_ref};
+
+ my @coderefs;
my $call;
if (defined $proto) {
- $call = _wrap $name, $proto, 0, '', \@cr, \%opts;
+ $call = _wrap $name, $proto, 0, '', \@coderefs, \%opts;
} else {
$call = _wrap $name, '', 0, '@_';
}
- if (@cr) {
- $call = 'my @c; '
- . join('', map { 'push @c, $_[' . $_ . ']; ' } @cr)
- . $call
+
+ if (@coderefs) {
+ my $decls = @coderefs > 1 ? 'my @c = @_[' . join(', ', @coderefs) . ']; '
+ : 'my @c = ($_[' . $coderefs[0] . ']); ';
+ $call = $decls . $call;
}
- $call = '{ ' . $call . ' }';
- $call = 'sub ' . $call if $opts{sub};
- $call = eval $call if $opts{compile};
+
+ $call = "{ $call }";
+ $call = "sub $call" if $opts{sub};
+
+ if ($opts{compile}) {
+ my $err;
+ {
+ local $@;
+ $call = eval $call;
+ $err = $@;
+ }
+ croak _clean_msg $err if $err;
+ }
+
return $call;
}
+=head2 C<recall $name, @args>
+
+Calls the function C<$name> with the prototyped argument list C<@args>.
+That is, C<@args> should be what C<@_> is when you call a subroutine with C<$name> as prototype.
+You can still force the prototype by passing C<< { $name => $proto } >> as the first argument.
+
+ my $a = [ ];
+ recall { 'CORE::push' => '\@$' }, $a, 1, 2, 3; # $a just contains 1
+
+It's implemented in terms of L</wrap>, and hence calls C<eval> at each run.
+If you plan to recall several times, consider using L</wrap> instead.
+
+=cut
+
+sub recall;
+
+BEGIN {
+ my $safe_wrap = sub {
+ my $name = shift;
+
+ my ($wrap, $err);
+ {
+ local $@;
+ $wrap = eval { wrap $name };
+ $err = $@;
+ }
+
+ $wrap, $err;
+ };
+
+ if ("$]" == 5.008) {
+ # goto tends to crash a lot on perl 5.8.0
+ *recall = sub {
+ my ($wrap, $err) = $safe_wrap->(shift);
+ croak _clean_msg $err if $err;
+ $wrap->(@_)
+ }
+ } else {
+ *recall = sub {
+ my ($wrap, $err) = $safe_wrap->(shift);
+ croak _clean_msg $err if $err;
+ goto $wrap;
+ }
+ }
+}
+
=head1 EXPORT
-The functions L</flatten>, L</recall> and L</wrap> are only exported on request, either by providing their name or by the C<':funcs'> and C<':all'> tags.
+The functions L</flatten>, L</wrap> and L</recall> are only exported on request, either by providing their name or by the C<':funcs'> and C<':all'> tags.
=cut
-use base qw/Exporter/;
+use base qw<Exporter>;
-use vars qw/@EXPORT @EXPORT_OK %EXPORT_TAGS/;
+use vars qw<@EXPORT @EXPORT_OK %EXPORT_TAGS>;
@EXPORT = ();
%EXPORT_TAGS = (
- 'funcs' => [ qw/flatten recall wrap/ ]
+ 'funcs' => [ qw<flatten wrap recall> ]
);
@EXPORT_OK = map { @$_ } values %EXPORT_TAGS;
$EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
-You can contact me by mail or on #perl @ FreeNode (vincent or Prof_Vince).
+You can contact me by mail or on C<irc.perl.org> (vincent).
=head1 BUGS
-Please report any bugs or feature requests to C<bug-sub-prototype-util at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Prototype-Util>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
+Please report any bugs or feature requests to C<bug-sub-prototype-util at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Prototype-Util>.
+I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
=head1 SUPPORT
=head1 COPYRIGHT & LICENSE
-Copyright 2008 Vincent Pit, all rights reserved.
+Copyright 2008,2009,2010,2011 Vincent Pit, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.