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