/ 
pyperl-1.0
River stage zero No dependents
/ perlmodule

NAME

perlmodule - Embed a Perl interpreter in Python

SYNOPSIS

import perl

# Simple arithmetics
six = perl.eval("3+3")

# Eval can also return functions
sum = perl.eval("sub { my $s = shift; $s += shift while @_; $s }")
print sum(1,2,3)

# Example of using a perl module from python
perl.require("Digest::MD5")
md5 = perl.callm("new", "Digest::MD5")
md5.add("Foo")
md5.hexdigest()

# Direct manipulation of perl data
inc = perl.get_ref("@INC")
inc.append("./extra")

DESCRIPTION

The perl module allows you to easily embed a Perl interpreter in any Python program. It can be used to invoke arbitrary Perl code, load any Perl modules and make calls directly into Perl functions. The Perl code invoked can call back into Python as it see fit.

The following functions are made available by the perl module:

perl.eval( CODE )

The perl.eval function takes a string of perl code as argument and will let perl compile and execute the code. The code is evaluated in scalar context and returns the value of the last statement executed.

Any exception raised by perl will be turned into perl.PerlError exception for Python. The content of $@ is avalable as the value of the python exception.

perl.require( MODULE )

This will load the perl module into the perl interpreter. If the module can not be located or fails to load properly, then a perl.PerlError exception is raised.

perl.call( FUNC, ARGS,... )

This will call the perl function named FUNC with the given arguments. See the section about calling perl functions below.

perl.callm( METHOD, OBJ, ARGS,... )

This will call the perl method on the object with the given arguments. The OBJ argument can also be a string denoting the name of a class. This is used to call class methods, like constructors.

perl.defined( NAME )

This function check if a thing identified by NAME is defined in the perl name space. If the name is not prefixed with a perl data type symbol ("$", "@", "%", "$" or "&") then it is assumed to be the name of a function (i.e. "&" is assumed).

perl.get_ref( NAME, [ CREATE ] )

This function is used to obtain references to things inside the perl name space. The function can also be used to construct new anonymous perl data objects.

The NAME argument is the name of the thing to obtain a reference to. If the name is not prefixed with a perl data type symbol ("$", "@", "%", "$" or "&") then it is assumed to be the name of a function (i.e. "&" is assumed). If the optional CREATE argument is given and is TRUE, then the named object will be created unless it already exists. If CREATE is FALSE, and the named object does not exists, then a perl.PerlError exception will be raised.

If the NAME argument is simply "$", "@" or "%" then a new scalar, array or hash is created and a reference to it is returned. This is much more efficient than using something like perl.eval("[]") to obtain an anonymous perl array reference.

perl.array( SEQUENCE )

This function works in the same way as the python list() or tuple() builtin functions. It will turn any python SEQUENCE object into a perl array.

The following attributes are available:

perl.PerlError

The perl exception object. See the section on Exceptions below.

perl.MULTI_PERL

This value is TRUE if the perlmodule was compiled with the MULTI_PERL flavour and FALSE otherwise.

When MULTI_PERL is enabled, then each python thread will get its own separate perl interpreter. This avoid the need for a perl lock and allow full concurrency for perl code executing in different threads.

Calling perl functions

There are 4 ways perl functions can be called from python. Named functions and class methods can be invoked through the perl.call() and perl.callm() functions. In additon reference to perl code objects and methods on reference to other perl objects can be called directly.

Data types of arguments and return values are mapped between the languages as follows:

Python                Perl
--------------        ------------------------------------
None            <---> undef
string          <---> string
float           <---> number
int             <---> int
long            <---> int (or Python::Object if overflow)
perl ref object <---> ref
object          <---> Python::Object

Python keyword arguments are passed to perl as key/value pairs after any other arguments. Keywords that start with "__" are reserved and not passed on. The special keyword argument __wantarray__ can be used to specify what context to call the perl function in. A function called in array context always return a tuple.

Array context can also be set up with versions of perl.call() and perl.callm() with _tuple suffix; i.e. perl.call_tuple() an perl.callm_tuple().

Perl ref object

Reference to perl objects (as returned by perl.get_ref() or passed to python as function arguments or return values) are wrapped up in a python extention type called perl ref object. The main purpose of these objects are to wrap arbitrary perl data such that it can be hold by python and passed back into perl at some later time. In the same way python objects passed to perl are wrapped up as Python::Object.

The perl ref object wrapper also provide behaviour that make the perl objects conform to the various interfaces that the corresponding python data type provide. This make it possible to use perl data mostly transparently in existing python code.

The following special attributes are supported by perl ref objects.

p.__class__

This attribute denote the name of the class that the object is blessed into. Perl objects can be blessed from python by assignment to the __class__ attribute. A value of None denotes an unblessed object.

p.__type__

This read-only attribute denote the type of the perl object. It is a string like "SCALAR", "ARRAY", "HASH" or "CODE".

The perl builtin ref() function can be defined in python like this:

def ref(o):
   return o.__class__ or o.__type__
p.__value__

This attribute is only present for references to perl scalars. It is used to dereference the scalar reference. Example:

pid = perl.get_ref("$$")
print pid.__value__
p.__wantarray__

This attribute denoted the default context that is used if the object is called. A value of None denotes void context. A TRUE value denotes list context and a FALSE value denote scalar context. The default is 0, i.e. scalar context.

p.__methodname__

All perl ref object can be assossiated with a method name. If the object is called and this attribute is set, then we will try to call the correspondigly called perl method on the wrapped up perl object.

p.foo

Access to any other attribute will return a new perl ref object that wraps the same underlying perl object, but which has the __methodname__ attribute initialized to the attribute name. The result of this is simply that:

p.foo()

works as expected. The value of __wantarray__ will be inherited by the new wrapper.

p.foo_tuple

If an attribute with the suffix _tuple is read, then a method wrapper is created with the __wantarray__ attribute set to a TRUE value.

A perl array wrapped up as a perl ref object support the following methods and operators that make it compatible with python lists:

array.append(object)

Appends a new element to the end of the array. Same as perl's push(@array, $object)

array.insert(index, object)

Insert a new element at the indicated position in the array. Similar to perl's splice(@array, $index, 0, $object)

array.extend(seqence)

Appends the elements a the sequence to the end of the array. Same as perl's push(@array, @sequence)

array.pop()

Removes the last element from the array and returns it. Same as perl's pop(@array)

array.pop(index)

Removes the element with the indicated index from the array and returns it. Same as perl's splice(@array, $index, 1)

array.remove(object)

Searches for the given object in the array and removes first occurence if found. Raises an exception if no matching element is found.

array.index(object)

Searches for the given object in the array and returns the index to the first occurence found. Raises an exception if no matching element is found.s

array.count(object)

Returns the number of occurences of the given object in the array. Similar to perl's scalar(grep $_ eq $object, @array).

array.reverse()

Reverse sequence of the elements of the array in-place. Return None.

array.sort()

Not implemented yet.

array[i]

Arrays can be indexed in the natural way. Reference to out of bounds indexes raise an IndexError exception.

This automatically also enables various operations like:

x in array
x not int array
min(array)
max(array)

for x in array: ...
map(foo, array)
reduce(foo, array)
filter(foo, array)
array[low:high]

Slicing and assigment to slices are supported for arrays.

del array[i]
del array[low:high]
array + array

Arrays can be concatenated with the "+" operator.

array * i

Arrays can be repeated with the "*" operator.

A perl hash wrapped up as a perl ref object support the following methods that make it compatible with python dictionaries. Note that the key argument of perl hashes must be strings. A TypeError exception is raised if non-string keys are used.

hash.has_key(key)

Check if the hash has the key. Same as perl's exists $hash{$key}.

hash.keys()

Returns a list of all keys. Same as perl's keys %hash.

hash.values()

Returns a list of all values. Same as perl's values %hash.

hash.items()

Returns a list of (key, value) tuples.

hash.clear()

Removes all elements from the hash.

hash.copy()

Creates a new hash with the same elements and return it.

hash.update(mapping)

Updates hash with content of other mapping object.

hash.get(key)

Returns hash[key] if any value with the given key exists, None otherwise.

==item hash.get(key, default)

Returns hash[key] if any value with the given key exists, default otherwise.

hash[key]

Specific hashes values can be read or assigned to using subscription syntax. Reading a non-existing key raise an KeyError exception.

del hash[key]

Hash elements can be removed with the 'del' operator.

Other features of all perl ref objects are:

p(...)

Perl ref objects can be called. If the __methodname__ attribute is set, then this will try to call the given method with the wrapped perl reference as the object. If the wrapped perl object is CODE, then it is called.

str(p)

Perl ref objects stringify as a string on the following form:

<perl Foo=HASH(0x80db1e0) ref at 810fff0>

This shows a wrapper around a HASH blessed into the "Foo" package.

repr(p)

Same as str() currently.

len(p)

For arrays and hashes this return the size. For all other things it will raise a TypeError exception.

if p: ...

Empty arrays and hashes evaluate to a false value in boolean contexts. Every other object will be TRUE.

Exceptions

If a perl exception is raised, and caught in python then the exception type object will be perl.PerlError and the value will be the stringified stuff from $@.

BUGS

Perl call frames are currently invisible in python tracebacks.

COPYRIGHT

(C) 2000-2001 ActiveState

This code is distributed under the same terms as Perl; you can redistribute it and/or modify it under the terms of either the GNU General Public License or the Artistic License.

THIS SOFTWARE IS PROVIDED BY ACTIVESTATE `AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ACTIVESTATE OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

SEE ALSO

Python::Object