Top |
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()
.
void (*JSCExceptionHandler) (JSCContext *context
,JSCException *exception
,gpointer user_data
);
Function used to handle JavaScript exceptions in a JSCContext.
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.
JSCContext *
jsc_context_new_with_virtual_machine (JSCVirtualMachine *vm
);
Create a new JSCContext in virtual_machine
.
JSCVirtualMachine *
jsc_context_get_virtual_machine (JSCContext *context
);
Get the JSCVirtualMachine where context
was created.
JSCException *
jsc_context_get_exception (JSCContext *context
);
Get the last unhandled exception thrown in context
by API functions calls.
a JSCException or NULL
if there isn't any
unhandled exception in the JSCContext.
[transfer none][nullable]
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()
.
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()
.
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()
.
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()
.
void jsc_context_throw_exception (JSCContext *context
,JSCException *exception
);
Throw exception
to context
.
void
jsc_context_clear_exception (JSCContext *context
);
Clear the uncaught exception in context
if any.
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.
void
jsc_context_pop_exception_handler (JSCContext *context
);
Remove the last JSCExceptionHandler previously pushed to context
with
jsc_context_push_exception_handler()
.
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.
JSCValue * jsc_context_evaluate (JSCContext *context
,const char *code
,gssize length
);
Evaluate code
in context
.
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.
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.
context |
||
code |
a JavaScript script to evaluate |
|
length |
length of |
|
object_instance |
an object instance. |
[nullable] |
object_class |
a JSCClass or |
[nullable] |
uri |
the source URI |
|
line_number |
the starting line number |
|
object |
return location for a JSCValue. |
[out][transfer full] |
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.
context |
||
code |
a JavaScript script to check |
|
length |
length of |
|
mode |
||
uri |
the source URI |
|
line_number |
the starting line number |
|
exception |
return location for a JSCException, or |
[out][optional][transfer full] |
JSCValue *
jsc_context_get_global_object (JSCContext *context
);
Get a JSCValue referencing the context
global object
void jsc_context_set_value (JSCContext *context
,const char *name
,JSCValue *value
);
Set a property of context
global object with name
and value
.
JSCValue * jsc_context_get_value (JSCContext *context
,const char *name
);
Get a property of context
global object with name
.
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.
context |
||
name |
the class name |
|
parent_class |
a JSCClass or |
[nullable] |
vtable |
an optional JSCClassVTable or |
[nullable] |
destroy_notify |
a destroy notifier for class instances. |
[nullable] |
Enum values to specify a mode to check for syntax errors in jsc_context_check_syntax()
.
Enum values to specify the result of jsc_context_check_syntax()
.
“virtual-machine”
property“virtual-machine” JSCVirtualMachine *
The JSCVirtualMachine in which the context was created.
Owner: JSCContext
Flags: Read / Write / Construct Only