Clarify our policy towards C++ compilers

[perl/modules/indirect.git] / lib / indirect.pm

diff --git a/lib/indirect.pm b/lib/indirect.pm
index 34920db30092002a79bbf1a6b8282c91b0f8612d..87b9083f0d6a099151be5454d59c6e1a7a236528 100644 (file)
--- a/lib/indirect.pm
+++ b/lib/indirect.pm
@@ -1,6 +1,6 @@
 package indirect;
 
-use 5.008;
+use 5.008001;
 
 use strict;
 use warnings;
@@ -11,13 +11,13 @@ indirect - Lexically warn about using the indirect object syntax.
 
 =head1 VERSION
 
-Version 0.18
+Version 0.23
 
 =cut
 
 our $VERSION;
 BEGIN {
- $VERSION = '0.18';
+ $VERSION = '0.23';
 }
 
 =head1 SYNOPSIS
@@ -35,7 +35,7 @@ BEGIN {
     }
     try { ... }; # warns
 
-    no indirect ':fatal';
+    no indirect ':fatal';    # or 'FATAL', or ':Fatal' ...
     if (defied $foo) { ... } # croaks, note the typo
 
     # From the command-line
@@ -48,7 +48,9 @@ BEGIN {
 =head1 DESCRIPTION
 
 When enabled (or disabled as some may prefer to say, since you actually turn it on by calling C<no indirect>), this pragma warns about indirect object syntax constructs that may have slipped into your code.
-This syntax is now considered harmful, since its parsing has many quirks and its use is error prone (when C<swoosh> isn't defined, C<swoosh $x> actually compiles to C<< $x->swoosh >>).
+
+This syntax is now considered harmful, since its parsing has many quirks and its use is error prone (when C<swoosh> is not defined, C<swoosh $x> actually compiles to C<< $x->swoosh >>).
+In L<http://www.shadowcat.co.uk/blog/matt-s-trout/indirect-but-still-fatal>, Matt S. Trout gives an example of an indirect construct that can cause a particularly bewildering error.
 
 It 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>.
@@ -70,7 +72,7 @@ BEGIN {
 
 =head1 METHODS
 
-=head2 C<< unimport [ hook => $hook | ':fatal' ] >>
+=head2 C<< unimport [ hook => $hook | ':fatal', 'FATAL', ... ] >>
 
 Magically called when C<no indirect @opts> is encountered.
 Turns the module on.
@@ -80,7 +82,7 @@ The policy to apply depends on what is first found in C<@opts> :
 
 =item *
 
-If it's the string C<':fatal'>, the compilation will croak on the first indirect syntax met.
+If it is a string that matches C</^:?fatal$/i>, the compilation will croak on the first indirect syntax met.
 
 =item *
 
@@ -103,7 +105,7 @@ sub unimport {
   my $arg = shift;
   if ($arg eq 'hook') {
    $hook = shift;
-  } elsif ($arg eq ':fatal') {
+  } elsif ($arg =~ /^:?fatal$/i) {
    $hook = sub { die msg(@_) };
   }
   last if $hook;
@@ -173,13 +175,14 @@ In this case, the pragma will always be considered to be thread-safe, and as suc
 This is useful for disabling C<indirect> in production environments.
 
 Note that clearing this variable after C<indirect> was loaded has no effect.
-If you want to reenable the pragma later, you also need to reload it by deleting the C<'indirect.pm'> entry from C<%INC>.
+If you want to re-enable the pragma later, you also need to reload it by deleting the C<'indirect.pm'> entry from C<%INC>.
 
 =head1 CAVEATS
 
-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.
+The implementation was tweaked to work around several limitations of vanilla C<perl> pragmas : it's thread safe, and does not suffer from a C<perl 5.8.x-5.10.0> bug that causes all pragmas to propagate into C<require>d scopes.
 
-C<meth $obj> (no semicolon) at the end of a file won't be seen as an indirect object syntax, although it will as soon as there is another token before the end (as in C<meth $obj;> or C<meth $obj 1>).
+Before C<perl> 5.12, C<meth $obj> (no semicolon) at the end of a file is not seen as an indirect object syntax, although it is as soon as there is another token before the end (as in C<meth $obj;> or C<meth $obj 1>).
+If you use C<perl> 5.12 or greater, those constructs are correctly reported.
 
 With 5.8 perls, the pragma does not propagate into C<eval STRING>.
 This is due to a shortcoming in the way perl handles the hints hash, which is addressed in perl 5.10.
@@ -189,7 +192,10 @@ Hence C<my $x = new Class if 0> will be caught.
 
 =head1 DEPENDENCIES
 
-L<perl> 5.8.
+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).
 
@@ -220,7 +226,7 @@ Andrew Main and Florian Ragwitz, for testing on real-life code and reporting iss
 
 =head1 COPYRIGHT & LICENSE
 
-Copyright 2008-2009 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.