1/* Copyright JS Foundation and other contributors, http://js.foundation
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16#ifndef JERRYSCRIPT_CORE_H
17#define JERRYSCRIPT_CORE_H
18
19#include <stdbool.h>
20#include <stddef.h>
21#include <stdint.h>
22
23#include "jerryscript-compiler.h"
24
25#ifdef __cplusplus
26extern "C"
27{
28#endif /* __cplusplus */
29
30/** \addtogroup jerry Jerry engine interface
31 * @{
32 */
33
34/**
35 * Major version of JerryScript API.
36 */
37#define JERRY_API_MAJOR_VERSION 2
38
39/**
40 * Minor version of JerryScript API.
41 */
42#define JERRY_API_MINOR_VERSION 4
43
44/**
45 * Patch version of JerryScript API.
46 */
47#define JERRY_API_PATCH_VERSION 0
48
49/**
50 * JerryScript init flags.
51 */
52typedef enum
53{
54 JERRY_INIT_EMPTY = (0u), /**< empty flag set */
55 JERRY_INIT_SHOW_OPCODES = (1u << 0), /**< dump byte-code to log after parse */
56 JERRY_INIT_SHOW_REGEXP_OPCODES = (1u << 1), /**< dump regexp byte-code to log after compilation */
57 JERRY_INIT_MEM_STATS = (1u << 2), /**< dump memory statistics */
58 JERRY_INIT_MEM_STATS_SEPARATE = (1u << 3), /**< deprecated, an unused placeholder now */
59 JERRY_INIT_DEBUGGER = (1u << 4), /**< deprecated, an unused placeholder now */
60} jerry_init_flag_t;
61
62/**
63 * JerryScript API Error object types.
64 */
65typedef enum
66{
67 JERRY_ERROR_NONE = 0, /**< No Error */
68
69 JERRY_ERROR_COMMON, /**< Error */
70 JERRY_ERROR_EVAL, /**< EvalError */
71 JERRY_ERROR_RANGE, /**< RangeError */
72 JERRY_ERROR_REFERENCE, /**< ReferenceError */
73 JERRY_ERROR_SYNTAX, /**< SyntaxError */
74 JERRY_ERROR_TYPE, /**< TypeError */
75 JERRY_ERROR_URI /**< URIError */
76} jerry_error_t;
77
78/**
79 * JerryScript feature types.
80 */
81typedef enum
82{
83 JERRY_FEATURE_CPOINTER_32_BIT, /**< 32 bit compressed pointers */
84 JERRY_FEATURE_ERROR_MESSAGES, /**< error messages */
85 JERRY_FEATURE_JS_PARSER, /**< js-parser */
86 JERRY_FEATURE_MEM_STATS, /**< memory statistics */
87 JERRY_FEATURE_PARSER_DUMP, /**< parser byte-code dumps */
88 JERRY_FEATURE_REGEXP_DUMP, /**< regexp byte-code dumps */
89 JERRY_FEATURE_SNAPSHOT_SAVE, /**< saving snapshot files */
90 JERRY_FEATURE_SNAPSHOT_EXEC, /**< executing snapshot files */
91 JERRY_FEATURE_DEBUGGER, /**< debugging */
92 JERRY_FEATURE_VM_EXEC_STOP, /**< stopping ECMAScript execution */
93 JERRY_FEATURE_JSON, /**< JSON support */
94 JERRY_FEATURE_PROMISE, /**< promise support */
95 JERRY_FEATURE_TYPEDARRAY, /**< Typedarray support */
96 JERRY_FEATURE_DATE, /**< Date support */
97 JERRY_FEATURE_REGEXP, /**< Regexp support */
98 JERRY_FEATURE_LINE_INFO, /**< line info available */
99 JERRY_FEATURE_LOGGING, /**< logging */
100 JERRY_FEATURE_SYMBOL, /**< symbol support */
101 JERRY_FEATURE_DATAVIEW, /**< DataView support */
102 JERRY_FEATURE_PROXY, /**< Proxy support */
103 JERRY_FEATURE_MAP, /**< Map support */
104 JERRY_FEATURE_SET, /**< Set support */
105 JERRY_FEATURE_WEAKMAP, /**< WeakMap support */
106 JERRY_FEATURE_WEAKSET, /**< WeakSet support */
107 JERRY_FEATURE_BIGINT, /**< BigInt support */
108 JERRY_FEATURE_REALM, /**< realm support */
109 JERRY_FEATURE__COUNT /**< number of features. NOTE: must be at the end of the list */
110} jerry_feature_t;
111
112/**
113 * Option flags for jerry_parse and jerry_parse_function functions.
114 */
115typedef enum
116{
117 JERRY_PARSE_NO_OPTS = 0, /**< no options passed */
118 JERRY_PARSE_STRICT_MODE = (1 << 0), /**< enable strict mode */
119 JERRY_PARSE_MODULE = (1 << 1) /**< parse source as an ECMAScript module */
120} jerry_parse_opts_t;
121
122/**
123 * GC operational modes.
124 */
125typedef enum
126{
127 JERRY_GC_PRESSURE_LOW, /**< free unused objects, but keep memory
128 * allocated for performance improvements
129 * such as property hash tables for large objects */
130 JERRY_GC_PRESSURE_HIGH /**< free as much memory as possible */
131} jerry_gc_mode_t;
132
133/**
134 * Jerry regexp flags.
135 */
136typedef enum
137{
138 JERRY_REGEXP_FLAG_GLOBAL = (1u << 1), /**< Globally scan string */
139 JERRY_REGEXP_FLAG_IGNORE_CASE = (1u << 2), /**< Ignore case */
140 JERRY_REGEXP_FLAG_MULTILINE = (1u << 3), /**< Multiline string scan */
141 JERRY_REGEXP_FLAG_STICKY = (1u << 4), /**< ECMAScript v11, 21.2.5.14 */
142 JERRY_REGEXP_FLAG_UNICODE = (1u << 5), /**< ECMAScript v11, 21.2.5.17 */
143 JERRY_REGEXP_FLAG_DOTALL = (1u << 6) /**< ECMAScript v11, 21.2.5.3 */
144} jerry_regexp_flags_t;
145
146/**
147 * Character type of JerryScript.
148 */
149typedef uint8_t jerry_char_t;
150
151/**
152 * Size type of JerryScript.
153 */
154typedef uint32_t jerry_size_t;
155
156/**
157 * Length type of JerryScript.
158 */
159typedef uint32_t jerry_length_t;
160
161/**
162 * Description of a JerryScript value.
163 */
164typedef uint32_t jerry_value_t;
165
166/**
167 * Description of ECMA property descriptor.
168 */
169typedef struct
170{
171 /** Is [[Value]] defined? */
172 bool is_value_defined;
173
174 /** Is [[Get]] defined? */
175 bool is_get_defined;
176
177 /** Is [[Set]] defined? */
178 bool is_set_defined;
179
180 /** Is [[Writable]] defined? */
181 bool is_writable_defined;
182
183 /** [[Writable]] */
184 bool is_writable;
185
186 /** Is [[Enumerable]] defined? */
187 bool is_enumerable_defined;
188
189 /** [[Enumerable]] */
190 bool is_enumerable;
191
192 /** Is [[Configurable]] defined? */
193 bool is_configurable_defined;
194
195 /** [[Configurable]] */
196 bool is_configurable;
197
198 /** [[Value]] */
199 jerry_value_t value;
200
201 /** [[Get]] */
202 jerry_value_t getter;
203
204 /** [[Set]] */
205 jerry_value_t setter;
206} jerry_property_descriptor_t;
207
208/**
209 * Description of JerryScript heap memory stats.
210 * It is for memory profiling.
211 */
212typedef struct
213{
214 size_t version; /**< the version of the stats struct */
215 size_t size; /**< heap total size */
216 size_t allocated_bytes; /**< currently allocated bytes */
217 size_t peak_allocated_bytes; /**< peak allocated bytes */
218 size_t reserved[4]; /**< padding for future extensions */
219} jerry_heap_stats_t;
220
221/**
222 * Type of an external function handler.
223 */
224typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj,
225 const jerry_value_t this_val,
226 const jerry_value_t args_p[],
227 const jerry_length_t args_count);
228
229/**
230 * Native free callback of an object.
231 */
232typedef void (*jerry_object_native_free_callback_t) (void *native_p);
233
234/**
235 * Decorator callback for Error objects. The decorator can create
236 * or update any properties of the newly created Error object.
237 */
238typedef void (*jerry_error_object_created_callback_t) (const jerry_value_t error_object, void *user_p);
239
240/**
241 * Callback which tells whether the ECMAScript execution should be stopped.
242 *
243 * As long as the function returns with undefined the execution continues.
244 * When a non-undefined value is returned the execution stops and the value
245 * is thrown by the engine (if the error flag is not set for the returned
246 * value the engine automatically sets it).
247 *
248 * Note: if the function returns with a non-undefined value it
249 * must return with the same value for future calls.
250 */
251typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p);
252
253/**
254 * Function type applied for each data property of an object.
255 */
256typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name,
257 const jerry_value_t property_value,
258 void *user_data_p);
259/**
260 * Function type applied for each object in the engine.
261 */
262typedef bool (*jerry_objects_foreach_t) (const jerry_value_t object,
263 void *user_data_p);
264
265/**
266 * Function type applied for each matching object in the engine.
267 */
268typedef bool (*jerry_objects_foreach_by_native_info_t) (const jerry_value_t object,
269 void *object_data_p,
270 void *user_data_p);
271
272/**
273 * User context item manager
274 */
275typedef struct
276{
277 /**
278 * Callback responsible for initializing a context item, or NULL to zero out the memory. This is called lazily, the
279 * first time jerry_get_context_data () is called with this manager.
280 *
281 * @param [in] data The buffer that JerryScript allocated for the manager. The buffer is zeroed out. The size is
282 * determined by the bytes_needed field. The buffer is kept alive until jerry_cleanup () is called.
283 */
284 void (*init_cb) (void *data);
285
286 /**
287 * Callback responsible for deinitializing a context item, or NULL. This is called as part of jerry_cleanup (),
288 * right *before* the VM has been cleaned up. This is a good place to release strong references to jerry_value_t's
289 * that the manager may be holding.
290 * Note: because the VM has not been fully cleaned up yet, jerry_object_native_info_t free_cb's can still get called
291 * *after* all deinit_cb's have been run. See finalize_cb for a callback that is guaranteed to run *after* all
292 * free_cb's have been run.
293 *
294 * @param [in] data The buffer that JerryScript allocated for the manager.
295 */
296 void (*deinit_cb) (void *data);
297
298 /**
299 * Callback responsible for finalizing a context item, or NULL. This is called as part of jerry_cleanup (),
300 * right *after* the VM has been cleaned up and destroyed and jerry_... APIs cannot be called any more. At this point,
301 * all values in the VM have been cleaned up. This is a good place to clean up native state that can only be cleaned
302 * up at the very end when there are no more VM values around that may need to access that state.
303 *
304 * @param [in] data The buffer that JerryScript allocated for the manager. After returning from this callback,
305 * the data pointer may no longer be used.
306 */
307 void (*finalize_cb) (void *data);
308
309 /**
310 * Number of bytes to allocate for this manager. This is the size of the buffer that JerryScript will allocate on
311 * behalf of the manager. The pointer to this buffer is passed into init_cb, deinit_cb and finalize_cb. It is also
312 * returned from the jerry_get_context_data () API.
313 */
314 size_t bytes_needed;
315} jerry_context_data_manager_t;
316
317/**
318 * Function type for allocating buffer for JerryScript context.
319 */
320typedef void *(*jerry_context_alloc_t) (size_t size, void *cb_data_p);
321
322/**
323 * Type information of a native pointer.
324 */
325typedef struct
326{
327 jerry_object_native_free_callback_t free_cb; /**< the free callback of the native pointer */
328} jerry_object_native_info_t;
329
330/**
331 * An opaque declaration of the JerryScript context structure.
332 */
333typedef struct jerry_context_t jerry_context_t;
334
335/**
336 * Enum that contains the supported binary operation types
337 */
338typedef enum
339{
340 JERRY_BIN_OP_EQUAL = 0u, /**< equal comparison (==) */
341 JERRY_BIN_OP_STRICT_EQUAL, /**< strict equal comparison (===) */
342 JERRY_BIN_OP_LESS, /**< less relation (<) */
343 JERRY_BIN_OP_LESS_EQUAL, /**< less or equal relation (<=) */
344 JERRY_BIN_OP_GREATER, /**< greater relation (>) */
345 JERRY_BIN_OP_GREATER_EQUAL, /**< greater or equal relation (>=)*/
346 JERRY_BIN_OP_INSTANCEOF, /**< instanceof operation */
347 JERRY_BIN_OP_ADD, /**< addition operator (+) */
348 JERRY_BIN_OP_SUB, /**< subtraction operator (-) */
349 JERRY_BIN_OP_MUL, /**< multiplication operator (*) */
350 JERRY_BIN_OP_DIV, /**< division operator (/) */
351 JERRY_BIN_OP_REM, /**< remainder operator (%) */
352} jerry_binary_operation_t;
353
354/**
355 * General engine functions.
356 */
357void jerry_init (jerry_init_flag_t flags);
358void jerry_cleanup (void);
359void jerry_register_magic_strings (const jerry_char_t * const *ex_str_items_p,
360 uint32_t count,
361 const jerry_length_t *str_lengths_p);
362void jerry_gc (jerry_gc_mode_t mode);
363void *jerry_get_context_data (const jerry_context_data_manager_t *manager_p);
364
365bool jerry_get_memory_stats (jerry_heap_stats_t *out_stats_p);
366
367/**
368 * Parser and executor functions.
369 */
370bool jerry_run_simple (const jerry_char_t *script_source_p, size_t script_source_size, jerry_init_flag_t flags);
371jerry_value_t jerry_parse (const jerry_char_t *resource_name_p, size_t resource_name_length,
372 const jerry_char_t *source_p, size_t source_size, uint32_t parse_opts);
373jerry_value_t jerry_parse_function (const jerry_char_t *resource_name_p, size_t resource_name_length,
374 const jerry_char_t *arg_list_p, size_t arg_list_size,
375 const jerry_char_t *source_p, size_t source_size, uint32_t parse_opts);
376jerry_value_t jerry_run (const jerry_value_t func_val);
377jerry_value_t jerry_eval (const jerry_char_t *source_p, size_t source_size, uint32_t parse_opts);
378
379jerry_value_t jerry_run_all_enqueued_jobs (void);
380
381/**
382 * Get the global context.
383 */
384jerry_value_t jerry_get_global_object (void);
385
386/**
387 * Checker functions of 'jerry_value_t'.
388 */
389bool jerry_value_is_abort (const jerry_value_t value);
390bool jerry_value_is_array (const jerry_value_t value);
391bool jerry_value_is_boolean (const jerry_value_t value);
392bool jerry_value_is_constructor (const jerry_value_t value);
393bool jerry_value_is_error (const jerry_value_t value);
394bool jerry_value_is_function (const jerry_value_t value);
395bool jerry_value_is_async_function (const jerry_value_t value);
396bool jerry_value_is_number (const jerry_value_t value);
397bool jerry_value_is_null (const jerry_value_t value);
398bool jerry_value_is_object (const jerry_value_t value);
399bool jerry_value_is_promise (const jerry_value_t value);
400bool jerry_value_is_proxy (const jerry_value_t value);
401bool jerry_value_is_string (const jerry_value_t value);
402bool jerry_value_is_symbol (const jerry_value_t value);
403bool jerry_value_is_bigint (const jerry_value_t value);
404bool jerry_value_is_undefined (const jerry_value_t value);
405
406/**
407 * JerryScript API value type information.
408 */
409typedef enum
410{
411 JERRY_TYPE_NONE = 0u, /**< no type information */
412 JERRY_TYPE_UNDEFINED, /**< undefined type */
413 JERRY_TYPE_NULL, /**< null type */
414 JERRY_TYPE_BOOLEAN, /**< boolean type */
415 JERRY_TYPE_NUMBER, /**< number type */
416 JERRY_TYPE_STRING, /**< string type */
417 JERRY_TYPE_OBJECT, /**< object type */
418 JERRY_TYPE_FUNCTION, /**< function type */
419 JERRY_TYPE_ERROR, /**< error/abort type */
420 JERRY_TYPE_SYMBOL, /**< symbol type */
421 JERRY_TYPE_BIGINT, /**< bigint type */
422} jerry_type_t;
423
424/**
425 * JerryScript object type information.
426 */
427typedef enum
428{
429 JERRY_OBJECT_TYPE_NONE = 0u, /**< Non object type */
430 JERRY_OBJECT_TYPE_GENERIC, /**< Generic JavaScript object without any internal property */
431 JERRY_OBJECT_TYPE_ARRAY, /**< Array object */
432 JERRY_OBJECT_TYPE_PROXY, /**< Proxy object */
433 JERRY_OBJECT_TYPE_FUNCTION, /**< Function object (see jerry_function_get_type) */
434 JERRY_OBJECT_TYPE_TYPEDARRAY, /**< %TypedArray% object (see jerry_get_typedarray_type) */
435 JERRY_OBJECT_TYPE_ITERATOR, /**< Iterator object (see jerry_iterator_get_type) */
436 JERRY_OBJECT_TYPE_CONTAINER, /**< Container object (see jerry_container_get_type) */
437
438 JERRY_OBJECT_TYPE_ARGUMENTS, /**< Arguments object */
439 JERRY_OBJECT_TYPE_BOOLEAN, /**< Boolean object */
440 JERRY_OBJECT_TYPE_DATE, /**< Date object */
441 JERRY_OBJECT_TYPE_NUMBER, /**< Number object */
442 JERRY_OBJECT_TYPE_REGEXP, /**< RegExp object */
443 JERRY_OBJECT_TYPE_STRING, /**< String object */
444 JERRY_OBJECT_TYPE_SYMBOL, /**< Symbol object */
445 JERRY_OBJECT_TYPE_GENERATOR, /**< Generator object */
446 JERRY_OBJECT_TYPE_BIGINT, /**< BigInt object */
447} jerry_object_type_t;
448
449/**
450 * JerryScript function object type information.
451 */
452typedef enum
453{
454 JERRY_FUNCTION_TYPE_NONE = 0u, /**< Non function type */
455 JERRY_FUNCTION_TYPE_GENERIC, /**< Generic JavaScript function */
456 JERRY_FUNCTION_TYPE_ACCESSOR, /**< Accessor function */
457 JERRY_FUNCTION_TYPE_BOUND, /**< Bound function */
458 JERRY_FUNCTION_TYPE_ARROW, /**< Arrow fuction */
459 JERRY_FUNCTION_TYPE_GENERATOR, /**< Generator function */
460} jerry_function_type_t;
461
462/**
463 * JerryScript iterator object type information.
464 */
465typedef enum
466{
467 JERRY_ITERATOR_TYPE_NONE = 0u, /**< Non iterator type */
468 JERRY_ITERATOR_TYPE_ARRAY, /**< Array iterator */
469 JERRY_ITERATOR_TYPE_STRING, /**< String iterator */
470 JERRY_ITERATOR_TYPE_MAP, /**< Map iterator */
471 JERRY_ITERATOR_TYPE_SET, /**< Set iterator */
472} jerry_iterator_type_t;
473
474/**
475 * JerryScript object property filter options.
476 */
477typedef enum
478{
479 JERRY_PROPERTY_FILTER_ALL = 0, /**< List all property keys independently
480 * from key type or property value attributes
481 * (equivalent to Reflect.ownKeys call) */
482 JERRY_PROPERTY_FILTER_TRAVERSE_PROTOTYPE_CHAIN = (1 << 0), /**< Include keys from the objects's
483 * prototype chain as well */
484 JERRY_PROPERTY_FILTER_EXLCUDE_NON_CONFIGURABLE = (1 << 1), /**< Exclude property key if
485 * the property is non-configurable */
486 JERRY_PROPERTY_FILTER_EXLCUDE_NON_ENUMERABLE = (1 << 2), /**< Exclude property key if
487 * the property is non-enumerable */
488 JERRY_PROPERTY_FILTER_EXLCUDE_NON_WRITABLE = (1 << 3), /**< Exclude property key if
489 * the property is non-writable */
490 JERRY_PROPERTY_FILTER_EXLCUDE_STRINGS = (1 << 4), /**< Exclude property key if it is a string */
491 JERRY_PROPERTY_FILTER_EXLCUDE_SYMBOLS = (1 << 5), /**< Exclude property key if it is a symbol */
492 JERRY_PROPERTY_FILTER_EXLCUDE_INTEGER_INDICES = (1 << 6), /**< Exclude property key if it is an integer index */
493 JERRY_PROPERTY_FILTER_INTEGER_INDICES_AS_NUMBER = (1 << 7), /**< By default integer index property keys are
494 * converted to string. Enabling this flags keeps
495 * integer index property keys as numbers. */
496} jerry_property_filter_t;
497
498jerry_type_t jerry_value_get_type (const jerry_value_t value);
499jerry_object_type_t jerry_object_get_type (const jerry_value_t value);
500jerry_function_type_t jerry_function_get_type (const jerry_value_t value);
501jerry_iterator_type_t jerry_iterator_get_type (const jerry_value_t value);
502
503/**
504 * Checker function of whether the specified compile feature is enabled.
505 */
506bool jerry_is_feature_enabled (const jerry_feature_t feature);
507
508/**
509 * Binary operations
510 */
511jerry_value_t jerry_binary_operation (jerry_binary_operation_t op,
512 const jerry_value_t lhs,
513 const jerry_value_t rhs);
514
515/**
516 * Error manipulation functions.
517 */
518jerry_value_t jerry_create_abort_from_value (jerry_value_t value, bool release);
519jerry_value_t jerry_create_error_from_value (jerry_value_t value, bool release);
520jerry_value_t jerry_get_value_from_error (jerry_value_t value, bool release);
521void jerry_set_error_object_created_callback (jerry_error_object_created_callback_t callback, void *user_p);
522
523/**
524 * Error object function(s).
525 */
526jerry_error_t jerry_get_error_type (jerry_value_t value);
527
528/**
529 * Getter functions of 'jerry_value_t'.
530 */
531bool jerry_get_boolean_value (const jerry_value_t value);
532double jerry_get_number_value (const jerry_value_t value);
533
534/**
535 * Functions for string values.
536 */
537jerry_size_t jerry_get_string_size (const jerry_value_t value);
538jerry_size_t jerry_get_utf8_string_size (const jerry_value_t value);
539jerry_length_t jerry_get_string_length (const jerry_value_t value);
540jerry_length_t jerry_get_utf8_string_length (const jerry_value_t value);
541jerry_size_t jerry_string_to_char_buffer (const jerry_value_t value, jerry_char_t *buffer_p, jerry_size_t buffer_size);
542jerry_size_t jerry_string_to_utf8_char_buffer (const jerry_value_t value,
543 jerry_char_t *buffer_p,
544 jerry_size_t buffer_size);
545jerry_size_t jerry_substring_to_char_buffer (const jerry_value_t value,
546 jerry_length_t start_pos,
547 jerry_length_t end_pos,
548 jerry_char_t *buffer_p,
549 jerry_size_t buffer_size);
550jerry_size_t jerry_substring_to_utf8_char_buffer (const jerry_value_t value,
551 jerry_length_t start_pos,
552 jerry_length_t end_pos,
553 jerry_char_t *buffer_p,
554 jerry_size_t buffer_size);
555
556/**
557 * Functions for array object values.
558 */
559uint32_t jerry_get_array_length (const jerry_value_t value);
560
561/**
562 * Converters of 'jerry_value_t'.
563 */
564bool jerry_value_to_boolean (const jerry_value_t value);
565jerry_value_t jerry_value_to_number (const jerry_value_t value);
566jerry_value_t jerry_value_to_object (const jerry_value_t value);
567jerry_value_t jerry_value_to_primitive (const jerry_value_t value);
568jerry_value_t jerry_value_to_string (const jerry_value_t value);
569jerry_value_t jerry_value_to_bigint (const jerry_value_t value);
570double jerry_value_as_integer (const jerry_value_t value);
571int32_t jerry_value_as_int32 (const jerry_value_t value);
572uint32_t jerry_value_as_uint32 (const jerry_value_t value);
573
574/**
575 * Acquire types with reference counter (increase the references).
576 */
577jerry_value_t jerry_acquire_value (jerry_value_t value);
578
579/**
580 * Release the referenced values.
581 */
582void jerry_release_value (jerry_value_t value);
583
584/**
585 * Create functions of API values.
586 */
587jerry_value_t jerry_create_array (uint32_t size);
588jerry_value_t jerry_create_boolean (bool value);
589jerry_value_t jerry_create_error (jerry_error_t error_type, const jerry_char_t *message_p);
590jerry_value_t jerry_create_error_sz (jerry_error_t error_type, const jerry_char_t *message_p,
591 jerry_size_t message_size);
592jerry_value_t jerry_create_external_function (jerry_external_handler_t handler_p);
593jerry_value_t jerry_create_number (double value);
594jerry_value_t jerry_create_number_infinity (bool sign);
595jerry_value_t jerry_create_number_nan (void);
596jerry_value_t jerry_create_null (void);
597jerry_value_t jerry_create_object (void);
598jerry_value_t jerry_create_promise (void);
599jerry_value_t jerry_create_proxy (const jerry_value_t target, const jerry_value_t handler);
600jerry_value_t jerry_create_regexp (const jerry_char_t *pattern, uint16_t flags);
601jerry_value_t jerry_create_regexp_sz (const jerry_char_t *pattern, jerry_size_t pattern_size, uint16_t flags);
602jerry_value_t jerry_create_string_from_utf8 (const jerry_char_t *str_p);
603jerry_value_t jerry_create_string_sz_from_utf8 (const jerry_char_t *str_p, jerry_size_t str_size);
604jerry_value_t jerry_create_string (const jerry_char_t *str_p);
605jerry_value_t jerry_create_string_sz (const jerry_char_t *str_p, jerry_size_t str_size);
606jerry_value_t jerry_create_external_string (const jerry_char_t *str_p,
607 jerry_object_native_free_callback_t free_cb);
608jerry_value_t jerry_create_external_string_sz (const jerry_char_t *str_p, jerry_size_t str_size,
609 jerry_object_native_free_callback_t free_cb);
610jerry_value_t jerry_create_symbol (const jerry_value_t value);
611jerry_value_t jerry_create_bigint (const uint64_t *digits_p, uint32_t size, bool sign);
612jerry_value_t jerry_create_undefined (void);
613jerry_value_t jerry_create_realm (void);
614
615/**
616 * General API functions of JS objects.
617 */
618jerry_value_t jerry_has_property (const jerry_value_t obj_val, const jerry_value_t prop_name_val);
619jerry_value_t jerry_has_own_property (const jerry_value_t obj_val, const jerry_value_t prop_name_val);
620bool jerry_has_internal_property (const jerry_value_t obj_val, const jerry_value_t prop_name_val);
621bool jerry_delete_property (const jerry_value_t obj_val, const jerry_value_t prop_name_val);
622bool jerry_delete_property_by_index (const jerry_value_t obj_val, uint32_t index);
623bool jerry_delete_internal_property (const jerry_value_t obj_val, const jerry_value_t prop_name_val);
624
625jerry_value_t jerry_get_property (const jerry_value_t obj_val, const jerry_value_t prop_name_val);
626jerry_value_t jerry_get_property_by_index (const jerry_value_t obj_val, uint32_t index);
627jerry_value_t jerry_get_internal_property (const jerry_value_t obj_val, const jerry_value_t prop_name_val);
628jerry_value_t jerry_set_property (const jerry_value_t obj_val, const jerry_value_t prop_name_val,
629 const jerry_value_t value_to_set);
630jerry_value_t jerry_set_property_by_index (const jerry_value_t obj_val, uint32_t index,
631 const jerry_value_t value_to_set);
632bool jerry_set_internal_property (const jerry_value_t obj_val, const jerry_value_t prop_name_val,
633 const jerry_value_t value_to_set);
634
635void jerry_init_property_descriptor_fields (jerry_property_descriptor_t *prop_desc_p);
636jerry_value_t jerry_define_own_property (const jerry_value_t obj_val,
637 const jerry_value_t prop_name_val,
638 const jerry_property_descriptor_t *prop_desc_p);
639
640bool jerry_get_own_property_descriptor (const jerry_value_t obj_val,
641 const jerry_value_t prop_name_val,
642 jerry_property_descriptor_t *prop_desc_p);
643void jerry_free_property_descriptor_fields (const jerry_property_descriptor_t *prop_desc_p);
644
645jerry_value_t jerry_call_function (const jerry_value_t func_obj_val, const jerry_value_t this_val,
646 const jerry_value_t args_p[], jerry_size_t args_count);
647jerry_value_t jerry_construct_object (const jerry_value_t func_obj_val, const jerry_value_t args_p[],
648 jerry_size_t args_count);
649
650jerry_value_t jerry_get_object_keys (const jerry_value_t obj_val);
651jerry_value_t jerry_get_prototype (const jerry_value_t obj_val);
652jerry_value_t jerry_set_prototype (const jerry_value_t obj_val, const jerry_value_t proto_obj_val);
653
654bool jerry_get_object_native_pointer (const jerry_value_t obj_val,
655 void **out_native_pointer_p,
656 const jerry_object_native_info_t *native_pointer_info_p);
657void jerry_set_object_native_pointer (const jerry_value_t obj_val,
658 void *native_pointer_p,
659 const jerry_object_native_info_t *native_info_p);
660bool jerry_delete_object_native_pointer (const jerry_value_t obj_val,
661 const jerry_object_native_info_t *native_info_p);
662
663bool jerry_objects_foreach (jerry_objects_foreach_t foreach_p,
664 void *user_data);
665bool jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *native_info_p,
666 jerry_objects_foreach_by_native_info_t foreach_p,
667 void *user_data_p);
668
669bool jerry_foreach_object_property (const jerry_value_t obj_val, jerry_object_property_foreach_t foreach_p,
670 void *user_data_p);
671
672jerry_value_t jerry_object_get_property_names (const jerry_value_t obj_val, jerry_property_filter_t filter);
673jerry_value_t jerry_from_property_descriptor (const jerry_property_descriptor_t *src_prop_desc_p);
674jerry_value_t jerry_to_property_descriptor (jerry_value_t obj_value, jerry_property_descriptor_t *out_prop_desc_p);
675/**
676 * Promise functions.
677 */
678jerry_value_t jerry_resolve_or_reject_promise (jerry_value_t promise, jerry_value_t argument, bool is_resolve);
679
680/**
681 * Enum values representing various Promise states.
682 */
683typedef enum
684{
685 JERRY_PROMISE_STATE_NONE = 0u, /**< Invalid/Unknown state (possibly called on a non-promise object). */
686 JERRY_PROMISE_STATE_PENDING, /**< Promise is in "Pending" state. */
687 JERRY_PROMISE_STATE_FULFILLED, /**< Promise is in "Fulfilled" state. */
688 JERRY_PROMISE_STATE_REJECTED, /**< Promise is in "Rejected" state. */
689} jerry_promise_state_t;
690
691jerry_value_t jerry_get_promise_result (const jerry_value_t promise);
692jerry_promise_state_t jerry_get_promise_state (const jerry_value_t promise);
693
694/**
695 * Symbol functions.
696 */
697
698/**
699 * List of well-known symbols.
700 */
701typedef enum
702{
703 JERRY_SYMBOL_ASYNC_ITERATOR, /**< @@asyncIterator well-known symbol */
704 JERRY_SYMBOL_HAS_INSTANCE, /**< @@hasInstance well-known symbol */
705 JERRY_SYMBOL_IS_CONCAT_SPREADABLE, /**< @@isConcatSpreadable well-known symbol */
706 JERRY_SYMBOL_ITERATOR, /**< @@iterator well-known symbol */
707 JERRY_SYMBOL_MATCH, /**< @@match well-known symbol */
708 JERRY_SYMBOL_REPLACE, /**< @@replace well-known symbol */
709 JERRY_SYMBOL_SEARCH, /**< @@search well-known symbol */
710 JERRY_SYMBOL_SPECIES, /**< @@species well-known symbol */
711 JERRY_SYMBOL_SPLIT, /**< @@split well-known symbol */
712 JERRY_SYMBOL_TO_PRIMITIVE, /**< @@toPrimitive well-known symbol */
713 JERRY_SYMBOL_TO_STRING_TAG, /**< @@toStringTag well-known symbol */
714 JERRY_SYMBOL_UNSCOPABLES, /**< @@unscopables well-known symbol */
715 JERRY_SYMBOL_MATCH_ALL, /**< @@matchAll well-known symbol */
716} jerry_well_known_symbol_t;
717
718jerry_value_t jerry_get_well_known_symbol (jerry_well_known_symbol_t symbol);
719jerry_value_t jerry_get_symbol_description (const jerry_value_t symbol);
720jerry_value_t jerry_get_symbol_descriptive_string (const jerry_value_t symbol);
721
722/**
723 * Realm functions.
724 */
725jerry_value_t jerry_set_realm (jerry_value_t realm_value);
726jerry_value_t jerry_realm_get_this (jerry_value_t realm_value);
727jerry_value_t jerry_realm_set_this (jerry_value_t realm_value, jerry_value_t this_value);
728
729/**
730 * BigInt functions.
731 */
732uint32_t jerry_get_bigint_size_in_digits (jerry_value_t value);
733void jerry_get_bigint_digits (jerry_value_t value, uint64_t *digits_p, uint32_t size, bool *sign_p);
734
735/**
736 * Proxy functions.
737 */
738jerry_value_t jerry_get_proxy_target (jerry_value_t proxy_value);
739
740/**
741 * Input validator functions.
742 */
743bool jerry_is_valid_utf8_string (const jerry_char_t *utf8_buf_p, jerry_size_t buf_size);
744bool jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, jerry_size_t buf_size);
745
746/*
747 * Dynamic memory management functions.
748 */
749void *jerry_heap_alloc (size_t size);
750void jerry_heap_free (void *mem_p, size_t size);
751
752/*
753 * External context functions.
754 */
755jerry_context_t *jerry_create_context (uint32_t heap_size, jerry_context_alloc_t alloc, void *cb_data_p);
756
757/**
758 * Miscellaneous functions.
759 */
760void jerry_set_vm_exec_stop_callback (jerry_vm_exec_stop_callback_t stop_cb, void *user_p, uint32_t frequency);
761jerry_value_t jerry_get_backtrace (uint32_t max_depth);
762jerry_value_t jerry_get_backtrace_from (uint32_t max_depth, jerry_value_t ignored_function);
763jerry_value_t jerry_get_resource_name (const jerry_value_t value);
764jerry_value_t jerry_get_new_target (void);
765
766/**
767 * Array buffer components.
768 */
769bool jerry_value_is_arraybuffer (const jerry_value_t value);
770jerry_value_t jerry_create_arraybuffer (const jerry_length_t size);
771jerry_value_t jerry_create_arraybuffer_external (const jerry_length_t size,
772 uint8_t *buffer_p,
773 jerry_object_native_free_callback_t free_cb);
774jerry_length_t jerry_arraybuffer_write (const jerry_value_t value,
775 jerry_length_t offset,
776 const uint8_t *buf_p,
777 jerry_length_t buf_size);
778jerry_length_t jerry_arraybuffer_read (const jerry_value_t value,
779 jerry_length_t offset,
780 uint8_t *buf_p,
781 jerry_length_t buf_size);
782jerry_length_t jerry_get_arraybuffer_byte_length (const jerry_value_t value);
783uint8_t *jerry_get_arraybuffer_pointer (const jerry_value_t value);
784jerry_value_t jerry_is_arraybuffer_detachable (const jerry_value_t value);
785jerry_value_t jerry_detach_arraybuffer (const jerry_value_t value);
786
787/**
788 * DataView functions.
789 */
790jerry_value_t
791jerry_create_dataview (const jerry_value_t value,
792 const jerry_length_t byte_offset,
793 const jerry_length_t byte_length);
794
795bool
796jerry_value_is_dataview (const jerry_value_t value);
797
798jerry_value_t
799jerry_get_dataview_buffer (const jerry_value_t dataview,
800 jerry_length_t *byte_offset,
801 jerry_length_t *byte_length);
802
803/**
804 * TypedArray functions.
805 */
806
807/**
808 * TypedArray types.
809 */
810typedef enum
811{
812 JERRY_TYPEDARRAY_INVALID = 0,
813 JERRY_TYPEDARRAY_UINT8,
814 JERRY_TYPEDARRAY_UINT8CLAMPED,
815 JERRY_TYPEDARRAY_INT8,
816 JERRY_TYPEDARRAY_UINT16,
817 JERRY_TYPEDARRAY_INT16,
818 JERRY_TYPEDARRAY_UINT32,
819 JERRY_TYPEDARRAY_INT32,
820 JERRY_TYPEDARRAY_FLOAT32,
821 JERRY_TYPEDARRAY_FLOAT64,
822 JERRY_TYPEDARRAY_BIGINT64,
823 JERRY_TYPEDARRAY_BIGUINT64,
824} jerry_typedarray_type_t;
825
826/**
827 * Container types.
828 */
829typedef enum
830{
831 JERRY_CONTAINER_TYPE_INVALID = 0, /**< Invalid container */
832 JERRY_CONTAINER_TYPE_MAP, /**< Map type */
833 JERRY_CONTAINER_TYPE_SET, /**< Set type */
834 JERRY_CONTAINER_TYPE_WEAKMAP, /**< WeakMap type */
835 JERRY_CONTAINER_TYPE_WEAKSET, /**< WeakSet type */
836} jerry_container_type_t;
837
838bool jerry_value_is_typedarray (jerry_value_t value);
839jerry_value_t jerry_create_typedarray (jerry_typedarray_type_t type_name, jerry_length_t length);
840jerry_value_t jerry_create_typedarray_for_arraybuffer_sz (jerry_typedarray_type_t type_name,
841 const jerry_value_t arraybuffer,
842 jerry_length_t byte_offset,
843 jerry_length_t length);
844jerry_value_t jerry_create_typedarray_for_arraybuffer (jerry_typedarray_type_t type_name,
845 const jerry_value_t arraybuffer);
846jerry_typedarray_type_t jerry_get_typedarray_type (jerry_value_t value);
847jerry_length_t jerry_get_typedarray_length (jerry_value_t value);
848jerry_value_t jerry_get_typedarray_buffer (jerry_value_t value,
849 jerry_length_t *byte_offset,
850 jerry_length_t *byte_length);
851jerry_value_t jerry_json_parse (const jerry_char_t *string_p, jerry_size_t string_size);
852jerry_value_t jerry_json_stringify (const jerry_value_t object_to_stringify);
853jerry_value_t jerry_create_container (jerry_container_type_t container_type,
854 const jerry_value_t *arguments_list_p,
855 jerry_length_t arguments_list_len);
856jerry_container_type_t jerry_get_container_type (const jerry_value_t value);
857
858/**
859 * @}
860 */
861
862#ifdef __cplusplus
863}
864#endif /* __cplusplus */
865#endif /* !JERRYSCRIPT_CORE_H */
866