Lexical::Sub3pm

Usage

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

Overview

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.