• COMPARTMENT - a Safe object, you create, that will be used by Eval::Context
• USE_STRICT - Controls if strict is used in the Safe compartment

  The default is to use strict. Note that "Safe" in perldoc default is to NOT use strict (undocumented).

• PRE_CODE - safe code you want to evaluate in the same context as the unsafe code

  This let you, for example, use certain modules which provide subroutines to be used in the evaluated code. The default compartment is quite restrictive and you can't even use strict in it without tuning the safe compartment.

A few remarks:

- See <http://rt.cpan.org/Ticket/Display.html?id=31090> on RT

- Pass the same package name to your safe compartment and to Eval::Context.

- If you really want to be on the safe side, control your input. When you use a module, are you sure the module hasn't been fiddle with?

- Leave strict on. Even for trivial code.

• How should you get values back from the eval-side

  Although you can use the mechanisms below to get values from the eval-side, the cleanest way is to get the results directly from the "eval" call.

          my $context = new Eval::Context() ;
          
          my ($scalr_new_value, $a_string) =
                  $context->eval
                          (
                          INSTALL_VARIABLES =>[[ '$scalar'  => 42]] ,
                          CODE => "\$scalar++ ;\n (\$scalar, 'a string') ;",
                          ) ;
      

• initializing variables on the eval side

  You can pass INSTALL_VARIABLES to "new" or "eval". You can initialize different variables for each run of "eval".

          my $context = new Eval::Context
                  (
                  INSTALL_VARIABLES =>
                          [
                          # variables on eval-side    #initialization source
                          [ '$data'                => 42],
                          [ '$scalar'              => $scalar_caller_side ],
                          [ '%hash'                => \%hash_caller_side ]
                          [ '$hash'                => \%hash_caller_side ],
                          [ '$object'              => $object ],
                          ] ,
                  ) ;
      

  The variables will be my variables on the eval-side.

  You can declare variables of any of the base types supported by perl. The initialization data , on the caller-side, is serialized and deserialized to make the values available on the eval-side. Modifying the variables on the eval-side does not modify the variables on the caller-side. The initialization data can be scalars or references and even my variables.

• Persistent variables

  When evaluating code many times in the same context, you may wish to have variables persist between evaluations. Eval::Context allows you to declare, define and control such state variables.

  This mechanism lets you control which variables are persistent. Access to the persistent variables is controlled per "eval" run. Persistent variables are my variables on the eval-side. Modifying the variables on the eval-side does not modify the variables on the caller-side.

  Define persistent variables:

          # note: creating persistent variables in 'new' makes little sense as
          # it will force those values in the persistent variables for every run.
          # This may or may not be what you want.
          
          my $context = new Eval::Context() ;
          
          $context->eval
                  (
                  INSTALL_VARIABLES =>
                          [
                          [ '$scalar'  => 42                 => $Eval::Context::PERSISTENT ] ,
                          
                          # make %hash and $hash available on the eval-side. both are
                          # initialized from the same caller-side hash
                          [ '%hash'    => \%hash_caller_side => $Eval::Context::PERSISTENT ] ,
                          [ '$hash'    => \%hash_caller_side => $Eval::Context::PERSISTENT ] ,
                          ],
                  CODE => '$scalar++',
                  ) ;
      

  Later, use the persistent value:

          $context->eval
                  (
                  INSTALL_VARIABLES =>
                          [
                          [ '$scalar'  => $Eval::Context::USE => $Eval::Context::PERSISTENT ] ,
                          # here you decided %hash and $hash shouldn't be available on the eval-side
                          ],
                          
                  CODE => '$scalar',
                  ) ;
      

  $Eval::Context::USE means "make the persistent variable and it's value available on the eval-side". Any other value will reinitialize the persistent variable. See also REMOVE_PERSISTENT in "eval".

• Manually synchronizing caller-side data with persistent eval-side data

  Although the first intent of persistent variables is to be used as state variables on the eval-side, you can get persistent variables values on the caller-side. To change the value of an eval-side persistent variable, simply reinitialize it with INSTALL_VARIABLES next time you call "eval".

          my $context = new Eval::Context
                          (
                          INSTALL_VARIABLES =>
                                  [ 
                                  ['%hash' => \%hash_caller_side => $Eval::Context::PERSISTENT] 
                                  ] ,
                          ) ;
                          
          $context->Eval(CODE => '$hash{A}++ ;') ;
          
          # throws exception if you request a non existing variable
          my %hash_after_eval = $context->GetPersistantVariables('%hash') ;
      

• Getting the list of all the PERSISTENT variables

          my @persistent_variable_names = $context->GetPersistantVariablesNames() ;
      

• Creating persistent variables on the eval-side

  The mechanism above gave you fine control over persistent variables on the eval-side. The negative side is that only the variables you made persistent exist on the eval-side. Eval::Context has another mechanism that allows the eval-side to store variables between evaluations without the caller-side declaration of the variables.

  To allow the eval-side to store any variable, add this to you "new" call.

          my $context = new Eval::Context
                  (
                  PACKAGE => 'my_package',
                  
                  EVAL_SIDE_PERSISTENT_VARIABLES =>
                          {
                          SAVE => { NAME => 'SavePersistent', VALIDATOR => sub{} },
                          GET  => { NAME => 'GetPersistent',  VALIDATOR => sub{} },
                          },
                  ) ;
      

  The eval-side can now store variables between calls to "eval"

          SavePersistent('name', $value) ;
      

  later in another call to "eval":

          my $variable = GetPersistent('name') ;
      

  By fine tuning EVAL_SIDE_PERSISTENT_VARIABLES you can control what variables are stored by the eval-side. This should seldom be used and only to help those storing data from the eval-side.

  You may have notices in the code above that a package name was passed as argument to "new". This is very important as the package names that are automatically generated differ for each "eval" call. If you want to run all you eval-side code in different packages (Eval::Context default behavior), you must tell Eval::Context where to store the eval-side values. This is done by setting CATEGORY

  The validator sub can verify if the value to be stored are valid, E.G.: variable name, variable value is within range, ...

  Here is an example of code run in different packages but can share variables. Only variables which names start with A are valid.

          new Eval::Context
                  (
                  EVAL_SIDE_PERSISTENT_VARIABLES =>
                          {
                          CATEGORY => 'TEST',
                          SAVE => 
                                  {
                                  NAME => 'SavePersistent',
                                  VALIDATOR => sub 
                                          {
                                          my ($self, $name, $value, $package) = @_ ;
                                          $self->{INTERACTION}{DIE}->
                                                  (
                                                  $self,
                                                  "SavePersistent: name '$name' doesn't start with A!"
                                                  )  unless $name =~ /^A/ ;
                                          },
                                  },
                                  
                          GET => {NAME => 'GetPersistent',VALIDATOR => sub {}},
                          },
                  ) ;
          
          $context->eval(CODE => 'SavePersistent('A_variable', 123) ;') ;
      

  later:

          $context->eval(CODE => 'GetPersistent('A_variable') ;') ;
      

• Shared variables

  You can also share references between the caller-side and the eval-side.

          my $context = 
                  new Eval::Context
                          (
                          INSTALL_VARIABLES =>
                                  [ 
                                  # reference to reference only
                                  [ '$scalar' => \$scalar           => $Eval::Context::SHARED ],
                                  [ '$hash'   => \%hash_caller_side => $Eval::Context::SHARED ],
                                  [ '$object' => $object            => $Eval::Context::SHARED ],
                                  ] ,
                          ) ;
      

  Modification of the variables on the eval-side will modify the variable on the caller-side. There are but a few reasons to share references. Note that you can share references to my variables.

INFO - defaults to CORE::print

This sub will be used when displaying information.

WARN - defaults to Carp::carp

This sub will be used when a warning is displayed.

DIE - defaults to Carp::confess

Used when an error occurs.

EVAL_DIE - defaults to Carp::confess, with a dump of the code to be evaluated

Used when an error occurs during code evaluation.