X-Git-Url: http://git.ieval.ro/?a=blobdiff_plain;f=lib%2Fevil.pm;h=54f2dd8a3be6a3f2d1336b12ae322bb423f57051;hb=refs%2Ftags%2F0.003001;hp=c5faa09bf2163ff7b4cf3b16ca3639d603866e82;hpb=277b168dc15c1824c8d4fc06b88f920bb82a9be2;p=acme-evil.git

diff --git a/lib/evil.pm b/lib/evil.pm
index c5faa09..54f2dd8 100644
--- a/lib/evil.pm
+++ b/lib/evil.pm
@@ -1,7 +1,7 @@
 #!/usr/bin/perl
 package evil;
 
-use 5.008009;
+use 5.010001;
 use strict;
 use warnings;
 
@@ -10,7 +10,7 @@ use Carp;
 my $INTERMEDIATE = __PACKAGE__.'/intermediate';
 my $LAX          = __PACKAGE__.'/lax';
 
-our $VERSION = 0.002;
+our $VERSION = 0.003001;
 
 our %tainted;
 our %wants_strict;
@@ -74,14 +74,31 @@ evil - RFC 3514 (evil bit) implementation for Perl modules
   # in A.pm
   package A;
   use evil;
-  ...
 
   # in B.pm
   package B;
   no evil ':strict';
   use A; # <dies>
-  ...
 
+  # in C.pm
+  package C;
+  use A;
+
+  # in D.pm
+  package D;
+  no evil;
+  use C; # <dies>
+
+  # in E.pm
+  package E;
+  no evil ':lax';
+  use C; # does not die, as C is not evil
+
+  # in F.pm
+  package F;
+  use C;
+  no evil;
+  # does not die, as modules loaded before the pragma are ignored
 
 =head1 DESCRIPTION
 
@@ -103,7 +120,7 @@ The pragma can be used in the following ways:
 =item use B<evil>;
 
 Marks the current package as evil. All malicious modules MUST use this
-directive to ensure the full functionality of this module.
+directive to ensure the full functionality of this pragma.
 
 =item no B<evil> ':strict';
 
@@ -113,38 +130,85 @@ loaded, whether at the moment of calling this pragma or in the future.
 
 =item no B<evil> ':disable';
 
-Removes the effect of any previous C<no B<evil> ':strict'>. In other
-words evil modules will now be allowed to be loaded.
+Removes the effect of any previous C<no B<evil> ':something'> used in
+this module, thus stating the module does not care about evil code.
 
-=item no B<evil> ':intermediate'; (TODO)
+=item no B<evil> ':intermediate'
 
-Not yet implemented. The calling module cannot function properly if it
-is using evil code, whether directly or indirectly. Throws an
-exception if an evil module is loaded by the calling module or by one
-of the children modules (or by one of their children modules, etc).
+The calling module cannot function properly if it is using evil code,
+whether directly or indirectly. Throws an exception if an evil module
+is subsequently loaded by the calling module or by one of the children
+modules (or by one of their children modules, etc). Also throws an
+exception if the current module is evil.
 
-=item no B<evil> ':lax'; (TODO)
+=item no B<evil> ':lax';
 
-Not yet implemented. The calling module cannot function properly if it
-is using evil code direcly. Throws an exception if the calling module
-loads an evil module.
+The calling module cannot function properly if it is using evil code
+direcly. Throws an exception if the calling module subsequently loads
+an evil module, or if the current module is evil.
 
 =item no B<evil>;
 
-This would normally be equivalent to C<no evil ':intermediate';> but
-since that mode is not yet implemented this call does the same as
-C<no evil ':strict';> while also emitting a warning saying that this
-behaviour will change in a future version.
+Synonym for C<no evil ':intermediate'>.
 
 =back
 
+=head1 BUGS
+
+The following does not die:
+
+  # Evil.pm
+  package Evil;
+  use evil;
+
+  # A.pm
+  package A;
+  use Evil;
+
+  # B.pm
+  package B;
+  no evil ':intermediate';
+  use Evil;
+
+  # script.pl
+  #!/usr/bin/perl
+  use A;
+  use B;
+
+Since Evil was loaded by A, B does not load Evil and therefore does
+not detect that Evil is... evil. If we loaded B before A in script.pl,
+we would get an exception. So order of loading modules matters for
+intermediate and lax modes. Strict mode is unaffected by this bug.
+
+=head1 CAVEATS
+
+When using intermediate and lax modes, any evil modules loaded before
+the pragma is enabled are ignored. This is by design, to allow
+temporarily disabling the pragma. An example:
+
+  package MyModule;
+  no evil;
+  use Some::Module;
+  use Another::Module;
+
+  no evil ':disable';
+  use Evil::Module; # does not die
+  no evil;
+
+  use Some::More::Modules;
+  ...
+
+Correct functioning of this pragma depends critically on the evil bit
+being set properly. If a faulty evil module fails to C<use evil;>, the
+pragma will not function properly.
+
 =head1 AUTHOR
 
 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (C) 2016 by Marius Gavrilescu
+Copyright (C) 2016-2017 by Marius Gavrilescu
 
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself, either Perl version 5.22.2 or,