DESCRIPTION

CPerlBase is a simple Symbian C++ class that wraps a Perl interpreter; its creation, use, and destroying. To understand what this is doing, and how to use the interpreter, a fair knowledge of perlapi, perlguts, and perlembed is recommended.

One useful thing CPerlBase does compared with just using the raw Perl C API is that it redirects the "std streams" (STDOUT et alia) to a text console implementation which while being very basic is marginally more usable than the Symbian basic text console.

The Basics

CPerlBase* NewInterpreterL();

The constructor that does not keep the object in the Symbian "cleanup stack". perl_alloc() and perl_construct() are called behind the curtains.

Accepts the same arguments as NewInterpreterLC().

CPerlBase* NewInterpreterLC();

The constructor that keeps the object in the Symbian "cleanup stack". perl_alloc() and perl_construct() are called behind the curtains.

Can have three arguments:

TBool aCloseStdlib = ETrue

Should a CPerlBase close the Symbian POSIX STDLIB when closing down. Good for one-shot script execution, probably less good for longer term embedded interpreter.

void (*aStdioInitFunc)(void*) = NULL

If set, called with aStdioInitCookie, and the default console is not created. You may want to set the iReadFunc() and iWriteFunc().

void *aStdioInitCookie = NULL

Used as the argument for aStdioInitFunc().

void Destroy();

The destructor of the interpreter. The class destructor calls first this and then the Symbian CloseSTDLIB().

perl_destruct(), perl_free(), and PERL_SYS_TERM() are called behind the curtains.

Utility functions

int Parse(int argc = 0, char *argv[] = 0, char *envp[] = 0);

Prepare an interpreter for executing by parsing input as if a C main() had been called. For example to parse a script, use argc of 2 and argv of { "perl", script_name }.

All arguments are optional: in case either argc or argv are zero, argc of 3 and argv of { "perl", "-e", "0" } is assumed.

PERL_SYS_INIT() and perl_parse() are called behind the curtains.

Note that a call to Parse() is required before Run().

Returns zero if parsing was successful, non-zero if not (and the stderr will get the error).

int Run()

Start executing an interpreter. A Parse() must have been called before a Run(): use 3 and { "", "-e", 0 } if you do not have an argv.

Note that a call to Parse() is required before Run().

perl_run() is called behind the curtains.

Returns zero if execution was successful, non-zero if not (and the stderr will get the error).

int ParseAndRun(int argc, char *argv[], char *envp[]);

Combined Parse() and Run(). The Run() is not run if the Parse() fails.

Returns zero if parsing and execution were successful, non-zero if not.

Like ParseAndRun() but works for Symbian filenames (UTF-16LE). The UTF-8 version of aFileName is always argv[argc-1], and argv[0] is always "perl".

Macros

diTHX

Set up my_perl from the current object (like dTHX).

diVAR

Set up my_vars from the current object (like dVAR).

Extending CPerlBase (subclassing, deriving from)

Note that it probably isn't worth the trouble to try to wrap the whole, rather large, Perl C API into a C++ API. Just use the C API.

The protected members of the class are:

PerlInterpreter* iPerl

The Perl interpreter.

struct perl_vars* iVars

The global variables of the interpreter.

TPerlState iState

The state of the Perl interpreter. TPerlState is one of EPerlNone, EPerlAllocated, EPerlConstructed, EPerlParsed, EPerlRunning, EPerlTerminated, EPerlPaused (these two are currently unused but in the future they might be used to indicate that the interpreter was stopped either non-resumably or resumably for some reason), EPerlSuccess (perl_run() succeeded), EPerlFailure (perl_run() failed), EPerlDestroying.