blob: 6b9c5d41761936d066e696d61c038948860d6e6b [file] [log] [blame]
barraclough@apple.comfc381882013-01-02 03:51:15 +00001/*
keith_miller@apple.com16bf7412019-01-14 20:27:17 +00002 * Copyright (C) 2013-2019 Apple Inc. All rights reserved.
barraclough@apple.comfc381882013-01-02 03:51:15 +00003 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 * 1. Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 *
13 * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
14 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
18 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
19 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
20 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
21 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
joepeck@webkit.orgb4ba4122013-12-12 18:41:35 +000023 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
barraclough@apple.comfc381882013-01-02 03:51:15 +000024 */
25
mhahnenberg@apple.comf0712f92013-02-21 20:00:33 +000026#ifndef JSContext_h
27#define JSContext_h
28
barraclough@apple.comfc381882013-01-02 03:51:15 +000029#include <JavaScriptCore/JavaScript.h>
mhahnenberg@apple.com4f18e952014-02-07 01:56:45 +000030#include <JavaScriptCore/WebKitAvailability.h>
barraclough@apple.comfc381882013-01-02 03:51:15 +000031
mhahnenberg@apple.comf0712f92013-02-21 20:00:33 +000032#if JSC_OBJC_API_ENABLED
barraclough@apple.comfc381882013-01-02 03:51:15 +000033
keith_miller@apple.com16bf7412019-01-14 20:27:17 +000034@class JSScript, JSVirtualMachine, JSValue, JSContext;
barraclough@apple.comfc381882013-01-02 03:51:15 +000035
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +000036/*!
37@interface
ggaren@apple.com58b89672015-10-16 23:57:35 +000038@discussion A JSContext is a JavaScript execution environment. All
39 JavaScript execution takes place within a context, and all JavaScript values
40 are tied to a context.
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +000041*/
timothy@apple.combd06ade2019-03-22 15:45:13 +000042JSC_CLASS_AVAILABLE(macos(10.9), ios(7.0))
barraclough@apple.comfc381882013-01-02 03:51:15 +000043@interface JSContext : NSObject
44
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +000045/*!
46@methodgroup Creating New JSContexts
47*/
48/*!
49@method
50@abstract Create a JSContext.
51@result The new context.
52*/
mrowe@apple.com4a0e6c12013-12-11 22:13:23 +000053- (instancetype)init;
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +000054
55/*!
56@method
57@abstract Create a JSContext in the specified virtual machine.
58@param virtualMachine The JSVirtualMachine in which the context will be created.
59@result The new context.
60*/
mrowe@apple.com4a0e6c12013-12-11 22:13:23 +000061- (instancetype)initWithVirtualMachine:(JSVirtualMachine *)virtualMachine;
barraclough@apple.comfc381882013-01-02 03:51:15 +000062
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +000063/*!
64@methodgroup Evaluating Scripts
65*/
66/*!
67@method
68@abstract Evaluate a string of JavaScript code.
69@param script A string containing the JavaScript code to evaluate.
70@result The last value generated by the script.
71*/
barraclough@apple.comfc381882013-01-02 03:51:15 +000072- (JSValue *)evaluateScript:(NSString *)script;
73
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +000074/*!
joepeck@webkit.org824b7472014-03-11 02:39:40 +000075@method
76@abstract Evaluate a string of JavaScript code, with a URL for the script's source file.
77@param script A string containing the JavaScript code to evaluate.
78@param sourceURL A URL for the script's source file. Used by debuggers and when reporting exceptions. This parameter is informative only: it does not change the behavior of the script.
79@result The last value generated by the script.
80*/
timothy@apple.combd06ade2019-03-22 15:45:13 +000081- (JSValue *)evaluateScript:(NSString *)script withSourceURL:(NSURL *)sourceURL JSC_API_AVAILABLE(macos(10.10), ios(8.0));
joepeck@webkit.org824b7472014-03-11 02:39:40 +000082
83/*!
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +000084@methodgroup Callback Accessors
85*/
86/*!
87@method
88@abstract Get the JSContext that is currently executing.
89@discussion This method may be called from within an Objective-C block or method invoked
90 as a callback from JavaScript to retrieve the callback's context. Outside of
91 a callback from JavaScript this method will return nil.
92@result The currently executing JSContext or nil if there isn't one.
93*/
barraclough@apple.comfc381882013-01-02 03:51:15 +000094+ (JSContext *)currentContext;
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +000095
96/*!
97@method
mhahnenberg@apple.com4f18e952014-02-07 01:56:45 +000098@abstract Get the JavaScript function that is currently executing.
99@discussion This method may be called from within an Objective-C block or method invoked
100 as a callback from JavaScript to retrieve the callback's context. Outside of
101 a callback from JavaScript this method will return nil.
102@result The currently executing JavaScript function or nil if there isn't one.
103*/
timothy@apple.combd06ade2019-03-22 15:45:13 +0000104+ (JSValue *)currentCallee JSC_API_AVAILABLE(macos(10.10), ios(8.0));
mhahnenberg@apple.com4f18e952014-02-07 01:56:45 +0000105
106/*!
107@method
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000108@abstract Get the <code>this</code> value of the currently executing method.
109@discussion This method may be called from within an Objective-C block or method invoked
110 as a callback from JavaScript to retrieve the callback's this value. Outside
111 of a callback from JavaScript this method will return nil.
112@result The current <code>this</code> value or nil if there isn't one.
113*/
barraclough@apple.comfc381882013-01-02 03:51:15 +0000114+ (JSValue *)currentThis;
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000115
116/*!
117@method
118@abstract Get the arguments to the current callback.
119@discussion This method may be called from within an Objective-C block or method invoked
120 as a callback from JavaScript to retrieve the callback's arguments, objects
121 in the returned array are instances of JSValue. Outside of a callback from
122 JavaScript this method will return nil.
123@result An NSArray of the arguments nil if there is no current callback.
124*/
barraclough@apple.comfc381882013-01-02 03:51:15 +0000125+ (NSArray *)currentArguments;
126
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000127/*!
mitz@apple.com5de0d142016-10-19 17:18:27 +0000128@functiongroup Global Properties
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000129*/
mitz@apple.com5de0d142016-10-19 17:18:27 +0000130
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000131/*!
mrowe@apple.com4a0e6c12013-12-11 22:13:23 +0000132@property
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000133@abstract Get the global object of the context.
134@discussion This method retrieves the global object of the JavaScript execution context.
135 Instances of JSContext originating from WebKit will return a reference to the
136 WindowProxy object.
137@result The global object.
138*/
mrowe@apple.com4a0e6c12013-12-11 22:13:23 +0000139@property (readonly, strong) JSValue *globalObject;
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000140
141/*!
142@property
143@discussion The <code>exception</code> property may be used to throw an exception to JavaScript.
144
145 Before a callback is made from JavaScript to an Objective-C block or method,
146 the prior value of the exception property will be preserved and the property
147 will be set to nil. After the callback has completed the new value of the
148 exception property will be read, and prior value restored. If the new value
149 of exception is not nil, the callback will result in that value being thrown.
150
151 This property may also be used to check for uncaught exceptions arising from
152 API function calls (since the default behaviour of <code>exceptionHandler</code> is to
153 assign an uncaught exception to this property).
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000154*/
mrowe@apple.com4a0e6c12013-12-11 22:13:23 +0000155@property (strong) JSValue *exception;
barraclough@apple.comfc381882013-01-02 03:51:15 +0000156
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000157/*!
158@property
159@discussion If a call to an API function results in an uncaught JavaScript exception, the
160 <code>exceptionHandler</code> block will be invoked. The default implementation for the
161 exception handler will store the exception to the exception property on
ggaren@apple.com58b89672015-10-16 23:57:35 +0000162 context. As a consequence the default behaviour is for uncaught exceptions
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000163 occurring within a callback from JavaScript to be rethrown upon return.
ggaren@apple.com58b89672015-10-16 23:57:35 +0000164 Setting this value to nil will cause all exceptions occurring
165 within a callback from JavaScript to be silently caught.
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000166*/
mrowe@apple.com4a0e6c12013-12-11 22:13:23 +0000167@property (copy) void(^exceptionHandler)(JSContext *context, JSValue *exception);
barraclough@apple.comfc381882013-01-02 03:51:15 +0000168
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000169/*!
170@property
ggaren@apple.com58b89672015-10-16 23:57:35 +0000171@discussion All instances of JSContext are associated with a JSVirtualMachine.
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000172*/
mrowe@apple.com4a0e6c12013-12-11 22:13:23 +0000173@property (readonly, strong) JSVirtualMachine *virtualMachine;
barraclough@apple.comfc381882013-01-02 03:51:15 +0000174
joepeck@webkit.orgd2ecf372013-12-04 18:20:37 +0000175/*!
176@property
177@discussion Name of the JSContext. Exposed when remote debugging the context.
178*/
timothy@apple.combd06ade2019-03-22 15:45:13 +0000179@property (copy) NSString *name JSC_API_AVAILABLE(macos(10.10), ios(8.0));
barraclough@apple.comfc381882013-01-02 03:51:15 +0000180@end
181
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000182/*!
183@category
184@discussion Instances of JSContext implement the following methods in order to enable
185 support for subscript access by key and index, for example:
186
187@textblock
188 JSContext *context;
189 JSValue *v = context[@"X"]; // Get value for "X" from the global object.
190 context[@"Y"] = v; // Assign 'v' to "Y" on the global object.
191@/textblock
192
193 An object key passed as a subscript will be converted to a JavaScript value,
194 and then the value converted to a string used to resolve a property of the
195 global object.
196*/
mrowe@apple.com4a0e6c12013-12-11 22:13:23 +0000197@interface JSContext (SubscriptSupport)
barraclough@apple.comfc381882013-01-02 03:51:15 +0000198
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000199/*!
mitz@apple.com5de0d142016-10-19 17:18:27 +0000200@method
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000201@abstract Get a particular property on the global object.
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000202@result The JSValue for the global object's property.
203*/
barraclough@apple.comfc381882013-01-02 03:51:15 +0000204- (JSValue *)objectForKeyedSubscript:(id)key;
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000205
206/*!
mitz@apple.com5de0d142016-10-19 17:18:27 +0000207@method
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000208@abstract Set a particular property on the global object.
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000209*/
barraclough@apple.coma56aeb22013-01-02 23:34:48 +0000210- (void)setObject:(id)object forKeyedSubscript:(NSObject <NSCopying> *)key;
barraclough@apple.comfc381882013-01-02 03:51:15 +0000211
212@end
213
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000214/*!
215@category
216@discussion These functions are for bridging between the C API and the Objective-C API.
217*/
mrowe@apple.com4a0e6c12013-12-11 22:13:23 +0000218@interface JSContext (JSContextRefSupport)
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000219
220/*!
221@method
222@abstract Create a JSContext, wrapping its C API counterpart.
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000223@result The JSContext equivalent of the provided JSGlobalContextRef.
224*/
ggaren@apple.com58bf4ea2013-04-30 21:55:43 +0000225+ (JSContext *)contextWithJSGlobalContextRef:(JSGlobalContextRef)jsGlobalContextRef;
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000226
227/*!
mrowe@apple.com4a0e6c12013-12-11 22:13:23 +0000228@property
mhahnenberg@apple.comfc0b6722013-11-23 02:54:31 +0000229@abstract Get the C API counterpart wrapped by a JSContext.
230@result The C API equivalent of this JSContext.
231*/
mrowe@apple.com4a0e6c12013-12-11 22:13:23 +0000232@property (readonly) JSGlobalContextRef JSGlobalContextRef;
keith_miller@apple.com16bf7412019-01-14 20:27:17 +0000233
ggaren@apple.com58bf4ea2013-04-30 21:55:43 +0000234@end
235
barraclough@apple.comfc381882013-01-02 03:51:15 +0000236#endif
mhahnenberg@apple.comf0712f92013-02-21 20:00:33 +0000237
238#endif // JSContext_h