view release on metacpan or  search on metacpan

lib/JavaScript/Duktape/XS.pm  view on Meta::CPAN

=encoding utf8

=head1 NAME

JavaScript::Duktape::XS - Perl XS binding for the Duktape Javascript embeddable
engine

=head1 VERSION

Version 0.000081

=head1 SYNOPSIS

    my $vm = JavaScript::Duktape::XS->new();

    my $options = {
        gather_stats          => 1,
        save_messages         => 1,
        max_memory_bytes      => 256*1024,
        max_timeout_us        => 2*1_000_000,
        catch_perl_exceptions => 1,
    };
    my $vm = JavaScript::Duktape::XS->new($options);

    $vm->set('global_name', [1, 2, 3]);
    my $aref = $vm->get('global_name');
    $vm->remove('global_name');

    $vm->set('my.object.slot', { foo => [ 4, 5 ] });
    my $href = $vm->get('my.object.slot');

    if ($vm->exists('my.object.slot')) { ... }

    my $typeof = $vm->typeof('my.object.slot');

    my $ok = $vm->instanceof('my.car.object', 'Car');

    # When function_name is called from JS, the arguments passed in
    # will be converted to Perl values; likewise, the value returned
    # from the Perl function will be converted to JS values.
    $vm->set('function_name', sub { my @args = @_; return \@args; });
    my $returned = $vm->eval('function_name(my.object.slot)');

    $vm->dispatch_function_in_event_loop('function_name');

    my $stats_href = $vm->get_stats();
    $vm->reset_stats();

    my $msgs_href = $vm->get_msgs();
    $vm->reset_msgs();

    my $globals = $vm->global_objects();

    my $rounds = $vm->run_gc();

    my $info = $vm->get_version_info();

    $vm->set('perl_module_resolve', \&module_resolve);
    $vm->set('perl_module_load',    \&module_load);
    $vm->eval('var badger = require("badger");');

=head1 DESCRIPTION

This module provides an XS wrapper to call Duktape from Perl.

The wrapper is used in an OO way: you create an instance of
C<JavaScript::Duktape::XS> and then invoke functions on it.

=head1 METHODS/ATTRIBUTES

=head2 new

Create a new instance of C<JavaScript::Duktape::XS>.  You can give an optional
hashref with a set of desired options; they can be:

=head3 gather_stats

The XS object will gather statistics about elapsed time and memory usage for
several of its operations.  You can then retrieve the stats by calling
C<get_stats>.

=head3 save_messages

Any message printed to the JavaScript console will instead be saved in a
hashref, where each key represents a "target" for the message (for example,
C<stdout> or C<stderr>).  You can then retrieve the messages by calling
C<get_msgs>.

=head3 max_memory_bytes

Limit the memory dynamically allocated to this many bytes.  If this option is
not used, there is no limit in place.

=head3 max_timeout_us

Limit the execution runtime of any single JavaScript call to this many
microseconds.  If this option is not used, there is no limit in place.

=head3 catch_perl_exceptions

Convert Perl exceptions that are thrown with C<die()> into a JavaScript
C<Error> object. These exception can then be caught in a C<catch> block in
the JavaScript code that had invoked Perl.  If this option is not used, Perl
exceptions are fatal from JavaScript's perspective and cannot be caught.

This option was added in version 0.000080.

=head2 set

Give a value to a given JavaScript variable or object slot.

The Perl value is converted into an equivalent JavaScript value, so you can
freely pass nested structures (hashes of arrays of hashes) and they will be
handled correctly.

Plain scalars are converted thus:

=over

=item * Instances of L<JSON::PP::Boolean> become JavaScript booleans.