NAME

JSPL::Context - An object in which we can execute JavaScript

SYNOPSIS

  use JSPL;

  my $ctx = JSPL::Runtime->new->create_context();

  # Add a function callable from javascript
  $ctx->bind_function(say => sub { print @_; });

  my $result = $ctx->eval($javascript_source);

DESCRIPTION

To interact with the SpiderMonkey JavaScript engine you need a JSPL::Context instance. To create one you can use the method "create_context" in JSPL::Runtime or obtain the "stock" one with "stock_context" in JSPL.

INTERFACE

INSTANCE METHODS

get_global ( )

Returns the global object associated with the JavaScript context, equivalent to $ctx->eval('this')

new_object ( )

Returns a newly born JavaScript Object. This is equivalent to $ctx->eval('({})')

get_controller ( )

Returns the JSPL::Controller controller associated with the JavaScript context.

bind_value ( $path => $value )

Defines a property with the given $path and $value.

$path is a string that reference a property in the global object or a path to deeper properties, creating empty Objects for any missing.

For example:

    $ctx->bind_value('foo' => $value); # Set 'foo' to $value

    $ctx->bind_value('foo.bar' => $value); # Create 'foo' as '{}' if needed
                                           # and set 'foo.bar' to $value

Trying to redefine an already existing property throws an exception, i.e. the last component of $path must not exists.

Returns $value

bind_object ( $path => $value )

The same as "bind_value" above, but check that $value is an object (i.e. a blessed reference), and throws otherwise.

bind_function ( name => $path, func => $subroutine )

bind_function ( $path => $subroutine )

Defines a Perl subroutine as a native function with the given $path. The argument $subroutine can either be the name of a subroutine or a reference to one.

The four arguments form should not be used in new code as can be deprecated in the future.

bind_all ( $name1 => $value1, ... )

Calls bind_value above for every pair of its arguments. Allowing you to mass populate the context.

unbind_value ( $path )

Remove a property from the context or a specified object.

call ( $name, @arguments )

call ( $function, @arguments )

Calls the JavaScript function named $name or the JSPL::Function instance $function and passes the rest of the arguments to the function.

can ( $name )

Check if in the context there is a function with a given $name. Returns a reference to the function if there otherwise returns undef.

The return value, if TRUE, can be called:

    if(my $date = $ctx->can('Date')) { # 'Date' is there
        print $date->(time * 1000); # Now
    }

compile ( $source )

Compiles the javascript code given in $source, and returns a JSPL::Script instance that can be executed over and over again without paying the compilation overhead every time.

If a compilation error occurs returns undef and sets $@.

compile_file ( $file_name )

Compiles the javascript code in $file_name, returns a JSPL::Script instance that can be executed over and over again without paying the compilation overhead every time.

If a compilation error occurs returns undef and sets $@.

eval ( $source )

Evaluates the javascript code given in $source and returns the result from the last statement. Any uncaught exception in JavaScript will cause a croak. See "RaiseExceptions"

eval_file ( $path )

Evaluates the javascript code in the file specified by $path and returns the result from the last statement.

If there is a compilation error (such as a syntax error) or an uncaught exception is thrown in javascript this method returns undef and $@ is set.

bind_class ( $jsclass )

Bind a native class created "with JSPL::PerlClass"

check_privileges ( )

To be used inside perl code called from javascript. Check that the context isn't restricted, otherwise dies with the error "Not enough privileges";

set_branch_handler ( $handler )

[ DEPRECATED. The support API was removed from SpiderMonkey v1.8+, calling set_branch_handler in that case will thrown a fatal error. See JSPL::Context::Timeout for a supported way to control a runaway script. ]

Attaches a branch callback handler (a function that is called when a branch is performed) to the context. The argument $handler may be a code-reference or the name of a subroutine.

To remove the handler call this method with an undefined argument.

The handler is called when a script branches backwards during execution, when a function returns and the end of the script. To continue execution the handler must return a true value. To abort execution either throw an exception or return a false value.

id ( )

Returns the "Context ID" of the calling context. Every context has an integer associated with it that can be used to identify a particular context.

See "find".

get_version ( )

Returns the runtime version of the context as a string, for example 1.7 or or ECMAv3.

set_version ( $version )

Sets the runtime version of the context to that specified in the string $version. Some features such as let and yield might not be enabled by default and thus must be turned on by specifying what JavaScript engine version we're using.

A list of these can be found at http://developer.mozilla.org/en/docs/JSVersion but may vary depending on the version of your runtime.

CLASS METHODS

There are available the following class methods

find ( $ContextId )

Returns the JSPL::Context object associated with a given $ContextId if exists or undef if not.

See "id".

current ( )

Returns the current JSPL::Context object.

To be used by perl subroutines designed to be called by javascript land when they need the context with in they are being called.

When there aren't an active context, it dies with the error "Not in a javascript context".

jsvisitor (REFERENCE_TO_SOMETHING)

Returns the JSPL::Visitor associated to the perl "thing" for which REFERENCE_TO_THING is a reference for, if any. Otherwise returns undef.

REFERENCE_TO_SOMETHING can be a reference to anything.

CONTEXT OPTIONS

There are a few options that change the operation of the context, those can be manipulated using the context handle as a HASH reference, all options are booleans so any value setted will be TRUE or FALSE as by perl rules and can be made local for localized changes.

  {
    local $ctx->{OptionFoo} = 1;
    # This code uses a TRUE OptionFoo;
    ...
  }
  # From here, OptionFoo uses its previous value
  ...

The currently defined options are:

AutoTie

If TRUE the wrapped instances of Array or Object when returned to perl will be automatically tied in real perl ARRAYs or HASHes, and your perl code will not see instances of JSPL::Object or JSPL::Array unless you explicitly use the tied perl function.

When FALSE the wrapper instances will be returned directly.

The default value is TRUE

ConstantsValue

If TRUE perl's "Constant Functions" defined in perl namespaces, when reflected to javascript will be seen as true constants attributes. When FALSE they will be seen as normal functions, so to obtain its values they must be called.

The default value is TRUE

ConvertRegExp

If TRUE all instances of javascript RegExp will be converted to perl RegExp, when FALSE they will be wrapped in JSPL::Object instances in the normal way.

The default value is TRUE

RaiseExceptions

When TRUE all untrapped exceptions in javascript space will raise a perl fatal exception. Set it to FALSE cause that exceptions results in only setting $@ and the operation returns undef.

The default value is TRUE

StrictEnable

Warn on dubious practice. Defaults to FALSE.

XMLEnable

In E4X (ECMAScript for XML) parse <!-- --> as a token. Defaults to TRUE.

JITEnable

Enable JIT compilation. Requires a SpiderMonkey with TraceMonkey. Defaults to FALSE.