mirror of
https://github.com/mozilla/gecko-dev.git
synced 2025-02-12 02:31:41 +00:00
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=koi8-r">
<meta name="Author" content="Vladimir Livshits">
<meta name="GENERATOR" content="Mozilla/4.5 [en] (WinNT; U) [Netscape]">
<title>PerlConnect Documentation</title>
<style>
A:link {text-decoration: none}
A:visited {text-decoration: none}
</style>
</head>
<body background="bg.jpg">
<center>
<h3>
P<font size=-1>ERL</font>C<font size=-1>ONNECT AND</font>JS<font size=-1>.pm</font></h3></center>
<center>U<font size=-1>SER-LEVEL </font><font size=+1>D</font><font size=-1>OCUMENTATION</font>
<br><a href="mailto:val4@cornell.edu">Vladimir Livshits</a>
<br>
<hr SIZE=1 NOSHADE WIDTH="100%"></center>
<ol>
<li>
<a href="#Overview">Overview</a></li>
<li>
<a href="#Features">Features</a></li>
<li>
<a href="#Design">Design</a></li>
<li>
<a href="#Installation">Installation</a></li>
<li>
<a href="#Limitations">Current Limitations and Futher Work</a></li>
</ol>
<h4>
<a NAME="Overview"></a>Overview</h4>
PerlConnect provides glue for the developer between JavaScript and Perl.
It currently consists of two parts, PerlConnect implemented in C and JS.pm
(<i>tentative name</i>), a Perl module written using XSUBs. PerlConnect
and JS.pm allow calling Perl from JS and JS from Perl, respectively. Whenever
possible, it is attempted to archieve the maximum level of transparency
for calling one language from the other. This is done by converting values
between the two languages, creating wrappers around objects, and emulating
the standard language syntax.
<h4>
<a NAME="Features"></a>PerlConnect Features</h4>
PerlConnect allows running a Perl interpreter concurrently with your JavaScript
embedding and executing Perl commands from JavaScript. You usually need
to create a Perl interpreter by saysing something like this:
<blockquote><tt>p = new Perl('Sys::Hostname', 'Test::Harness')</tt></blockquote>
In addition to creating an interpreter, this will also include the libraries
you pass to the Perl constructor, which is equivalent to <tt>use
Sys::Hostname; use Test::Harness</tt>. You can always include libraries
explicitly by using <tt>p.eval('use Sys::Hostname; use Test::Harness')</tt>.
There is also another way to do this: <tt>p.use('Sys::Hostname', 'Test::Harness')</tt>.
As you can see, TMTOWTDI. Natura lly, you will want to
look at the result of your function calls and <tt>eval</tt> statements.
Suppose, you do something like this:
<blockquote><tt>line = p.eval("'-' x 80")</tt></blockquote>
Perl's eval returns the last statement evaluated, unless you explicitly
say <tt>return</tt>. So now <tt>line</tt> contains 80 dashes. You can do
similar things with non-scalar data types:
<blockquote><tt>p.use('Time::gmtime');</tt>
<br><tt>t = p.eval('Time::gmtime::gmtime') // returns
[49,0,4,24,6,98,5,204,0]</tt></blockquote>
assigns a Perl array to <tt>t</tt>. You can print <tt>t</tt>, use the <tt>for/in</tt>
syntax to walk through it, compute its lenght, etc. You can read and assign
to individual elements using the standard syntax. However, PerlValues,
that is, the value we get from Perl, don't support all the standard operations,
for isntance, don't expect <tt>t.reverse()</tt> to work. Hashes can also
be returned from Perl:
<blockquote><tt>info=p.eval("{ver=>$], pid=>$$}")</tt></blockquote>
Now you can look at individual hash keys like this:
<blockquote><tt>info["ver"]</tt> or <tt>info.pid</tt></blockquote>
Suppose you want to use Perl to perform pattern-based string replacement.
Here's how you can do it from JavaScript:
<blockquote><tt>p.eval("\</tt>
<br><tt> sub perl_replace(){\</tt>
<br><tt> my($string, $find, $replace)
= @_;\</tt>
<br><tt> eval(\"\\$string =~
s/$find/$replace/g;\");\</tt>
<br><tt> return $string;\</tt>
<br><tt> }"</tt>
<br><tt>);</tt></blockquote>
and now
<blockquote><tt>p.perl_replace('Quick brown fox jumped over a lazy dog',
'dog', 'rhino')</tt></blockquote>
produces what you'd expect.
<p>You can use the same syntax to call procedures defined in modules other
than<tt> main. </tt>The example with<tt> gmtime </tt>can be rewritten like
this:
<blockquote><tt>p.use('Time::gmtime');</tt>
<br><tt>t = p.Time.gmtime.gmtime() // returns [49,0,4,24,6,98,5,204,0]</tt></blockquote>
You can reference variables exported by modules others than <tt>main</tt>
like this:
<blockquote><tt>a=p.Foo.$bar </tt>or<tt> a=p.Foo["$bar"] </tt>or
<br><tt>a=p.Foo["@bar"]</tt>or<tt> a=p.Foo["%bar"]</tt></blockquote>
Each of the stetements above returns a either an immediate JS value, for
scalar types, or a PerlValue for compound types. <tt>a.type </tt>contains
the type of the PerlValue in <tt>a</tt>. <i>This may change because we
may end up separating Perl hashes and arrays into separate classes.</i>
<h4>
JS.pm Features</h4>
<i>JS.pm is much less tested then PerlConnect.</i> You should be able to
do similar things from Perl. Just say
<blockquote><tt>use JS;</tt>
<br><tt>$js = <b>new</b> JS();</tt></blockquote>
and now you can do something like this:
<blockquote><tt>$js-><b>eval</b>(q/</tt>
<blockquote><tt>Object o = {};</tt>
<br><tt>o.a = 'p';</tt>
<br><tt>o.b = 'q';</tt>
<br><tt>return o;</tt></blockquote>
<tt>/);</tt></blockquote>
<b>//TODO: more features and examples</b>
<h4>
<a NAME="Design"></a>PerlConnect Design</h4>
PerlConnect is written in C. It uses both JavaScript and Perl APIs and
implements a mapping between the two. The are the following JavaScript
objects implemented by PerlConnect:
<br>
<center><table BORDER COLS=2 WIDTH="80%" >
<tr ALIGN=CENTER BGCOLOR="#CCCCCC">
<td ALIGN=CENTER VALIGN=CENTER WIDTH="20%"><b>Object</b></td>
<td><b>What it does</b></td>
</tr>
<tr ALIGN=CENTER VALIGN=CENTER>
<td WIDTH="30"><tt>Perl</tt></td>
<td ALIGN=LEFT VALIGN=TOP>Perl Interpreter Object. It's prototype type
is PerlModule, it corresponds to <tt>main::</tt>. Supports <tt>eval</tt>,
<tt>call</tt>,
<tt>use</tt>.</td>
</tr>
<tr ALIGN=CENTER VALIGN=CENTER>
<td><tt>PerlModule</tt></td>
<td ALIGN=LEFT VALIGN=TOP>Implements JS-like syntax for Perl modules. Doesn't
export provide any methods. <tt>path</tt> property shown the name of the
Perl module the object represents.</td>
</tr>
<tr ALIGN=CENTER VALIGN=CENTER>
<td><tt>PerlValue</tt></td>
<td ALIGN=LEFT VALIGN=TOP>Represents a value returned from <tt>eval</tt>,
<tt>call</tt>,
or obtained by using the subscript notation (<tt>p.Foo["@bar"]</tt>). Its
Perl type is stored in the <tt>type</tt> property.</td>
</tr>
</table></center>
<p>See comments in the code, <tt>jsperl.c</tt> and <tt>JS.pm</tt> for more
info.
<br>
<h4>
JS.pm Design</h4>
JSConnect is written using XSUBs, the language in which Perl extentions
are implemented. The source files are <tt>JS.xs</tt> and <tt>typemap</tt>.
After processing them using the XSUBs compiler, <tt>xsubpp</tt>, the resulting
C file should be compiled into a DLL. See <tt>JS.xs</tt> for more details
on how to to compile it. <tt>JS.pm</tt> provides bootstraping mechanism
to load this DLL. See <tt>perlxs</tt> and <tt>perlxsstut</tt> man pages
for more info. The following Perl packages (objects) are implemented:
<br>
<center><table BORDER COLS=2 WIDTH="80%" >
<tr ALIGN=CENTER BGCOLOR="#CCCCCC">
<td ALIGN=CENTER VALIGN=CENTER WIDTH="20%"><b>Package</b></td>
<td><b>What it contains</b></td>
</tr>
<tr ALIGN=CENTER VALIGN=CENTER>
<td><tt>JS</tt></td>
<td ALIGN=LEFT VALIGN=TOP>Doesn't not do anything in particular at this
point except defining a constuctor. So one can say <tt>$js = <b>new</b>
JS()</tt>, which will create a new runtime, add a context to it and return
that Context. JS also defines a bunch of private functions called from
C by PerlConnect. They are not exposed by default, but pushed onto <tt>@EXPORT_OK</tt>
array instead.</td>
</tr>
<tr ALIGN=CENTER VALIGN=CENTER>
<td><tt>JS::Runtime</tt></td>
<td ALIGN=LEFT VALIGN=TOP>Corresponds to <tt>JSRuntime*</tt> struct. Provides
a constructor and destructor. The destructor is invoked automatically,
so you don't have to worry about Runtime deallocation. Constructor syntax
is the following: <tt>$rt = <b>new</b> JS::Runtime(10_000)</tt>, where
the parameter is the same number you pass to <tt>JS_NewRuntime</tt>. There
are many private functions created in <tt>JS.xs</tt> that are not exported
by default.</td>
</tr>
<tr ALIGN=CENTER VALIGN=CENTER>
<td><tt>JS::Context</tt></td>
<td ALIGN=LEFT VALIGN=TOP>Corresponds to <tt>JSContext*</tt> struct. Provides
a constructor and destructor. The destructor is invoked automatically,
so you don't have to worry about Context deallocation. Constructor syntax
is the following: <tt>$rt = <b>new</b> JS::Context($rt, 1_000)</tt>, where
the parameter is the same number you pass to <tt>JS_NewContext</tt>. There
are many private functions created in <tt>JS.xs</tt> that are not exported
by default.</td>
</tr>
<tr>
<td ALIGN=CENTER><tt>JS::Object</tt></td>
<td>Corresponds to <tt>JSObject*</tt> struct. There is not that much here
yet. This object is intended as a wrapper around the <tt>JSObject* stuct</tt>.
Support for tying hashes and possibly arrays with <tt>JS::Objects</tt>
is coming.</td>
</tr>
<tr>
<td ALIGN=CENTER><i><tt><font color="#000000">[JS::Array]</font></tt></i></td>
<td><i>I am not quite sure if this is needed. One might probably get away
with just <tt>JS::Object</tt> defined. If it's implemented, it will be
very much similar to <tt>JS::Object</tt> above.</i></td>
</tr>
</table></center>
<p>All the modules above follow the convention of storing the variable
they return in the <tt>$this</tt> variable of the current class. So <tt>$JS::Context::this</tt>
will always be the last context created. <i>Currently, this is where JS
API function that require contexts get it.</i>
<h4>
<a NAME="Installation"></a>PerlConnect Installation</h4>
PerlConnect requires <tt>js/src</tt> and the Perl libraries and headers.
The only <tt>js/src</tt> file that must be included in <tt>../jsapi.h</tt>.
You need to compile it together with Perl libraries. Referer to the <tt>perlembed</tt>
man page for more details.
<br><b>On WINNT:</b>
<br>There are MSDEV Workspace and project files in the main PerlConnect
directory. There are two projects included in the PerlConnect workspace:
PerlConnect and PerlConnect shell. You can use the latter to test PerlConnect.
You will probably need to adjust the library and include paths. It is assumed
that the directory structure is fixed, that is, you have PerlConnect in
<tt>js/src/perlconnect</tt>. Set PERL_SRC environment variable to point
to the directory where you unpacked and compiled Perl sources.
<br><b>On UNIX:</b>
<br>Currently, you can use PerlConnect with the <tt>js.c</tt> shell. To
compile it on UNIX, you need to set the PERLCONNECT environment variable.
Then you can use the <tt>Makefile.ref</tt> in <tt>js/src</tt> directory.
(<b>//TODO check this!</b>) The makefile should read the variable from
the current environment. If this doesn't happent, you can try using <tt>gmake
PERLCONNECT=1</tt>. This will compile PerlConnect into <tt>js</tt>.
<h4>
JS.pm Installation</h4>
The following source files are distributed: <tt>JS.pm</tt>, <tt>JS.xs</tt>,
<tt>JS.c</tt>
(produced from <tt>JS.xs</tt> by <tt>xsubpp</tt>) and <tt>JS.def</tt> (required
by the Visual C compiler).
<br><b>On WINNT:</b>
<br>There is also a project file, <tt>JS.dsp</tt>. It automatically belongs
to the PerlConnect workspace. This project file builds a DLL, <tt>JS.dll</tt>
which is supposed to reside where Perl's DynaLoader can find it. On my
machine I put it under <tt>c:\perl\lib\auto\JS\JS.dll</tt>. You can also
put it in <tt>c:\perl\lib\</tt>. See DynaLoader documentation for more
info on how dynamic libraries are found.
<br><b>On UNIX:</b>
<br><b>//TODO:</b> <b>details of the makefiles</b>
<br>
<h4>
<a NAME="Limitations"></a>Current Limitations of the Package and Futher
Work</h4>
<ol>
<li>
Perl variables currently can't be assigned to, that is, <tt>p["$a"]=100</tt>
doesn't do anything.</li>
<li>
You can only have one interpreter running at a time. Despite the fact that
you can create multiple Perl objects on JavaScript, they all share the
same namespace. We can probably use <tt>Safe.pm</tt> to implement independent
namespaces.</li>
<li>
Module names resolution reports an error only when you try to evaluate
the last element of the resolution chain. Here is what I mean: if you reference
<tt>p.Foo.Bar.Var</tt>
and <tt>For</tt> or <tt>Bar</tt> don't exist, it will only complain that
p.Foo.Bar.Var is not a valid variable. Perl 5.005 provides <tt>exists Foo::{Bar::}</tt>
to check if Foo::Bar is a valid package.</li>
<li>
Dynamic loading of the Perl interpreter only if it is required.</li>
<li>
Recursive printing of Perl's arrays and hashes can be added. See Data::Dumper.pm</li>
<li>
Full support for tied hashes and arrays in Perl</li>
<li>
Calling JavaScript functions and accessing variables from Perl. JavaScript
calling syntax support using AUTOLOADing.</li>
<li>
JS can be made a directory with <tt>Object.pm</tt>, <tt>Context.pm</tt>,
etc. in it. See how C or Tk are organized on CPAN</li>
<li>
Distribution model for JS.pm. Perl provides something by default. See <tt>h2xs</tt>
man page, for example.</li>
</ol>
</body>
</html>