From: Marius Gavrilescu <marius@ieval.ro>
Date: Sat, 1 Apr 2017 16:00:05 +0000 (+0300)
Subject: Update POD
X-Git-Tag: 0.003~3
X-Git-Url: http://git.ieval.ro/?a=commitdiff_plain;h=177e0245e4ce9fd721aa0cd9314c2c1894bd1125;p=acme-evil.git

Update POD
---

diff --git a/lib/evil.pm b/lib/evil.pm
index c5faa09..08a8fe8 100644
--- a/lib/evil.pm
+++ b/lib/evil.pm
@@ -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,31 +130,51 @@ 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 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>