Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/mujs/docs/reference.html @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 <!DOCTYPE html>
2 <html>
3 <head>
4 <link href="style.css" rel="stylesheet">
5 <title>MuJS Reference</title>
6 </head>
7
8 <body>
9
10 <header>
11 <h1>MuJS Reference</h1>
12 </header>
13
14 <nav>
15 <a href="introduction.html">Introduction</a>
16 <a href="reference.html">Reference</a>
17 <a href="examples.html">Examples</a>
18 <a href="license.html">License</a>
19 <a href="http://git.ghostscript.com/?p=mujs.git;a=summary">Source</a>
20 <a href="https://bugs.ghostscript.com/">Bugs</a>
21 </nav>
22
23 <article>
24
25 <h2>Introduction</h2>
26
27 <p>
28 MuJS is a library, written in clean and simple C.
29 Being an extension library, MuJS has no notion of a main program: it only works embedded in a host client program.
30 The host program can invoke functions to execute Javascript code, read and write Javascript variables, and register C functions to be called by Javascript.
31
32 <p>
33 The MuJS distribution includes a sample host program called "mujs", which uses the MuJS library to offer a standalone Javascript interpreter for interactive or batch use.
34
35 <p>
36 This reference manual assumes that you are already familiar with the Javascript language, in particular the type system and object prototype mechanisms.
37
38 <h2>Basic Concepts</h2>
39
40 <h3>Values and Types</h3>
41
42 <p>
43 There are six basic types in Javascript: undefined, null, boolean, number, string and object.
44
45 <p>
46 Each object also has a class: object, array, function, userdata, regular expression, etc.
47
48 <p>
49 Javascript can call functions written in C provided by the host program, as well as other Javascript functions.
50
51 <p>
52 Objects with the userdata class are provided to allow arbitrary C data to be attached to Javascript objects.
53 A userdata object has a pointer to a block of raw memory, which is managed by the host.
54 Userdata values cannot be created or modified in Javascript, only through the C API.
55 This guarantees the integrity of data owned by the host program.
56
57 <p>
58 Custom properties on userdata objects can be implemented using getter and setter property accessor functions.
59
60 <p>
61 Numbers are represented using double precision floating point values.
62
63 <p>
64 Strings in the C interface are zero-terminated byte arrays in WTF-8 encoding.
65 This allows both arbitrary 16-bit values (as required by Javascript) and also
66 extended code points for the full 21-bit Unicode range.
67 These extended characters will mostly work as expected in Javascript.
68
69 <p>
70 If you have Javascript code that expects to work with UTF-16 surrogate pairs,
71 you will need to manually convert any extended characters to surrogate pairs
72 and back when passing strings between C and Javascript.
73
74 <p>
75 The U+0000 character is encoded as the two-byte sequence <C0 80>, same as in
76 modified UTF-8.
77
78 <h3>Environments</h3>
79
80 <p>
81 Each function executes within an environment which defines which variables are accessible.
82 This is a chain of all environment records in scope, with the global environment at the top.
83 Each environment record in MuJS is represented as an object with the null prototype, including the global environment object.
84
85 <p>
86 The registry is a hidden environment record which is only accessible to C.
87 This is where Javascript values and objects that should only be accessible to C functions may be stored.
88
89 <h3>Error Handling</h3>
90
91 <p>
92 All Javascript actions start from C code in the host program calling a function from the MuJS library.
93 Whenever an exception is thrown during the compilation or execution of Javascript, control returns to the host, which can take appropriate measures (such as printing an error message).
94 C code can also throw exceptions by calling functions to create an error object and return control to Javascript.
95
96 <p>
97 Internally, MuJS uses the C longjmp facility to handle errors.
98 A protected environment uses setjmp to set a recovery point.
99 The try statement in Javascript creates such a recovery point, as does calling js_dostring, js_dofile, js_ploadstring, js_ploadfile,
100 js_pcall and js_pconstruct.
101
102 <p>
103 When an error occurs or an exception is thrown from Javascript, it does a long jump to the most recent active recovery point.
104
105 <p>
106 If an error occurs outside any protected environment, MuJS first calls the panic function and then calls abort, thus exiting the host application.
107 Your panic function can avoid this exit by never returning (for example by doing a long jump to your own recovery point outside MuJS).
108
109 <h3>Garbage Collection</h3>
110
111 <p>
112 MuJS performs automatic memory management using a basic mark-and-sweep collector.
113 Collection is automatically triggered when enough allocations have accumulated.
114 You can also force a collection pass from C.
115
116 <p>
117 Userdata objects have an associated C finalizer function that is called when
118 the corresponding object is freed.
119
120 <h3>The Stack</h3>
121
122 <p>
123 MuJS uses a virtual stack to pass values to and from C.
124 Each element in this stack represents a Javascript value (null, number, string, etc).
125
126 <p>
127 Whenever Javascript calls C, the called function gets a new stack.
128 This stack initially contains the this value and any arguments passed to the function.
129 When the C function returns, the top value on the stack is passed back to the caller as the return value.
130
131 <p>
132 The stack values are accessed using stack indices.
133 Index 0 always contains the this value, and function arguments are index 1 and up.
134 Negative indices count down from the top of the stack, so index -1 is the top of the index and index -2 is the one below that.
135
136 <h2>The Application Program Interface</h2>
137
138 <h3>State</h3>
139
140 <pre>
141 typedef struct js_State js_State;
142 </pre>
143
144 <p>
145 The interpreter state is bundled up in the opaque struct js_State.
146 This state contains the value stacks, protected environments, and environment records.
147
148 <pre>
149 js_State *js_newstate(js_Alloc alloc, void *context, int flags);
150 </pre>
151
152 <p>
153 Create a new state using the allocator function and allocator context.
154 Pass NULL to use the default allocator.
155
156 <p>
157 The available flags:
158
159 <ul>
160 <li>JS_STRICT: compile and run code using ES5 strict mode.
161 </ul>
162
163 <pre>
164 void js_freestate(js_State *J);
165 </pre>
166
167 <p>
168 Destroy the state and free all dynamic memory used by the state.
169
170 <h3>Allocator</h3>
171
172 <p>
173 The interpreter uses a host provided function for all memory allocation needs:
174
175 <pre>
176 typedef void *(*js_Alloc)(void *memctx, void *ptr, int size);
177 </pre>
178
179 <p>
180 When size is zero, the allocator should behave like free and return NULL.
181 When size is not zero, the allocator should behave like realloc.
182 The allocator should return NULL if it cannot fulfill the request.
183 The default allocator uses malloc, realloc and free.
184
185 <h3>Panic</h3>
186
187 <pre>
188 typedef void (*js_Panic)(js_State *J);
189
190 js_Panic js_atpanic(js_State *J, js_Panic panic);
191 </pre>
192
193 Set a new panic function, and return the old one.
194
195 <h3>Report</h3>
196
197 <pre>
198 typedef void (*js_Report)(js_State *J, const char *message);
199
200 void js_setreport(js_State *J, js_Report report);
201 </pre>
202
203 <p>
204 Set a callback function for reporting various warnings
205 and garbage collection statistics.
206
207 <p>
208 The report function must <i>not</i> throw an exception
209 or call any other MuJS function except js_getcontext().
210
211 <h3>Garbage collection</h3>
212
213 <pre>
214 js_gc(js_State *J, int report);
215 </pre>
216
217 <p>
218 Force a garbage collection pass.
219 If the report argument is non-zero, send a summary of garbage collection statistics to
220 the report callback function.
221
222 <h3>Loading and compiling scripts</h3>
223
224 <p>
225 A script is compiled by calling js_loadstring or js_loadfile.
226 The result of a successful compilation is a function on the top of the stack.
227 This function can then be executed with js_call.
228
229 <pre>
230 void js_loadstring(js_State *J, const char *filename, const char *source);
231 void js_loadfile(js_State *J, const char *filename);
232 </pre>
233
234 <p>
235 Compile the script and push the resulting function.
236
237 <pre>
238 int js_ploadstring(js_State *J, const char *filename, const char *source);
239 int js_ploadfile(js_State *J, const char *filename);
240 </pre>
241
242 Like js_loadstring/js_loadfile but in a protected environment.
243 In case of success, return 0 with the result as a function on the stack.
244 In case of failure, return 1 with the error object on the stack.
245
246 <h3>Calling functions</h3>
247
248 <pre>
249 void js_call(js_State *J, int n);
250 </pre>
251
252 <p>
253 To call a function, you must use the following protocol:
254 1) push the function to call onto the stack,
255 2) push the this value to be used by the function,
256 3) push the arguments to the function in order,
257 4) finally, call js_call with the number of arguments pushed in step 3.
258
259 <p>
260 Pop the function, the this value, and all arguments;
261 execute the function;
262 then push the return value from the function.
263
264 <pre>
265 void js_construct(js_State *J, int n);
266 </pre>
267
268 <p>
269 The construct function implements the 'new' expression in Javascript.
270 This is similar to js_call, but without pushing a this value:
271 1) push the constructor function to call onto the stack,
272 2) push the arguments to the constructor function in order,
273 3) finally, call js_construct with the number of arguments pushed in step 2.
274
275 <pre>
276 int js_pcall(js_State *J, int n);
277 int js_pconstruct(js_State *J, int n);
278 </pre>
279
280 <p>
281 Like js_call and js_construct but in a protected environment.
282 In case of success, return 0 with the result on the stack.
283 In case of failure, return 1 with the error object on the stack.
284
285 <h3>Script helpers</h3>
286
287 <p>
288 There are two convenience functions for loading and executing code.
289
290 <pre>
291 int js_dostring(js_State *J, const char *source);
292 </pre>
293
294 <p>
295 Compile and execute the script in the zero-terminated string in source argument.
296 If any errors occur, call the report callback function and return 1.
297 Return 0 on success.
298
299 <pre>
300 int js_dofile(js_State *J, const char *filename);
301 </pre>
302
303 <p>
304 Load the script from the file with the given filename, then compile and execute it.
305 If any errors occur, call the report callback function and return 1.
306 Return 0 on success.
307
308 <h3>Protected environments</h3>
309
310 <p>
311 The js_try macro pushes a new protected environment and calls setjmp.
312 If it returns true, an error has occurred. The protected environment has been popped
313 and the error object is located on the top of the stack.
314
315 <p>
316 At the end of the code you want to run in the protected environment you must call
317 js_endtry in order to pop the protected environment. Note: you should <i>not</i> call
318 js_endtry when an error has occurred and you are in the true-branch of js_try.
319
320 <p>
321 Since the macro is a wrapper around setjmp, the usual
322 <a href="http://pubs.opengroup.org/onlinepubs/007908799/xsh/setjmp.html">restrictions</a> apply.
323 Use the following example as a guide for how to use js_try:
324
325 <pre>
326 if (js_try(J)) {
327 fprintf(stderr, "error: %s", js_trystring(J, -1, "Error"));
328 js_pop(J, 1);
329 return;
330 }
331 do_some_stuff();
332 js_endtry(J);
333 </pre>
334
335 <p>
336 Most of the time you shouldn't need to worry about protected environments.
337 The functions prefixed with 'p' (js_pcall, js_ploadstring, etc) handle setting
338 up the protected environment and return simple error codes.
339
340 <h3>Errors</h3>
341
342 <pre>
343 void js_throw(js_State *J);
344 </pre>
345
346 <p>
347 Pop the error object on the top of the stack and return control flow to the most recent protected environment.
348
349 <pre>
350 void js_newerror(js_State *J, const char *message);
351 void js_newevalerror(js_State *J, const char *message);
352 void js_newrangeerror(js_State *J, const char *message);
353 void js_newreferenceerror(js_State *J, const char *message);
354 void js_newsyntaxerror(js_State *J, const char *message);
355 void js_newtypeerror(js_State *J, const char *message);
356 void js_newurierror(js_State *J, const char *message);
357 </pre>
358
359 <p>
360 Push a new error object on the stack.
361
362 <pre>
363 void js_error(js_State *J, const char *fmt, ...);
364 void js_evalerror(js_State *J, const char *fmt, ...);
365 void js_rangeerror(js_State *J, const char *fmt, ...);
366 void js_referenceerror(js_State *J, const char *fmt, ...);
367 void js_syntaxerror(js_State *J, const char *fmt, ...);
368 void js_typeerror(js_State *J, const char *fmt, ...);
369 void js_urierror(js_State *J, const char *fmt, ...);
370 </pre>
371
372 <p>
373 Wrapper to push a new error object on the stack using a printf formatting string and call js_throw.
374
375 <h3>Stack manipulation</h3>
376
377 <pre>
378 int js_gettop(js_State *J);
379 void js_pop(js_State *J, int n);
380 void js_rot(js_State *J, int n);
381 void js_copy(js_State *J, int idx);
382 void js_remove(js_State *J, int idx);
383 void js_insert(js_State *J, int idx);
384 void js_replace(js_State* J, int idx);
385 </pre>
386
387 <h3>Comparisons and arithmetic</h3>
388
389 <pre>
390 void js_concat(js_State *J);
391 int js_compare(js_State *J, int *okay);
392 int js_equal(js_State *J);
393 int js_strictequal(js_State *J);
394 int js_instanceof(js_State *J);
395 </pre>
396
397 <p>
398 The equivalent of the '+', comparison, and instanceof operators.
399 The okay argument to js_compare is set to 0 if any of the values are NaN, otherwise it is set to 1.
400
401 </pre>
402
403 <h3>Primitive values</h3>
404
405 <pre>
406 void js_pushundefined(js_State *J);
407 void js_pushnull(js_State *J);
408 void js_pushboolean(js_State *J, int v);
409 void js_pushnumber(js_State *J, double v);
410 void js_pushstring(js_State *J, const char *v);
411 void js_pushliteral(js_State *J, const char *v);
412 </pre>
413
414 <p>
415 Push primitive values.
416 js_pushstring makes a copy of the string, so it may be freed or changed after passing it in.
417 js_pushliteral keeps a pointer to the string, so it must not be changed or freed after passing it in.
418
419 <pre>
420 int js_isdefined(js_State *J, int idx);
421 int js_isundefined(js_State *J, int idx);
422 int js_isnull(js_State *J, int idx);
423 int js_isboolean(js_State *J, int idx);
424 int js_isnumber(js_State *J, int idx);
425 int js_isstring(js_State *J, int idx);
426 int js_isprimitive(js_State *J, int idx);
427 </pre>
428
429 <p>
430 Test if a primitive value is of a given type.
431
432 <pre>
433 int js_toboolean(js_State *J, int idx);
434 double js_tonumber(js_State *J, int idx);
435 int js_tointeger(js_State *J, int idx);
436 int js_toint32(js_State *J, int idx);
437 unsigned int js_touint32(js_State *J, int idx);
438 short js_toint16(js_State *J, int idx);
439 unsigned short js_touint16(js_State *J, int idx);
440 const char *js_tostring(js_State *J, int idx);
441 </pre>
442
443 <p>
444 Convert the value at the given index into a C value.
445 If the value is an object, invoke the toString and/or valueOf methods to do the conversion.
446
447 <p>
448 The conversion may <i>change the actual value in the stack</i>!
449
450 <p>
451 There is no guarantee that the pointer returned by js_tostring will be valid after
452 the corresponding value is removed from the stack.
453
454 <p>
455 Note that the toString and valueOf methods that may be invoked by these functions
456 can throw exceptions. If you want to catch and ignore exceptions, use the following
457 functions instead. The 'error' argument is the default value that will be returned
458 if a toString/valueOf method throws an exception.
459
460 <pre>
461 int js_tryboolean(js_State *J, int idx, int error);
462 double js_trynumber(js_State *J, int idx, double error);
463 int js_tryinteger(js_State *J, int idx, int error);
464 const char *js_trystring(js_State *J, int idx, const char *error);
465 </pre>
466
467 <h3>Objects</h3>
468
469 <pre>
470 enum {
471 JS_REGEXP_G = 1,
472 JS_REGEXP_I = 2,
473 JS_REGEXP_M = 4,
474 };
475
476 void js_newobject(js_State *J);
477 void js_newarray(js_State *J);
478 void js_newboolean(js_State *J, int v);
479 void js_newnumber(js_State *J, double v);
480 void js_newstring(js_State *J, const char *v);
481 void js_newregexp(js_State *J, const char *pattern, int flags);
482 </pre>
483
484 <p>
485 Create and push objects on the stack.
486
487 <pre>
488 int js_isobject(js_State *J, int idx);
489 int js_isarray(js_State *J, int idx);
490 int js_iscallable(js_State *J, int idx);
491 int js_isregexp(js_State *J, int idx);
492 </pre>
493
494 <p>
495 Test the type and class of an object on the stack.
496
497 <h3>Properties</h3>
498
499 <p>
500 The property functions all work on an object.
501 If the stack slot referenced by the index does not contain an object, they will throw an error.
502
503 <pre>
504 enum {
505 JS_READONLY = 1,
506 JS_DONTENUM = 2,
507 JS_DONTCONF = 4,
508 };
509 </pre>
510
511 <p>
512 Property attribute bit-mask values.
513
514 <pre>
515 int js_hasproperty(js_State *J, int idx, const char *name);
516 </pre>
517
518 <p>
519 If the object has a property with the given name, return 1 and push the value of the property; otherwise return 0 and leave the stack untouched.
520
521 <pre>
522 void js_getproperty(js_State *J, int idx, const char *name);
523 </pre>
524
525 <p>
526 Push the value of the named property of the object.
527 If the object does not have the named property, push undefined instead.
528
529 <pre>
530 void js_setproperty(js_State *J, int idx, const char *name);
531 </pre>
532
533 <p>
534 Pop a value from the top of the stack and set the value of the named property of the object.
535
536 <pre>
537 void js_defproperty(js_State *J, int idx, const char *name, int atts);
538 </pre>
539
540 <p>
541 Pop a value from the top of the stack and set the value of the named property of the object.
542 Also define the property attributes.
543
544 <pre>
545 void js_defaccessor(js_State *J, int idx, const char *name, int atts);
546 </pre>
547
548 <p>
549 Define the getter and setter attributes of a property on the object.
550 Pop the two getter and setter functions from the stack.
551 Use null instead of a function object if you want to leave any of the functions unset.
552
553 <pre>
554 void js_delproperty(js_State *J, int idx, const char *name);
555 </pre>
556
557 <p>
558 Delete the named property from the object.
559
560 <h3>Array properties</h3>
561
562 <pre>
563 int js_getlength(js_State *J, int idx);
564 void js_setlength(js_State *J, int idx, int len);
565 </pre>
566
567 <p>
568 Wrappers to get and set the "length" property of an object.
569
570 <pre>
571 int js_hasindex(js_State *J, int idx, int i);
572 void js_getindex(js_State *J, int idx, int i);
573 void js_setindex(js_State *J, int idx, int i);
574 void js_delindex(js_State *J, int idx, int i);
575 </pre>
576
577 <p>
578 These array index functions functions are simple wrappers around the equivalent property functions.
579 They convert the numeric index to a string to use as the property name.
580
581 <h3>Globals</h3>
582
583 <pre>
584 void js_pushglobal(js_State *J);
585 </pre>
586
587 <p>
588 Push the object representing the global environment record.
589
590 <pre>
591 void js_getglobal(js_State *J, const char *name);
592 void js_setglobal(js_State *J, const char *name);
593 void js_defglobal(js_State *J, const char *name, int atts);
594 </pre>
595
596 <p>
597 Wrappers around js_pushglobal and js_get/set/defproperty to read and write the values of global variables.
598
599 <h3>C Functions</h3>
600
601 <pre>
602 void js_newcfunction(js_State *J, js_CFunction fun, const char *name, int length);
603 </pre>
604
605 <p>
606 Push a function object wrapping a C function pointer.
607
608 <p>
609 The length argument is the number of arguments to the function.
610 If the function is called with fewer arguments, the argument list will be padded with undefined.
611
612 <pre>
613 void js_newcconstructor(js_State *J,
614 js_CFunction fun, js_CFunction con,
615 const char *name, int length);
616 </pre>
617
618 <p>
619 Pop the object to set as the "prototype" property for the constructor function object.
620 Push a function object wrapping a C function pointer, allowing for separate function pointers for regular calls and 'new' operator calls.
621
622 <pre>
623 void js_currentfunction(js_State *J);
624 </pre>
625
626 <p>
627 Push the currently executing function object.
628
629 <h3>Userdata</h3>
630
631 <pre>
632 typedef void (*js_Finalize)(js_State *J, void *data);
633 typedef int (*js_HasProperty)(js_State *J, void *data, const char *name);
634 typedef int (*js_Put)(js_State *J, void *data, const char *name);
635 typedef int (*js_Delete)(js_State *J, void *data, const char *name);
636
637 void js_newuserdata(js_State *J, const char *tag, void *data,
638 js_Finalize finalize);
639
640 void js_newuserdatax(js_State *J, const char *tag, void *data,
641 js_HasProperty has,
642 js_Put put,
643 js_Delete delete,
644 js_Finalize finalize);
645 </pre>
646
647 <p>
648 Pop an object from the top of the stack to use as the internal prototype property for the new object.
649 Push a new userdata object wrapping a pointer to C memory.
650 The userdata object is tagged using a string, to represent the type of the C memory.
651
652 <p>
653 The finalize callback, if it is not NULL, will be called when the object is
654 freed by the garbage collector.
655
656 <p>
657 The extended function also has callback functions for overriding property accesses.
658 If these are set, they can be used to override accesses to certain properties.
659 Any property accesses that are not overridden will be handled as usual in the runtime.
660 The "HasProperty" callback should push a value and return true if it wants to
661 handle the property, otherwise it should do nothing and return false. "Put"
662 should read the top value and return true if it wants to handle the property.
663 Likewise, "Delete" should return true if it wants to handle the property.
664
665 <pre>
666 int js_isuserdata(js_State *J, int idx, const char *tag);
667 </pre>
668
669 <p>
670 Test if an object is a userdata object with the given type tag string.
671
672 <pre>
673 void *js_touserdata(js_State *J, int idx, const char *tag);
674 </pre>
675
676 <p>
677 Return the wrapped pointer from a userdata object.
678 If the object is undefined or null, return NULL.
679 If the object is not a userdata object with the given type tag string, throw a type error.
680
681 <h3>Registry</h3>
682
683 <p>
684 The registry can be used to store references to Javascript objects accessible from C,
685 but hidden from Javascript to prevent tampering.
686
687 <pre>
688 void js_getregistry(js_State *J, const char *name);
689 void js_setregistry(js_State *J, const char *name);
690 void js_delregistry(js_State *J, const char *name);
691 </pre>
692
693 <p>
694 Access properties on the hidden registry object.
695
696 <pre>
697 const char *js_ref(js_State *J);
698 </pre>
699
700 <p>
701 WIP: Pop a value from the stack and store it in the registry using a new unique property name.
702 Return the property name.
703
704 <pre>
705 void js_unref(js_State *J, const char *ref);
706 </pre>
707
708 <p>
709 WIP: Delete the reference from the registry.
710
711 </article>
712
713 <footer>
714 <a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a>
715 Copyright &copy; 2013-2017 Artifex Software Inc.
716 </footer>
717
718 </body>
719 </html>