David Leadbeater > JavaScript-V8 > JavaScript::V8::Context

Download:
JavaScript-V8-0.07.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  11
Open  3
View/Report Bugs
Source  

NAME ^

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

SYNOPSIS ^

  use JavaScript::V8;

  # Create a runtime and a context
  my $context = JavaScript::V8::Context->new();

  # Add a function which we can call from JavaScript
  $context->bind_function(print => sub { print @_ });

  my $result = $context->eval($source);

INTERFACE ^

new ( %parameters )

Create a new JavaScript::V8::Context object.

Several optional parameters are accepted:

time_limit

Force an exception after the script has run for a number of seconds; this limit will be enforced even if V8 calls back to Perl or blocks on IO.

enable_blessing

If enabled, JavaScript objects that have the __perlPackage property are converted to Perl blessed scalar references. These references are blessed into a Perl package with a name bless_prefix + __perlPackage. This package is automagically created and filled with methods from JavaScript object prototype. bless_prefix is optional and can be left out if you completely trust the JavaScript code you're running.

bless_prefix

Specifies a package name prefix to use for blessed JavaScript objects. Has no effect unless enable_blessing is set.

flags

Specify a string of flags to be passed to V8. See set_flags_from_string() for more details.

bind ( name => $scalar )

Converts the given scalar value (array ref, code ref, or hash ref) to a V8 value and binds it in this execution context.

Examples:

Functions

Pass the bind method the name of a function, and a corresponding code reference to have the name bound to the Perl code. For example:

  $context->bind(hello => sub { print shift, "\n" });
  $context->eval("hello('Hello from JavaScript')");
Basic objects

Pass the bind method the name of an object, and a hash reference containing method names and corresponding code references, for example:

  $context->bind(
    test_object => {
      method => sub { return shift },
    },
  );

  print $context->eval("test_object.method('Hello')");
Blessed objects

Pass the bind method the name of an object, and a blessed reference, for example:

  $context->bind(
    perl_object => $blessed_reference,
  );

  print $context->eval("perl_object.method('Hello')");

This requires Perl 5.10 or later.

Arrays

Pass the bind method a JavaScript variable name with an array reference to have the name bound to the Perl array reference. Note that this binding is one way; JavaScript can access Perl arrays and manipulate them, but changes are not made available to the calling Perl code. Similarly, a JavaScript array cannot be manipulated directly in Perl. Example:

  my $test_array_ref = ["hello"];

  $context->bind(
    test_array => $test_array_ref,
  );

  print $context->eval("test_array.pop()");

Calling the JavaScript pop method does not alter $test_array_ref in Perl.

Hashes

Pass the bind method a JavaScript variable name with a hash reference to have the name bound to the Perl hash reference. For example:

  $context->bind(
    window => {
      location => "http://perl.org",
    },
  );

  print $context->eval("window.location");

This creates the "window.location" property in JavaScript. Properties can be changed in JavaScript, but do not change the corresponding Perl data structure.

The exact semantics of this interface are subject to change in a future version (the binding may become more complete).

bind_function ( $name => $subroutine_ref )

DEPRECATED. This is just an alias for bind.

eval ( $source[, $origin] )

Evaluates the JavaScript code given in $source and returns the result from the last statement.

JavaScript::V8 attempts to convert the return value to the corresponding Perl type:

    JavaScript return type    |   Type returned by eval()
  ----------------------------+----------------------------
  Undefined, null             | undef
  Numeric                     | scalar
  Boolean                     | scalar (1 or 0)
  String                      | scalar
  Function                    | code reference
  Object                      | hash reference or blessed scalar reference
  Array                       | array reference

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. If an optional origin for $source has been provided, this will be reported as the origin of the error in $@. This is useful for debugging when eval-ing code from multiple different files or locations.

A function reference returned from JavaScript is not wrapped in the context created by eval(), so JavaScript exceptions will propagate to Perl code.

JavaScript function object having a __perlReturnsList property set that returns an array will return a list to Perl when called in list context.

set_flags_from_string ( $flags )

Set or unset various flags supported by V8 (see http://code.google.com/p/v8/source/browse/trunk/src/flag-definitions.h or src/flag-definitions.h in the V8 source for details of all available flags).

For example, the builtins_in_stack_traces flag controls showing built-in functions in stack traces. To set this, call:

  $context->set_flags_from_string("--builtins-in-stack-traces");

Note underscores are replaced with hyphens. Note that flags which are enabled by default are disabled by prefixing the name with "no" - for example, the "foo" flag could be disabled with --nofoo.

Flags are commonly used for debugging or changing the behaviour of V8 in some way. Some flags can only be set whenever a context is created - set these with the flags parameter to new().

idle_notification( )

Used as a hint to tell V8 that your application is idle, so now might be a suitable time for garbage collection. Returns 1 if there is no further work V8 can currently do.

Most users of JavaScript::V8 will not need this.

name_global( $name )

Give the global object a name that is accessible from JavaScript. This is useful to e.g. name "window" as the top level object, as is usually the case in web browsers. (This is somewhat limited, at some point a fuller and more correct API might be added).

syntax highlighting: