package indirect;
-use 5.008001;
+use 5.008_001;
use strict;
use warnings;
=head1 VERSION
-Version 0.25
+Version 0.38
=cut
our $VERSION;
BEGIN {
- $VERSION = '0.25';
+ $VERSION = '0.38';
}
=head1 SYNOPSIS
When enabled, this pragma warns about indirect method calls that are present in your code.
The indirect syntax is now considered harmful, since its parsing has many quirks and its use is error prone : when the subroutine C<foo> has not been declared in the current package, C<foo $x> actually compiles to C<< $x->foo >>, and C<< foo { key => 1 } >> to C<< 'key'->foo(1) >>.
-In L<http://www.shadowcat.co.uk/blog/matt-s-trout/indirect-but-still-fatal>, Matt S. Trout gives an example of an undesirable indirect method call on a block that can cause a particularly bewildering error.
+Please refer to the L</REFERENCES> section for a more complete list of reasons for avoiding this construct.
This pragma currently does not warn for core functions (C<print>, C<say>, C<exec> or C<system>).
This may change in the future, or may be added as optional features that would be enabled by passing options to C<unimport>.
=head1 METHODS
-=head2 C<< unimport [ 'global', hook => $hook | 'fatal' ] >>
+=head2 C<unimport>
+
+ no indirect;
+ no indirect 'fatal';
+ no indirect hook => sub { my ($obj, $name, $file, $line) = @_; ... };
+ no indirect 'global';
+ no indirect 'global, 'fatal';
+ no indirect 'global', hook => sub { ... };
Magically called when C<no indirect @opts> is encountered.
Turns the module on.
If it is a string that matches C</^:?fatal$/i>, the compilation will croak when the first indirect method call is found.
+This option is mutually exclusive with the C<'hook'> option.
+
=item *
If the key/value pair C<< hook => $hook >> comes first, C<$hook> will be called for each error with a string representation of the object as C<$_[0]>, the method name as C<$_[1]>, the current file as C<$_[2]> and the line number as C<$_[3]>.
If and only if the object is actually a block, C<$_[0]> is assured to start by C<'{'>.
+This option is mutually exclusive with the C<'fatal'> option.
+
=item *
If none of C<fatal> and C<hook> are specified, a warning will be emitted for each indirect method call.
=cut
+sub _no_hook_and_fatal {
+ require Carp;
+ Carp::croak("The 'fatal' and 'hook' options are mutually exclusive");
+}
+
sub unimport {
shift;
- my $hook;
- my $global;
+ my ($global, $fatal, $hook);
+
while (@_) {
my $arg = shift;
if ($arg eq 'hook') {
- last if $hook;
+ _no_hook_and_fatal() if $fatal;
$hook = shift;
} elsif ($arg =~ /^:?fatal$/i) {
- last if $hook;
- $hook = sub { die msg(@_) };
+ _no_hook_and_fatal() if defined $hook;
+ $fatal = 1;
} elsif ($arg =~ /^:?global$/i) {
$global = 1;
}
}
- $hook = sub { warn msg(@_) } unless defined $hook;
+
+ unless (defined $hook) {
+ $hook = $fatal ? sub { die msg(@_) } : sub { warn msg(@_) };
+ }
$^H |= 0x00020000;
if ($global) {
=head2 C<import>
+ use indirect;
+
Magically called at each C<use indirect>. Turns the module off.
As explained in L</unimport>'s description, an C<use indirect> statement will lexically override a global policy previously installed by C<no indirect 'global', ...> (if there's one).
=head1 FUNCTIONS
-=head2 C<msg $object, $method, $file, $line>
+=head2 C<msg>
+
+ my $msg = msg($object, $method, $file, $line);
Returns the default error message that C<indirect> generates when an indirect method call is reported.
The search for indirect method calls happens before constant folding.
Hence C<my $x = new Class if 0> will be caught.
+=head1 REFERENCES
+
+Numerous articles have been written about the quirks of the indirect object construct :
+
+=over 4
+
+=item *
+
+L<http://markmail.org/message/o7d5sxnydya7bwvv> : B<Far More Than Everything You've Ever Wanted to Know about the Indirect Object syntax>, Tom Christiansen, 1998-01-28.
+
+This historical post to the C<perl5-porters> mailing list raised awareness about the perils of this syntax.
+
+=item *
+
+L<http://www.shadowcat.co.uk/blog/matt-s-trout/indirect-but-still-fatal> : B<Indirect but still fatal>, Matt S. Trout, 2009-07-29.
+
+In this blog post, the author gives an example of an undesirable indirect method call on a block that causes a particularly bewildering error.
+
+=back
+
=head1 DEPENDENCIES
L<perl> 5.8.1.
A C compiler.
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.
-L<XSLoader> (standard since perl 5.006).
+L<Carp> (standard since perl 5), L<XSLoader> (since perl 5.6.0).
=head1 AUTHOR
perldoc indirect
-Tests code coverage report is available at L<http://www.profvince.com/perl/cover/indirect>.
-
=head1 ACKNOWLEDGEMENTS
Bram, for motivation and advices.
=head1 COPYRIGHT & LICENSE
-Copyright 2008,2009,2010,2011 Vincent Pit, all rights reserved.
+Copyright 2008,2009,2010,2011,2012,2013,2014,2015,2016,2017 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.
projects / perl / modules / indirect.git / blobdiff