JSCContext: JavaScriptCore GLib Reference Manual

## JSCContext JSCContext — JavaScript execution context |

## Functions

void | (*JSCExceptionHandler) ()
JSCContext * | jsc_context_new ()
JSCContext * | jsc_context_new_with_virtual_machine ()
JSCVirtualMachine * | jsc_context_get_virtual_machine ()
JSCException * | jsc_context_get_exception ()
void | jsc_context_throw ()
void | jsc_context_throw_printf ()
void | jsc_context_throw_with_name ()
void | jsc_context_throw_with_name_printf ()
void | jsc_context_throw_exception ()
void | jsc_context_clear_exception ()
void | jsc_context_push_exception_handler ()
void | jsc_context_pop_exception_handler ()
JSCContext * | jsc_context_get_current ()
JSCValue * | jsc_context_evaluate ()
JSCValue * | jsc_context_evaluate_with_source_uri ()
JSCValue * | jsc_context_evaluate_in_object ()
JSCCheckSyntaxResult | jsc_context_check_syntax ()
JSCValue * | jsc_context_get_global_object ()
void | jsc_context_set_value ()
JSCValue * | jsc_context_get_value ()
JSCClass * | jsc_context_register_class ()

## Properties

JSCVirtualMachine * | virtual-machine | Read / Write / Construct Only

## Types and Values

| JSCContext
enum | JSCCheckSyntaxMode
enum | JSCCheckSyntaxResult

## Object Hierarchy

        GObject
        ╰── JSCContext

## Description

JSCContext represents a JavaScript execution context, where all operations take place and where the values will be associated.

When a new context is created, a global object is allocated and the built-in JavaScript objects (Object, Function, String, Array) are populated. You can execute JavaScript in the context by using `jsc_context_evaluate()` or `jsc_context_evaluate_with_source_uri()`. It's also possible to register custom objects in the context with `jsc_context_register_class()`.

## Functions

### JSCExceptionHandler ()

    void
    (*JSCExceptionHandler) (JSCContext *context,
                            JSCException *exception,
                            gpointer user_data);

Function used to handle JavaScript exceptions in a JSCContext.

#### Parameters

context | a JSCContext |
exception | a JSCException |
user_data | user data |

### jsc_context_new ()

    JSCContext *
    jsc_context_new (void);

Create a new JSCContext. The context is created in a new JSCVirtualMachine. Use `jsc_context_new_with_virtual_machine()` to create a new JSCContext in an existing JSCVirtualMachine.

#### Returns

the newly created JSCContext.

[transfer full]

### jsc_context_new_with_virtual_machine ()

    JSCContext *
    jsc_context_new_with_virtual_machine (JSCVirtualMachine *vm);

Create a new JSCContext in `virtual_machine` .

#### Parameters

vm | a JSCVirtualMachine |

#### Returns

the newly created JSCContext.

[transfer full]

### jsc_context_get_virtual_machine ()

    JSCVirtualMachine *
    jsc_context_get_virtual_machine (JSCContext *context);

Get the JSCVirtualMachine where `context` was created.

#### Parameters

context | a JSCContext |

#### Returns

the JSCVirtualMachine where the JSCContext was created.

[transfer none]

### jsc_context_get_exception ()

    JSCException *
    jsc_context_get_exception (JSCContext *context);

Get the last unhandled exception thrown in `context` by API functions calls.

#### Parameters

context | a JSCContext |

#### Returns

a JSCException or `NULL` if there isn't any unhandled exception in the JSCContext.

[transfer none][nullable]

### jsc_context_throw ()

    void
    jsc_context_throw (JSCContext *context,
                       const char *error_message);

Throw an exception to `context` using the given error message. The created JSCException can be retrieved with `jsc_context_get_exception()`.

#### Parameters

context | a JSCContext |
error_message | an error message |

### jsc_context_throw_printf ()

    void
    jsc_context_throw_printf (JSCContext *context,
                              const char *format,
                              ...);

Throw an exception to `context` using the given formatted string as error message. The created JSCException can be retrieved with `jsc_context_get_exception()`.

#### Parameters

context | a JSCContext |
format | the string format |
... | the parameters to insert into the format string |

### jsc_context_throw_with_name ()

    void
    jsc_context_throw_with_name (JSCContext *context,
                                 const char *error_name,
                                 const char *error_message);

Throw an exception to `context` using the given error name and message. The created JSCException can be retrieved with `jsc_context_get_exception()`.

#### Parameters

context | a JSCContext |
error_name | the error name |
error_message | an error message |

### jsc_context_throw_with_name_printf ()

    void
    jsc_context_throw_with_name_printf (JSCContext *context,
                                        const char *error_name,
                                        const char *format,
                                        ...);

Throw an exception to `context` using the given error name and the formatted string as error message. The created JSCException can be retrieved with `jsc_context_get_exception()`.

#### Parameters

context | a JSCContext |
error_name | the error name |
format | the string format |
... | the parameters to insert into the format string |

### jsc_context_throw_exception ()

    void
    jsc_context_throw_exception (JSCContext *context,
                                 JSCException *exception);

Throw `exception` to `context` .

#### Parameters

context | a JSCContext |
exception | a JSCException |

### jsc_context_clear_exception ()

    void
    jsc_context_clear_exception (JSCContext *context);

Clear the uncaught exception in `context` if any.

#### Parameters

context | a JSCContext |

### jsc_context_push_exception_handler ()

    void
    jsc_context_push_exception_handler (JSCContext *context,
                                        JSCExceptionHandler handler,
                                        gpointer user_data,
                                        GDestroyNotify destroy_notify);

Push an exception handler in `context` . Whenever a JavaScript exception happens in the JSCContext, the given `handler` will be called. The default JSCExceptionHandler simply calls `jsc_context_throw_exception()` to throw the exception to the JSCContext. If you don't want to catch the exception, but only get notified about it, call `jsc_context_throw_exception()` in `handler` like the default one does. The last exception handler pushed is the only one used by the JSCContext, use `jsc_context_pop_exception_handler()` to remove it and set the previous one. When `handler` is removed from the context, `destroy_notify` i called with `user_data` as parameter.

#### Parameters

context | a JSCContext |
handler | a JSCExceptionHandler |
user_data | user data to pass to `handler` . | [closure]
destroy_notify | destroy notifier for `user_data` . | [nullable]

### jsc_context_pop_exception_handler ()

    void
    jsc_context_pop_exception_handler (JSCContext *context);

Remove the last JSCExceptionHandler previously pushed to `context` with `jsc_context_push_exception_handler()`.

#### Parameters

context | a JSCContext |

### jsc_context_get_current ()

    JSCContext *
    jsc_context_get_current (void);

Get the JSCContext that is currently executing a function. This should only be called within a function or method callback, otherwise `NULL` will be returned.

#### Returns

the JSCContext that is currently executing.

[transfer none][nullable]

### jsc_context_evaluate ()

    JSCValue *
    jsc_context_evaluate (JSCContext *context,
                          const char *code,
                          gssize length);

Evaluate `code` in `context` .

#### Parameters

context | a JSCContext |
code | a JavaScript script to evaluate |
length | length of `code` , or -1 if `code` is a nul-terminated string |

#### Returns

a JSCValue representing the last value generated by the script.

[transfer full]

### jsc_context_evaluate_with_source_uri ()

    JSCValue *
    jsc_context_evaluate_with_source_uri (JSCContext *context,
                                          const char *code,
                                          gssize length,
                                          const char *uri,
                                          guint line_number);

Evaluate `code` in `context` using `uri` as the source URI. The `line_number` is the starting line number in `uri` ; the value is one-based so the first line is 1. `uri` and `line_number` will be shown in exceptions and they don't affect the behavior of the script.

#### Parameters

context | a JSCContext |
code | a JavaScript script to evaluate |
length | length of `code` , or -1 if `code` is a nul-terminated string |
uri | the source URI |
line_number | the starting line number |

#### Returns

a JSCValue representing the last value generated by the script.

[transfer full]

### jsc_context_evaluate_in_object ()

    JSCValue *
    jsc_context_evaluate_in_object (JSCContext *context,
                                    const char *code,
                                    gssize length,
                                    gpointer object_instance,
                                    JSCClass *object_class,
                                    const char *uri,
                                    guint line_number,
                                    JSCValue **object);

Evaluate `code` and create an new object where symbols defined in `code` will be added as properties, instead of being added to `context` global object. The new object is returned as `object` parameter. Similar to how `jsc_value_new_object()` works, if `object_instance` is not `NULL` `object_class` must be provided too. The `line_number` is the starting line number in `uri` ; the value is one-based so the first line is 1. `uri` and `line_number` will be shown in exceptions and they don't affect the behavior of the script.

#### Parameters

context | a JSCContext |
code | a JavaScript script to evaluate |
length | length of `code` , or -1 if `code` is a nul-terminated string |
object_instance | an object instance. | [nullable]
object_class | a JSCClass or `NULL` to use the default. | [nullable]
uri | the source URI |
line_number | the starting line number |
object | return location for a JSCValue. | [out][transfer full]

#### Returns

a JSCValue representing the last value generated by the script.

[transfer full]

### jsc_context_check_syntax ()

    JSCCheckSyntaxResult
    jsc_context_check_syntax (JSCContext *context,
                              const char *code,
                              gssize length,
                              JSCCheckSyntaxMode mode,
                              const char *uri,
                              unsigned  line_number,
                              JSCException **exception);

Check the given `code` in `context` for syntax errors. The `line_number` is the starting line number in `uri` ; the value is one-based so the first line is 1. `uri` and `line_number` are only used to fill the `exception` . In case of errors `exception` will be set to a new JSCException with the details. You can pass `NULL` to `exception` to ignore the error details.

#### Parameters

context | a JSCContext |
code | a JavaScript script to check |
length | length of `code` , or -1 if `code` is a nul-terminated string |
mode | a JSCCheckSyntaxMode |
uri | the source URI |
line_number | the starting line number |
exception | return location for a JSCException, or `NULL` to ignore. | [out][optional][transfer full]

#### Returns

a JSCCheckSyntaxResult

### jsc_context_get_global_object ()

    JSCValue *
    jsc_context_get_global_object (JSCContext *context);

Get a JSCValue referencing the `context` global object

#### Parameters

context | a JSCContext |

#### Returns

a JSCValue.

[transfer full]

### jsc_context_set_value ()

    void
    jsc_context_set_value (JSCContext *context,
                           const char *name,
                           JSCValue *value);

Set a property of `context` global object with `name` and `value` .

#### Parameters

context | a JSCContext |
name | the value name |
value | a JSCValue |

### jsc_context_get_value ()

    JSCValue *
    jsc_context_get_value (JSCContext *context,
                           const char *name);

Get a property of `context` global object with `name` .

#### Parameters

context | a JSCContext |
name | the value name |

#### Returns

a JSCValue.

[transfer full]

### jsc_context_register_class ()

    JSCClass *
    jsc_context_register_class (JSCContext *context,
                                const char *name,
                                JSCClass *parent_class,
                                JSCClassVTable *vtable,
                                GDestroyNotify destroy_notify);

Register a custom class in `context` using the given `name` . If the new class inherits from another JSCClass, the parent should be passed as `parent_class` , otherwise `NULL` should be used. The optional `vtable` parameter allows to provide a custom implementation for handling the class, for example, to handle external properties not added to the prototype. When an instance of the JSCClass is cleared in the context, `destroy_notify` is called with the instance as parameter.

#### Parameters

context | a JSCContext |
name | the class name |
parent_class | a JSCClass or `NULL`. | [nullable]
vtable | an optional JSCClassVTable or `NULL`. | [nullable]
destroy_notify | a destroy notifier for class instances. | [nullable]

#### Returns

a JSCClass.

[transfer none]

## Types and Values

### JSCContext

    typedef struct _JSCContext JSCContext;

### enum JSCCheckSyntaxMode

Enum values to specify a mode to check for syntax errors in `jsc_context_check_syntax()`.

#### Members

JSC_CHECK_SYNTAX_MODE_SCRIPT | mode to check syntax of a script |
JSC_CHECK_SYNTAX_MODE_MODULE | mode to check syntax of a module |

### enum JSCCheckSyntaxResult

Enum values to specify the result of `jsc_context_check_syntax()`.

#### Members

JSC_CHECK_SYNTAX_RESULT_SUCCESS | no errors |
JSC_CHECK_SYNTAX_RESULT_RECOVERABLE_ERROR | recoverable syntax error |
JSC_CHECK_SYNTAX_RESULT_IRRECOVERABLE_ERROR | irrecoverable syntax error |
JSC_CHECK_SYNTAX_RESULT_UNTERMINATED_LITERAL_ERROR | unterminated literal error |
JSC_CHECK_SYNTAX_RESULT_OUT_OF_MEMORY_ERROR | out of memory error |
JSC_CHECK_SYNTAX_RESULT_STACK_OVERFLOW_ERROR | stack overflow error |

## Property Details

### The `“virtual-machine”` property

      “virtual-machine”          JSCVirtualMachine *

The JSCVirtualMachine in which the context was created.

Flags: Read / Write / Construct Only