API/JSContext.h

   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
  48 NS_CLASS_AVAILABLE(10_9, 7_0)
  49 #else
  50 OBJC_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 /*!
 213 method
 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 /*!
 221 method
 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