JSContext

Introduction

An instance of JSContext represents a JavaScript execution environment. All JavaScript execution takes place within a context. JSContext is also used to manage the life-cycle of objects within the JavaScript virtual machine. Every instance of JSValue is associated with a JSContext via a strong reference. The JSValue will keep the JSContext it references alive so long as the JSValue remains alive. When all of the JSValues that reference a particular JSContext have been deallocated the JSContext will be deallocated unless it has been previously retained.

Creating New JSContexts

Group members:

Callback Accessors

Group members:

Evaluating Scripts

Group members:

Global Properties

Methods

+currentArguments

Get the arguments to the current callback.

+currentCallee

Get the JavaScript function that is currently executing.

+currentContext

Get the JSContext that is currently executing.

+currentThis

Get the this value of the currently executing method.

-evaluateScript:

Evaluate a string of JavaScript code.

-evaluateScript:withSourceURL:

Evaluate a string of JavaScript code, with a URL for the script's source file.

-init

Create a JSContext.

-initWithVirtualMachine:

Create a JSContext in the specified virtual machine.

currentArguments

Get the arguments to the current callback.

+ (NSArray *)currentArguments; 

Return Value

An NSArray of the arguments nil if there is no current callback.

Discussion

This method may be called from within an Objective-C block or method invoked as a callback from JavaScript to retrieve the callback's arguments, objects in the returned array are instances of JSValue. Outside of a callback from JavaScript this method will return nil.

currentCallee

Get the JavaScript function that is currently executing.

+ (JSValue *)currentCallee ; 

Return Value

The currently executing JavaScript function or nil if there isn't one.

Discussion

This method may be called from within an Objective-C block or method invoked as a callback from JavaScript to retrieve the callback's context. Outside of a callback from JavaScript this method will return nil.

Availability

Available in Mac OS X v10.10. Available in iOS v8.0.

currentContext

Get the JSContext that is currently executing.

+ (JSContext *)currentContext; 

Return Value

The currently executing JSContext or nil if there isn't one.

Discussion

This method may be called from within an Objective-C block or method invoked as a callback from JavaScript to retrieve the callback's context. Outside of a callback from JavaScript this method will return nil.

currentThis

Get the this value of the currently executing method.

+ (JSValue *)currentThis; 

Return Value

The current this value or nil if there isn't one.

Discussion

This method may be called from within an Objective-C block or method invoked as a callback from JavaScript to retrieve the callback's this value. Outside of a callback from JavaScript this method will return nil.

evaluateScript:

Evaluate a string of JavaScript code.

- (JSValue *)evaluateScript:(NSString *)script; 

Parameters

Return Value

The last value generated by the script.

evaluateScript:withSourceURL:

Evaluate a string of JavaScript code, with a URL for the script's source file.

- (JSValue *)evaluateScript:(NSString *)script withSourceURL:(NSURL *)sourceURL ; 

Parameters

Return Value

The last value generated by the script.

Availability

Available in Mac OS X v10.10. Available in iOS v8.0.

init

Create a JSContext.

- (instancetype)init; 

Return Value

The new context.

initWithVirtualMachine:

Create a JSContext in the specified virtual machine.

- (instancetype)initWithVirtualMachine:(JSVirtualMachine *)virtualMachine; 

Parameters

Return Value

The new context.

Properties

exception

exceptionHandler

globalObject

Get the global object of the context.

name

virtualMachine

exception

@property (strong) JSValue *exception; 

Discussion

The exception property may be used to throw an exception to JavaScript.

Before a callback is made from JavaScript to an Objective-C block or method, the prior value of the exception property will be preserved and the property will be set to nil. After the callback has completed the new value of the exception property will be read, and prior value restored. If the new value of exception is not nil, the callback will result in that value being thrown.

This property may also be used to check for uncaught exceptions arising from API function calls (since the default behaviour of exceptionHandler is to assign an uncaught exception to this property).

If a JSValue originating from a different JSVirtualMachine than this context is assigned to this property, an Objective-C exception will be raised.

exceptionHandler

@property (copy) void(^exceptionHandler)(JSContext *context,
    JSValue *exception); 

Discussion

If a call to an API function results in an uncaught JavaScript exception, the exceptionHandler block will be invoked. The default implementation for the exception handler will store the exception to the exception property on context. As a consequence the default behaviour is for unhandled exceptions occurring within a callback from JavaScript to be rethrown upon return. Setting this value to nil will result in all uncaught exceptions thrown from the API being silently consumed.

globalObject

Get the global object of the context.

@property (readonly,
    strong) JSValue *globalObject; 

Return Value

The global object.

Discussion

This method retrieves the global object of the JavaScript execution context. Instances of JSContext originating from WebKit will return a reference to the WindowProxy object.

name

@property (copy) NSString *name ; 

Discussion

Name of the JSContext. Exposed when remote debugging the context.

Availability

Available in Mac OS X v10.10. Available in iOS v8.0.

virtualMachine

@property (readonly,
    strong) JSVirtualMachine *virtualMachine; 

Discussion

All instances of JSContext are associated with a single JSVirtualMachine. The virtual machine provides an "object space" or set of execution resources.