NAME
JavaScript::QuickJS - Run JavaScript via QuickJS in Perl
SYNOPSIS
Quick and dirty …
my $val = JavaScript::QuickJS->new()->eval( q<
let foo = "bar";
[ "The", "last", "value", "is", "returned." ];
> );DESCRIPTION
This library embeds Fabrice Bellard’s QuickJS engine into a Perl XS module. You can thus run JavaScript (ES2020 specification) directly in your Perl programs.
This distribution includes all needed C code; unlike with most XS modules that interface with C libraries, you don’t need QuickJS pre-installed on your system.
METHODS
$obj = CLASS->new()
Instantiates CLASS.
$obj = OBJ->set_globals( NAME1 => VALUE1, .. )
Sets 1 or more globals in OBJ. See below for details on type conversions from Perl to JavaScript.
$obj = OBJ->helpers()
Defines QuickJS’s “helpers”, e.g., console.log.
$obj = OBJ->std()
Enables (but does not import) QuickJS’s std module.
$obj = OBJ->os()
Like std() but for QuickJS’s os module.
$VALUE = OBJ->eval( $JS_CODE )
Comparable to running qjs -e '...'. Returns the last value from $JS_CODE; see below for details on type conversions from JavaScript to Perl.
Untrapped exceptions in JavaScript will be rethrown as Perl exceptions.
$JS_CODE is a character string.
OBJ->eval_module( $JS_CODE )
Runs $JS_CODE as a module, which enables ES6 module syntax. Note that no values can be returned directly in this mode of execution.
$obj = OBJ->set_module_base( $PATH )
Sets a base path (a byte string) for ES6 module imports.
$obj = OBJ->unset_module_base()
Restores QuickJS’s default directory for ES6 module imports (as of this writing, it’s the process’s current directory).
TYPE CONVERSION: JAVASCRIPT → PERL
This module converts returned values from JavaScript thus:
JS string primitives become character strings in Perl.
JS number & boolean primitives become corresponding Perl values.
JS null & undefined become Perl undef.
JS objects …
Arrays become Perl array references.
“Plain” objects become Perl hash references.
Functions become Perl code references.
Behaviour is UNDEFINED for other object types.
TYPE CONVERSION: PERL → JAVASCRIPT
Generally speaking, it’s the inverse of JS → Perl, though since Perl doesn’t differentiate “numeric strings” from “numbers” there’s occasional ambiguity. In such cases, behavior is undefined; be sure to typecast in JavaScript accordingly.
Perl strings, numbers, & booleans become corresponding JavaScript primitives.
Perl undef becomes JS null.
Unblessed array & hash references become JavaScript arrays and “plain” objects.
Types::Serialiser booleans become JavaScript booleans.
Perl code references become JavaScript functions.
Anything else triggers an exception.
MEMORY HANDLING NOTES
If any instance of a class of this distribution is DESTROY()ed at Perl’s global destruction, we assume that this is a memory leak, and a warning is thrown. To prevent this, avoid circular references.
Callbacks make that tricky. As noted above, JavaScript functions given to Perl become Perl code references. Those code references are closures around the QuickJS context & runtime; once the code reference is destroyed, we release its reference to QuickJS.
Perl code references given to JavaScript become JavaScript functions; however, QuickJS exposes no facility analogous to Perl DESTROY(). Thus, we retain those Perl code references as part of the QuickJS context.
Consider the following:
my $return;
$js->set_globals( __return => sub { $return = shift; () } );
$js->eval('__return( a => a )');Here $js retains a reference to the __return callback. That callback refers to $return. Once we run eval(), Perl $return stores another callback, which stores a reference to $js. Here we have a circular reference. The way to break it is simply:
undef $return;… which is ugly, but it is what it is for now.
Note also that the __return callback ends with (). Recall that, in Perl, a function’s last statement value is the function’s default return value. Without the (), then, our callback would return $return, which would create yet another reference cycle.
CHARACTER ENCODING NOTES
Although QuickJS (like all JS engines) assumes its strings are text, you can oftentimes pass in byte strings and get a reasonable result.
One place where this falls over, though, is ES6 modules. QuickJS, when it loads an ES6 module, decodes that module’s string literals to characters. Thus, if you pass in byte strings from Perl, QuickJS will treat your Perl byte strings’ code points as character code points, and when you combine those code points with the ones from your ES6 module you may get mangled output.
Another place that may create trouble is if your argument to eval() or eval_module() (above) contains JSON. Perl’s popular JSON encoders output byte strings by default, but as noted above, eval() and eval_module() need character strings. So either configure your JSON encoder to output characters, or decode JSON bytes to characters before calling eval()/eval_module().
For best results, always interact with QuickJS via character strings, and double-check that you’re doing it that way consistently.
NUMERIC PRECISION
Note the following if you expect to deal with “large” numbers:
JavaScript’s numeric-precision limits apply. (cf. Number.MAX_SAFE_INTEGER.)
Perl’s stringification of numbers may be less precise than JavaScript’s storage of those numbers, or even than Perl’s own storage. For example, in Perl 5.34
print 1000000000000001.0prints1e+15.To counteract this loss of precision, add 0 to Perl’s numeric scalars (e.g.,
print 0 + 1000000000000001.0); this will encourage Perl to store numbers as integers when possible, which fixes the precision problem.Long-double and quad-math perls may lose precision when converting numbers to/from JavaScript. To see if this affects your perl—which, if you’re unsure, it probably doesn’t—run
perl -V, and see if the compile-time options mention long doubles or quad math.
OS SUPPORT
QuickJS supports Linux & macOS natively, so these work without issue.
FreeBSD, OpenBSD, & Cygwin work after a few patches that we apply when building this library. (Hopefully these will eventually merge into QuickJS.)
SEE ALSO
Other JavaScript modules on CPAN include:
JavaScript::Duktape::XS and JavaScript::Duktape make the Duktape library available to Perl. They’re similar to this library, but Duktape itself (as of this writing) lacks support for several JavaScript constructs that QuickJS supports. (It’s also slower.)
JavaScript::V8 and JavaScript::V8::XS expose Google’s V8 library to Perl. Neither seems to support current V8 versions.
JE is a pure-Perl (!) JavaScript engine.
JavaScript and JavaScript::Lite expose Mozilla’s SpiderMonkey engine to Perl.
LICENSE & COPYRIGHT
Copyright 2022 Gasper Software Consulting.
This library is licensed under the same terms as Perl itself. See perlartistic.