perlmodule
Perl
doc
-
Part of CPAN
distribution
pyperl 1.0.
perlmodule - Embed a Perl interpreter in Python
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")
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.
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().
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.
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 $@.
Perl call frames are currently invisible in python tracebacks.
(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.
Python::Object
|
