Move Symbol API to SPI
[WebKit-https.git] / Source / JavaScriptCore / API / JSValue.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 JSValue_h
27 #define JSValue_h
28
29 #if JSC_OBJC_API_ENABLED
30
31 #import <CoreGraphics/CGGeometry.h>
32
33 @class JSContext;
34
35 /*!
36 @interface
37 @discussion A JSValue is a reference to a JavaScript value. Every JSValue
38  originates from a JSContext and holds a strong reference to it.
39  When a JSValue instance method creates a new JSValue, the new value
40  originates from the same JSContext.
41
42  All JSValues values also originate from a JSVirtualMachine
43  (available indirectly via the context property). It is an error to pass a
44  JSValue to a method or property of a JSValue or JSContext originating from a
45  different JSVirtualMachine. Doing so will raise an Objective-C exception.
46 */
47 NS_CLASS_AVAILABLE(10_9, 7_0)
48 @interface JSValue : NSObject
49
50 /*!
51 @property
52 @abstract The JSContext that this value originates from.
53 */
54 @property (readonly, strong) JSContext *context;
55
56 /*!
57 @methodgroup Creating JavaScript Values
58 */
59 /*!
60 @method
61 @abstract Create a JSValue by converting an Objective-C object.
62 @discussion The resulting JSValue retains the provided Objective-C object.
63 @param value The Objective-C object to be converted.
64 @result The new JSValue.
65 */
66 + (JSValue *)valueWithObject:(id)value inContext:(JSContext *)context;
67
68 /*!
69 @method
70 @abstract Create a JavaScript value from a BOOL primitive.
71 @param context The JSContext in which the resulting JSValue will be created.
72 @result The new JSValue representing the equivalent boolean value.
73 */
74 + (JSValue *)valueWithBool:(BOOL)value inContext:(JSContext *)context;
75
76 /*!
77 @method
78 @abstract Create a JavaScript value from a double primitive.
79 @param context The JSContext in which the resulting JSValue will be created.
80 @result The new JSValue representing the equivalent boolean value.
81 */
82 + (JSValue *)valueWithDouble:(double)value inContext:(JSContext *)context;
83
84 /*!
85 @method
86 @abstract Create a JavaScript value from an <code>int32_t</code> primitive.
87 @param context The JSContext in which the resulting JSValue will be created.
88 @result The new JSValue representing the equivalent boolean value.
89 */
90 + (JSValue *)valueWithInt32:(int32_t)value inContext:(JSContext *)context;
91
92 /*!
93 @method
94 @abstract Create a JavaScript value from a <code>uint32_t</code> primitive.
95 @param context The JSContext in which the resulting JSValue will be created.
96 @result The new JSValue representing the equivalent boolean value.
97 */
98 + (JSValue *)valueWithUInt32:(uint32_t)value inContext:(JSContext *)context;
99
100 /*!
101 @method
102 @abstract Create a new, empty JavaScript object.
103 @param context The JSContext in which the resulting object will be created.
104 @result The new JavaScript object.
105 */
106 + (JSValue *)valueWithNewObjectInContext:(JSContext *)context;
107
108 /*!
109 @method
110 @abstract Create a new, empty JavaScript array.
111 @param context The JSContext in which the resulting array will be created.
112 @result The new JavaScript array.
113 */
114 + (JSValue *)valueWithNewArrayInContext:(JSContext *)context;
115
116 /*!
117 @method
118 @abstract Create a new JavaScript regular expression object.
119 @param pattern The regular expression pattern.
120 @param flags The regular expression flags.
121 @param context The JSContext in which the resulting regular expression object will be created.
122 @result The new JavaScript regular expression object.
123 */
124 + (JSValue *)valueWithNewRegularExpressionFromPattern:(NSString *)pattern flags:(NSString *)flags inContext:(JSContext *)context;
125
126 /*!
127 @method
128 @abstract Create a new JavaScript error object.
129 @param message The error message.
130 @param context The JSContext in which the resulting error object will be created.
131 @result The new JavaScript error object.
132 */
133 + (JSValue *)valueWithNewErrorFromMessage:(NSString *)message inContext:(JSContext *)context;
134
135 /*!
136 @method
137 @abstract Create the JavaScript value <code>null</code>.
138 @param context The JSContext to which the resulting JSValue belongs.
139 @result The JSValue representing the JavaScript value <code>null</code>.
140 */
141 + (JSValue *)valueWithNullInContext:(JSContext *)context;
142
143 /*!
144 @method
145 @abstract Create the JavaScript value <code>undefined</code>.
146 @param context The JSContext to which the resulting JSValue belongs.
147 @result The JSValue representing the JavaScript value <code>undefined</code>.
148 */
149 + (JSValue *)valueWithUndefinedInContext:(JSContext *)context;
150
151 /*!
152 @methodgroup Converting to Objective-C Types
153 @discussion When converting between JavaScript values and Objective-C objects a copy is
154  performed. Values of types listed below are copied to the corresponding
155  types on conversion in each direction. For NSDictionaries, entries in the
156  dictionary that are keyed by strings are copied onto a JavaScript object.
157  For dictionaries and arrays, conversion is recursive, with the same object
158  conversion being applied to all entries in the collection.
159
160 <pre>
161 @textblock
162    Objective-C type  |   JavaScript type
163  --------------------+---------------------
164          nil         |     undefined
165         NSNull       |        null
166        NSString      |       string
167        NSNumber      |   number, boolean
168      NSDictionary    |   Object object
169        NSArray       |    Array object
170         NSDate       |     Date object
171        NSBlock (1)   |   Function object (1)
172           id (2)     |   Wrapper object (2)
173         Class (3)    | Constructor object (3)
174 @/textblock
175 </pre>
176
177  (1) Instances of NSBlock with supported arguments types will be presented to
178  JavaScript as a callable Function object. For more information on supported
179  argument types see JSExport.h. If a JavaScript Function originating from an
180  Objective-C block is converted back to an Objective-C object the block will
181  be returned. All other JavaScript functions will be converted in the same
182  manner as a JavaScript object of type Object.
183
184  (2) For Objective-C instances that do not derive from the set of types listed
185  above, a wrapper object to provide a retaining handle to the Objective-C
186  instance from JavaScript. For more information on these wrapper objects, see
187  JSExport.h. When a JavaScript wrapper object is converted back to Objective-C
188  the Objective-C instance being retained by the wrapper is returned.
189
190  (3) For Objective-C Class objects a constructor object containing exported
191  class methods will be returned. See JSExport.h for more information on
192  constructor objects.
193
194  For all methods taking arguments of type id, arguments will be converted
195  into a JavaScript value according to the above conversion.
196 */
197 /*!
198 @method
199 @abstract Convert this JSValue to an Objective-C object.
200 @discussion The JSValue is converted to an Objective-C object according 
201  to the conversion rules specified above.
202 @result The Objective-C representation of this JSValue.
203 */
204 - (id)toObject;
205
206 /*!
207 @method
208 @abstract Convert a JSValue to an Objective-C object of a specific class.
209 @discussion The JSValue is converted to an Objective-C object of the specified Class. 
210  If the result is not of the specified Class then <code>nil</code> will be returned.
211 @result An Objective-C object of the specified Class or <code>nil</code>.
212 */
213 - (id)toObjectOfClass:(Class)expectedClass;
214
215 /*!
216 @method
217 @abstract Convert a JSValue to a boolean.
218 @discussion The JSValue is converted to a boolean according to the rules specified 
219  by the JavaScript language.
220 @result The boolean result of the conversion.
221 */
222 - (BOOL)toBool;
223
224 /*!
225 @method
226 @abstract Convert a JSValue to a double.
227 @discussion The JSValue is converted to a number according to the rules specified 
228  by the JavaScript language.
229 @result The double result of the conversion.
230 */
231 - (double)toDouble;
232
233 /*!
234 @method
235 @abstract Convert a JSValue to an <code>int32_t</code>.
236 @discussion The JSValue is converted to an integer according to the rules specified 
237  by the JavaScript language.
238 @result The <code>int32_t</code> result of the conversion.
239 */
240 - (int32_t)toInt32;
241
242 /*!
243 @method
244 @abstract Convert a JSValue to a <code>uint32_t</code>.
245 @discussion The JSValue is converted to an integer according to the rules specified 
246  by the JavaScript language.
247 @result The <code>uint32_t</code> result of the conversion.
248 */
249 - (uint32_t)toUInt32;
250
251 /*!
252 @method
253 @abstract Convert a JSValue to a NSNumber.
254 @discussion If the JSValue represents a boolean, a NSNumber value of YES or NO 
255  will be returned. For all other types the value will be converted to a number according 
256  to the rules specified by the JavaScript language.
257 @result The NSNumber result of the conversion.
258 */
259 - (NSNumber *)toNumber;
260
261 /*!
262 @method
263 @abstract Convert a JSValue to a NSString.
264 @discussion The JSValue is converted to a string according to the rules specified 
265  by the JavaScript language.
266 @result The NSString containing the result of the conversion.
267 */
268 - (NSString *)toString;
269
270 /*!
271 @method
272 @abstract Convert a JSValue to a NSDate.
273 @discussion The value is converted to a number representing a time interval 
274  since 1970 which is then used to create a new NSDate instance.
275 @result The NSDate created using the converted time interval.
276 */
277 - (NSDate *)toDate;
278
279 /*!
280 @method
281 @abstract Convert a JSValue to a NSArray.
282 @discussion If the value is <code>null</code> or <code>undefined</code> then <code>nil</code> is returned.
283  If the value is not an object then a JavaScript TypeError will be thrown.
284  The property <code>length</code> is read from the object, converted to an unsigned
285  integer, and an NSArray of this size is allocated. Properties corresponding
286  to indicies within the array bounds will be copied to the array, with
287  JSValues converted to equivalent Objective-C objects as specified.
288 @result The NSArray containing the recursively converted contents of the 
289  converted JavaScript array.
290 */
291 - (NSArray *)toArray;
292
293 /*!
294 @method
295 @abstract Convert a JSValue to a NSDictionary.
296 @discussion If the value is <code>null</code> or <code>undefined</code> then <code>nil</code> is returned.
297  If the value is not an object then a JavaScript TypeError will be thrown.
298  All enumerable properties of the object are copied to the dictionary, with
299  JSValues converted to equivalent Objective-C objects as specified.
300 @result The NSDictionary containing the recursively converted contents of
301  the converted JavaScript object.
302 */
303 - (NSDictionary *)toDictionary;
304
305 /*!
306 @functiongroup Checking JavaScript Types
307 */
308
309 /*!
310 @property
311 @abstract Check if a JSValue corresponds to the JavaScript value <code>undefined</code>.
312 */ 
313 @property (readonly) BOOL isUndefined;
314
315 /*!
316 @property
317 @abstract Check if a JSValue corresponds to the JavaScript value <code>null</code>.
318 */
319 @property (readonly) BOOL isNull;
320
321 /*!
322 @property
323 @abstract Check if a JSValue is a boolean.
324 */
325 @property (readonly) BOOL isBoolean;
326
327 /*!
328 @property
329 @abstract Check if a JSValue is a number.
330 @discussion In JavaScript, there is no differentiation between types of numbers.
331  Semantically all numbers behave like doubles except in special cases like bit
332  operations. 
333 */
334 @property (readonly) BOOL isNumber;
335
336 /*!
337 @property
338 @abstract Check if a JSValue is a string.
339 */
340 @property (readonly) BOOL isString;
341
342 /*!
343 @property
344 @abstract Check if a JSValue is an object.
345 */
346 @property (readonly) BOOL isObject;
347
348 /*!
349 @property
350 @abstract Check if a JSValue is an array.
351 */ 
352 @property (readonly) BOOL isArray JSC_API_AVAILABLE(macosx(10.11), ios(9.0));
353
354 /*!
355 @property
356 @abstract Check if a JSValue is a date.
357 */ 
358 @property (readonly) BOOL isDate JSC_API_AVAILABLE(macosx(10.11), ios(9.0));
359
360 /*!
361 @method
362 @abstract Compare two JSValues using JavaScript's <code>===</code> operator.
363 */
364 - (BOOL)isEqualToObject:(id)value;
365
366 /*!
367 @method
368 @abstract Compare two JSValues using JavaScript's <code>==</code> operator.
369 */
370 - (BOOL)isEqualWithTypeCoercionToObject:(id)value;
371
372 /*!
373 @method
374 @abstract Check if a JSValue is an instance of another object.
375 @discussion This method has the same function as the JavaScript operator <code>instanceof</code>.
376  If an object other than a JSValue is passed, it will first be converted according to
377  the aforementioned rules.
378 */
379 - (BOOL)isInstanceOf:(id)value;
380
381 /*!
382 @methodgroup Calling Functions and Constructors
383 */
384 /*!
385 @method
386 @abstract Invoke a JSValue as a function.
387 @discussion In JavaScript, if a function doesn't explicitly return a value then it
388  implicitly returns the JavaScript value <code>undefined</code>.
389 @param arguments The arguments to pass to the function.
390 @result The return value of the function call. 
391 */
392 - (JSValue *)callWithArguments:(NSArray *)arguments;
393
394 /*!
395 @method
396 @abstract Invoke a JSValue as a constructor.
397 @discussion This is equivalent to using the <code>new</code> syntax in JavaScript.
398 @param arguments The arguments to pass to the constructor.
399 @result The return value of the constructor call.
400 */
401 - (JSValue *)constructWithArguments:(NSArray *)arguments;
402
403 /*!
404 @method
405 @abstract Invoke a method on a JSValue.
406 @discussion Accesses the property named <code>method</code> from this value and 
407  calls the resulting value as a function, passing this JSValue as the <code>this</code>
408  value along with the specified arguments.
409 @param method The name of the method to be invoked.
410 @param arguments The arguments to pass to the method.
411 @result The return value of the method call.
412 */
413 - (JSValue *)invokeMethod:(NSString *)method withArguments:(NSArray *)arguments;
414
415 @end
416
417 /*!
418 @category
419 @discussion Objective-C methods exported to JavaScript may have argument and/or return
420  values of struct types, provided that conversion to and from the struct is
421  supported by JSValue. Support is provided for any types where JSValue
422  contains both a class method <code>valueWith<Type>:inContext:</code>, and and instance
423  method <code>to<Type></code>- where the string <code><Type></code> in these selector names match,
424  with the first argument to the former being of the same struct type as the
425  return type of the latter.
426  Support is provided for structs of type CGPoint, NSRange, CGRect and CGSize.
427 */
428 @interface JSValue (StructSupport)
429
430 /*!
431 @method
432 @abstract Create a JSValue from a CGPoint.
433 @result A newly allocated JavaScript object containing properties
434  named <code>x</code> and <code>y</code>, with values from the CGPoint.
435 */
436 + (JSValue *)valueWithPoint:(CGPoint)point inContext:(JSContext *)context;
437
438 /*!
439 @method
440 @abstract Create a JSValue from a NSRange.
441 @result A newly allocated JavaScript object containing properties
442  named <code>location</code> and <code>length</code>, with values from the NSRange.
443 */
444 + (JSValue *)valueWithRange:(NSRange)range inContext:(JSContext *)context;
445
446 /*!
447 @method
448 @abstract 
449 Create a JSValue from a CGRect.
450 @result A newly allocated JavaScript object containing properties
451  named <code>x</code>, <code>y</code>, <code>width</code>, and <code>height</code>, with values from the CGRect.
452 */
453 + (JSValue *)valueWithRect:(CGRect)rect inContext:(JSContext *)context;
454
455 /*!
456 @method
457 @abstract Create a JSValue from a CGSize.
458 @result A newly allocated JavaScript object containing properties
459  named <code>width</code> and <code>height</code>, with values from the CGSize.
460 */
461 + (JSValue *)valueWithSize:(CGSize)size inContext:(JSContext *)context;
462
463 /*!
464 @method
465 @abstract Convert a JSValue to a CGPoint.
466 @discussion Reads the properties named <code>x</code> and <code>y</code> from
467  this JSValue, and converts the results to double.
468 @result The new CGPoint.
469 */
470 - (CGPoint)toPoint;
471
472 /*!
473 @method
474 @abstract Convert a JSValue to an NSRange.
475 @discussion Reads the properties named <code>location</code> and
476  <code>length</code> from this JSValue and converts the results to double.
477 @result The new NSRange.
478 */
479 - (NSRange)toRange;
480
481 /*!
482 @method
483 @abstract Convert a JSValue to a CGRect.
484 @discussion Reads the properties named <code>x</code>, <code>y</code>, 
485  <code>width</code>, and <code>height</code> from this JSValue and converts the results to double.
486 @result The new CGRect.
487 */
488 - (CGRect)toRect;
489
490 /*!
491 @method
492 @abstract Convert a JSValue to a CGSize.
493 @discussion Reads the properties named <code>width</code> and
494  <code>height</code> from this JSValue and converts the results to double.
495 @result The new CGSize.
496 */
497 - (CGSize)toSize;
498
499 @end
500
501 /*!
502  @category
503  @discussion These methods enable querying properties on a JSValue.
504  */
505 @interface JSValue (PropertyAccess)
506
507 /*!
508  @method
509  @abstract Access a property of a JSValue.
510  @result The JSValue for the requested property or the JSValue <code>undefined</code>
511  if the property does not exist.
512  */
513 - (JSValue *)valueForProperty:(NSString *)property;
514
515 /*!
516  @method
517  @abstract Set a property on a JSValue.
518  */
519 - (void)setValue:(id)value forProperty:(NSString *)property;
520
521 /*!
522  @method
523  @abstract Delete a property from a JSValue.
524  @result YES if deletion is successful, NO otherwise.
525  */
526 - (BOOL)deleteProperty:(NSString *)property;
527
528 /*!
529  @method
530  @abstract Check if a JSValue has a property.
531  @discussion This method has the same function as the JavaScript operator <code>in</code>.
532  @result Returns YES if property is present on the value.
533  */
534 - (BOOL)hasProperty:(NSString *)property;
535
536 /*!
537  @method
538  @abstract Define properties with custom descriptors on JSValues.
539  @discussion This method may be used to create a data or accessor property on an object.
540  This method operates in accordance with the Object.defineProperty method in the
541  JavaScript language.
542  */
543 - (void)defineProperty:(NSString *)property descriptor:(id)descriptor;
544
545 /*!
546  @method
547  @abstract Access an indexed (numerical) property on a JSValue.
548  @result The JSValue for the property at the specified index.
549  Returns the JavaScript value <code>undefined</code> if no property exists at that index.
550  */
551 - (JSValue *)valueAtIndex:(NSUInteger)index;
552
553 /*!
554  @method
555  @abstract Set an indexed (numerical) property on a JSValue.
556  @discussion For JSValues that are JavaScript arrays, indices greater than
557  UINT_MAX - 1 will not affect the length of the array.
558  */
559 - (void)setValue:(id)value atIndex:(NSUInteger)index;
560
561 @end
562
563 /*!
564 @category
565 @discussion Instances of JSValue implement the following methods in order to enable
566  support for subscript access by key and index, for example:
567
568 @textblock
569     JSValue *objectA, *objectB;
570     JSValue *v1 = object[@"X"]; // Get value for property "X" from 'object'.
571     JSValue *v2 = object[42];   // Get value for index 42 from 'object'.
572     object[@"Y"] = v1;          // Assign 'v1' to property "Y" of 'object'.
573     object[101] = v2;           // Assign 'v2' to index 101 of 'object'.
574 @/textblock
575
576  An object key passed as a subscript will be converted to a JavaScript value,
577  and then the value converted to a string used as a property name.
578 */
579 @interface JSValue (SubscriptSupport)
580
581 - (JSValue *)objectForKeyedSubscript:(id)key;
582 - (JSValue *)objectAtIndexedSubscript:(NSUInteger)index;
583 - (void)setObject:(id)object forKeyedSubscript:(NSObject <NSCopying> *)key;
584 - (void)setObject:(id)object atIndexedSubscript:(NSUInteger)index;
585
586 @end
587
588 /*!
589 @category
590 @discussion  These functions are for bridging between the C API and the Objective-C API.
591 */
592 @interface JSValue (JSValueRefSupport)
593
594 /*!
595 @method
596 @abstract Creates a JSValue, wrapping its C API counterpart.
597 @result The Objective-C API equivalent of the specified JSValueRef.
598 */
599 + (JSValue *)valueWithJSValueRef:(JSValueRef)value inContext:(JSContext *)context;
600
601 /*!
602 @property
603 @abstract Returns the C API counterpart wrapped by a JSContext.
604 @result The C API equivalent of this JSValue.
605 */
606 @property (readonly) JSValueRef JSValueRef;
607 @end
608
609 #ifdef __cplusplus
610 extern "C" {
611 #endif
612
613 /*!
614 @group Property Descriptor Constants
615 @discussion These keys may assist in creating a property descriptor for use with the
616  defineProperty method on JSValue.
617  Property descriptors must fit one of three descriptions:
618
619  Data Descriptor:
620   - A descriptor containing one or both of the keys <code>value</code> and <code>writable</code>,
621     and optionally containing one or both of the keys <code>enumerable</code> and
622     <code>configurable</code>. A data descriptor may not contain either the <code>get</code> or
623     <code>set</code> key.
624     A data descriptor may be used to create or modify the attributes of a
625     data property on an object (replacing any existing accessor property).
626
627  Accessor Descriptor:
628   - A descriptor containing one or both of the keys <code>get</code> and <code>set</code>, and
629     optionally containing one or both of the keys <code>enumerable</code> and
630     <code>configurable</code>. An accessor descriptor may not contain either the <code>value</code>
631     or <code>writable</code> key.
632     An accessor descriptor may be used to create or modify the attributes of
633     an accessor property on an object (replacing any existing data property).
634
635  Generic Descriptor:
636   - A descriptor containing one or both of the keys <code>enumerable</code> and
637     <code>configurable</code>. A generic descriptor may not contain any of the keys
638     <code>value</code>, <code>writable</code>, <code>get</code>, or <code>set</code>.
639     A generic descriptor may be used to modify the attributes of an existing
640     data or accessor property, or to create a new data property.
641 */
642 /*!
643 @const 
644 */
645 JS_EXPORT extern NSString * const JSPropertyDescriptorWritableKey;
646 /*!
647 @const 
648 */
649 JS_EXPORT extern NSString * const JSPropertyDescriptorEnumerableKey;
650 /*!
651 @const 
652 */
653 JS_EXPORT extern NSString * const JSPropertyDescriptorConfigurableKey;
654 /*!
655 @const 
656 */
657 JS_EXPORT extern NSString * const JSPropertyDescriptorValueKey;
658 /*!
659 @const 
660 */
661 JS_EXPORT extern NSString * const JSPropertyDescriptorGetKey;
662 /*!
663 @const 
664 */
665 JS_EXPORT extern NSString * const JSPropertyDescriptorSetKey;
666
667 #ifdef __cplusplus
668 } // extern "C"
669 #endif
670
671 #endif
672
673 #endif // JSValue_h