NAME

Perl - embed a perl interpreter in a Perl program

SYNOPSIS

    use Perl;

    my $p = Perl->new;
    print $p->eval(q/"Hello" . " " . "world" . "\n"/);

DESCRIPTION

A Perl object represents a separate perl interpreter that you can manipulate from within Perl. This allows you to run other scripts without affecting your current interpreter, and then examine the results.

METHODS

Perl->new(PARAMS)

This creates and initialises a new perl interpreter, and returns an object through which you can manipulate it. Paramaters are

ARGV => ARRAYREF

This sets the arguments for the perl interpreter, as passed to "perl_parse" in perlembed. An initial argv[0] of "perl" will be added automatically, so don't try and include one. If no arguments are passed, a single argument of -e0 will be used.

USE => ARRAYREF

This will add appropriate -M arguments to the argv of the new interpreter. These will be added before any args given with ARGV.

INC [=> ARRAYREF]

This will pass appropriate -I arguments to the interpreter, before those from either ARGV or USE. If the ARRAYREF is not specified, it will pass in the current @INC, omitting entries that are references.

If the creation fails, it returns undef.

$perl->run

This invokes "perl_run" in perlembed on the interpreter, which will run the program given on the command line in Perl->new, if any. END blocks will be run at the end of this, so if you install any you must make sure to call this.

$perl->eval(q/EXPR/)

This returns the result of evaluating EXPR in the other interpreter. Results are passed back using Storable, and if anything is returned that cannot be frozen an exception will be thrown. Any exceptions thrown will be caught in $@ and undef returned, as with normal eval. Exception objects which cannot be frozen will be returned as "Unfreezable exception: " followed by their stringification.

The EXPR will be evaluated in the same context (list, scalar, void) as eval is called in.

This will croak if Storable cannot be required in the sub-interpreter.

FUNCTIONS

make_expr(EXPR)

This will construct an expression that evaluates to a deep clone of EXPR, suitable for interpolating into a string to pass to $perl->eval. This will croak if MIME::Base64 cannot be required in the sub-perl.

EXPR will be evaluated in scalar context.

This will croak if EXPR cannot be frozen. If MIME::Base64 cannot be required in the sub-perl, the expression will die when evaluated. (If Storable cannot be required, $perl->eval would have croaked already.)

The value of $Perl::Eval (see below) at the time of the call will be stored inside the expression. If it is a coderef, it will be treated as though it is false (for obvious reasons).

PUBLIC VARIABLES

%Perl::Expr

This is a tied hash which returns the result of calling Perl::make_expr on the given key: it makes it easier to interpolate into strings.

$Perl::Deparse, $Perl::Eval

These are used to set the values of $Storable::Deparse and $Storable::Eval ("CODE REFERENCES" in Storable) while passing values to and from the sub-interpreter.

ENVIRONMENT

PERL_PERLPM_DEBUG

If this variable is set in the environment, copious amount of debugging info will be produced on STDERR. This is almost certainly of no use to anyone but me.

BUGS AND IRRITATIONS

Anything that can't be Stored, in particular filehandles, can't be passed between interpreters. It should be possible to pass data back and forth using the threads::shared mechanism rather than Storable, but that's a whole new can of worms.

More tests are needed, particularly of threaded stuff. I don't know enough about threads to know what needs testing.

AUTHOR

Gurusamy Sarathy <gsar@umich.edu>

Modified and updated for 5.8 by Ben Morrow <ben@morrow.me.uk>

COPYRIGHT

This program is distributed under the same terms as perl itself.

cpanm Perl

perl -MCPAN -e shell
install Perl