:right-sidebar: True Context =================================================================== .. currentmodule:: gi.repository.JavaScriptCore .. class:: Context(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` 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 :func:`~gi.repository.JavaScriptCore.Context.evaluate` or :func:`~gi.repository.JavaScriptCore.Context.evaluate_with_source_uri`. It's also possible to register custom objects in the context with :func:`~gi.repository.JavaScriptCore.Context.register_class`. Constructors ------------ .. rst-class:: interim-class .. class:: Context :no-index: .. classmethod:: new() -> ~gi.repository.JavaScriptCore.Context Create a new :obj:`~gi.repository.JavaScriptCore.Context`\. The context is created in a new :obj:`~gi.repository.JavaScriptCore.VirtualMachine`\. Use :func:`~gi.repository.JavaScriptCore.Context.new_with_virtual_machine` to create a new :obj:`~gi.repository.JavaScriptCore.Context` in an existing :obj:`~gi.repository.JavaScriptCore.VirtualMachine`\. .. classmethod:: new_with_virtual_machine(vm: ~gi.repository.JavaScriptCore.VirtualMachine) -> ~gi.repository.JavaScriptCore.Context Create a new :obj:`~gi.repository.JavaScriptCore.Context` in ``virtual_machine``\. :param vm: a :obj:`~gi.repository.JavaScriptCore.VirtualMachine` Methods ------- .. rst-class:: interim-class .. class:: Context :no-index: .. method:: check_syntax(code: str, length: int, mode: ~gi.repository.JavaScriptCore.CheckSyntaxMode, uri: str, line_number: int) -> ~typing.Tuple[~gi.repository.JavaScriptCore.CheckSyntaxResult, ~gi.repository.JavaScriptCore.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 :obj:`~gi.repository.JavaScriptCore.Exception` with the details. You can pass :const:`None` to ``exception`` to ignore the error details. :param code: a JavaScript script to check :param length: length of ``code``\, or -1 if ``code`` is a nul-terminated string :param mode: a :obj:`~gi.repository.JavaScriptCore.CheckSyntaxMode` :param uri: the source URI :param line_number: the starting line number .. method:: clear_exception() -> None Clear the uncaught exception in ``context`` if any. .. method:: evaluate(code: str, length: int) -> ~gi.repository.JavaScriptCore.Value Evaluate ``code`` in ``context``\. :param code: a JavaScript script to evaluate :param length: length of ``code``\, or -1 if ``code`` is a nul-terminated string .. method:: evaluate_in_object(code: str, length: int, object_instance: ~typing.Any, object_class: ~gi.repository.JavaScriptCore.Class | None, uri: str, line_number: int) -> ~typing.Tuple[~gi.repository.JavaScriptCore.Value, ~gi.repository.JavaScriptCore.Value] 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 :func:`~gi.repository.JavaScriptCore.Value.new_object` works, if ``object_instance`` is not :const:`None` ``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. :param code: a JavaScript script to evaluate :param length: length of ``code``\, or -1 if ``code`` is a nul-terminated string :param object_instance: an object instance :param object_class: a :obj:`~gi.repository.JavaScriptCore.Class` or :const:`None` to use the default :param uri: the source URI :param line_number: the starting line number .. method:: evaluate_with_source_uri(code: str, length: int, uri: str, line_number: int) -> ~gi.repository.JavaScriptCore.Value 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. :param code: a JavaScript script to evaluate :param length: length of ``code``\, or -1 if ``code`` is a nul-terminated string :param uri: the source URI :param line_number: the starting line number .. classmethod:: get_current() -> ~gi.repository.JavaScriptCore.Context | None Get the :obj:`~gi.repository.JavaScriptCore.Context` that is currently executing a function. This should only be called within a function or method callback, otherwise :const:`None` will be returned. .. method:: get_exception() -> ~gi.repository.JavaScriptCore.Exception | None Get the last unhandled exception thrown in ``context`` by API functions calls. .. method:: get_global_object() -> ~gi.repository.JavaScriptCore.Value Get a :obj:`~gi.repository.JavaScriptCore.Value` referencing the ``context`` global object .. method:: get_value(name: str) -> ~gi.repository.JavaScriptCore.Value Get a property of ``context`` global object with ``name``\. :param name: the value name .. method:: get_virtual_machine() -> ~gi.repository.JavaScriptCore.VirtualMachine Get the :obj:`~gi.repository.JavaScriptCore.VirtualMachine` where ``context`` was created. .. method:: pop_exception_handler() -> None Remove the last :obj:`~gi.repository.JavaScriptCore.ExceptionHandler` previously pushed to ``context`` with :func:`~gi.repository.JavaScriptCore.Context.push_exception_handler`. .. method:: push_exception_handler(handler: ~typing.Callable[[~gi.repository.JavaScriptCore.Context, ~gi.repository.JavaScriptCore.Exception, ~typing.Any], None], user_data: ~typing.Any = None) -> None Push an exception handler in ``context``\. Whenever a JavaScript exception happens in the :obj:`~gi.repository.JavaScriptCore.Context`\, the given ``handler`` will be called. The default :obj:`~gi.repository.JavaScriptCore.ExceptionHandler` simply calls :func:`~gi.repository.JavaScriptCore.Context.throw_exception` to throw the exception to the :obj:`~gi.repository.JavaScriptCore.Context`\. If you don't want to catch the exception, but only get notified about it, call :func:`~gi.repository.JavaScriptCore.Context.throw_exception` in ``handler`` like the default one does. The last exception handler pushed is the only one used by the :obj:`~gi.repository.JavaScriptCore.Context`\, use :func:`~gi.repository.JavaScriptCore.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. :param handler: a :obj:`~gi.repository.JavaScriptCore.ExceptionHandler` :param user_data: user data to pass to ``handler`` .. method:: register_class(name: str, parent_class: ~gi.repository.JavaScriptCore.Class | None = None, vtable: ~gi.repository.JavaScriptCore.ClassVTable | None = None, destroy_notify: ~typing.Callable[[~typing.Any], None] | None = None) -> ~gi.repository.JavaScriptCore.Class Register a custom class in ``context`` using the given ``name``\. If the new class inherits from another :obj:`~gi.repository.JavaScriptCore.Class`\, the parent should be passed as ``parent_class``\, otherwise :const:`None` 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 :obj:`~gi.repository.JavaScriptCore.Class` is cleared in the context, ``destroy_notify`` is called with the instance as parameter. :param name: the class name :param parent_class: a :obj:`~gi.repository.JavaScriptCore.Class` or :const:`None` :param vtable: an optional :obj:`~gi.repository.JavaScriptCore.ClassVTable` or :const:`None` :param destroy_notify: a destroy notifier for class instances .. method:: set_value(name: str, value: ~gi.repository.JavaScriptCore.Value) -> None Set a property of ``context`` global object with ``name`` and ``value``\. :param name: the value name :param value: a :obj:`~gi.repository.JavaScriptCore.Value` .. method:: throw(error_message: str) -> None Throw an exception to ``context`` using the given error message. The created :obj:`~gi.repository.JavaScriptCore.Exception` can be retrieved with :func:`~gi.repository.JavaScriptCore.Context.get_exception`. :param error_message: an error message .. method:: throw_exception(exception: ~gi.repository.JavaScriptCore.Exception) -> None Throw ``exception`` to ``context``\. :param exception: a :obj:`~gi.repository.JavaScriptCore.Exception` .. method:: throw_with_name(error_name: str, error_message: str) -> None Throw an exception to ``context`` using the given error name and message. The created :obj:`~gi.repository.JavaScriptCore.Exception` can be retrieved with :func:`~gi.repository.JavaScriptCore.Context.get_exception`. :param error_name: the error name :param error_message: an error message Properties ---------- .. rst-class:: interim-class .. class:: Context :no-index: .. attribute:: props.virtual_machine :type: ~gi.repository.JavaScriptCore.VirtualMachine The type of the None singleton.