1 /*

     2  * Copyright (C) 2006 Apple Computer, 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 COMPUTER, 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 COMPUTER, 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 JSValueRef_h

    27 #define JSValueRef_h

    28 

    29 #include <JavaScriptCore/JSBase.h>

    30 #include <JavaScriptCore/WebKitAvailability.h>

    31 

    32 #ifndef __cplusplus

    33 #include <stdbool.h>

    34 #endif

    35 

    36 /*!

    37 @enum JSType

    38 @abstract     A constant identifying the type of a JSValue.

    39 @constant     kJSTypeUndefined  The unique undefined value.

    40 @constant     kJSTypeNull       The unique null value.

    41 @constant     kJSTypeBoolean    A primitive boolean value, one of true or false.

    42 @constant     kJSTypeNumber     A primitive number value.

    43 @constant     kJSTypeString     A primitive string value.

    44 @constant     kJSTypeObject     An object value (meaning that this JSValueRef is a JSObjectRef).

    45 */

    46 typedef enum {

    47     kJSTypeUndefined,

    48     kJSTypeNull,

    49     kJSTypeBoolean,

    50     kJSTypeNumber,

    51     kJSTypeString,

    52     kJSTypeObject

    53 } JSType;

    54 

    55 #ifdef __cplusplus

    56 extern "C" {

    57 #endif

    58 

    59 /*!

    60 @function

    61 @abstract       Returns a JavaScript value's type.

    62 @param ctx  The execution context to use.

    63 @param value    The JSValue whose type you want to obtain.

    64 @result         A value of type JSType that identifies value's type.

    65 */

    66 JS_EXPORT JSType JSValueGetType(JSContextRef ctx, JSValueRef value);

    67 

    68 /*!

    69 @function

    70 @abstract       Tests whether a JavaScript value's type is the undefined type.

    71 @param ctx  The execution context to use.

    72 @param value    The JSValue to test.

    73 @result         true if value's type is the undefined type, otherwise false.

    74 */

    75 JS_EXPORT bool JSValueIsUndefined(JSContextRef ctx, JSValueRef value);

    76 

    77 /*!

    78 @function

    79 @abstract       Tests whether a JavaScript value's type is the null type.

    80 @param ctx  The execution context to use.

    81 @param value    The JSValue to test.

    82 @result         true if value's type is the null type, otherwise false.

    83 */

    84 JS_EXPORT bool JSValueIsNull(JSContextRef ctx, JSValueRef value);

    85 

    86 /*!

    87 @function

    88 @abstract       Tests whether a JavaScript value's type is the boolean type.

    89 @param ctx  The execution context to use.

    90 @param value    The JSValue to test.

    91 @result         true if value's type is the boolean type, otherwise false.

    92 */

    93 JS_EXPORT bool JSValueIsBoolean(JSContextRef ctx, JSValueRef value);

    94 

    95 /*!

    96 @function

    97 @abstract       Tests whether a JavaScript value's type is the number type.

    98 @param ctx  The execution context to use.

    99 @param value    The JSValue to test.

   100 @result         true if value's type is the number type, otherwise false.

   101 */

   102 JS_EXPORT bool JSValueIsNumber(JSContextRef ctx, JSValueRef value);

   103 

   104 /*!

   105 @function

   106 @abstract       Tests whether a JavaScript value's type is the string type.

   107 @param ctx  The execution context to use.

   108 @param value    The JSValue to test.

   109 @result         true if value's type is the string type, otherwise false.

   110 */

   111 JS_EXPORT bool JSValueIsString(JSContextRef ctx, JSValueRef value);

   112 

   113 /*!

   114 @function

   115 @abstract       Tests whether a JavaScript value's type is the object type.

   116 @param ctx  The execution context to use.

   117 @param value    The JSValue to test.

   118 @result         true if value's type is the object type, otherwise false.

   119 */

   120 JS_EXPORT bool JSValueIsObject(JSContextRef ctx, JSValueRef value);

   121 

   122 /*!

   123 @function

   124 @abstract Tests whether a JavaScript value is an object with a given class in its class chain.

   125 @param ctx The execution context to use.

   126 @param value The JSValue to test.

   127 @param jsClass The JSClass to test against.

   128 @result true if value is an object and has jsClass in its class chain, otherwise false.

   129 */

   130 JS_EXPORT bool JSValueIsObjectOfClass(JSContextRef ctx, JSValueRef value, JSClassRef jsClass);

   131 

   132 /* Comparing values */

   133 

   134 /*!

   135 @function

   136 @abstract Tests whether two JavaScript values are equal, as compared by the JS == operator.

   137 @param ctx The execution context to use.

   138 @param a The first value to test.

   139 @param b The second value to test.

   140 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.

   141 @result true if the two values are equal, false if they are not equal or an exception is thrown.

   142 */

   143 JS_EXPORT bool JSValueIsEqual(JSContextRef ctx, JSValueRef a, JSValueRef b, JSValueRef* exception);

   144 

   145 /*!

   146 @function

   147 @abstract       Tests whether two JavaScript values are strict equal, as compared by the JS === operator.

   148 @param ctx  The execution context to use.

   149 @param a        The first value to test.

   150 @param b        The second value to test.

   151 @result         true if the two values are strict equal, otherwise false.

   152 */

   153 JS_EXPORT bool JSValueIsStrictEqual(JSContextRef ctx, JSValueRef a, JSValueRef b);

   154 

   155 /*!

   156 @function

   157 @abstract Tests whether a JavaScript value is an object constructed by a given constructor, as compared by the JS instanceof operator.

   158 @param ctx The execution context to use.

   159 @param value The JSValue to test.

   160 @param constructor The constructor to test against.

   161 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.

   162 @result true if value is an object constructed by constructor, as compared by the JS instanceof operator, otherwise false.

   163 */

   164 JS_EXPORT bool JSValueIsInstanceOfConstructor(JSContextRef ctx, JSValueRef value, JSObjectRef constructor, JSValueRef* exception);

   165 

   166 /* Creating values */

   167 

   168 /*!

   169 @function

   170 @abstract       Creates a JavaScript value of the undefined type.

   171 @param ctx  The execution context to use.

   172 @result         The unique undefined value.

   173 */

   174 JS_EXPORT JSValueRef JSValueMakeUndefined(JSContextRef ctx);

   175 

   176 /*!

   177 @function

   178 @abstract       Creates a JavaScript value of the null type.

   179 @param ctx  The execution context to use.

   180 @result         The unique null value.

   181 */

   182 JS_EXPORT JSValueRef JSValueMakeNull(JSContextRef ctx);

   183 

   184 /*!

   185 @function

   186 @abstract       Creates a JavaScript value of the boolean type.

   187 @param ctx  The execution context to use.

   188 @param boolean  The bool to assign to the newly created JSValue.

   189 @result         A JSValue of the boolean type, representing the value of boolean.

   190 */

   191 JS_EXPORT JSValueRef JSValueMakeBoolean(JSContextRef ctx, bool boolean);

   192 

   193 /*!

   194 @function

   195 @abstract       Creates a JavaScript value of the number type.

   196 @param ctx  The execution context to use.

   197 @param number   The double to assign to the newly created JSValue.

   198 @result         A JSValue of the number type, representing the value of number.

   199 */

   200 JS_EXPORT JSValueRef JSValueMakeNumber(JSContextRef ctx, double number);

   201 

   202 /*!

   203 @function

   204 @abstract       Creates a JavaScript value of the string type.

   205 @param ctx  The execution context to use.

   206 @param string   The JSString to assign to the newly created JSValue. The

   207  newly created JSValue retains string, and releases it upon garbage collection.

   208 @result         A JSValue of the string type, representing the value of string.

   209 */

   210 JS_EXPORT JSValueRef JSValueMakeString(JSContextRef ctx, JSStringRef string);

   211 

   212 /* Converting to and from JSON formatted strings */

   213 

   214 /*!

   215  @function

   216  @abstract       Creates a JavaScript value from a JSON formatted string.

   217  @param ctx      The execution context to use.

   218  @param string   The JSString containing the JSON string to be parsed.

   219  @result         A JSValue containing the parsed value, or NULL if the input is invalid.

   220  */

   221 JS_EXPORT JSValueRef JSValueMakeFromJSONString(JSContextRef ctx, JSStringRef string) AVAILABLE_AFTER_WEBKIT_VERSION_4_0;

   222 

   223 /*!

   224  @function

   225  @abstract       Creates a JavaScript string containing the JSON serialized representation of a JS value.

   226  @param ctx      The execution context to use.

   227  @param value    The value to serialize.

   228  @param indent   The number of spaces to indent when nesting.  If 0, the resulting JSON will not contains newlines.  The size of the indent is clamped to 10 spaces.

   229  @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.

   230  @result         A JSString with the result of serialization, or NULL if an exception is thrown.

   231  */

   232 JS_EXPORT JSStringRef JSValueCreateJSONString(JSContextRef ctx, JSValueRef value, unsigned indent, JSValueRef* exception) AVAILABLE_AFTER_WEBKIT_VERSION_4_0;

   233 

   234 /* Converting to primitive values */

   235 

   236 /*!

   237 @function

   238 @abstract       Converts a JavaScript value to boolean and returns the resulting boolean.

   239 @param ctx  The execution context to use.

   240 @param value    The JSValue to convert.

   241 @result         The boolean result of conversion.

   242 */

   243 JS_EXPORT bool JSValueToBoolean(JSContextRef ctx, JSValueRef value);

   244 

   245 /*!

   246 @function

   247 @abstract       Converts a JavaScript value to number and returns the resulting number.

   248 @param ctx  The execution context to use.

   249 @param value    The JSValue to convert.

   250 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.

   251 @result         The numeric result of conversion, or NaN if an exception is thrown.

   252 */

   253 JS_EXPORT double JSValueToNumber(JSContextRef ctx, JSValueRef value, JSValueRef* exception);

   254 

   255 /*!

   256 @function

   257 @abstract       Converts a JavaScript value to string and copies the result into a JavaScript string.

   258 @param ctx  The execution context to use.

   259 @param value    The JSValue to convert.

   260 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.

   261 @result         A JSString with the result of conversion, or NULL if an exception is thrown. Ownership follows the Create Rule.

   262 */

   263 JS_EXPORT JSStringRef JSValueToStringCopy(JSContextRef ctx, JSValueRef value, JSValueRef* exception);

   264 

   265 /*!

   266 @function

   267 @abstract Converts a JavaScript value to object and returns the resulting object.

   268 @param ctx  The execution context to use.

   269 @param value    The JSValue to convert.

   270 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.

   271 @result         The JSObject result of conversion, or NULL if an exception is thrown.

   272 */

   273 JS_EXPORT JSObjectRef JSValueToObject(JSContextRef ctx, JSValueRef value, JSValueRef* exception);

   274 

   275 /* Garbage collection */

   276 /*!

   277 @function

   278 @abstract Protects a JavaScript value from garbage collection.

   279 @param ctx The execution context to use.

   280 @param value The JSValue to protect.

   281 @discussion Use this method when you want to store a JSValue in a global or on the heap, where the garbage collector will not be able to discover your reference to it.

   282  

   283 A value may be protected multiple times and must be unprotected an equal number of times before becoming eligible for garbage collection.

   284 */

   285 JS_EXPORT void JSValueProtect(JSContextRef ctx, JSValueRef value);

   286 

   287 /*!

   288 @function

   289 @abstract       Unprotects a JavaScript value from garbage collection.

   290 @param ctx      The execution context to use.

   291 @param value    The JSValue to unprotect.

   292 @discussion     A value may be protected multiple times and must be unprotected an 

   293  equal number of times before becoming eligible for garbage collection.

   294 */

   295 JS_EXPORT void JSValueUnprotect(JSContextRef ctx, JSValueRef value);

   296 

   297 #ifdef __cplusplus

   298 }

   299 #endif

   300 

   301 #endif /* JSValueRef_h */