NAME

JE - Pure-Perl ECMAScript (JavaScript) Engine

"JE" is short for "JavaScript::Engine."

VERSION

Version 0.013 (alpha release)

The API is still subject to change. If you have the time and the interest, please experiment with this module. If you have any ideas for the API, or would like to help with development, please e-mail the author.

SYNOPSIS

 use JE;

 $j = new JE; # create a new global object

 $j->eval('({"this": "that", "the": "other"}["this"])');
 # returns "that"

 $parsed = $j->parse('new Array(1,2,3)');

 $rv = $parsed->execute; # returns a JE::Object::Array
 $rv->value;             # returns a Perl array ref

 $obj = $j->eval('new Object');
 # create a new object

 $j->prop(document => $obj); # set property
 $j->prop('document'); # get a property
 # Also:
 $j->{document} = $obj;
 $j->{document} = {}; # gets converted to a JE::Object
 $j->{document}{location}{href}; # autovivification

 $j->method(alert => "text"); # invoke a method


 # create global function from a Perl subroutine:
 $j->new_function(print => sub { print @_, "\n" } );

 $j->eval(<<'--end--');
         function correct(s) {
                 s = s.replace(/[EA]/g, function(s){
                         return ['E','A'][+(s=='E')]
                 })
                 return s.charAt(0) +
                        s.substring(1,4).toLowerCase() +
                        s.substring(4)
         }
         print(correct("ECMAScript")) // :-)
 --end--

DESCRIPTION

JE is a pure-Perl JavaScript engine. Here are some of its strengths:

-

Easy to install (no C compiler necessary)

-

Compatible with Data::Dump::Streamer, so the runtime environment can be serialised

-

The parser can be extended/customised to support extra (or fewer) language features (not yet complete)

-

All JavaScript datatypes can be manipulated directly from Perl (they all have overloaded operators)

JE's greatest weakness is that it's slow (well, what did you expect?).

METHODS

See also JE::Object, which this class inherits from, and JE::Types.

$j = JE->new

This class method constructs and returns a new JavaScript environment, the JE object itself being the global object.

$j->parse( STRING )

parse parses the code contained in STRING and returns a parse tree (a JE::Code object).

If the syntax is not valid, undef will be returned and $@ will contain an error message. Otherwise $@ will be a null string.

The JE::Code class provides the method execute for executing the pre-compiled syntax tree.

$j->compile( STRING )

Just an alias for parse.

$j->eval ( STRING )

eval evaluates the JavaScript code contained in STRING. E.g.:

$j->eval('[1,2,3]') # returns a JE::Object::Array which can be used as
                    # an array ref

If an error occurs, undef will be returned and $@ will contain the error message. If no error occurs, $@ will be a null string.

This is actually just a wrapper around parse and the execute method of the JE::Code class.

If the JavaScript code evaluates to an lvalue, a JE::LValue object will be returned. You can use this like any other return value (e.g., as an array ref if it points to a JS array). In addition, you can use the set and get methods to set/get the value of the property to which the lvalue refers. (See also JE::LValue.) E.g., this will create a new object named document:

$j->eval('this.document')->set({});

Note that I used this.document rather than just document, since the latter would throw an error if the variable did not exist.

$j->new_function($name, sub { ... })

$j->new_function(sub { ... })

This creates and returns a new function object. If $name is given, it will become a property of the global object.

Use this to make a Perl subroutine accessible from JavaScript.

For more ways to create functions, see JE::Object::Function.

This is actually a method of JE::Object, so you can use it on any object:

$j->prop('Math')->new_function(double => sub { 2 * shift });

$j->new_method($name, sub { ... })

This is just like new_function, except that, when the function is called, the subroutine's first argument (number 0) will be the object with which the function is called. E.g.:

$j->eval('String.prototype')->new_method(
        reverse => sub { scalar reverse shift }
);
# ... then later ...
$j->eval(q[ 'a string'.reverse() ]); # returns 'gnirts a'

$j->upgrade( @values )

This method upgrades the value or values given to it. See "UPGRADING VALUES" in JE::Types for more detail.

If you pass it more than one argument in scalar context, it returns the number of arguments--but that is subject to change, so don't do that.

$j->undefined

Returns the JavaScript undefined value.

$j->null

Returns the JavaScript null value.

$j->new_parser

Not yet implemented.

This will return a parser object (see JE::Parser) which allows you to customise the way statements are parsed and executed.