Provided by: libeval-context-perl_0.09.11-5_all bug

NAME

        Eval::Context - Evalute perl code in context wraper

SYNOPSIS

               use Eval::Context ;

               my $context = new Eval::Context(PRE_CODE => "use strict;\nuse warnings;\n") ;

               # code will be evaluated with strict and warnings loaded in the context.

               $context->eval(CODE => 'print "evaluated in an Eval::Context!" ;') ;
               $context->eval(CODE_FROM_FILE => 'file.pl') ;

DESCRIPTION

       This module define a subroutine that let you evaluate Perl code in a specific context. The
       code can be passed directly as a string or as a file name to read from. It also provides
       some subroutines to let you define and optionally share variables and subroutines between
       your code and the code you wish to evaluate. Finally there is some support for running
       your code in a safe compartment.

Don't play with fire!

       Don't start using this module, or any other module, thinking it will let you take code
       from anywhere and be safe. Read perlsec, Safe, Opcode, Taint and other security related
       documents. Control your input.

SUBROUTINES/METHODS

       Subroutines that are not part of the public interface are marked with [p].

   new(@named_arguments)
       Create an Eval::Context object.  The object is used as a repository of "default" values
       for your code evaluations.  The context can be used many times. The values can be
       temporarily overridden during the "eval" call.

         my $context = new Eval::Context() ; # default context

         my $context = new Eval::Context
                       (
                       NAME              => 'libraries evaluation context',
                       PACKAGE           => 'libraries',
                       SAFE              => {...} ;

                       PRE_CODE          => "use strict ;\n"
                       POST_CODE         => sub{},
                       PERL_EVAL_CONTEXT => undef,

                       INSTALL_SUBS      => {...},
                       INSTALL_VARIABLES => [...],
                       EVAL_SIDE_PERSISTENT_VARIABLES => {...},

                       INTERACTION => {...},
                       DISPLAY_SOURCE_IN_CONTEXT => 1, #useful when debuging
                       ) ;

       ARGUMENTS

       • @named_arguments - setup data for the object

         All the arguments optional. The argument passed to "new" can also be passed to "eval".
         All arguments are named.

         •   NAME - use when displaying information about the object.

             Set automatically to 'Anonymous' if not set. The name will also be reported by perl
             if an error occurs during your code evaluation.

         •   PACKAGE - the package the code passed to "eval" will evaluated be in.

             If not set, a unique package name is generated and used for every "eval" call.

         •   REMOVE_PACKAGE_AFTER_EVAL - When set the content of the package after evaluation
             will be erase

             The default behavior is to remove all data from after the call to "eval".

         •   PRE_CODE - code prepended to the code passed to eval

         •   POST_CODE - code appended to the code passed to eval

         •   PERL_EVAL_CONTEXT - the context to eval code in (void, scalar, list).

             This option Works as  "wantarray" in perlfunc. It will override the context in which
             "eval" is called.

         •   INSTALL_SUBS - subs that will be available in the eval.

             A hash where the keys are a function names and the values a code references.

         •   SAFE

             This argument must be a hash reference. if the hash is empty, a default safe
             compartment will be used.  Read Safe documentation for more information.

                     SAFE => {} # default safe environment

             You can have a finer control over the safe compartment Eval::Context that will be
             used.

                     my $compartment = new Safe('ABC') ;

                     my $context = new Eval::Context
                             (
                             SAFE => # controlling the safe environment
                                     {
                                     PACKAGE     => 'ABC',
                                     PRE_CODE    => "use my module ;\n" # code we consider safe
                                     USE_STRICT  => 0,                # set to 1 by default
                                     COMPARTMENT => $compartment ,   # use default if not passed
                                     } ,
                             }

                     $context->eval(CODE => .....) ;

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

         •   INSTALL_VARIABLES - "Give me sugar baby" Ash.

             Eval::Context has mechanisms you can use to set and share variables with the code
             you will evaluate. There are two sides in an Eval::Context. The caller-side, the
             side where the calls to "eval" are made and the eval-side, the side where the code
             to be evaluated is run.

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

         •   INTERACTION

             Lets you define subs used to interact with the user.

                     INTERACTION      =>
                             {
                             INFO     => \&sub,
                             WARN     => \&sub,
                             DIE      => \&sub,
                             EVAL_DIE => \&sub,
                             }

             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.

         •   FILE - the file where the object has been created.

             This is practical if you want to wrap the object.

             FILE and LINE will be set automatically if not set.

         •   LINE - the line where the object has been created. Set automatically if not set.

         •   DISPLAY_SOURCE_IN_CONTEXT - if set, the code to evaluated will be displayed before
             evaluation

       Return

       • an Eval::Context object.

   [p] Setup
       Helper sub called by new.

   [p] CheckOptionNames
       Verifies the named options passed as arguments with a list of valid options. Calls
       {INTERACTION}{DIE} in case of error.

   [p] SetInteractionDefault
       Sets {INTERACTION} fields that are not set by the user.

   [p] CanonizeName
       Transform a string into a a string with can be used as a package name or file name usable
       within perl code.

   eval(@named_arguments)
       Evaluates Perl code, passed as a string or read from a file, in the context.

               my $context = new Eval::Context(PRE_CODE => "use strict;\nuse warnings;\n") ;

               $context->eval(CODE => 'print "evaluated in an Eval::Context!";') ;
               $context->eval(CODE_FROM_FILE => 'file.pl') ;

       Call context

       Evaluation context of the code (void, scalar, list) is the same as the context this
       subroutine was called in or in the context defined by PERL_EVAL_CONTEXT if that option is
       present.

       Arguments

       NOTE: You can override any argument passed to "new". The override is temporary during the
       duration of this call.

       • @named_arguments - Any of "new" options plus the following.

         •   CODE - a string containing perl code (valid code or an exception is raised)

         •   CODE_FROM_FILE - a file containing  perl code

         •   REMOVE_PERSISTENT

             A list of regex used to match the persistent variable names to be removed,
             persistent variable removal is done before any variable installation is done

         •   FILE and LINE - will be used in the evaluated code 'file_name' set to the caller's
             file and line by default

         NOTE: CODE or CODE_FROM_FILE is mandatory.

       Return

       • What the code to be evaluated returns

   [p] VerifyAndCompleteOptions
       Helper sub for "eval".

   [p] EvalCleanup
       Handles the package cleanup or persistent variables cleanup after a call to "eval".

   [p] GetPackageName
       Returns a canonized package name. the name is either passed as argument from the caller or
       a temporary package name.

   [p] EvalSetup
       Handles the setup of the context before eval-side code is evaluated. Sets the variables
       and the shared subroutines.

   [p] VerifyCodeInput
       Verify that CODE or CODE_FROM_FILE are properly set.

   [p] RemovePersistent
       Handles the removal of persistent variables.

   [p] GetCallContextWrapper
       Generates perl code to wrap the code to be evaluated in the right calling context.

   [p] SetupSafeCompartment
       If running in safe mode, setup a safe compartment from the argument, otherwise defines the
       evaluation package.

   [p] GetInstalledVariablesCode
       Generates variables on the eval-side from the INSTALL_VARIABLES definitions.  Dispatches
       the generation to specialize subroutines.

   [p] GetPersistentVariablesSetFromCaller
       Generates code to make persistent variables, defined on the caller-side available on the
       eval-side.

   [p] GetSharedVariablesSetFromCaller
       Handles the mechanism used to share variables (references) between the caller-side and the
       eval-side.

       Shared variables must be defined and references. If the shared variable is undef, the
       variable that was previously shared, under the passed name, is used if it exists or an
       exception is raised.

       Also check that variables are not PERSISTENT and SHARED.

   [p] GetVariablesSetFromCaller
       Generates code that creates local variables on the eval-side

   GetPersistentVariableNames()
       Arguments - none

       Returns - the list of existing persistent variables names

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

   GetPersistantVariables(@variable_names)
       Arguments

       • @variable_names - list of variable names to retrieve

       Returns - list of values corresponding to the input names

       This subroutine will return whatever the caller-site set or the eval-side modified. Thus
       if you created a %hash persistent variable, a hash (not a hash reference) will be
       returned.

       If you request multiple values, list flattening will be in effect. Be careful.

               my $context = new Eval::Context
                               (
                               INSTALL_VARIABLES =>
                                       [
                                       ['%hash' => \%hash_caller_side => $Eval::Context::PERSISTENT]
                                       ] ,
                               ) ;

               $context->Eval(CODE => '$hash{A}++ ;') ;

               # may throw exception
               my %hash_after_eval = $context->GetPersistantVariables('%hash') ;

   [p] SetEvalSidePersistenceHandlers
       Set the code needed to handle eval-side persistent variables.

   [p] RemoveEvalSidePersistenceHandlers
       Removes eval-side persistent variable handlers. Used after calling "eval" so the next
       "eval" can not access eval-side persistent variables without being allowed to do so.

BUGS AND LIMITATIONS

       I have reported a very strange error when Safe and Carp are used together.
       <http://rt.cpan.org/Ticket/Display.html?id=31090>. The error can be reproduced without
       using Eval::Context.

AUTHOR

               Khemir Nadim ibn Hamouda
               CPAN ID: NKH
               mailto:nadim@khemir.net

LICENSE AND COPYRIGHT

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

SUPPORT

       You can find documentation for this module with the perldoc command.

           perldoc Eval::Context

       You can also look for information at:

       •   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/Eval-Context>

       •   RT: CPAN's request tracker

           Please report any bugs or feature requests to  L <bug-eval-context@rt.cpan.org>.

           We will be notified, and then you'll automatically be notified of progress on your bug
           as we make changes.

       •   Search CPAN

           <http://search.cpan.org/dist/Eval-Context>