NAME

JE - Pure-Perl ECMAScript (JavaScript) Engine

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

VERSION

Version 0.008 (alpha release)

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 => {});   # same thing (more or less)
  $j->prop('document'); # get a property

  $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

This is a pure-Perl JavaScript engine. All JavaScript values are actually Perl objects underneath. When you create a new JE object, you are basically creating a new JavaScript "world," the JE object itself being the global object. To add properties and methods to it from Perl, and to access those properties, see JE::Types and JE::Object, which this class inherits from.

If you want to create your own global object class (such as a web browser window), inherit from JE.

METHODS

$j = JE->new

This class method constructs and returns a new global scope (JE 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->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.