2007-11-27 Alp Toker <alp@atoker.com>
[WebKit-https.git] / JavaScriptCore / API / JSBase.h
1 // -*- mode: c++; c-basic-offset: 4 -*-
2 /*
3  * Copyright (C) 2006 Apple Computer, Inc.  All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in the
12  *    documentation and/or other materials provided with the distribution.
13  *
14  * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY
15  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
17  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE COMPUTER, INC. OR
18  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
19  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
20  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
21  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
22  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
24  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
25  */
26
27 #ifndef JSBase_h
28 #define JSBase_h
29
30 #include <stdbool.h>
31
32 /* JavaScript engine interface */
33
34 /*! @typedef JSContextRef A JavaScript execution context. Holds the global object and other execution state. */
35 typedef const struct OpaqueJSContext* JSContextRef;
36
37 /*! @typedef JSGlobalContextRef A global JavaScript execution context. A JSGlobalContext is a JSContext. */
38 typedef struct OpaqueJSContext* JSGlobalContextRef;
39
40 /*! @typedef JSString A UTF16 character buffer. The fundamental string representation in JavaScript. */
41 typedef struct OpaqueJSString* JSStringRef;
42
43 /*! @typedef JSClassRef A JavaScript class. Used with JSObjectMake to construct objects with custom behavior. */
44 typedef struct OpaqueJSClass* JSClassRef;
45
46 /*! @typedef JSPropertyNameArrayRef An array of JavaScript property names. */
47 typedef struct OpaqueJSPropertyNameArray* JSPropertyNameArrayRef;
48
49 /*! @typedef JSPropertyNameAccumulatorRef An ordered set used to collect the names of a JavaScript object's properties. */
50 typedef struct OpaqueJSPropertyNameAccumulator* JSPropertyNameAccumulatorRef;
51
52
53 /* JavaScript data types */
54
55 /*! @typedef JSValueRef A JavaScript value. The base type for all JavaScript values, and polymorphic functions on them. */
56 typedef const struct OpaqueJSValue* JSValueRef;
57
58 /*! @typedef JSObjectRef A JavaScript object. A JSObject is a JSValue. */
59 typedef struct OpaqueJSValue* JSObjectRef;
60
61 /* JavaScript symbol exports */
62
63 #undef JS_EXPORT
64 #if defined(WIN32) || defined(_WIN32)
65     #define JS_EXPORT
66 #elif defined(__GNUC__)
67     #define JS_EXPORT __attribute__((visibility("default")))
68 #else
69     #define JS_EXPORT extern
70 #endif
71
72 #ifdef __cplusplus
73 extern "C" {
74 #endif
75
76 /* Script Evaluation */
77
78 /*!
79 @function
80 @abstract Evaluates a string of JavaScript.
81 @param ctx The execution context to use.
82 @param script A JSString containing the script to evaluate.
83 @param thisObject The object to use as "this," or NULL to use the global object as "this."
84 @param sourceURL A JSString containing a URL for the script's source file. This is only used when reporting exceptions. Pass NULL if you do not care to include source file information in exceptions.
85 @param startingLineNumber An integer value specifying the script's starting line number in the file located at sourceURL. This is only used when reporting exceptions.
86 @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.
87 @result The JSValue that results from evaluating script, or NULL if an exception is thrown.
88 */
89 JS_EXPORT JSValueRef JSEvaluateScript(JSContextRef ctx, JSStringRef script, JSObjectRef thisObject, JSStringRef sourceURL, int startingLineNumber, JSValueRef* exception);
90
91 /*!
92 @function JSCheckScriptSyntax
93 @abstract Checks for syntax errors in a string of JavaScript.
94 @param ctx The execution context to use.
95 @param script A JSString containing the script to check for syntax errors.
96 @param sourceURL A JSString containing a URL for the script's source file. This is only used when reporting exceptions. Pass NULL if you do not care to include source file information in exceptions.
97 @param startingLineNumber An integer value specifying the script's starting line number in the file located at sourceURL. This is only used when reporting exceptions.
98 @param exception A pointer to a JSValueRef in which to store a syntax error exception, if any. Pass NULL if you do not care to store a syntax error exception.
99 @result true if the script is syntactically correct, otherwise false.
100 */
101 JS_EXPORT bool JSCheckScriptSyntax(JSContextRef ctx, JSStringRef script, JSStringRef sourceURL, int startingLineNumber, JSValueRef* exception);
102
103 /*!
104 @function
105 @abstract Performs a JavaScript garbage collection. 
106 @param ctx This parameter is currently unused. Pass NULL.
107 @discussion JavaScript values that are on the machine stack, in a register, 
108  protected by JSValueProtect, set as the global object of an execution context, 
109  or reachable from any such value will not be collected. 
110  
111  During JavaScript execution, you are not required to call this function; the 
112  JavaScript engine will garbage collect as needed. One place you may want to call 
113  this function, however, is after releasing the last reference to a JSGlobalContextRef. 
114  At that point, a garbage collection can free the objects still referenced by the 
115  JSGlobalContextRef's global object, along with the global object itself.
116 */
117 JS_EXPORT void JSGarbageCollect(JSContextRef ctx);
118
119 #ifdef __cplusplus
120 }
121 #endif
122
123 #endif // JSBase_h