Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Lexical::Sub(3)	      User Contributed Perl Documentation      Lexical::Sub(3)

       Lexical::Sub - subroutines without namespace pollution

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

       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.
       These lexical definitions propagate into	string "eval"s,	on Perl
       versions	that support it	(5.9.3 and later).

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

       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

       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.

       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 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.

       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.

       Lexical::Import,	Lexical::Var

       Andrew Main (Zefram) <>

       Copyright (C) 2009, 2010, 2011, 2012, 2013 Andrew Main (Zefram)

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

perl v5.32.1			  2021-02-28		       Lexical::Sub(3)


Want to link to this manual page? Use this URL:

home | help