From 177e0245e4ce9fd721aa0cd9314c2c1894bd1125 Mon Sep 17 00:00:00 2001 From: Marius Gavrilescu Date: Sat, 1 Apr 2017 19:00:05 +0300 Subject: [PATCH] Update POD --- lib/evil.pm | 73 ++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 55 insertions(+), 18 deletions(-) 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; # - ... + # in C.pm + package C; + use A; + + # in D.pm + package D; + no evil; + use C; # + + # 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; 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 ':strict'; @@ -113,31 +130,51 @@ loaded, whether at the moment of calling this pragma or in the future. =item no B ':disable'; -Removes the effect of any previous C ':strict'>. In other -words evil modules will now be allowed to be loaded. +Removes the effect of any previous C ':something'> used in +this module, thus stating the module does not care about evil code. -=item no B ':intermediate'; (TODO) +=item no B ':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 ':lax'; (TODO) +=item no B ':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; -This would normally be equivalent to C but -since that mode is not yet implemented this call does the same as -C while also emitting a warning saying that this -behaviour will change in a future version. +Synonym for C. =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, the +pragma will not function properly. + =head1 AUTHOR Marius Gavrilescu, Emarius@ieval.roE -- 2.39.2