1Eval::Closure(3)      User Contributed Perl Documentation     Eval::Closure(3)
2
3
4

NAME

6       Eval::Closure - safely and cleanly create closures via string eval
7

VERSION

9       version 0.14
10

SYNOPSIS

12         use Eval::Closure;
13
14         my $code = eval_closure(
15             source      => 'sub { $foo++ }',
16             environment => {
17                 '$foo' => \1,
18             },
19         );
20
21         warn $code->(); # 1
22         warn $code->(); # 2
23
24         my $code2 = eval_closure(
25             source => 'sub { $code->() }',
26         ); # dies, $code isn't in scope
27

DESCRIPTION

29       String eval is often used for dynamic code generation. For instance,
30       "Moose" uses it heavily, to generate inlined versions of accessors and
31       constructors, which speeds code up at runtime by a significant amount.
32       String eval is not without its issues however - it's difficult to
33       control the scope it's used in (which determines which variables are in
34       scope inside the eval), and it's easy to miss compilation errors, since
35       eval catches them and sticks them in $@ instead.
36
37       This module attempts to solve these problems. It provides an
38       "eval_closure" function, which evals a string in a clean environment,
39       other than a fixed list of specified variables. Compilation errors are
40       rethrown automatically.
41

FUNCTIONS

43   eval_closure(%args)
44       This function provides the main functionality of this module. It is
45       exported by default. It takes a hash of parameters, with these keys
46       being valid:
47
48       source
49           The string to be evaled. It should end by returning a code
50           reference. It can access any variable declared in the "environment"
51           parameter (and only those variables). It can be either a string, or
52           an arrayref of lines (which will be joined with newlines to produce
53           the string).
54
55       environment
56           The environment to provide to the eval. This should be a hashref,
57           mapping variable names (including sigils) to references of the
58           appropriate type. For instance, a valid value for environment would
59           be "{ '@foo' => [] }" (which would allow the generated function to
60           use an array named @foo). Generally, this is used to allow the
61           generated function to access externally defined variables (so you
62           would pass in a reference to a variable that already exists).
63
64           In perl 5.18 and greater, the environment hash can contain
65           variables with a sigil of "&". This will create a lexical sub in
66           the evaluated code (see "The 'lexical_subs' feature" in feature).
67           Using a "&" sigil on perl versions before lexical subs were
68           available will throw an error.
69
70       alias
71           If set to true, the coderef returned closes over the variables
72           referenced in the environment hashref. (This feature requires
73           Devel::LexAlias.) If set to false, the coderef closes over a
74           shallow copy of the variables.
75
76           If this argument is omitted, Eval::Closure will currently assume
77           false, but this assumption may change in a future version.
78
79       description
80           This lets you provide a bit more information in backtraces.
81           Normally, when a function that was generated through string eval is
82           called, that stack frame will show up as "(eval n)", where 'n' is a
83           sequential identifier for every string eval that has happened so
84           far in the program. Passing a "description" parameter lets you
85           override that to something more useful (for instance, Moose
86           overrides the description for accessors to something like "accessor
87           foo at MyClass.pm, line 123").
88
89       line
90           This lets you override the particular line number that appears in
91           backtraces, much like the "description" option. The default is 1.
92
93       terse_error
94           Normally, this function appends the source code that failed to
95           compile, and prepends some explanatory text. Setting this option to
96           true suppresses that behavior so you get only the compilation error
97           that Perl actually reported.
98

BUGS

100       No known bugs.
101
102       Please report any bugs to GitHub Issues at
103       <https://github.com/doy/eval-closure/issues>.
104

SEE ALSO

106       •   Class::MOP::Method::Accessor
107
108           This module is a factoring out of code that used to live here
109

SUPPORT

111       You can find this documentation for this module with the perldoc
112       command.
113
114           perldoc Eval::Closure
115
116       You can also look for information at:
117
118       •   MetaCPAN
119
120           <https://metacpan.org/release/Eval-Closure>
121
122       •   Github
123
124           <https://github.com/doy/eval-closure>
125
126       •   RT: CPAN's request tracker
127
128           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Eval-Closure>
129
130       •   CPAN Ratings
131
132           <http://cpanratings.perl.org/d/Eval-Closure>
133

NOTES

135       Based on code from Class::MOP::Method::Accessor, by Stevan Little and
136       the Moose Cabal.
137

AUTHOR

139       Jesse Luehrs <doy@tozt.net>
140
142       This software is copyright (c) 2016 by Jesse Luehrs.
143
144       This is free software; you can redistribute it and/or modify it under
145       the same terms as the Perl 5 programming language system itself.
146
147
148
149perl v5.36.0                      2023-01-20                  Eval::Closure(3)
Impressum