1Sub::Exporter::Lexical(U3s)er Contributed Perl DocumentatSiuobn::Exporter::Lexical(3)
2
3
4

NAME

6       Sub::Exporter::Lexical - to export lexically-available subs with
7       Sub::Exporter
8

VERSION

10       version 1.000
11

SYNOPSIS

13       In an exporting library:
14
15         package Some::Toolkit;
16
17         use Sub::Exporter -setup => {
18           exports   => [ qw(foo bar baz) ],
19         };
20
21         sub foo { ... }
22         sub bar { ... }
23         sub baz { ... }
24
25       In an importing library:
26
27         package Vehicle::Autobot;
28
29         use Sub::Exporter::Lexical lexical_installer => { -as => 'lex' };
30
31         ...;
32
33         {
34           use Some:::Toolkit { installer => lex }, qw(foo bar);
35
36           foo(1,2,3);
37           my $x = bar;
38
39           ...
40         };
41
42         # ... and here, foo and bar are no longer available ...
43

DESCRIPTION

45       Sub::Exporter::Lexical provides an alternate installer for
46       Sub::Exporter.  Installers are documented in Sub::Exporter's
47       documentation; all you need to know is that by using
48       Sub::Exporter::Lexical's installer, you can import routines into a
49       lexical scope that will be cleaned up when that scope ends.
50
51       There are two places it makes sense to use the lexical installer: when
52       configuring Sub::Exporter in your exporting package or when importing
53       from a package that uses Sub::Exporter.  For the first case, do
54       something like this:
55
56         package Some::Toolkit;
57         use Sub::Exporter::Lexical ();
58         use Sub::Exporter -setup => {
59           exports   => [ ... ],
60           installer => Sub::Exporter::Lexical::lexical_installer,
61         };
62
63       For the second:
64
65         package My::Library;
66
67         use Sub::Exporter::Lexical ();
68         use Some::Toolkit
69           { installer => Sub::Exporter::Lexical::lexical_installer },
70           qw(foo bar baz);
71

PERL VERSION

73       This module is shipped with no promise about what version of perl it
74       will require in the future.  In practice, this tends to mean "you need
75       a perl from the last three years," but you can't rely on that.  If a
76       new version of perl ship, this software may begin to require it for any
77       reason, and there is no promise that patches will be accepted to lower
78       the minimum required perl.
79

EXPORTS

81       Sub::Exporter::Lexical offers only one routine for export, and it may
82       also be called by its full package name:
83
84   lexical_installer
85       This routine returns an installer suitable for use as the "installer"
86       argument to Sub::Exporter.  It installs all requested routines as
87       usual, but marks them to be removed from the target package as soon as
88       the block in which it was called is complete.
89
90       It does not affect the behavior of routines exported into scalar
91       references.
92
93       More importantly, it does not affect scopes in which it is invoked at
94       runtime, rather than compile time.  This is important!  It means that
95       this works:
96
97         {
98           use Some::Toolkit { installer => lexical_installer }, qw(foo);
99           foo(1,2,3);
100         }
101
102         foo(); # this dies
103
104       ...but this does not...
105
106         {
107           require Some::Toolkit;
108           Some::Toolkit->import({ installer => lexical_installer }, qw(foo));
109           foo(1,2,3);
110         }
111
112         foo(); # this does not die, even though you might expect it to
113
114       Finally, you can't supply a "-as => \$var" install destination yet.
115

AUTHOR

117       Ricardo Signes <cpan@semiotic.systems>
118

CONTRIBUTORS

120       •   Hans Dieter Pearcey <hdp@weftsoar.net>
121
122       •   Ricardo Signes <rjbs@semiotic.systems>
123

125       This software is copyright (c) 2023 by Ricardo Signes.
126
127       This is free software; you can redistribute it and/or modify it under
128       the same terms as the Perl 5 programming language system itself.
129
130
131
132perl v5.38.0                      2023-07-21         Sub::Exporter::Lexical(3)
Impressum