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.

perl v5.38.2                                       2024-03-31                                  Lexical::Sub(3pm)