1/* 2 * Copyright (C) 2013 Apple Inc. All rights reserved. 3 * 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 23 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24 */ 25 26#ifndef JSContext_h 27#define JSContext_h 28 29#include <JavaScriptCore/JavaScript.h> 30#include <JavaScriptCore/WebKitAvailability.h> 31 32#if JSC_OBJC_API_ENABLED 33 34@class JSVirtualMachine, JSValue; 35 36/*! 37@interface 38@discussion An instance of JSContext represents a JavaScript execution environment. All 39 JavaScript execution takes place within a context. 40 JSContext is also used to manage the life-cycle of objects within the 41 JavaScript virtual machine. Every instance of JSValue is associated with a 42 JSContext via a strong reference. The JSValue will keep the JSContext it 43 references alive so long as the JSValue remains alive. When all of the JSValues 44 that reference a particular JSContext have been deallocated the JSContext 45 will be deallocated unless it has been previously retained. 46*/ 47#ifndef JSC_OBJC_API_AVAILABLE_MAC_OS_X_1080 48NS_CLASS_AVAILABLE(10_9, 7_0) 49#else 50OBJC_VISIBLE 51#endif 52@interface JSContext : NSObject 53 54/*! 55@methodgroup Creating New JSContexts 56*/ 57/*! 58@method 59@abstract Create a JSContext. 60@result The new context. 61*/ 62- (instancetype)init; 63 64/*! 65@method 66@abstract Create a JSContext in the specified virtual machine. 67@param virtualMachine The JSVirtualMachine in which the context will be created. 68@result The new context. 69*/ 70- (instancetype)initWithVirtualMachine:(JSVirtualMachine *)virtualMachine; 71 72/*! 73@methodgroup Evaluating Scripts 74*/ 75/*! 76@method 77@abstract Evaluate a string of JavaScript code. 78@param script A string containing the JavaScript code to evaluate. 79@result The last value generated by the script. 80*/ 81- (JSValue *)evaluateScript:(NSString *)script; 82 83/*! 84@method 85@abstract Evaluate a string of JavaScript code, with a URL for the script's source file. 86@param script A string containing the JavaScript code to evaluate. 87@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. 88@result The last value generated by the script. 89*/ 90- (JSValue *)evaluateScript:(NSString *)script withSourceURL:(NSURL *)sourceURL NS_AVAILABLE(10_10, 8_0); 91 92/*! 93@methodgroup Callback Accessors 94*/ 95/*! 96@method 97@abstract Get the JSContext that is currently executing. 98@discussion This method may be called from within an Objective-C block or method invoked 99 as a callback from JavaScript to retrieve the callback's context. Outside of 100 a callback from JavaScript this method will return nil. 101@result The currently executing JSContext or nil if there isn't one. 102*/ 103+ (JSContext *)currentContext; 104 105/*! 106@method 107@abstract Get the JavaScript function that is currently executing. 108@discussion This method may be called from within an Objective-C block or method invoked 109 as a callback from JavaScript to retrieve the callback's context. Outside of 110 a callback from JavaScript this method will return nil. 111@result The currently executing JavaScript function or nil if there isn't one. 112*/ 113+ (JSValue *)currentCallee NS_AVAILABLE(10_10, 8_0); 114 115/*! 116@method 117@abstract Get the <code>this</code> value of the currently executing method. 118@discussion This method may be called from within an Objective-C block or method invoked 119 as a callback from JavaScript to retrieve the callback's this value. Outside 120 of a callback from JavaScript this method will return nil. 121@result The current <code>this</code> value or nil if there isn't one. 122*/ 123+ (JSValue *)currentThis; 124 125/*! 126@method 127@abstract Get the arguments to the current callback. 128@discussion This method may be called from within an Objective-C block or method invoked 129 as a callback from JavaScript to retrieve the callback's arguments, objects 130 in the returned array are instances of JSValue. Outside of a callback from 131 JavaScript this method will return nil. 132@result An NSArray of the arguments nil if there is no current callback. 133*/ 134+ (NSArray *)currentArguments; 135 136/*! 137@methodgroup Global Properties 138*/ 139/*! 140@property 141@abstract Get the global object of the context. 142@discussion This method retrieves the global object of the JavaScript execution context. 143 Instances of JSContext originating from WebKit will return a reference to the 144 WindowProxy object. 145@result The global object. 146*/ 147@property (readonly, strong) JSValue *globalObject; 148 149/*! 150@property 151@discussion The <code>exception</code> property may be used to throw an exception to JavaScript. 152 153 Before a callback is made from JavaScript to an Objective-C block or method, 154 the prior value of the exception property will be preserved and the property 155 will be set to nil. After the callback has completed the new value of the 156 exception property will be read, and prior value restored. If the new value 157 of exception is not nil, the callback will result in that value being thrown. 158 159 This property may also be used to check for uncaught exceptions arising from 160 API function calls (since the default behaviour of <code>exceptionHandler</code> is to 161 assign an uncaught exception to this property). 162 163 If a JSValue originating from a different JSVirtualMachine than this context 164 is assigned to this property, an Objective-C exception will be raised. 165*/ 166@property (strong) JSValue *exception; 167 168/*! 169@property 170@discussion If a call to an API function results in an uncaught JavaScript exception, the 171 <code>exceptionHandler</code> block will be invoked. The default implementation for the 172 exception handler will store the exception to the exception property on 173 context. As a consequence the default behaviour is for unhandled exceptions 174 occurring within a callback from JavaScript to be rethrown upon return. 175 Setting this value to nil will result in all uncaught exceptions thrown from 176 the API being silently consumed. 177*/ 178@property (copy) void(^exceptionHandler)(JSContext *context, JSValue *exception); 179 180/*! 181@property 182@discussion All instances of JSContext are associated with a single JSVirtualMachine. The 183 virtual machine provides an "object space" or set of execution resources. 184*/ 185@property (readonly, strong) JSVirtualMachine *virtualMachine; 186 187/*! 188@property 189@discussion Name of the JSContext. Exposed when remote debugging the context. 190*/ 191@property (copy) NSString *name NS_AVAILABLE(10_10, 8_0); 192 193@end 194 195/*! 196@category 197@discussion Instances of JSContext implement the following methods in order to enable 198 support for subscript access by key and index, for example: 199 200@textblock 201 JSContext *context; 202 JSValue *v = context[@"X"]; // Get value for "X" from the global object. 203 context[@"Y"] = v; // Assign 'v' to "Y" on the global object. 204@/textblock 205 206 An object key passed as a subscript will be converted to a JavaScript value, 207 and then the value converted to a string used to resolve a property of the 208 global object. 209*/ 210@interface JSContext (SubscriptSupport) 211 212/*! 213method 214@abstract Get a particular property on the global object. 215@param key 216@result The JSValue for the global object's property. 217*/ 218- (JSValue *)objectForKeyedSubscript:(id)key; 219 220/*! 221method 222@abstract Set a particular property on the global object. 223@param object 224@param key 225*/ 226- (void)setObject:(id)object forKeyedSubscript:(NSObject <NSCopying> *)key; 227 228@end 229 230/*! 231@category 232@discussion These functions are for bridging between the C API and the Objective-C API. 233*/ 234@interface JSContext (JSContextRefSupport) 235 236/*! 237@method 238@abstract Create a JSContext, wrapping its C API counterpart. 239@param jsGlobalContextRef 240@result The JSContext equivalent of the provided JSGlobalContextRef. 241*/ 242+ (JSContext *)contextWithJSGlobalContextRef:(JSGlobalContextRef)jsGlobalContextRef; 243 244/*! 245@property 246@abstract Get the C API counterpart wrapped by a JSContext. 247@result The C API equivalent of this JSContext. 248*/ 249@property (readonly) JSGlobalContextRef JSGlobalContextRef; 250@end 251 252#endif 253 254#endif // JSContext_h 255