نديم ابن ﺤﻣﻮﺪﺓ الخمير - Nadim Khemir > Eval-Context-0.09.11 > Eval::Context

Download:
Eval-Context-0.09.11.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.09   Source  

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

Return

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

Return

[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

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:

syntax highlighting: