Main
Language
Runtime
Tools
FAQs
Changes
Download
Licence
cheesy

The Idle-Perl interface

This is the preliminary documentation for the Idle-Perl glue module. This module allows you to embed (and execute) live Perl code in your Idle script, so long as you have at least a Perl core DLL installed (although a full Perl installation is definitely advisable).

After a require('Perl') all exported functions are called with prefix Perl.

Back to the main Idle Runtime library documentation.

Module Perl
top of page

The Perl module needs two DLLs to work properly. One is the glue DLL, Perlglue.dll, which forms the interface between Idle and Perl. This DLL, in turn, loads the Perl core DLL (the Perl module requires Perl version 5.10.x, so the glue DLL will look for Perl510.dl; this has to be somewhere in the path). Both libraries are included in the Idle-Perl distribution.

The Perl module supports dynamic loading of Perl modules. That means that things like globs, XS modules et cetera are all supported so long as you have a complete Perl installation. If you do not have (or do not want to install) a full Perl you can still use the standard functions inside the Perl core DLL. However, trying to use the Perl dynamic loader to access modules that are not (correctly) installed can have all sorts of interesting side effects (though most probably Perl will just panic). This practice is best avoided.

Perl.alloc()
top of page

This allocates a new Perl interpreter and returns it as a userdatum. In case of an error the function returns nil. You can create more than one Perl instance in a script, but not in parallel (this is a limitation of the glue library). However, consecutively allocated Perl instances have their own state and keep this state between calls. To free a Perl instance, call Perl.free():

local myPerl=Perl.alloc()
-- ... lots of calls to Perl
Perl.free(myPerl)

Perl.callsub(pint,name[,...])
top of page

Calls a Perl function (a sub, in Perl lingo). pint is a Perl interpreter allocated by a call to Perl.alloc(); name is a string with the name of the sub to call. The sub has to be defined before it can be called (see Perl.eval()). The optional parameters (the maximum supported is 24 parameters) will be handed to the Perl sub where they can be accessed in the usual ways.

This function returns nothing, so if you want to transfer values back to Idle, you should initialise one or more Perl variables with the result(s) and read them from Idle (see Perl.getNumber() and Perl.getString()).

Perl.eval(pint,str)
top of page

Evaluates the string str as Perl code, with pint being a previously allocated Perl interpreter. The string can be as long or as short as you want and can contain function and variable definitions, but it has to be syntactically correct Perl. The Perl interpreter keeps state between calls to Perl.eval(); this allows to define Perl variables and functions for later use.

This functions returns nothing. However, in the case of an error, the internal Perl eval loop that is used to implement this call will set the Perl scalar variable $__err to the Perl error message. By checking this variable (see Perl.getstring()) you can determine whether the call was successful:

local pint=Perl.alloc()
Perl.eval(pint,'$a=2*6;')
local err=Perl.getString(pint,'__err')
if err=='' then print(Perl.getNumber(pint,'a'))  -- okay
else print(err) end  -- something went wrong

Perl.free(pint)
top of page

Frees a Perl instance. You must free the current instance before creating a new one.

Perl.getNumber(pint,name)
top of page

Reads Perl scalar variable name from inside Perl interpreter pint and returns its value as a number. The name given should not include the '$' that Perl uses to signify a scalar. If the variable is not defined, the function returns nil.

Perl.getString(pint,name)
top of page

Reads Perl scalar variable name from inside Perl interpreter pint and returns its value as a string. The name given should not include the '$' that Perl uses to signify a scalar. If the variable is not defined, the function returns nil.

Perl.setNumber(pint,name,value)
top of page

Sets Perl scalar variable name inside Perl interpreter pint to numerical value value. The name given should not include the '$' that Perl uses to signify a scalar.

Perl.setString(pint,name,value)
top of page

Sets Perl scalar variable name inside Perl interpreter pint to string value value. The name given should not include the '$' that Perl uses to signify a scalar.

Perl.new(boff)
top of page

This function is an example wrapper, one of many possible implementation strategies to access Perl from Idle in a simple and efficient manner. It returns a table p with the following elements:

The boolean parameter boff, if true, switches off Idle's buffering of stdout. Unbuffered output may be necessary if both Perl and Idle write to stdout.

Here is a simple, but complete example:

require('Perl')
local pI=Perl.new(true)  -- allocate a Perl interpreter
local perl=pI.eval       -- shortcut to call the beast
local ps=pI.string       -- shortcut to access Perl variables as strings
local pn=pI.number       -- shortcut to access Perl variables as numbers
local pc=pI.call         -- shortcut to call a Perl sub

pn.pi=math.pi  -- The Perl variable $pi is now ~Pi
perl'$aString="Hello, world! Here is your pi: $pi.";'
print(ps.aString)
perl[[
  sub testsub {
    print "1st parameter: $_[0]\n";
    print "2nd parameter: $_[1]\n";
  }
]]
pc('testsub','Print this...','and that.')
pI=nil


$$ built from IdlePerl.txt d106963c4f77 Mon Sep 27 13:27:10 2010 +0000 thomasl $$