[apple/javascriptcore.git] / API / JSBase.h

/*
 * Copyright (C) 2006 Apple Inc.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef JSBase_h
#define JSBase_h

#ifndef __cplusplus
#include <stdbool.h>
#endif

#ifdef __OBJC__
#import <Foundation/Foundation.h>
#endif

/* JavaScript engine interface */

/*! @typedef JSContextGroupRef A group that associates JavaScript contexts with one another. Contexts in the same group may share and exchange JavaScript objects. */
typedef const struct OpaqueJSContextGroup* JSContextGroupRef;

/*! @typedef JSContextRef A JavaScript execution context. Holds the global object and other execution state. */
typedef const struct OpaqueJSContext* JSContextRef;

/*! @typedef JSGlobalContextRef A global JavaScript execution context. A JSGlobalContext is a JSContext. */
typedef struct OpaqueJSContext* JSGlobalContextRef;

/*! @typedef JSStringRef A UTF16 character buffer. The fundamental string representation in JavaScript. */
typedef struct OpaqueJSString* JSStringRef;

/*! @typedef JSClassRef A JavaScript class. Used with JSObjectMake to construct objects with custom behavior. */
typedef struct OpaqueJSClass* JSClassRef;

/*! @typedef JSPropertyNameArrayRef An array of JavaScript property names. */
typedef struct OpaqueJSPropertyNameArray* JSPropertyNameArrayRef;

/*! @typedef JSPropertyNameAccumulatorRef An ordered set used to collect the names of a JavaScript object's properties. */
typedef struct OpaqueJSPropertyNameAccumulator* JSPropertyNameAccumulatorRef;


/* JavaScript data types */

/*! @typedef JSValueRef A JavaScript value. The base type for all JavaScript values, and polymorphic functions on them. */
typedef const struct OpaqueJSValue* JSValueRef;

/*! @typedef JSObjectRef A JavaScript object. A JSObject is a JSValue. */
typedef struct OpaqueJSValue* JSObjectRef;

/* JavaScript symbol exports */
/* These rules should stay the same as in WebKit2/Shared/API/c/WKBase.h */

#undef JS_EXPORT
#if defined(JS_NO_EXPORT)
#define JS_EXPORT
#elif defined(__GNUC__) && !defined(__CC_ARM) && !defined(__ARMCC__)
#define JS_EXPORT __attribute__((visibility("default")))
#elif defined(WIN32) || defined(_WIN32) || defined(_WIN32_WCE) || defined(__CC_ARM) || defined(__ARMCC__)
#if defined(BUILDING_JavaScriptCore) || defined(STATICALLY_LINKED_WITH_JavaScriptCore)
#define JS_EXPORT __declspec(dllexport)
#else
#define JS_EXPORT __declspec(dllimport)
#endif
#else /* !defined(JS_NO_EXPORT) */
#define JS_EXPORT
#endif /* defined(JS_NO_EXPORT) */

/* JS tests uses WTF but has no config.h, so we need to set the export defines here. */
#ifndef WTF_EXPORT_PRIVATE
#define WTF_EXPORT_PRIVATE JS_EXPORT
#endif

#ifdef __cplusplus
extern "C" {
#endif

/* Script Evaluation */

/*!
@function JSEvaluateScript
@abstract Evaluates a string of JavaScript.
@param ctx The execution context to use.
@param script A JSString containing the script to evaluate.
@param thisObject The object to use as "this," or NULL to use the global object as "this."
@param sourceURL A JSString containing a URL for the script's source file. This is used by debuggers and when reporting exceptions. Pass NULL if you do not care to include source file information.
@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. The value is one-based, so the first line is line 1 and invalid values are clamped to 1.
@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.
@result The JSValue that results from evaluating script, or NULL if an exception is thrown.
*/
JS_EXPORT JSValueRef JSEvaluateScript(JSContextRef ctx, JSStringRef script, JSObjectRef thisObject, JSStringRef sourceURL, int startingLineNumber, JSValueRef* exception);

/*!
@function JSCheckScriptSyntax
@abstract Checks for syntax errors in a string of JavaScript.
@param ctx The execution context to use.
@param script A JSString containing the script to check for syntax errors.
@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.
@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. The value is one-based, so the first line is line 1 and invalid values are clamped to 1.
@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.
@result true if the script is syntactically correct, otherwise false.
*/
JS_EXPORT bool JSCheckScriptSyntax(JSContextRef ctx, JSStringRef script, JSStringRef sourceURL, int startingLineNumber, JSValueRef* exception);

/*!
@function JSGarbageCollect
@abstract Performs a JavaScript garbage collection.
@param ctx The execution context to use.
@discussion JavaScript values that are on the machine stack, in a register,
 protected by JSValueProtect, set as the global object of an execution context,
 or reachable from any such value will not be collected.

 During JavaScript execution, you are not required to call this function; the
 JavaScript engine will garbage collect as needed. JavaScript values created
 within a context group are automatically destroyed when the last reference
 to the context group is released.
*/
JS_EXPORT void JSGarbageCollect(JSContextRef ctx);

#ifdef __cplusplus
}
#endif

/* Enable the Objective-C API for platforms with a modern runtime. */
#if !defined(JSC_OBJC_API_ENABLED)
#ifndef JSC_OBJC_API_AVAILABLE_MAC_OS_X_1080
#define JSC_OBJC_API_ENABLED (defined(__clang__) && defined(__APPLE__) && ((defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && __MAC_OS_X_VERSION_MIN_REQUIRED >= 1090 && !defined(__i386__)) || (defined(TARGET_OS_IPHONE) && TARGET_OS_IPHONE)))
#else
#define JSC_OBJC_API_ENABLED (defined(__clang__) && defined(__APPLE__) && ((defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && __MAC_OS_X_VERSION_MIN_REQUIRED >= 1080 && !defined(__i386__)) || (defined(TARGET_OS_IPHONE) && TARGET_OS_IPHONE)))
#endif
#endif

#endif /* JSBase_h */
Commit	Line	Data
b37bf2e1	1	/*
81345200	2	* Copyright (C) 2006 Apple Inc. All rights reserved.
b37bf2e1 A	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	*
81345200	13	* THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
b37bf2e1 A	14	* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
b37bf2e1 A	15	* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
81345200	16	* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR
b37bf2e1 A	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
81345200	23	* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
b37bf2e1 A	24	*/
	25
	26	#ifndef JSBase_h
	27	#define JSBase_h
	28
9dae56ea	29	#ifndef __cplusplus
b37bf2e1	30	#include <stdbool.h>
9dae56ea	31	#endif
b37bf2e1	32
93a37866 A	33	#ifdef __OBJC__
	34	#import <Foundation/Foundation.h>
	35	#endif
	36
b37bf2e1 A	37	/* JavaScript engine interface */
b37bf2e1 A	38
9dae56ea A	39	/! @typedef JSContextGroupRef A group that associates JavaScript contexts with one another. Contexts in the same group may share and exchange JavaScript objects. /
	40	typedef const struct OpaqueJSContextGroup* JSContextGroupRef;
	41
b37bf2e1 A	42	/! @typedef JSContextRef A JavaScript execution context. Holds the global object and other execution state. /
	43	typedef const struct OpaqueJSContext* JSContextRef;
	44
	45	/! @typedef JSGlobalContextRef A global JavaScript execution context. A JSGlobalContext is a JSContext. /
	46	typedef struct OpaqueJSContext* JSGlobalContextRef;
	47
	48	/! @typedef JSStringRef A UTF16 character buffer. The fundamental string representation in JavaScript. /
	49	typedef struct OpaqueJSString* JSStringRef;
	50
	51	/! @typedef JSClassRef A JavaScript class. Used with JSObjectMake to construct objects with custom behavior. /
	52	typedef struct OpaqueJSClass* JSClassRef;
	53
	54	/! @typedef JSPropertyNameArrayRef An array of JavaScript property names. /
	55	typedef struct OpaqueJSPropertyNameArray* JSPropertyNameArrayRef;
	56
	57	/! @typedef JSPropertyNameAccumulatorRef An ordered set used to collect the names of a JavaScript object's properties. /
	58	typedef struct OpaqueJSPropertyNameAccumulator* JSPropertyNameAccumulatorRef;
	59
	60
	61	/* JavaScript data types */
	62
	63	/! @typedef JSValueRef A JavaScript value. The base type for all JavaScript values, and polymorphic functions on them. /
	64	typedef const struct OpaqueJSValue* JSValueRef;
	65
	66	/! @typedef JSObjectRef A JavaScript object. A JSObject is a JSValue. /
	67	typedef struct OpaqueJSValue* JSObjectRef;
	68
	69	/* JavaScript symbol exports */
14957cd0	70	/* These rules should stay the same as in WebKit2/Shared/API/c/WKBase.h */
b37bf2e1 A	71
b37bf2e1 A	72	#undef JS_EXPORT
f9bf01c6	73	#if defined(JS_NO_EXPORT)
14957cd0	74	#define JS_EXPORT
f9bf01c6	75	#elif defined(__GNUC__) && !defined(__CC_ARM) && !defined(__ARMCC__)
14957cd0 A	76	#define JS_EXPORT __attribute__((visibility("default")))
14957cd0 A	77	#elif defined(WIN32) \|\| defined(_WIN32) \|\| defined(_WIN32_WCE) \|\| defined(__CC_ARM) \|\| defined(__ARMCC__)
93a37866	78	#if defined(BUILDING_JavaScriptCore) \|\| defined(STATICALLY_LINKED_WITH_JavaScriptCore)
14957cd0	79	#define JS_EXPORT __declspec(dllexport)
b37bf2e1	80	#else
14957cd0 A	81	#define JS_EXPORT __declspec(dllimport)
	82	#endif
	83	#else /* !defined(JS_NO_EXPORT) */
	84	#define JS_EXPORT
	85	#endif /* defined(JS_NO_EXPORT) */
	86
	87	/* JS tests uses WTF but has no config.h, so we need to set the export defines here. */
	88	#ifndef WTF_EXPORT_PRIVATE
	89	#define WTF_EXPORT_PRIVATE JS_EXPORT
b37bf2e1 A	90	#endif
	91
	92	#ifdef __cplusplus
	93	extern "C" {
	94	#endif
	95
	96	/* Script Evaluation */
	97
	98	/*!
9dae56ea	99	@function JSEvaluateScript
b37bf2e1 A	100	@abstract Evaluates a string of JavaScript.
	101	@param ctx The execution context to use.
	102	@param script A JSString containing the script to evaluate.
	103	@param thisObject The object to use as "this," or NULL to use the global object as "this."
81345200 A	104	@param sourceURL A JSString containing a URL for the script's source file. This is used by debuggers and when reporting exceptions. Pass NULL if you do not care to include source file information.
81345200 A	105	@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. The value is one-based, so the first line is line 1 and invalid values are clamped to 1.
b37bf2e1 A	106	@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.
	107	@result The JSValue that results from evaluating script, or NULL if an exception is thrown.
	108	*/
	109	JS_EXPORT JSValueRef JSEvaluateScript(JSContextRef ctx, JSStringRef script, JSObjectRef thisObject, JSStringRef sourceURL, int startingLineNumber, JSValueRef* exception);
	110
	111	/*!
	112	@function JSCheckScriptSyntax
	113	@abstract Checks for syntax errors in a string of JavaScript.
	114	@param ctx The execution context to use.
	115	@param script A JSString containing the script to check for syntax errors.
	116	@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.
81345200	117	@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. The value is one-based, so the first line is line 1 and invalid values are clamped to 1.
b37bf2e1 A	118	@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.
	119	@result true if the script is syntactically correct, otherwise false.
	120	*/
	121	JS_EXPORT bool JSCheckScriptSyntax(JSContextRef ctx, JSStringRef script, JSStringRef sourceURL, int startingLineNumber, JSValueRef* exception);
	122
	123	/*!
9dae56ea	124	@function JSGarbageCollect
81345200	125	@abstract Performs a JavaScript garbage collection.
9dae56ea	126	@param ctx The execution context to use.
81345200 A	127	@discussion JavaScript values that are on the machine stack, in a register,
81345200 A	128	protected by JSValueProtect, set as the global object of an execution context,
9dae56ea A	129	or reachable from any such value will not be collected.
9dae56ea A	130
81345200	131	During JavaScript execution, you are not required to call this function; the
9dae56ea A	132	JavaScript engine will garbage collect as needed. JavaScript values created
	133	within a context group are automatically destroyed when the last reference
	134	to the context group is released.
b37bf2e1 A	135	*/
	136	JS_EXPORT void JSGarbageCollect(JSContextRef ctx);
	137
	138	#ifdef __cplusplus
	139	}
	140	#endif
	141
93a37866 A	142	/* Enable the Objective-C API for platforms with a modern runtime. */
93a37866 A	143	#if !defined(JSC_OBJC_API_ENABLED)
81345200 A	144	#ifndef JSC_OBJC_API_AVAILABLE_MAC_OS_X_1080
	145	#define JSC_OBJC_API_ENABLED (defined(__clang__) && defined(__APPLE__) && ((defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && __MAC_OS_X_VERSION_MIN_REQUIRED >= 1090 && !defined(__i386__)) \|\| (defined(TARGET_OS_IPHONE) && TARGET_OS_IPHONE)))
	146	#else
	147	#define JSC_OBJC_API_ENABLED (defined(__clang__) && defined(__APPLE__) && ((defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && __MAC_OS_X_VERSION_MIN_REQUIRED >= 1080 && !defined(__i386__)) \|\| (defined(TARGET_OS_IPHONE) && TARGET_OS_IPHONE)))
	148	#endif
93a37866 A	149	#endif
93a37866 A	150
9dae56ea	151	#endif /* JSBase_h */