JSCContext

JSCContext — JavaScript execution context

Functions

Properties

JSCVirtualMachine * virtual-machine Read / Write / Construct Only

Types and Values

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

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]

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