EP


Examples:
----------
The best way to learn how to use EP is to look at the examples in:

$EP_HOME/tests/

EPTest.cpp: Currently the only sample program.






Creating an Interpreter:
-------------------------

The base of EP is a singleton of class EP.  To get the EP instance, call EP::GetInstance ( ).  This returns a pointer to EP.

EP * MyEP = EP::GetInstance ( );

From MyEP, some information is available about the perl instance being used, such as the version and whether it was compiled with support for multiple interpreters (multiplicity in perl-speak).

MyEP::sPerlVersion -- std::string with version info
MyEP::nMultiplicty -- int, true if multiplicity support compiled into perl

Also, from MyEP, you can set the number of interpreters to be put in the interpreter pool.  A perl interpreter is wrapped in an object of class EPI (Embedded Perl Interpreter).

MyEP->SetDesiredEPIs ( NumberOfInterpreters );

This is the maximum number of interpreters that are available at any one time.

To get an EPI object from the pool, do the following:

EPI * MyEPI = MyEP->GetEPI ( );

Now you have a perl interpreter instance and are ready to go.

When you are done with your interpreter, return it to the pool by calling:

MyEP->GiveBackEPI ( MyEPI );

This makes the interpreter available for use at a later time or by another thread.

Summarized:
EP * MyEP = EP::GetInstance ( );
MyEP->SetDesiredEPIs ( 1 );
EPI * MyEPI = MyEP->GetEPI ( );
...use MyEPI...
MyEP->GiveBackEPI ( MyEPI );

Using an Interpreter:
----------------------

Once you have an EPI object, as described above, you can then start doing perl-ish stuff.

To load a perl program from a file:

MyEPI->LoadPerl ( "/path/to/perl/program" );

This loads up the program into the interpreter.  It will run any code that would normally be run if it was run using the normal perl command line program.  However, it may be useful to have a perl program with everything in subroutines -- no code which would normally be run.  

To run a specific subroutine after calling MyEPI->LoadPerl ( ... ):

MyEPI->RunSubroutine ( "MySubroutineName" );

This will run the specified subroutine name with no parameters passed to it, and will disregard any return values.  

NOTE: Sending in parameters and retrieving return values will be covered later.

You can also retrieve the actual PerlInterpreter object from an EPI object by calling:

PerlInterpreter * MyPerlInterpreter = MyEPI->GetPerlInterpreter ( );

This will not be necessary for using the EP API, only if you want to do raw perl API calls.



Perl Variables:
----------------

Variables may be created for an interpreter from within the C++ program.

Each of the three basic types (four if you count references as being different from scalars) are wrapped in EP.

EPScalar - wraps the perl scalar type.  This is NOT used for references, only strings and numbers.

-- EPReference - wraps perl references.  EPReference inherits from EPScalar and can therefor be used anywhere a scalar is wanted, but it has more functionality than a plain EPScalar.

EPArray - wraps the perl list/array type.

EPHash - wraps the perl hash/associative array type.

To create any of these types (FIX: references possibly excluded, documentation not complete on references), create it as you would a normal variable, except an EPI (perl interpreter wrapper) must be specified.  This is because you are actually creating the variable inside an interpreter.  Because multiple interpreters may be present, it is always required to specify the interpreter in which the variable is to be created.  You must also specify the name for the variable INSIDE the interpreter.  This is the name perl code would reference the variable as.  It doesn't have to match up to the C++ variable name.

EPI * MyEPI = MyEP->GetEPI ( );
EPScalar MyScalarNumber ( 4, MyEPI, "MagicNumber" );
EPScalar MyScalarString ( "Hello", MyEPI, "SomeString" );
EPScalar MyScalarDefault ( MyEPI, "Default" );

MyScalarNumber creates a variable named $MagicNumber inside the MyEPI perl interpreter and sets the value to 4.

MyScalarString creates a variable named $SomeString inside the MyEPI perl interpreter and sets the value to "Hello".

MyScalarDefault creates a variable named $Default inside the MyEPI perl interpreter and sets the value to the empty string "".

These variables are global variables (FIX: I think?).

The following constructor types exist:
Default      - (no initialization value)
int          - initializes with the value of the int
unsigned int - initializes with value of the unsigned int
double       - initializes with the value of the double
std::string  - initializes to the value of the std::string (char * will convert to std::string)

Operators =, +, -, *, / are all defined for EPScalar.

Also, GetInt(), GetUnsignedInt(), GetDouble(), and GetStdString() all exist for getting C++ values from an EPScalar.

EPReference:
------------
FIX: Nothing yet


EPArray:
---------

To create an EPArray, use the following constructor:
EPArray MyArray ( MyEPI, "MyArrayName" );

MyArray creates an empty array named @MyArrayName inside the MyEPI interpreter.

To set a value inside the array, use:
MyArray.Store ( Index, EPScalar );

To retrieve the value at a position, use:
MyArray.Fetch ( Index );

To delete the value from a position, use:
MyArray.Delete ( Index );

To check the length of an EPArray, use:
MyArray.Length ( );

To check to see if there is a value at a position (FIX: ??), use:
MyArray.Exists ( Index );

Also, operator[] is defined to retrieve the value at a position.  It cannot be used to set a new value at the position, though (FIX: ??)


EPHash:
--------

To create an EPHash, use the following constructor:
EPHash MyHash ( MyEPI, "MyHashName" );

MyHash creates an empty hash named %MyHashName inside the MyEPI interpreter.

To set a value inside the hash, use:
void MyHash.Store ( ConstCharPointerKey, EPScalarValue );
 or
void MyHash.Store ( StdStringKey, EPScalarValue );

To retrieve the value at a key, use:
EPScalar MyHash.Fetch ( CharPointerKey );

To check to see if there is a value at a key, use:
MyHash.Exists ( CharPointerKey ); // returns true if exists

To completely clear the hash, use:
void MyHash.Clear ( );

To delete an entry from the hash, use:
void MyHash.Delete ( CharPointerKey );

Operator[] is defined to do the same thing as MyHash.Fetch ( ... ).



EPVariableList: 
----------------

EPVariableList is a list of EPVariables.  It works exactly the same as a std::list, except it defines operator>> and operator<< which are basically push and pop (pop will shove the value into the pointer on the receiving end, as well as remove the item from the list). 


Calling a Subroutine With Parameters:
--------------------------------------

First, do all the stuff described previously to get an interpreter and load a perl program.  Originally we just called:

MyEPI->RunSubroutine ( "MySubroutine" );

Now we will pass in a second parameter:
EPScalar Scalar1 ( MyEPI );
EPScalar Scalar2 ( MyEPI );
EPScalar Scalar3 ( MyEPI );

EPVariableList MyParamList;
MyParamList << &Scalar1 << &Scalar2 << &Scalar3;

EPVariableList MyReturnList;

MyReturnList = MyEPI->RunSubroutine ( "MySubroutine", MyParamList );

Scalar1, Scalar2, and Scalar3 were passed in as $_[0], $_[1], and $_[2].

NOTE: Scalar1, Scalar2, and Scalar3 have no names inside the interpreter.  That is because they will not be referenced by name, so it isn't necessary.

Any return values will be pushed into MyReturnList.  Use the standard std::list methods to determine the number of returned values:

printf ( "Got %d results back from MySubroutine\n", MyReturnList.size ( ) );




Other Stuff:
-------------

When you EP::GiveBackEPI ( ... ), all EPVariables associated with that interpreter are destroyed.  If you try and use them, bad things will happen.