Repository navigation
Expand file tree
/
Copy pathJSContext.h
More file actions
254 lines (221 loc) · 8.83 KB
/
Copy pathJSContext.h
File metadata and controls
254 lines (221 loc) · 8.83 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
/*
* Copyright (C) 2013 Apple Inc. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
* OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef JSContext_h
#define JSContext_h
#include <JavaScriptCore/JavaScript.h>
#include <JavaScriptCore/WebKitAvailability.h>
#if JSC_OBJC_API_ENABLED
@class JSVirtualMachine, JSValue;
/*!
@interface
@discussion 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.
*/
#ifndef JSC_OBJC_API_AVAILABLE_MAC_OS_X_1080
NS_CLASS_AVAILABLE(10_9, 7_0)
#else
OBJC_VISIBLE
#endif
@interface JSContext : NSObject
/*!
@methodgroup Creating New JSContexts
*/
/*!
@method
@abstract Create a JSContext.
@result The new context.
*/
- (instancetype)init;
/*!
@method
@abstract Create a JSContext in the specified virtual machine.
@param virtualMachine The JSVirtualMachine in which the context will be created.
@result The new context.
*/
- (instancetype)initWithVirtualMachine:(JSVirtualMachine *)virtualMachine;
/*!
@methodgroup Evaluating Scripts
*/
/*!
@method
@abstract Evaluate a string of JavaScript code.
@param script A string containing the JavaScript code to evaluate.
@result The last value generated by the script.
*/
- (JSValue *)evaluateScript:(NSString *)script;
/*!
@method
@abstract Evaluate a string of JavaScript code, with a URL for the script's source file.
@param script A string containing the JavaScript code to evaluate.
@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.
@result The last value generated by the script.
*/
- (JSValue *)evaluateScript:(NSString *)script withSourceURL:(NSURL *)sourceURL NS_AVAILABLE(10_10, 8_0);
/*!
@methodgroup Callback Accessors
*/
/*!
@method
@abstract Get the JSContext that is currently executing.
@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.
@result The currently executing JSContext or nil if there isn't one.
*/
+ (JSContext *)currentContext;
/*!
@method
@abstract Get the JavaScript function that is currently executing.
@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.
@result The currently executing JavaScript function or nil if there isn't one.
*/
+ (JSValue *)currentCallee NS_AVAILABLE(10_10, 8_0);
/*!
@method
@abstract Get the <code>this</code> value of the currently executing method.
@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.
@result The current <code>this</code> value or nil if there isn't one.
*/
+ (JSValue *)currentThis;
/*!
@method
@abstract Get the arguments to the 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.
@result An NSArray of the arguments nil if there is no current callback.
*/
+ (NSArray *)currentArguments;
/*!
@methodgroup Global Properties
*/
/*!
@property
@abstract Get the global object of the context.
@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.
@result The global object.
*/
@property (readonly, strong) JSValue *globalObject;
/*!
@property
@discussion The <code>exception</code> 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 <code>exceptionHandler</code> 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.
*/
@property (strong) JSValue *exception;
/*!
@property
@discussion If a call to an API function results in an uncaught JavaScript exception, the
<code>exceptionHandler</code> 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.
*/
@property (copy) void(^exceptionHandler)(JSContext *context, JSValue *exception);
/*!
@property
@discussion All instances of JSContext are associated with a single JSVirtualMachine. The
virtual machine provides an "object space" or set of execution resources.
*/
@property (readonly, strong) JSVirtualMachine *virtualMachine;
/*!
@property
@discussion Name of the JSContext. Exposed when remote debugging the context.
*/
@property (copy) NSString *name NS_AVAILABLE(10_10, 8_0);
@end
/*!
@category
@discussion Instances of JSContext implement the following methods in order to enable
support for subscript access by key and index, for example:
@textblock
JSContext *context;
JSValue *v = context[@"X"]; // Get value for "X" from the global object.
context[@"Y"] = v; // Assign 'v' to "Y" on the global object.
@/textblock
An object key passed as a subscript will be converted to a JavaScript value,
and then the value converted to a string used to resolve a property of the
global object.
*/
@interface JSContext (SubscriptSupport)
/*!
method
@abstract Get a particular property on the global object.
@param key
@result The JSValue for the global object's property.
*/
- (JSValue *)objectForKeyedSubscript:(id)key;
/*!
method
@abstract Set a particular property on the global object.
@param object
@param key
*/
- (void)setObject:(id)object forKeyedSubscript:(NSObject <NSCopying> *)key;
@end
/*!
@category
@discussion These functions are for bridging between the C API and the Objective-C API.
*/
@interface JSContext (JSContextRefSupport)
/*!
@method
@abstract Create a JSContext, wrapping its C API counterpart.
@param jsGlobalContextRef
@result The JSContext equivalent of the provided JSGlobalContextRef.
*/
+ (JSContext *)contextWithJSGlobalContextRef:(JSGlobalContextRef)jsGlobalContextRef;
/*!
@property
@abstract Get the C API counterpart wrapped by a JSContext.
@result The C API equivalent of this JSContext.
*/
@property (readonly) JSGlobalContextRef JSGlobalContextRef;
@end
#endif
#endif // JSContext_h