forked from c-smile/quickjspp
-
Notifications
You must be signed in to change notification settings - Fork 0
/
quickjs.html
1383 lines (1278 loc) · 50.2 KB
/
quickjs.html
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
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>QuickJS Javascript Engine</title>
<meta name="description" content="QuickJS Javascript Engine">
<meta name="keywords" content="QuickJS Javascript Engine">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="#SEC_Contents" rel="contents" title="Table of Contents">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body lang="en">
<h1 class="settitle" align="center">QuickJS Javascript Engine</h1>
<a name="SEC_Contents"></a>
<h2 class="contents-heading">Table of Contents</h2>
<div class="contents">
<ul class="no-bullet">
<li><a name="toc-Introduction" href="#Introduction">1 Introduction</a>
<ul class="no-bullet">
<li><a name="toc-Main-Features" href="#Main-Features">1.1 Main Features</a></li>
</ul></li>
<li><a name="toc-Usage" href="#Usage">2 Usage</a>
<ul class="no-bullet">
<li><a name="toc-Installation" href="#Installation">2.1 Installation</a></li>
<li><a name="toc-Quick-start" href="#Quick-start">2.2 Quick start</a></li>
<li><a name="toc-Command-line-options" href="#Command-line-options">2.3 Command line options</a>
<ul class="no-bullet">
<li><a name="toc-qjs-interpreter" href="#qjs-interpreter">2.3.1 <code>qjs</code> interpreter</a></li>
<li><a name="toc-qjsc-compiler" href="#qjsc-compiler">2.3.2 <code>qjsc</code> compiler</a></li>
</ul></li>
<li><a name="toc-qjscalc-application" href="#qjscalc-application">2.4 <code>qjscalc</code> application</a></li>
<li><a name="toc-Built_002din-tests" href="#Built_002din-tests">2.5 Built-in tests</a></li>
<li><a name="toc-Test262-_0028ECMAScript-Test-Suite_0029" href="#Test262-_0028ECMAScript-Test-Suite_0029">2.6 Test262 (ECMAScript Test Suite)</a></li>
</ul></li>
<li><a name="toc-Specifications" href="#Specifications">3 Specifications</a>
<ul class="no-bullet">
<li><a name="toc-Language-support" href="#Language-support">3.1 Language support</a>
<ul class="no-bullet">
<li><a name="toc-ES2020-support" href="#ES2020-support">3.1.1 ES2020 support</a></li>
<li><a name="toc-ECMA402" href="#ECMA402">3.1.2 ECMA402</a></li>
<li><a name="toc-Extensions" href="#Extensions">3.1.3 Extensions</a></li>
<li><a name="toc-Mathematical-extensions" href="#Mathematical-extensions">3.1.4 Mathematical extensions</a></li>
</ul></li>
<li><a name="toc-Modules" href="#Modules">3.2 Modules</a></li>
<li><a name="toc-Standard-library" href="#Standard-library">3.3 Standard library</a>
<ul class="no-bullet">
<li><a name="toc-Global-objects" href="#Global-objects">3.3.1 Global objects</a></li>
<li><a name="toc-std-module" href="#std-module">3.3.2 <code>std</code> module</a></li>
<li><a name="toc-os-module" href="#os-module">3.3.3 <code>os</code> module</a></li>
</ul></li>
<li><a name="toc-QuickJS-C-API" href="#QuickJS-C-API">3.4 QuickJS C API</a>
<ul class="no-bullet">
<li><a name="toc-Runtime-and-contexts" href="#Runtime-and-contexts">3.4.1 Runtime and contexts</a></li>
<li><a name="toc-JSValue" href="#JSValue">3.4.2 JSValue</a></li>
<li><a name="toc-C-functions" href="#C-functions">3.4.3 C functions</a></li>
<li><a name="toc-Exceptions" href="#Exceptions">3.4.4 Exceptions</a></li>
<li><a name="toc-Script-evaluation" href="#Script-evaluation">3.4.5 Script evaluation</a></li>
<li><a name="toc-JS-Classes" href="#JS-Classes">3.4.6 JS Classes</a></li>
<li><a name="toc-C-Modules" href="#C-Modules">3.4.7 C Modules</a></li>
<li><a name="toc-Memory-handling" href="#Memory-handling">3.4.8 Memory handling</a></li>
<li><a name="toc-Execution-timeout-and-interrupts" href="#Execution-timeout-and-interrupts">3.4.9 Execution timeout and interrupts</a></li>
</ul></li>
</ul></li>
<li><a name="toc-Internals" href="#Internals">4 Internals</a>
<ul class="no-bullet">
<li><a name="toc-Bytecode" href="#Bytecode">4.1 Bytecode</a></li>
<li><a name="toc-Executable-generation" href="#Executable-generation">4.2 Executable generation</a>
<ul class="no-bullet">
<li><a name="toc-qjsc-compiler-1" href="#qjsc-compiler-1">4.2.1 <code>qjsc</code> compiler</a></li>
<li><a name="toc-Binary-JSON" href="#Binary-JSON">4.2.2 Binary JSON</a></li>
</ul></li>
<li><a name="toc-Runtime" href="#Runtime">4.3 Runtime</a>
<ul class="no-bullet">
<li><a name="toc-Strings" href="#Strings">4.3.1 Strings</a></li>
<li><a name="toc-Objects" href="#Objects">4.3.2 Objects</a></li>
<li><a name="toc-Atoms" href="#Atoms">4.3.3 Atoms</a></li>
<li><a name="toc-Numbers" href="#Numbers">4.3.4 Numbers</a></li>
<li><a name="toc-Garbage-collection" href="#Garbage-collection">4.3.5 Garbage collection</a></li>
<li><a name="toc-JSValue-1" href="#JSValue-1">4.3.6 JSValue</a></li>
<li><a name="toc-Function-call" href="#Function-call">4.3.7 Function call</a></li>
</ul></li>
<li><a name="toc-RegExp" href="#RegExp">4.4 RegExp</a></li>
<li><a name="toc-Unicode" href="#Unicode">4.5 Unicode</a></li>
<li><a name="toc-BigInt_002c-BigFloat_002c-BigDecimal" href="#BigInt_002c-BigFloat_002c-BigDecimal">4.6 BigInt, BigFloat, BigDecimal</a></li>
</ul></li>
<li><a name="toc-License" href="#License">5 License</a></li>
</ul>
</div>
<a name="Introduction"></a>
<h2 class="chapter">1 Introduction</h2>
<p>QuickJS is a small and embeddable Javascript engine. It supports the
ES2020 specification
<a name="DOCF1" href="#FOOT1"><sup>1</sup></a>
including modules, asynchronous generators, proxies and BigInt.
</p>
<p>It supports mathematical extensions such as big decimal float float
numbers (BigDecimal), big binary floating point numbers (BigFloat),
and operator overloading.
</p>
<a name="Main-Features"></a>
<h3 class="section">1.1 Main Features</h3>
<ul>
<li> Small and easily embeddable: just a few C files, no external dependency, 210 KiB of x86 code for a simple “hello world” program.
</li><li> Fast interpreter with very low startup time: runs the 69000 tests of the ECMAScript Test Suite<a name="DOCF2" href="#FOOT2"><sup>2</sup></a> in about 95 seconds on a single core of a desktop PC. The complete life cycle of a runtime instance completes in less than 300 microseconds.
</li><li> Almost complete ES2020 support including modules, asynchronous
generators and full Annex B support (legacy web compatibility). Many
features from the upcoming ES2021 specification
<a name="DOCF3" href="#FOOT3"><sup>3</sup></a> are also supported.
</li><li> Passes nearly 100% of the ECMAScript Test Suite tests when selecting the ES2020 features.
</li><li> Compile Javascript sources to executables with no external dependency.
</li><li> Garbage collection using reference counting (to reduce memory usage and have deterministic behavior) with cycle removal.
</li><li> Mathematical extensions: BigDecimal, BigFloat, operator overloading, bigint mode, math mode.
</li><li> Command line interpreter with contextual colorization and completion implemented in Javascript.
</li><li> Small built-in standard library with C library wrappers.
</li></ul>
<a name="Usage"></a>
<h2 class="chapter">2 Usage</h2>
<a name="Installation"></a>
<h3 class="section">2.1 Installation</h3>
<p>A Makefile is provided to compile the engine on Linux or MacOS/X. A
preliminary Windows support is available thru cross compilation on a
Linux host with the MingGW tools.
</p>
<p>Edit the top of the <code>Makefile</code> if you wish to select specific
options then run <code>make</code>.
</p>
<p>You can type <code>make install</code> as root if you wish to install the binaries and support files to
<code>/usr/local</code> (this is not necessary to use QuickJS).
</p>
<a name="Quick-start"></a>
<h3 class="section">2.2 Quick start</h3>
<p><code>qjs</code> is the command line interpreter (Read-Eval-Print Loop). You can pass
Javascript files and/or expressions as arguments to execute them:
</p>
<div class="example">
<pre class="example">./qjs examples/hello.js
</pre></div>
<p><code>qjsc</code> is the command line compiler:
</p>
<div class="example">
<pre class="example">./qjsc -o hello examples/hello.js
./hello
</pre></div>
<p>generates a <code>hello</code> executable with no external dependency.
</p>
<a name="Command-line-options"></a>
<h3 class="section">2.3 Command line options</h3>
<a name="qjs-interpreter"></a>
<h4 class="subsection">2.3.1 <code>qjs</code> interpreter</h4>
<pre class="verbatim">usage: qjs [options] [file [args]]
</pre>
<p>Options are:
</p><dl compact="compact">
<dt><code>-h</code></dt>
<dt><code>--help</code></dt>
<dd><p>List options.
</p>
</dd>
<dt><code>-e <code>EXPR</code></code></dt>
<dt><code>--eval <code>EXPR</code></code></dt>
<dd><p>Evaluate EXPR.
</p>
</dd>
<dt><code>-i</code></dt>
<dt><code>--interactive</code></dt>
<dd><p>Go to interactive mode (it is not the default when files are provided on the command line).
</p>
</dd>
<dt><code>-m</code></dt>
<dt><code>--module</code></dt>
<dd><p>Load as ES6 module (default=autodetect). A module is autodetected if
the filename extension is <code>.mjs</code> or if the first keyword of the
source is <code>import</code>.
</p>
</dd>
<dt><code>--script</code></dt>
<dd><p>Load as ES6 script (default=autodetect).
</p>
</dd>
<dt><code>--bignum</code></dt>
<dd><p>Enable the bignum extensions: BigDecimal object, BigFloat object and
the <code>"use math"</code> directive.
</p>
</dd>
<dt><code>-I file</code></dt>
<dt><code>--include file</code></dt>
<dd><p>Include an additional file.
</p>
</dd>
</dl>
<p>Advanced options are:
</p>
<dl compact="compact">
<dt><code>--std</code></dt>
<dd><p>Make the <code>std</code> and <code>os</code> modules available to the loaded
script even if it is not a module.
</p>
</dd>
<dt><code>-d</code></dt>
<dt><code>--dump</code></dt>
<dd><p>Dump the memory usage stats.
</p>
</dd>
<dt><code>-q</code></dt>
<dt><code>--quit</code></dt>
<dd><p>just instantiate the interpreter and quit.
</p>
</dd>
</dl>
<a name="qjsc-compiler"></a>
<h4 class="subsection">2.3.2 <code>qjsc</code> compiler</h4>
<pre class="verbatim">usage: qjsc [options] [files]
</pre>
<p>Options are:
</p><dl compact="compact">
<dt><code>-c</code></dt>
<dd><p>Only output bytecode in a C file. The default is to output an executable file.
</p></dd>
<dt><code>-e</code></dt>
<dd><p>Output <code>main()</code> and bytecode in a C file. The default is to output an
executable file.
</p></dd>
<dt><code>-o output</code></dt>
<dd><p>Set the output filename (default = <samp>out.c</samp> or <samp>a.out</samp>).
</p>
</dd>
<dt><code>-N cname</code></dt>
<dd><p>Set the C name of the generated data.
</p>
</dd>
<dt><code>-m</code></dt>
<dd><p>Compile as Javascript module (default=autodetect).
</p>
</dd>
<dt><code>-D module_name</code></dt>
<dd><p>Compile a dynamically loaded module and its dependencies. This option
is needed when your code uses the <code>import</code> keyword or the
<code>os.Worker</code> constructor because the compiler cannot statically
find the name of the dynamically loaded modules.
</p>
</dd>
<dt><code>-M module_name[,cname]</code></dt>
<dd><p>Add initialization code for an external C module. See the
<code>c_module</code> example.
</p>
</dd>
<dt><code>-x</code></dt>
<dd><p>Byte swapped output (only used for cross compilation).
</p>
</dd>
<dt><code>-flto</code></dt>
<dd><p>Use link time optimization. The compilation is slower but the
executable is smaller and faster. This option is automatically set
when the <code>-fno-x</code> options are used.
</p>
</dd>
<dt><code>-fno-[eval|string-normalize|regexp|json|proxy|map|typedarray|promise|bigint]</code></dt>
<dd><p>Disable selected language features to produce a smaller executable file.
</p>
</dd>
<dt><code>-fbignum</code></dt>
<dd><p>Enable the bignum extensions: BigDecimal object, BigFloat object and
the <code>"use math"</code> directive.
</p>
</dd>
</dl>
<a name="qjscalc-application"></a>
<h3 class="section">2.4 <code>qjscalc</code> application</h3>
<p>The <code>qjscalc</code> application is a superset of the <code>qjs</code>
command line interpreter implementing a Javascript calculator with
arbitrarily large integer and floating point numbers, fractions,
complex numbers, polynomials and matrices. The source code is in
<samp>qjscalc.js</samp>. More documentation and a web version are available at
<a href="http://numcalc.com">http://numcalc.com</a>.
</p>
<a name="Built_002din-tests"></a>
<h3 class="section">2.5 Built-in tests</h3>
<p>Run <code>make test</code> to run the few built-in tests included in the
QuickJS archive.
</p>
<a name="Test262-_0028ECMAScript-Test-Suite_0029"></a>
<h3 class="section">2.6 Test262 (ECMAScript Test Suite)</h3>
<p>A test262 runner is included in the QuickJS archive. The test262 tests
can be installed in the QuickJS source directory with:
</p>
<div class="example">
<pre class="example">git clone https://github.com/tc39/test262.git test262
cd test262
patch -p1 < ../tests/test262.patch
cd ..
</pre></div>
<p>The patch adds the implementation specific <code>harness</code> functions
and optimizes the inefficient RegExp character classes and Unicode
property escapes tests (the tests themselves are not modified, only a
slow string initialization function is optimized).
</p>
<p>The tests can be run with
</p><div class="example">
<pre class="example">make test2
</pre></div>
<p>The configuration files <code>test262.conf</code>
(resp. <code>test262o.conf</code> for the old ES5.1 tests<a name="DOCF4" href="#FOOT4"><sup>4</sup></a>))
contain the options to run the various tests. Tests can be excluded
based on features or filename.
</p>
<p>The file <code>test262_errors.txt</code> contains the current list of
errors. The runner displays a message when a new error appears or when
an existing error is corrected or modified. Use the <code>-u</code> option
to update the current list of errors (or <code>make test2-update</code>).
</p>
<p>The file <code>test262_report.txt</code> contains the logs of all the
tests. It is useful to have a clearer analysis of a particular
error. In case of crash, the last line corresponds to the failing
test.
</p>
<p>Use the syntax <code>./run-test262 -c test262.conf -f filename.js</code> to
run a single test. Use the syntax <code>./run-test262 -c test262.conf
N</code> to start testing at test number <code>N</code>.
</p>
<p>For more information, run <code>./run-test262</code> to see the command line
options of the test262 runner.
</p>
<p><code>run-test262</code> accepts the <code>-N</code> option to be invoked from
<code>test262-harness</code><a name="DOCF5" href="#FOOT5"><sup>5</sup></a>
thru <code>eshost</code>. Unless you want to compare QuickJS with other
engines under the same conditions, we do not recommend to run the
tests this way as it is much slower (typically half an hour instead of
about 100 seconds).
</p>
<a name="Specifications"></a>
<h2 class="chapter">3 Specifications</h2>
<a name="Language-support"></a>
<h3 class="section">3.1 Language support</h3>
<a name="ES2020-support"></a>
<h4 class="subsection">3.1.1 ES2020 support</h4>
<p>The ES2020 specification is almost fully supported including the Annex
B (legacy web compatibility) and the Unicode related features.
</p>
<p>The following features are not supported yet:
</p>
<ul>
<li> Tail calls<a name="DOCF6" href="#FOOT6"><sup>6</sup></a>
</li></ul>
<a name="ECMA402"></a>
<h4 class="subsection">3.1.2 ECMA402</h4>
<p>ECMA402 (Internationalization API) is not supported.
</p>
<a name="Extensions"></a>
<h4 class="subsection">3.1.3 Extensions</h4>
<ul>
<li> The directive <code>"use strip"</code> indicates that the debug information (including the source code of the functions) should not be retained to save memory. As <code>"use strict"</code>, the directive can be global to a script or local to a function.
</li><li> The first line of a script beginning with <code>#!</code> is ignored.
</li></ul>
<a name="Mathematical-extensions"></a>
<h4 class="subsection">3.1.4 Mathematical extensions</h4>
<p>The mathematical extensions are fully backward compatible with
standard Javascript. See <code>jsbignum.pdf</code> for more information.
</p>
<ul>
<li> <code>BigDecimal</code> support: arbitrary large floating point numbers in base 10.
</li><li> <code>BigFloat</code> support: arbitrary large floating point numbers in base 2.
</li><li> Operator overloading.
</li><li> The directive <code>"use bigint"</code> enables the bigint mode where integers are <code>BigInt</code> by default.
</li><li> The directive <code>"use math"</code> enables the math mode where the division and power operators on integers produce fractions. Floating point literals are <code>BigFloat</code> by default and integers are <code>BigInt</code> by default.
</li></ul>
<a name="Modules"></a>
<h3 class="section">3.2 Modules</h3>
<p>ES6 modules are fully supported. The default name resolution is the
following:
</p>
<ul>
<li> Module names with a leading <code>.</code> or <code>..</code> are relative
to the current module path.
</li><li> Module names without a leading <code>.</code> or <code>..</code> are system
modules, such as <code>std</code> or <code>os</code>.
</li><li> Module names ending with <code>.so</code> are native modules using the
QuickJS C API.
</li></ul>
<a name="Standard-library"></a>
<h3 class="section">3.3 Standard library</h3>
<p>The standard library is included by default in the command line
interpreter. It contains the two modules <code>std</code> and <code>os</code> and
a few global objects.
</p>
<a name="Global-objects"></a>
<h4 class="subsection">3.3.1 Global objects</h4>
<dl compact="compact">
<dt><code>scriptArgs</code></dt>
<dd><p>Provides the command line arguments. The first argument is the script name.
</p></dd>
<dt><code>print(...args)</code></dt>
<dd><p>Print the arguments separated by spaces and a trailing newline.
</p></dd>
<dt><code>console.log(...args)</code></dt>
<dd><p>Same as print().
</p>
</dd>
</dl>
<a name="std-module"></a>
<h4 class="subsection">3.3.2 <code>std</code> module</h4>
<p>The <code>std</code> module provides wrappers to the libc <samp>stdlib.h</samp>
and <samp>stdio.h</samp> and a few other utilities.
</p>
<p>Available exports:
</p>
<dl compact="compact">
<dt><code>exit(n)</code></dt>
<dd><p>Exit the process.
</p>
</dd>
<dt><code>evalScript(str, options = undefined)</code></dt>
<dd><p>Evaluate the string <code>str</code> as a script (global
eval). <code>options</code> is an optional object containing the following
optional properties:
</p>
<dl compact="compact">
<dt><code>backtrace_barrier</code></dt>
<dd><p>Boolean (default = false). If true, error backtraces do not list the
stack frames below the evalScript.
</p></dd>
</dl>
</dd>
<dt><code>loadScript(filename)</code></dt>
<dd><p>Evaluate the file <code>filename</code> as a script (global eval).
</p>
</dd>
<dt><code>loadFile(filename)</code></dt>
<dd><p>Load the file <code>filename</code> and return it as a string assuming UTF-8
encoding. Return <code>null</code> in case of I/O error.
</p>
</dd>
<dt><code>open(filename, flags, errorObj = undefined)</code></dt>
<dd><p>Open a file (wrapper to the libc <code>fopen()</code>). Return the FILE
object or <code>null</code> in case of I/O error. If <code>errorObj</code> is not
undefined, set its <code>errno</code> property to the error code or to 0 if
no error occured.
</p>
</dd>
<dt><code>popen(command, flags, errorObj = undefined)</code></dt>
<dd><p>Open a process by creating a pipe (wrapper to the libc
<code>popen()</code>). Return the FILE
object or <code>null</code> in case of I/O error. If <code>errorObj</code> is not
undefined, set its <code>errno</code> property to the error code or to 0 if
no error occured.
</p>
</dd>
<dt><code>fdopen(fd, flags, errorObj = undefined)</code></dt>
<dd><p>Open a file from a file handle (wrapper to the libc
<code>fdopen()</code>). Return the FILE
object or <code>null</code> in case of I/O error. If <code>errorObj</code> is not
undefined, set its <code>errno</code> property to the error code or to 0 if
no error occured.
</p>
</dd>
<dt><code>tmpfile(errorObj = undefined)</code></dt>
<dd><p>Open a temporary file. Return the FILE
object or <code>null</code> in case of I/O error. If <code>errorObj</code> is not
undefined, set its <code>errno</code> property to the error code or to 0 if
no error occured.
</p>
</dd>
<dt><code>puts(str)</code></dt>
<dd><p>Equivalent to <code>std.out.puts(str)</code>.
</p>
</dd>
<dt><code>printf(fmt, ...args)</code></dt>
<dd><p>Equivalent to <code>std.out.printf(fmt, ...args)</code>.
</p>
</dd>
<dt><code>sprintf(fmt, ...args)</code></dt>
<dd><p>Equivalent to the libc sprintf().
</p>
</dd>
<dt><code>in</code></dt>
<dt><code>out</code></dt>
<dt><code>err</code></dt>
<dd><p>Wrappers to the libc file <code>stdin</code>, <code>stdout</code>, <code>stderr</code>.
</p>
</dd>
<dt><code>SEEK_SET</code></dt>
<dt><code>SEEK_CUR</code></dt>
<dt><code>SEEK_END</code></dt>
<dd><p>Constants for seek().
</p>
</dd>
<dt><code>Error</code></dt>
<dd>
<p>Enumeration object containing the integer value of common errors
(additional error codes may be defined):
</p>
<dl compact="compact">
<dt><code>EINVAL</code></dt>
<dt><code>EIO</code></dt>
<dt><code>EACCES</code></dt>
<dt><code>EEXIST</code></dt>
<dt><code>ENOSPC</code></dt>
<dt><code>ENOSYS</code></dt>
<dt><code>EBUSY</code></dt>
<dt><code>ENOENT</code></dt>
<dt><code>EPERM</code></dt>
<dt><code>EPIPE</code></dt>
</dl>
</dd>
<dt><code>strerror(errno)</code></dt>
<dd><p>Return a string that describes the error <code>errno</code>.
</p>
</dd>
<dt><code>gc()</code></dt>
<dd><p>Manually invoke the cycle removal algorithm. The cycle removal
algorithm is automatically started when needed, so this function is
useful in case of specific memory constraints or for testing.
</p>
</dd>
<dt><code>getenv(name)</code></dt>
<dd><p>Return the value of the environment variable <code>name</code> or
<code>undefined</code> if it is not defined.
</p>
</dd>
<dt><code>setenv(name, value)</code></dt>
<dd><p>Set the value of the environment variable <code>name</code> to the string
<code>value</code>.
</p>
</dd>
<dt><code>unsetenv(name)</code></dt>
<dd><p>Delete the environment variable <code>name</code>.
</p>
</dd>
<dt><code>getenviron()</code></dt>
<dd><p>Return an object containing the environment variables as key-value pairs.
</p>
</dd>
<dt><code>urlGet(url, options = undefined)</code></dt>
<dd>
<p>Download <code>url</code> using the <samp>curl</samp> command line
utility. <code>options</code> is an optional object containing the following
optional properties:
</p>
<dl compact="compact">
<dt><code>binary</code></dt>
<dd><p>Boolean (default = false). If true, the response is an ArrayBuffer
instead of a string. When a string is returned, the data is assumed
to be UTF-8 encoded.
</p>
</dd>
<dt><code>full</code></dt>
<dd>
<p>Boolean (default = false). If true, return the an object contains
the properties <code>response</code> (response content),
<code>responseHeaders</code> (headers separated by CRLF), <code>status</code>
(status code). <code>response</code> is <code>null</code> is case of protocol or
network error. If <code>full</code> is false, only the response is
returned if the status is between 200 and 299. Otherwise <code>null</code>
is returned.
</p>
</dd>
</dl>
</dd>
<dt><code>parseExtJSON(str)</code></dt>
<dd>
<p>Parse <code>str</code> using a superset of <code>JSON.parse</code>. The
following extensions are accepted:
</p>
<ul>
<li> Single line and multiline comments
</li><li> unquoted properties (ASCII-only Javascript identifiers)
</li><li> trailing comma in array and object definitions
</li><li> single quoted strings
</li><li> <code>\f</code> and <code>\v</code> are accepted as space characters
</li><li> leading plus in numbers
</li><li> octal (<code>0o</code> prefix) and hexadecimal (<code>0x</code> prefix) numbers
</li></ul>
</dd>
</dl>
<p>FILE prototype:
</p>
<dl compact="compact">
<dt><code>close()</code></dt>
<dd><p>Close the file. Return 0 if OK or <code>-errno</code> in case of I/O error.
</p></dd>
<dt><code>puts(str)</code></dt>
<dd><p>Outputs the string with the UTF-8 encoding.
</p></dd>
<dt><code>printf(fmt, ...args)</code></dt>
<dd><p>Formatted printf.
</p>
<p>The same formats as the standard C library <code>printf</code> are
supported. Integer format types (e.g. <code>%d</code>) truncate the Numbers
or BigInts to 32 bits. Use the <code>l</code> modifier (e.g. <code>%ld</code>) to
truncate to 64 bits.
</p>
</dd>
<dt><code>flush()</code></dt>
<dd><p>Flush the buffered file.
</p></dd>
<dt><code>seek(offset, whence)</code></dt>
<dd><p>Seek to a give file position (whence is
<code>std.SEEK_*</code>). <code>offset</code> can be a number or a bigint. Return
0 if OK or <code>-errno</code> in case of I/O error.
</p></dd>
<dt><code>tell()</code></dt>
<dd><p>Return the current file position.
</p></dd>
<dt><code>tello()</code></dt>
<dd><p>Return the current file position as a bigint.
</p></dd>
<dt><code>eof()</code></dt>
<dd><p>Return true if end of file.
</p></dd>
<dt><code>fileno()</code></dt>
<dd><p>Return the associated OS handle.
</p></dd>
<dt><code>error()</code></dt>
<dd><p>Return true if there was an error.
</p></dd>
<dt><code>clearerr()</code></dt>
<dd><p>Clear the error indication.
</p>
</dd>
<dt><code>read(buffer, position, length)</code></dt>
<dd><p>Read <code>length</code> bytes from the file to the ArrayBuffer <code>buffer</code> at byte
position <code>position</code> (wrapper to the libc <code>fread</code>).
</p>
</dd>
<dt><code>write(buffer, position, length)</code></dt>
<dd><p>Write <code>length</code> bytes to the file from the ArrayBuffer <code>buffer</code> at byte
position <code>position</code> (wrapper to the libc <code>fwrite</code>).
</p>
</dd>
<dt><code>getline()</code></dt>
<dd><p>Return the next line from the file, assuming UTF-8 encoding, excluding
the trailing line feed.
</p>
</dd>
<dt><code>readAsString(max_size = undefined)</code></dt>
<dd><p>Read <code>max_size</code> bytes from the file and return them as a string
assuming UTF-8 encoding. If <code>max_size</code> is not present, the file
is read up its end.
</p>
</dd>
<dt><code>getByte()</code></dt>
<dd><p>Return the next byte from the file. Return -1 if the end of file is reached.
</p>
</dd>
<dt><code>putByte(c)</code></dt>
<dd><p>Write one byte to the file.
</p></dd>
</dl>
<a name="os-module"></a>
<h4 class="subsection">3.3.3 <code>os</code> module</h4>
<p>The <code>os</code> module provides Operating System specific functions:
</p>
<ul>
<li> low level file access
</li><li> signals
</li><li> timers
</li><li> asynchronous I/O
</li><li> workers (threads)
</li></ul>
<p>The OS functions usually return 0 if OK or an OS specific negative
error code.
</p>
<p>Available exports:
</p>
<dl compact="compact">
<dt><code>open(filename, flags, mode = 0o666)</code></dt>
<dd><p>Open a file. Return a handle or < 0 if error.
</p>
</dd>
<dt><code>O_RDONLY</code></dt>
<dt><code>O_WRONLY</code></dt>
<dt><code>O_RDWR</code></dt>
<dt><code>O_APPEND</code></dt>
<dt><code>O_CREAT</code></dt>
<dt><code>O_EXCL</code></dt>
<dt><code>O_TRUNC</code></dt>
<dd><p>POSIX open flags.
</p>
</dd>
<dt><code>O_TEXT</code></dt>
<dd><p>(Windows specific). Open the file in text mode. The default is binary mode.
</p>
</dd>
<dt><code>close(fd)</code></dt>
<dd><p>Close the file handle <code>fd</code>.
</p>
</dd>
<dt><code>seek(fd, offset, whence)</code></dt>
<dd><p>Seek in the file. Use <code>std.SEEK_*</code> for
<code>whence</code>. <code>offset</code> is either a number or a bigint. If
<code>offset</code> is a bigint, a bigint is returned too.
</p>
</dd>
<dt><code>read(fd, buffer, offset, length)</code></dt>
<dd><p>Read <code>length</code> bytes from the file handle <code>fd</code> to the
ArrayBuffer <code>buffer</code> at byte position <code>offset</code>.
Return the number of read bytes or < 0 if error.
</p>
</dd>
<dt><code>write(fd, buffer, offset, length)</code></dt>
<dd><p>Write <code>length</code> bytes to the file handle <code>fd</code> from the
ArrayBuffer <code>buffer</code> at byte position <code>offset</code>.
Return the number of written bytes or < 0 if error.
</p>
</dd>
<dt><code>isatty(fd)</code></dt>
<dd><p>Return <code>true</code> is <code>fd</code> is a TTY (terminal) handle.
</p>
</dd>
<dt><code>ttyGetWinSize(fd)</code></dt>
<dd><p>Return the TTY size as <code>[width, height]</code> or <code>null</code> if not available.
</p>
</dd>
<dt><code>ttySetRaw(fd)</code></dt>
<dd><p>Set the TTY in raw mode.
</p>
</dd>
<dt><code>remove(filename)</code></dt>
<dd><p>Remove a file. Return 0 if OK or <code>-errno</code>.
</p>
</dd>
<dt><code>rename(oldname, newname)</code></dt>
<dd><p>Rename a file. Return 0 if OK or <code>-errno</code>.
</p>
</dd>
<dt><code>realpath(path)</code></dt>
<dd><p>Return <code>[str, err]</code> where <code>str</code> is the canonicalized absolute
pathname of <code>path</code> and <code>err</code> the error code.
</p>
</dd>
<dt><code>getcwd()</code></dt>
<dd><p>Return <code>[str, err]</code> where <code>str</code> is the current working directory
and <code>err</code> the error code.
</p>
</dd>
<dt><code>chdir(path)</code></dt>
<dd><p>Change the current directory. Return 0 if OK or <code>-errno</code>.
</p>
</dd>
<dt><code>mkdir(path, mode = 0o777)</code></dt>
<dd><p>Create a directory at <code>path</code>. Return 0 if OK or <code>-errno</code>.
</p>
</dd>
<dt><code>stat(path)</code></dt>
<dt><code>lstat(path)</code></dt>
<dd>
<p>Return <code>[obj, err]</code> where <code>obj</code> is an object containing the
file status of <code>path</code>. <code>err</code> is the error code. The
following fields are defined in <code>obj</code>: dev, ino, mode, nlink,
uid, gid, rdev, size, blocks, atime, mtime, ctime. The times are
specified in milliseconds since 1970. <code>lstat()</code> is the same as
<code>stat()</code> excepts that it returns information about the link
itself.
</p>
</dd>
<dt><code>S_IFMT</code></dt>
<dt><code>S_IFIFO</code></dt>
<dt><code>S_IFCHR</code></dt>
<dt><code>S_IFDIR</code></dt>
<dt><code>S_IFBLK</code></dt>
<dt><code>S_IFREG</code></dt>
<dt><code>S_IFSOCK</code></dt>
<dt><code>S_IFLNK</code></dt>
<dt><code>S_ISGID</code></dt>
<dt><code>S_ISUID</code></dt>
<dd><p>Constants to interpret the <code>mode</code> property returned by
<code>stat()</code>. They have the same value as in the C system header
<samp>sys/stat.h</samp>.
</p>
</dd>
<dt><code>utimes(path, atime, mtime)</code></dt>
<dd><p>Change the access and modification times of the file <code>path</code>. The
times are specified in milliseconds since 1970. Return 0 if OK or <code>-errno</code>.
</p>
</dd>
<dt><code>symlink(target, linkpath)</code></dt>
<dd><p>Create a link at <code>linkpath</code> containing the string <code>target</code>. Return 0 if OK or <code>-errno</code>.
</p>
</dd>
<dt><code>readlink(path)</code></dt>
<dd><p>Return <code>[str, err]</code> where <code>str</code> is the link target and <code>err</code>
the error code.
</p>
</dd>
<dt><code>readdir(path)</code></dt>
<dd><p>Return <code>[array, err]</code> where <code>array</code> is an array of strings
containing the filenames of the directory <code>path</code>. <code>err</code> is
the error code.
</p>
</dd>
<dt><code>setReadHandler(fd, func)</code></dt>
<dd><p>Add a read handler to the file handle <code>fd</code>. <code>func</code> is called
each time there is data pending for <code>fd</code>. A single read handler
per file handle is supported. Use <code>func = null</code> to remove the
handler.
</p>
</dd>
<dt><code>setWriteHandler(fd, func)</code></dt>
<dd><p>Add a write handler to the file handle <code>fd</code>. <code>func</code> is
called each time data can be written to <code>fd</code>. A single write
handler per file handle is supported. Use <code>func = null</code> to remove
the handler.
</p>
</dd>
<dt><code>signal(signal, func)</code></dt>
<dd><p>Call the function <code>func</code> when the signal <code>signal</code>
happens. Only a single handler per signal number is supported. Use
<code>null</code> to set the default handler or <code>undefined</code> to ignore
the signal. Signal handlers can only be defined in the main thread.
</p>
</dd>
<dt><code>SIGINT</code></dt>
<dt><code>SIGABRT</code></dt>
<dt><code>SIGFPE</code></dt>
<dt><code>SIGILL</code></dt>
<dt><code>SIGSEGV</code></dt>
<dt><code>SIGTERM</code></dt>
<dd><p>POSIX signal numbers.
</p>
</dd>
<dt><code>kill(pid, sig)</code></dt>
<dd><p>Send the signal <code>sig</code> to the process <code>pid</code>.
</p>
</dd>
<dt><code>exec(args[, options])</code></dt>
<dd><p>Execute a process with the arguments <code>args</code>. <code>options</code> is an
object containing optional parameters:
</p>
<dl compact="compact">
<dt><code>block</code></dt>
<dd><p>Boolean (default = true). If true, wait until the process is
terminated. In this case, <code>exec</code> return the exit code if positive
or the negated signal number if the process was interrupted by a
signal. If false, do not block and return the process id of the child.
</p>
</dd>
<dt><code>usePath</code></dt>
<dd><p>Boolean (default = true). If true, the file is searched in the
<code>PATH</code> environment variable.
</p>
</dd>
<dt><code>file</code></dt>
<dd><p>String (default = <code>args[0]</code>). Set the file to be executed.
</p>
</dd>
<dt><code>cwd</code></dt>
<dd><p>String. If present, set the working directory of the new process.
</p>
</dd>
<dt><code>stdin</code></dt>
<dt><code>stdout</code></dt>
<dt><code>stderr</code></dt>
<dd><p>If present, set the handle in the child for stdin, stdout or stderr.
</p>
</dd>
<dt><code>env</code></dt>
<dd><p>Object. If present, set the process environment from the object
key-value pairs. Otherwise use the same environment as the current
process.
</p>
</dd>
<dt><code>uid</code></dt>
<dd><p>Integer. If present, the process uid with <code>setuid</code>.
</p>
</dd>
<dt><code>gid</code></dt>
<dd><p>Integer. If present, the process gid with <code>setgid</code>.
</p>
</dd>
</dl>
</dd>
<dt><code>waitpid(pid, options)</code></dt>
<dd><p><code>waitpid</code> Unix system call. Return the array <code>[ret,
status]</code>. <code>ret</code> contains <code>-errno</code> in case of error.
</p>
</dd>
<dt><code>WNOHANG</code></dt>
<dd><p>Constant for the <code>options</code> argument of <code>waitpid</code>.
</p>
</dd>
<dt><code>dup(fd)</code></dt>
<dd><p><code>dup</code> Unix system call.
</p>
</dd>
<dt><code>dup2(oldfd, newfd)</code></dt>
<dd><p><code>dup2</code> Unix system call.
</p>
</dd>
<dt><code>pipe()</code></dt>
<dd><p><code>pipe</code> Unix system call. Return two handles as <code>[read_fd,
write_fd]</code> or null in case of error.
</p>
</dd>
<dt><code>sleep(delay_ms)</code></dt>
<dd><p>Sleep during <code>delay_ms</code> milliseconds.
</p>
</dd>
<dt><code>setTimeout(func, delay)</code></dt>
<dd><p>Call the function <code>func</code> after <code>delay</code> ms. Return a handle
to the timer.