NAME

       Lexical::Sub - subroutines without namespace pollution

SYNOPSIS

           use Lexical::Sub quux => sub { $_[0] + 1 };
           use Lexical::Sub carp => \&Carp::carp;

DESCRIPTION

       This module implements lexical scoping of subroutines.  Although it can be used directly,
       it is mainly intended to be infrastructure for modules that manage namespaces.

       This module influences the meaning of single-part subroutine names that appear directly in
       code, such as "&foo" and "foo(123)".  Normally, in the absence of any particular
       declaration, these would refer to the subroutine of that name located in the current
       package.  A "Lexical::Sub" declaration can change this to refer to any particular
       subroutine, bypassing the package system entirely.  A subroutine name that includes an
       explicit package part, such as "&main::foo", always refers to the subroutine in the
       specified package, and is unaffected by this module.  A symbolic reference through a
       string value, such as ""&{'foo'}"", also looks in the package system, and so is unaffected
       by this module.

       Bareword references to subroutines, such as "foo(123)", only work on Perl 5.11.2 and
       later.  On earlier Perls you must use the "&" sigil, as in "&foo(123)".

       A name definition supplied by this module takes effect from the end of the definition
       statement up to the end of the immediately enclosing block, except where it is shadowed
       within a nested block.  This is the same lexical scoping that the "my", "our", and "state"
       keywords supply.  Definitions from Lexical::Sub and from "my"/"our"/"state" can shadow
       each other, on Perl versions where these duration keywords can be applied to subroutines
       (5.17.4 and later), except that Lexical::Sub can't shadow a "my"/"our"/"state" subroutine
       prior to Perl 5.19.1.  These lexical definitions propagate into string "eval"s, on Perl
       versions that support it (5.9.3 and later).

       This module only manages subroutines of static duration (the kind of duration that
       subroutines declared without "my" have).  To get a fresh subroutine for each invocation of
       a function, use "my sub", on a Perl version that supports it (5.17.4 and later).

       This module is implemented through the mechanism of Lexical::Var.  Its distinct name and
       declaration syntax exist to make Lexical::Var lexical subroutine declarations clearer.

PACKAGE METHODS

       These methods are meant to be invoked on the "Lexical::Sub" package.

       Lexical::Sub->import(NAME => REF, ...)
           Sets up lexical subroutine declarations, in the lexical environment that is currently
           compiling.  Each NAME must be a bare subroutine name (e.g., "foo"), and each REF must
           be a reference to a subroutine.  The name is lexically associated with the referenced
           subroutine.

       Lexical::Sub->unimport(NAME [=> REF], ...)
           Sets up negative lexical subroutine declarations, in the lexical environment that is
           currently compiling.  Each NAME must be a bare subroutine name (e.g., "foo").  If the
           name is given on its own, it is lexically dissociated from any subroutine.  Within the
           resulting scope, the subroutine name will not be recognised.  If a REF (which must be
           a reference to a subroutine) is specified with a name, the name will be dissociated if
           and only if it is currently associated with that subroutine.

BUGS

       Subroutine invocations without the "&" sigil cannot be correctly processed on Perl
       versions earlier than 5.11.2.  This is because the parser needs to look up the subroutine
       early, in order to let any prototype affect parsing, and it looks up the subroutine by a
       different mechanism than is used to generate the call op.  (Some forms of sigilless call
       have other complications of a similar nature.)  If an attempt is made to call a
       Lexical::Sub lexical subroutine via a bareword on an older Perl, this module will probably
       still be able to intercept the call op, and will throw an exception to indicate that the
       parsing has gone wrong.  However, in some cases compilation goes further wrong before this
       module can catch it, resulting in either a confusing parse error or (in rare situations)
       silent compilation to an incorrect op sequence.  On Perl 5.11.2 and later, sigilless
       subroutine calls work correctly, except for an issue noted below.

       Subroutine calls that have neither sigil nor parentheses (around the argument list) are
       subject to an ambiguity with indirect object syntax.  If the first argument expression
       begins with a bareword or a scalar variable reference then the Perl parser is liable to
       interpret the call as an indirect method call.  Normally this syntax would be interpreted
       as a subroutine call if the subroutine exists, but the parser doesn't look at lexically-
       defined subroutines for this purpose.  The call interpretation can be forced by prefixing
       the first argument expression with a "+", or by wrapping the whole argument list in
       parentheses.

       In the earlier Perl versions that support "my"/"our"/"state" subroutines, starting from
       Perl 5.17.4, the mechanism for core lexical subroutines suffers a couple of bugs that mean
       that Lexical::Sub can't shadow subroutines declared that way.  This was fixed in Perl
       5.19.1.

       Package hash entries get created for subroutine names that are used, even though the
       subroutines are not actually being stored or looked up in the package.  This can
       occasionally result in a "used only once" warning failing to occur when it should.

       On Perls prior to 5.15.5, if this package's "import" or "unimport" method is called from
       inside a string "eval" inside a "BEGIN" block, it does not have proper access to the
       compiling environment, and will complain that it is being invoked outside compilation.
       Calling from the body of a "require"d or "do"ed file causes the same problem on the same
       Perl versions.  Other kinds of indirection within a "BEGIN" block, such as calling via a
       normal function, do not cause this problem.

       When judging whether the "unimport" method should hide a subroutine, this module can't
       distinguish between a lexical subroutine established by this module and a "state"
       subroutine.  This may change in the future.

SEE ALSO

       Lexical::Import, Lexical::Var

AUTHOR

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

COPYRIGHT

       Copyright (C) 2009, 2010, 2011, 2012, 2013, 2023 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.