1Eval::Context(3pm) User Contributed Perl Documentation Eval::Context(3pm)
2
6 Eval::Context - Evalute perl code in context wraper
7
9 use Eval::Context ;
10 my $context = new Eval::Context(PRE_CODE => "use strict;\nuse warnings;\n") ;
12 # code will be evaluated with strict and warnings loaded in the context.
14 $context->eval(CODE => 'print "evaluated in an Eval::Context!" ;') ;
16 $context->eval(CODE_FROM_FILE => 'file.pl') ;
17
19 This module define a subroutine that let you evaluate Perl code in a
20 specific context. The code can be passed directly as a string or as a
21 file name to read from. It also provides some subroutines to let you
22 define and optionally share variables and subroutines between your code
23 and the code you wish to evaluate. Finally there is some support for
24 running your code in a safe compartment.
25
27 Don't start using this module, or any other module, thinking it will
28 let you take code from anywhere and be safe. Read perlsec, Safe,
29 Opcode, Taint and other security related documents. Control your input.
30
32 Subroutines that are not part of the public interface are marked with
33 [p].
34 new(@named_arguments)
36 Create an Eval::Context object. The object is used as a repository of
37 "default" values for your code evaluations. The context can be used
38 many times. The values can be temporarily overridden during the "eval"
39 call.
40 my $context = new Eval::Context() ; # default context
42 my $context = new Eval::Context
44 (
45 NAME => 'libraries evaluation context',
46 PACKAGE => 'libraries',
47 SAFE => {...} ;
48 PRE_CODE => "use strict ;\n"
50 POST_CODE => sub{},
51 PERL_EVAL_CONTEXT => undef,
52 INSTALL_SUBS => {...},
54 INSTALL_VARIABLES => [...],
55 EVAL_SIDE_PERSISTENT_VARIABLES => {...},
56 INTERACTION => {...},
58 DISPLAY_SOURCE_IN_CONTEXT => 1, #useful when debuging
59 ) ;
60 ARGUMENTS
62 • @named_arguments - setup data for the object
64 All the arguments optional. The argument passed to "new" can also be
66 passed to "eval". All arguments are named.
67 • NAME - use when displaying information about the object.
69 Set automatically to 'Anonymous' if not set. The name will also
71 be reported by perl if an error occurs during your code
72 evaluation.
73 • PACKAGE - the package the code passed to "eval" will evaluated be
75 in.
76 If not set, a unique package name is generated and used for every
78 "eval" call.
79 • REMOVE_PACKAGE_AFTER_EVAL - When set the content of the package
81 after evaluation will be erase
82 The default behavior is to remove all data from after the call to
84 "eval".
85 • PRE_CODE - code prepended to the code passed to eval
87 • POST_CODE - code appended to the code passed to eval
89 • PERL_EVAL_CONTEXT - the context to eval code in (void, scalar,
91 list).
92 This option Works as "wantarray" in perlfunc. It will override
94 the context in which "eval" is called.
95 • INSTALL_SUBS - subs that will be available in the eval.
97 A hash where the keys are a function names and the values a code
99 references.
100 • SAFE
102 This argument must be a hash reference. if the hash is empty, a
104 default safe compartment will be used. Read Safe documentation
105 for more information.
106 SAFE => {} # default safe environment
108 You can have a finer control over the safe compartment
110 Eval::Context that will be used.
111 my $compartment = new Safe('ABC') ;
113 my $context = new Eval::Context
115 (
116 SAFE => # controlling the safe environment
117 {
118 PACKAGE => 'ABC',
119 PRE_CODE => "use my module ;\n" # code we consider safe
120 USE_STRICT => 0, # set to 1 by default
121 COMPARTMENT => $compartment , # use default if not passed
122 } ,
123 }
124 $context->eval(CODE => .....) ;
126 • COMPARTMENT - a Safe object, you create, that will be used by
128 Eval::Context
129 • USE_STRICT - Controls if strict is used in the Safe
131 compartment
132 The default is to use strict. Note that "Safe" in perldoc
134 default is to NOT use strict (undocumented).
135 • PRE_CODE - safe code you want to evaluate in the same context
137 as the unsafe code
138 This let you, for example, use certain modules which provide
140 subroutines to be used in the evaluated code. The default
141 compartment is quite restrictive and you can't even use
142 strict in it without tuning the safe compartment.
143 A few remarks:
145 - See <http://rt.cpan.org/Ticket/Display.html?id=31090> on RT
147 - Pass the same package name to your safe compartment and to
149 Eval::Context.
150 - If you really want to be on the safe side, control your input.
152 When you use a module, are you sure the module hasn't been fiddle
153 with?
154 - Leave strict on. Even for trivial code.
156 • INSTALL_VARIABLES - "Give me sugar baby" Ash.
158 Eval::Context has mechanisms you can use to set and share
160 variables with the code you will evaluate. There are two sides in
161 an Eval::Context. The caller-side, the side where the calls to
162 "eval" are made and the eval-side, the side where the code to be
163 evaluated is run.
164 • How should you get values back from the eval-side
166 Although you can use the mechanisms below to get values from
168 the eval-side, the cleanest way is to get the results
169 directly from the "eval" call.
170 my $context = new Eval::Context() ;
172 my ($scalr_new_value, $a_string) =
174 $context->eval
175 (
176 INSTALL_VARIABLES =>[[ '$scalar' => 42]] ,
177 CODE => "\$scalar++ ;\n (\$scalar, 'a string') ;",
178 ) ;
179 • initializing variables on the eval side
181 You can pass INSTALL_VARIABLES to "new" or "eval". You can
183 initialize different variables for each run of "eval".
184 my $context = new Eval::Context
186 (
187 INSTALL_VARIABLES =>
188 [
189 # variables on eval-side #initialization source
190 [ '$data' => 42],
191 [ '$scalar' => $scalar_caller_side ],
192 [ '%hash' => \%hash_caller_side ]
193 [ '$hash' => \%hash_caller_side ],
194 [ '$object' => $object ],
195 ] ,
196 ) ;
197 The variables will be my variables on the eval-side.
199 You can declare variables of any of the base types supported
201 by perl. The initialization data , on the caller-side, is
202 serialized and deserialized to make the values available on
203 the eval-side. Modifying the variables on the eval-side does
204 not modify the variables on the caller-side. The
205 initialization data can be scalars or references and even my
206 variables.
207 • Persistent variables
209 When evaluating code many times in the same context, you may
211 wish to have variables persist between evaluations.
212 Eval::Context allows you to declare, define and control such
213 state variables.
214 This mechanism lets you control which variables are
216 persistent. Access to the persistent variables is controlled
217 per "eval" run. Persistent variables are my variables on the
218 eval-side. Modifying the variables on the eval-side does not
219 modify the variables on the caller-side.
220 Define persistent variables:
222 # note: creating persistent variables in 'new' makes little sense as
224 # it will force those values in the persistent variables for every run.
225 # This may or may not be what you want.
226 my $context = new Eval::Context() ;
228 $context->eval
230 (
231 INSTALL_VARIABLES =>
232 [
233 [ '$scalar' => 42 => $Eval::Context::PERSISTENT ] ,
234 # make %hash and $hash available on the eval-side. both are
236 # initialized from the same caller-side hash
237 [ '%hash' => \%hash_caller_side => $Eval::Context::PERSISTENT ] ,
238 [ '$hash' => \%hash_caller_side => $Eval::Context::PERSISTENT ] ,
239 ],
240 CODE => '$scalar++',
241 ) ;
242 Later, use the persistent value:
244 $context->eval
246 (
247 INSTALL_VARIABLES =>
248 [
249 [ '$scalar' => $Eval::Context::USE => $Eval::Context::PERSISTENT ] ,
250 # here you decided %hash and $hash shouldn't be available on the eval-side
251 ],
252 CODE => '$scalar',
254 ) ;
255 $Eval::Context::USE means "make the persistent variable and
257 it's value available on the eval-side". Any other value will
258 reinitialize the persistent variable. See also
259 REMOVE_PERSISTENT in "eval".
260 • Manually synchronizing caller-side data with persistent eval-
262 side data
263 Although the first intent of persistent variables is to be
265 used as state variables on the eval-side, you can get
266 persistent variables values on the caller-side. To change the
267 value of an eval-side persistent variable, simply
268 reinitialize it with INSTALL_VARIABLES next time you call
269 "eval".
270 my $context = new Eval::Context
272 (
273 INSTALL_VARIABLES =>
274 [
275 ['%hash' => \%hash_caller_side => $Eval::Context::PERSISTENT]
276 ] ,
277 ) ;
278 $context->Eval(CODE => '$hash{A}++ ;') ;
280 # throws exception if you request a non existing variable
282 my %hash_after_eval = $context->GetPersistantVariables('%hash') ;
283 • Getting the list of all the PERSISTENT variables
285 my @persistent_variable_names = $context->GetPersistantVariablesNames() ;
287 • Creating persistent variables on the eval-side
289 The mechanism above gave you fine control over persistent
291 variables on the eval-side. The negative side is that only
292 the variables you made persistent exist on the eval-side.
293 Eval::Context has another mechanism that allows the eval-side
294 to store variables between evaluations without the caller-
295 side declaration of the variables.
296 To allow the eval-side to store any variable, add this to you
298 "new" call.
299 my $context = new Eval::Context
301 (
302 PACKAGE => 'my_package',
303 EVAL_SIDE_PERSISTENT_VARIABLES =>
305 {
306 SAVE => { NAME => 'SavePersistent', VALIDATOR => sub{} },
307 GET => { NAME => 'GetPersistent', VALIDATOR => sub{} },
308 },
309 ) ;
310 The eval-side can now store variables between calls to "eval"
312 SavePersistent('name', $value) ;
314 later in another call to "eval":
316 my $variable = GetPersistent('name') ;
318 By fine tuning EVAL_SIDE_PERSISTENT_VARIABLES you can control
320 what variables are stored by the eval-side. This should
321 seldom be used and only to help those storing data from the
322 eval-side.
323 You may have notices in the code above that a package name
325 was passed as argument to "new". This is very important as
326 the package names that are automatically generated differ for
327 each "eval" call. If you want to run all you eval-side code
328 in different packages (Eval::Context default behavior), you
329 must tell Eval::Context where to store the eval-side values.
330 This is done by setting CATEGORY
331 The validator sub can verify if the value to be stored are
333 valid, E.G.: variable name, variable value is within range,
334 ...
335 Here is an example of code run in different packages but can
337 share variables. Only variables which names start with A are
338 valid.
339 new Eval::Context
341 (
342 EVAL_SIDE_PERSISTENT_VARIABLES =>
343 {
344 CATEGORY => 'TEST',
345 SAVE =>
346 {
347 NAME => 'SavePersistent',
348 VALIDATOR => sub
349 {
350 my ($self, $name, $value, $package) = @_ ;
351 $self->{INTERACTION}{DIE}->
352 (
353 $self,
354 "SavePersistent: name '$name' doesn't start with A!"
355 ) unless $name =~ /^A/ ;
356 },
357 },
358 GET => {NAME => 'GetPersistent',VALIDATOR => sub {}},
360 },
361 ) ;
362 $context->eval(CODE => 'SavePersistent('A_variable', 123) ;') ;
364 later:
366 $context->eval(CODE => 'GetPersistent('A_variable') ;') ;
368 • Shared variables
370 You can also share references between the caller-side and the
372 eval-side.
373 my $context =
375 new Eval::Context
376 (
377 INSTALL_VARIABLES =>
378 [
379 # reference to reference only
380 [ '$scalar' => \$scalar => $Eval::Context::SHARED ],
381 [ '$hash' => \%hash_caller_side => $Eval::Context::SHARED ],
382 [ '$object' => $object => $Eval::Context::SHARED ],
383 ] ,
384 ) ;
385 Modification of the variables on the eval-side will modify
387 the variable on the caller-side. There are but a few reasons
388 to share references. Note that you can share references to my
389 variables.
390 • INTERACTION
392 Lets you define subs used to interact with the user.
394 INTERACTION =>
396 {
397 INFO => \&sub,
398 WARN => \&sub,
399 DIE => \&sub,
400 EVAL_DIE => \&sub,
401 }
402 INFO - defaults to CORE::print
404 This sub will be used when displaying information.
405 WARN - defaults to Carp::carp
407 This sub will be used when a warning is displayed.
408 DIE - defaults to Carp::confess
410 Used when an error occurs.
411 EVAL_DIE - defaults to Carp::confess, with a dump of the code to
413 be evaluated
414 Used when an error occurs during code evaluation.
415 • FILE - the file where the object has been created.
417 This is practical if you want to wrap the object.
419 FILE and LINE will be set automatically if not set.
421 • LINE - the line where the object has been created. Set
423 automatically if not set.
424 • DISPLAY_SOURCE_IN_CONTEXT - if set, the code to evaluated will be
426 displayed before evaluation
427 Return
429 • an Eval::Context object.
431 [p] Setup
433 Helper sub called by new.
434 [p] CheckOptionNames
436 Verifies the named options passed as arguments with a list of valid
437 options. Calls {INTERACTION}{DIE} in case of error.
438 [p] SetInteractionDefault
440 Sets {INTERACTION} fields that are not set by the user.
441 [p] CanonizeName
443 Transform a string into a a string with can be used as a package name
444 or file name usable within perl code.
445 eval(@named_arguments)
447 Evaluates Perl code, passed as a string or read from a file, in the
448 context.
449 my $context = new Eval::Context(PRE_CODE => "use strict;\nuse warnings;\n") ;
451 $context->eval(CODE => 'print "evaluated in an Eval::Context!";') ;
453 $context->eval(CODE_FROM_FILE => 'file.pl') ;
454 Call context
456 Evaluation context of the code (void, scalar, list) is the same as the
458 context this subroutine was called in or in the context defined by
459 PERL_EVAL_CONTEXT if that option is present.
460 Arguments
462 NOTE: You can override any argument passed to "new". The override is
464 temporary during the duration of this call.
465 • @named_arguments - Any of "new" options plus the following.
467 • CODE - a string containing perl code (valid code or an exception
469 is raised)
470 • CODE_FROM_FILE - a file containing perl code
472 • REMOVE_PERSISTENT
474 A list of regex used to match the persistent variable names to be
476 removed, persistent variable removal is done before any variable
477 installation is done
478 • FILE and LINE - will be used in the evaluated code 'file_name'
480 set to the caller's file and line by default
481 NOTE: CODE or CODE_FROM_FILE is mandatory.
483 Return
485 • What the code to be evaluated returns
487 [p] VerifyAndCompleteOptions
489 Helper sub for "eval".
490 [p] EvalCleanup
492 Handles the package cleanup or persistent variables cleanup after a
493 call to "eval".
494 [p] GetPackageName
496 Returns a canonized package name. the name is either passed as argument
497 from the caller or a temporary package name.
498 [p] EvalSetup
500 Handles the setup of the context before eval-side code is evaluated.
501 Sets the variables and the shared subroutines.
502 [p] VerifyCodeInput
504 Verify that CODE or CODE_FROM_FILE are properly set.
505 [p] RemovePersistent
507 Handles the removal of persistent variables.
508 [p] GetCallContextWrapper
510 Generates perl code to wrap the code to be evaluated in the right
511 calling context.
512 [p] SetupSafeCompartment
514 If running in safe mode, setup a safe compartment from the argument,
515 otherwise defines the evaluation package.
516 [p] GetInstalledVariablesCode
518 Generates variables on the eval-side from the INSTALL_VARIABLES
519 definitions. Dispatches the generation to specialize subroutines.
520 [p] GetPersistentVariablesSetFromCaller
522 Generates code to make persistent variables, defined on the caller-side
523 available on the eval-side.
524 [p] GetSharedVariablesSetFromCaller
526 Handles the mechanism used to share variables (references) between the
527 caller-side and the eval-side.
528 Shared variables must be defined and references. If the shared variable
530 is undef, the variable that was previously shared, under the passed
531 name, is used if it exists or an exception is raised.
532 Also check that variables are not PERSISTENT and SHARED.
534 [p] GetVariablesSetFromCaller
536 Generates code that creates local variables on the eval-side
537 GetPersistentVariableNames()
539 Arguments - none
540 Returns - the list of existing persistent variables names
542 my @persistent_variable_names = $context->GetPersistantVariablesNames() ;
544 GetPersistantVariables(@variable_names)
546 Arguments
547 • @variable_names - list of variable names to retrieve
549 Returns - list of values corresponding to the input names
551 This subroutine will return whatever the caller-site set or the eval-
553 side modified. Thus if you created a %hash persistent variable, a hash
554 (not a hash reference) will be returned.
555 If you request multiple values, list flattening will be in effect. Be
557 careful.
558 my $context = new Eval::Context
560 (
561 INSTALL_VARIABLES =>
562 [
563 ['%hash' => \%hash_caller_side => $Eval::Context::PERSISTENT]
564 ] ,
565 ) ;
566 $context->Eval(CODE => '$hash{A}++ ;') ;
568 # may throw exception
570 my %hash_after_eval = $context->GetPersistantVariables('%hash') ;
571 [p] SetEvalSidePersistenceHandlers
573 Set the code needed to handle eval-side persistent variables.
574 [p] RemoveEvalSidePersistenceHandlers
576 Removes eval-side persistent variable handlers. Used after calling
577 "eval" so the next "eval" can not access eval-side persistent variables
578 without being allowed to do so.
579
581 I have reported a very strange error when Safe and Carp are used
582 together. <http://rt.cpan.org/Ticket/Display.html?id=31090>. The error
583 can be reproduced without using Eval::Context.
584
586 Khemir Nadim ibn Hamouda
587 CPAN ID: NKH
588 mailto:nadim@khemir.net
589
591 This program is free software; you can redistribute it and/or modify it
592 under the same terms as Perl itself.
593
595 You can find documentation for this module with the perldoc command.
596 perldoc Eval::Context
598 You can also look for information at:
600 • AnnoCPAN: Annotated CPAN documentation
602 <http://annocpan.org/dist/Eval-Context>
604 • RT: CPAN's request tracker
606 Please report any bugs or feature requests to L
608 <bug-eval-context@rt.cpan.org>.
609 We will be notified, and then you'll automatically be notified of
611 progress on your bug as we make changes.
612 • Search CPAN
614 <http://search.cpan.org/dist/Eval-Context>
616perl v5.38.0 2023-07-20 Eval::Context(3pm)