NAME

Lexical::SealRequireHints - prevent leakage of lexical hints

SYNOPSIS

use Lexical::SealRequireHints;

DESCRIPTION

This module works around two historical bugs in Perl's handling of the %^H (lexical hints) variable. One bug causes lexical state in one file to leak into another that is required/used from it. This bug, [perl #68590], was present up to Perl 5.10, fixed in Perl 5.11.0. The second bug causes lexical state (normally a blank %^H once the first bug is fixed) to leak outwards from utf8.pm, if it is automatically loaded during Unicode regular expression matching, into whatever source is compiling at the time of the regexp match. This bug, [perl #73174], was present from Perl 5.8.7 up to Perl 5.11.5, fixed in Perl 5.12.0.

Both of these bugs seriously damage the usability of any module relying on %^H for lexical scoping, on the affected Perl versions. It is in practice essential for such modules to work around these bugs. On versions of Perl that require such a workaround, this module globally changes the behaviour of require, including use and the implicit require performed in Unicode regular expression matching, so that it no longer exhibits these bugs. This is the most convenient kind of workaround, and is meant to be invoked by any module that makes use of lexical state.

The workaround supplied by this module takes effect the first time its import method is called. Typically this will be done by means of a use statement. This should be done before putting anything into %^H that would have a problem with leakage; usually it suffices to do this when loading the module that supplies the mechanism to set up the vulnerable lexical state. Invoking this module multiple times, from multiple lexical-related modules, is not a problem: the workaround is only applied once, and applies to everything.

This module is implemented in XS, with a pure Perl backup version for systems that can't handle XS modules. The XS version has a better chance of playing nicely with other modules that modify require handling.

BUGS

The operation of this module depends on influencing the compilation of require. As a result, it cannot prevent lexical state leakage through a require statement that was compiled before this module was invoked. This is not a problem when lexical state is managed in the usual ways: the leakage that is a problem is almost always through use statements, which are executed immediately after they are compiled. The situations that would escape the sealant of this module are rather convoluted. If such a problem does occur, a workaround is to invoke this module earlier.

SEE ALSO

perlpragma

AUTHOR

Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

Copyright (C) 2009, 2010, 2011 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.