File: README.md

package info (click to toggle)
libjavascript-quickjs-perl 0.21-2
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 4,180 kB
  • sloc: ansic: 72,822; javascript: 7,743; perl: 1,065; makefile: 353; sh: 108
file content (286 lines) | stat: -rw-r--r-- 10,659 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
# NAME

JavaScript::QuickJS - Run JavaScript via [QuickJS](https://bellard.org/quickjs) in Perl

# SYNOPSIS

Quick and dirty …

    my $val = JavaScript::QuickJS->new()->eval( q<
        let foo = "bar";
        [ "The", "last", "value", "is", "returned." ];
    > );

… or load ES6 modules:

    my $js = JavaScript::QuickJS->new()->helpers();

    $js->eval_module( q/
        import * as coolStuff from 'cool/stuff';

        for (const [key, value] of Object.entries(coolStuff)) {
            console.log(key, value);
        }
    / );

# DESCRIPTION

This library embeds Fabrice Bellard’s [QuickJS](https://bellard.org/quickjs)
engine into a Perl XS module. You can thus run JavaScript
([ES2020](https://tc39.github.io/ecma262/) 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( %CONFIG\_OPTS )

Instantiates _CLASS_. %CONFIG\_OPTS have the same effect as in
`configure()` below.

## $obj = _OBJ_->configure( %OPTS )

Tunes the QuickJS interpreter. Returns _OBJ_.

%OPTS are any of:

- `max_stack_size`
- `memory_limit`
- `gc_threshold`

For more information on these, see QuickJS itself.

## $obj = _OBJ_->set\_globals( NAME1 => VALUE1, .. )

Sets 1 or more globals in _OBJ_. See below for details on type conversions
from Perl to JavaScript.

Returns _OBJ_.

## $obj = _OBJ_->helpers()

Defines QuickJS’s “helpers”, e.g., `console.log`.

Returns _OBJ_.

## $obj = _OBJ_->std()

Enables QuickJS’s `std` module and creates a global of the same name
that’s usable from both script and module modes.

This resembles `qjs`’s `--std` flag except that it _only_ enables
`std`, not `os`.

Returns _OBJ_.

## $obj = _OBJ_->os()

Like `std()` but enables QuickJS’s `os` module instead of `std`.

## $VALUE = _OBJ_->eval( $JS\_CODE )

Like running `qjs -e '...'`. Returns $JS\_CODE’s last value;
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.

## $promise = _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.

Returns a promise that resolves once the module is loaded.

## $obj = _OBJ_->await()

Blocks until all of _OBJ_’s pending work (if any) is complete.

For example, if you `eval()` some code that creates a promise, call
this to wait for that promise to complete.

Returns _OBJ_.

## $obj = _OBJ_->set\_module\_base( $PATH )

Sets a base path (a byte string) for ES6 module imports.

Returns _OBJ_.

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

Returns _OBJ_.

# 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.
    - Function, RegExp, and Date objects become Perl
    [JavaScript::QuickJS::Function](https://metacpan.org/pod/JavaScript%3A%3AQuickJS%3A%3AFunction), [JavaScript::QuickJS::RegExp](https://metacpan.org/pod/JavaScript%3A%3AQuickJS%3A%3ARegExp),
    and [JavaScript::QuickJS::Date](https://metacpan.org/pod/JavaScript%3A%3AQuickJS%3A%3ADate) objects, respectively.
    - Behaviour is **UNDEFINED** for other object types.

# TYPE CONVERSION: PERL → JAVASCRIPT

Generally speaking, it’s the inverse of JS → Perl:

- Perl strings, numbers, & booleans become corresponding JavaScript
primitives.

    **IMPORTANT:** Perl versions before 5.36 don’t reliably distinguish “numeric
    strings” from “numbers”. If your perl predates 5.36, typecast accordingly
    to prevent your Perl “number” from becoming a JavaScript string. (Even in
    5.36 and later it’s still a good idea.)

- Perl undef becomes JS null.
- Unblessed array & hash references become JavaScript arrays and
“plain” objects.
- [Types::Serialiser](https://metacpan.org/pod/Types%3A%3ASerialiser) booleans become JavaScript booleans.
- Perl code references become JavaScript functions.
- Perl [JavaScript::QuickJS::Function](https://metacpan.org/pod/JavaScript%3A%3AQuickJS%3A%3AFunction), [JavaScript::QuickJS::RegExp](https://metacpan.org/pod/JavaScript%3A%3AQuickJS%3A%3ARegExp),
and [JavaScript::QuickJS::Date](https://metacpan.org/pod/JavaScript%3A%3AQuickJS%3A%3ADate) objects become their original
JavaScript objects.
- 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, and clean up all global
instances.

Callbacks make that tricky. When you give a JavaScript function to Perl,
that Perl object holds a reference to the QuickJS context. Only once that
object is `DESTROY()`ed do we release that QuickJS context reference.

Consider the following:

    my $return;

    $js->set_globals(  __return => sub { $return = shift; () } );

    $js->eval('__return( a => a )');

This sets $return to be a [JavaScript::QuickJS::Function](https://metacpan.org/pod/JavaScript%3A%3AQuickJS%3A%3AFunction) instance. That
object holds a reference to $js. $js also stores `__return()`,
which is a Perl code reference that closes around $return. Thus, we have
a reference cycle: $return refers to $js, and $js refers to $return. Those
two values will thus leak, and you’ll see a warning about it at Perl’s
global destruction time.

To break the reference cycle, just do:

    undef $return;

… once you’re done with that variable.

You _might_ have thought you could instead do:

    $js->set_globals( __return => undef )

… but that doesn’t work because $js holds a reference to all Perl code
references it **ever** receives. This is because QuickJS, unlike Perl,
doesn’t expose object destructors (`DESTROY()` in Perl), so there’s no
good way to release that reference to the code reference.

# CHARACTER ENCODING NOTES

QuickJS (like all JS engines) assumes its strings are text. Since Perl
can’t distinguish text from bytes, though, it’s possible to convert
Perl byte strings to JavaScript strings. It often yields a reasonable
result, but not always.

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 those 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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.0` prints `1e+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 this 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 that perl’s
compile-time options mention long doubles or quad math.

# OS SUPPORT

QuickJS supports Linux, macOS, and Windows 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.)

# LIBATOMIC

QuickJS uses C11 atomics. Most platforms implement that functionality in
hardware, but others (e.g., arm32) don’t. To fill that void, we need to link
to libatomic.

This library’s build logic detects whether libatomic is necessary and will
only link to it if needed. If, for some reason, you need manual control over
that linking, set `JS_QUICKJS_LINK_LIBATOMIC` in the environment to 1 or a
falsy value.

If you don’t know what any of that means, you can probably ignore it.

# SEE ALSO

Other JavaScript modules on CPAN include:

- [JavaScript::Duktape::XS](https://metacpan.org/pod/JavaScript%3A%3ADuktape%3A%3AXS) and [JavaScript::Duktape](https://metacpan.org/pod/JavaScript%3A%3ADuktape) make the
[Duktape](https://duktape.org) 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](https://metacpan.org/pod/JavaScript%3A%3AV8) and [JavaScript::V8::XS](https://metacpan.org/pod/JavaScript%3A%3AV8%3A%3AXS) expose Google’s
[V8](https://v8.dev) library to Perl. Neither seems to support current
V8 versions.
- [JE](https://metacpan.org/pod/JE) is a pure-Perl (!) JavaScript engine.
- [JavaScript](https://metacpan.org/pod/JavaScript) and [JavaScript::Lite](https://metacpan.org/pod/JavaScript%3A%3ALite) expose Mozilla’s
[SpiderMonkey](https://spidermonkey.dev/) engine to Perl.

# LICENSE & COPYRIGHT

This library is copyright 2023 Gasper Software Consulting.

This library is licensed under the same terms as Perl itself.
See [perlartistic](https://metacpan.org/pod/perlartistic).

QuickJS is copyright Fabrice Bellard and Charlie Gordon. It is released
under the [MIT license](https://opensource.org/licenses/MIT).