1/*
2 * Copyright (C) 2012 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. AND ITS CONTRIBUTORS ``AS IS''
14 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
15 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
17 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
19 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
20 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
21 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
22 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
23 * THE POSSIBILITY OF SUCH DAMAGE.
24 */
25
26#ifndef JSScriptRefPrivate_h
27#define JSScriptRefPrivate_h
28
29#include <JavaScriptCore/JSContextRef.h>
30#include <JavaScriptCore/JSStringRef.h>
31#include <JavaScriptCore/JSValueRef.h>
32
33/*! @typedef JSScriptRef A JavaScript script reference. */
34typedef struct OpaqueJSScript* JSScriptRef;
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/*!
41 @function
42 @abstract Creates a script reference from an ascii string, without copying or taking ownership of the string
43 @param contextGroup The context group the script is to be used in.
44 @param url The source url to be reported in errors and exceptions.
45 @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.
46 @param source The source string. This is required to be pure ASCII and to never be deallocated.
47 @param length The length of the source string.
48 @param errorMessage A pointer to a JSStringRef in which to store the parse error message if the source is not valid. Pass NULL if you do not care to store an error message.
49 @param errorLine A pointer to an int in which to store the line number of a parser error. Pass NULL if you do not care to store an error line.
50 @result A JSScriptRef for the provided source, or NULL if any non-ASCII character is found in source or if the source is not a valid JavaScript program. Ownership follows the Create Rule.
51 @discussion Use this function to create a reusable script reference with a constant
52 buffer as the backing string. The source string must outlive the global context.
53 */
54JS_EXPORT JSScriptRef JSScriptCreateReferencingImmortalASCIIText(JSContextGroupRef contextGroup, JSStringRef url, int startingLineNumber, const char* source, size_t length, JSStringRef* errorMessage, int* errorLine);
55
56/*!
57 @function
58 @abstract Creates a script reference from a string
59 @param contextGroup The context group the script is to be used in.
60 @param url The source url to be reported in errors and exceptions.
61 @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.
62 @param source The source string.
63 @param errorMessage A pointer to a JSStringRef in which to store the parse error message if the source is not valid. Pass NULL if you do not care to store an error message.
64 @param errorLine A pointer to an int in which to store the line number of a parser error. Pass NULL if you do not care to store an error line.
65 @result A JSScriptRef for the provided source, or NULL is the source is not a valid JavaScript program. Ownership follows the Create Rule.
66 */
67JS_EXPORT JSScriptRef JSScriptCreateFromString(JSContextGroupRef contextGroup, JSStringRef url, int startingLineNumber, JSStringRef source, JSStringRef* errorMessage, int* errorLine);
68
69/*!
70 @function
71 @abstract Retains a JavaScript script.
72 @param script The script to retain.
73 */
74JS_EXPORT void JSScriptRetain(JSScriptRef script);
75
76/*!
77 @function
78 @abstract Releases a JavaScript script.
79 @param script The script to release.
80 */
81JS_EXPORT void JSScriptRelease(JSScriptRef script);
82
83/*!
84 @function
85 @abstract Evaluates a JavaScript script.
86 @param ctx The execution context to use.
87 @param script The JSScript to evaluate.
88 @param thisValue The value to use as "this" when evaluating the script.
89 @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.
90 @result The JSValue that results from evaluating script, or NULL if an exception is thrown.
91 */
92JS_EXPORT JSValueRef JSScriptEvaluate(JSContextRef ctx, JSScriptRef script, JSValueRef thisValue, JSValueRef* exception);
93
94
95#ifdef __cplusplus
96}
97#endif
98
99#endif /* JSScriptRefPrivate_h */
100