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(print => sub { print @_ });

  # Bind variables
  $context->bind( bottles => 3 );
  $context->bind( wine_type => ['red', 'white', 'sparkling'] );
  $context->bind( wine_type_description => {
      white     => "White wine is a wine whose color is slightly yellow. This kind of wine is produced using non-coloured grapes or using red-skinned grapes' juice, not allowing it to extract pigment from the skin.",
      red       => "Red wine is a type of wine made from dark-coloured (black) grape varieties. The actual colour of the wine can range from intense violet, typical of young wines, through to brick red for mature wines and brown for older red wines.",
      sparkling => "Sparkling wine is a wine with significant levels of carbon dioxide in it making it fizzy. The carbon dioxide may result from natural fermentation, either in a bottle, as with the méthode champenoise, in a large tank designed to withstand the pressures involved (as in the Charmat process), or as a result of carbon dioxide injection.",
  });

  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_ro ( $name => $scalar )

Like bind() but makes the item read-only on the global object (i.e. it is not recursive, if you need that use tie or other Perl mechanisms).

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 https://github.com/v8/v8/blob/master/src/flags/flag-definitions.h or src/flags/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 and isolate are created - set these with the flags parameter to new().

idle_notification( )

Triggers full garbage collection by telling v8 that memory is low. For compatibility with older versions of this module, it always returns true. There is no need to call it in a loop.

Most users of JavaScript::V8 will not need this. It can be a slow operation.

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).