1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/* Functions for compiling and evaluating scripts. */
#ifndef js_CompilationAndEvaluation_h
#define js_CompilationAndEvaluation_h
#include <stddef.h> // size_t
#include <stdio.h> // FILE
#include "jstypes.h" // JS_PUBLIC_API
#include "js/RootingAPI.h" // JS::Handle, JS::MutableHandle
#include "js/TypeDecls.h"
struct JS_PUBLIC_API JSContext;
class JS_PUBLIC_API JSFunction;
class JS_PUBLIC_API JSObject;
class JS_PUBLIC_API JSScript;
namespace mozilla {
union Utf8Unit;
}
namespace JS {
class JS_PUBLIC_API InstantiateOptions;
class JS_PUBLIC_API ReadOnlyCompileOptions;
template <typename UnitT>
class SourceText;
} // namespace JS
/**
* Given a buffer, return false if the buffer might become a valid JavaScript
* script with the addition of more lines, or true if the validity of such a
* script is conclusively known (because it's the prefix of a valid script --
* and possibly the entirety of such a script).
*
* The intent of this function is to enable interactive compilation: accumulate
* lines in a buffer until JS_Utf8BufferIsCompilableUnit is true, then pass it
* to the compiler.
*
* The provided buffer is interpreted as UTF-8 data. An error is reported if
* a UTF-8 encoding error is encountered.
*/
extern JS_PUBLIC_API bool JS_Utf8BufferIsCompilableUnit(
JSContext* cx, JS::Handle<JSObject*> obj, const char* utf8, size_t length);
/*
* NB: JS_ExecuteScript and the JS::Evaluate APIs come in two flavors: either
* they use the global as the scope, or they take a HandleValueVector of
* objects to use as the scope chain. In the former case, the global is also
* used as the "this" keyword value and the variables object (ECMA parlance for
* where 'var' and 'function' bind names) of the execution context for script.
* In the latter case, the first object in the provided list is used, unless the
* list is empty, in which case the global is used.
*
* Why a runtime option? The alternative is to add APIs duplicating those
* for the other value of flags, and that doesn't seem worth the code bloat
* cost. Such new entry points would probably have less obvious names, too, so
* would not tend to be used. The ContextOptionsRef adjustment, OTOH, can be
* more easily hacked into existing code that does not depend on the bug; such
* code can continue to use the familiar JS::Evaluate, etc., entry points.
*/
/**
* Evaluate a script in the scope of the current global of cx.
*/
extern JS_PUBLIC_API bool JS_ExecuteScript(JSContext* cx,
JS::Handle<JSScript*> script,
JS::MutableHandle<JS::Value> rval);
extern JS_PUBLIC_API bool JS_ExecuteScript(JSContext* cx,
JS::Handle<JSScript*> script);
/**
* As above, but providing an explicit scope chain. envChain must not include
* the global object on it; that's implicit. It needs to contain the other
* objects that should end up on the script's scope chain.
*/
extern JS_PUBLIC_API bool JS_ExecuteScript(JSContext* cx,
JS::HandleObjectVector envChain,
JS::Handle<JSScript*> script,
JS::MutableHandle<JS::Value> rval);
extern JS_PUBLIC_API bool JS_ExecuteScript(JSContext* cx,
JS::HandleObjectVector envChain,
JS::Handle<JSScript*> script);
namespace JS {
/**
* Evaluate the given source buffer in the scope of the current global of cx,
* and return the completion value in |rval|.
*/
extern JS_PUBLIC_API bool Evaluate(JSContext* cx,
const ReadOnlyCompileOptions& options,
SourceText<char16_t>& srcBuf,
MutableHandle<Value> rval);
/**
* As above, but providing an explicit scope chain. envChain must not include
* the global object on it; that's implicit. It needs to contain the other
* objects that should end up on the script's scope chain.
*/
extern JS_PUBLIC_API bool Evaluate(JSContext* cx, HandleObjectVector envChain,
const ReadOnlyCompileOptions& options,
SourceText<char16_t>& srcBuf,
MutableHandle<Value> rval);
/**
* Evaluate the provided UTF-8 data in the scope of the current global of |cx|,
* and return the completion value in |rval|. If the data contains invalid
* UTF-8, an error is reported.
*/
extern JS_PUBLIC_API bool Evaluate(JSContext* cx,
const ReadOnlyCompileOptions& options,
SourceText<mozilla::Utf8Unit>& srcBuf,
MutableHandle<Value> rval);
/**
* Evaluate the UTF-8 contents of the file at the given path, and return the
* completion value in |rval|. (The path itself is UTF-8 encoded, too.) If
* the contents contain any malformed UTF-8, an error is reported.
*/
extern JS_PUBLIC_API bool EvaluateUtf8Path(
JSContext* cx, const ReadOnlyCompileOptions& options, const char* filename,
MutableHandle<Value> rval);
/**
* Compile the provided script using the given options. Return the script on
* success, or return null on failure (usually with an error reported).
*/
extern JS_PUBLIC_API JSScript* Compile(JSContext* cx,
const ReadOnlyCompileOptions& options,
SourceText<char16_t>& srcBuf);
/**
* Compile the provided script using the given options. Return the script on
* success, or return null on failure (usually with an error reported).
*/
extern JS_PUBLIC_API JSScript* Compile(JSContext* cx,
const ReadOnlyCompileOptions& options,
SourceText<mozilla::Utf8Unit>& srcBuf);
/**
* Compile the UTF-8 contents of the given file into a script. It is an error
* if the file contains invalid UTF-8. Return the script on success, or return
* null on failure (usually with an error reported).
*/
extern JS_PUBLIC_API JSScript* CompileUtf8File(
JSContext* cx, const ReadOnlyCompileOptions& options, FILE* file);
/**
* Compile the UTF-8 contents of the file at the given path into a script.
* (The path itself is in the system encoding, not [necessarily] UTF-8.) It
* is an error if the file's contents are invalid UTF-8. Return the script on
* success, or return null on failure (usually with an error reported).
*/
extern JS_PUBLIC_API JSScript* CompileUtf8Path(
JSContext* cx, const ReadOnlyCompileOptions& options, const char* filename);
/**
* Compile a function with envChain plus the global as its scope chain.
* envChain must contain objects in the current compartment of cx. The actual
* scope chain used for the function will consist of With wrappers for those
* objects, followed by the current global of the compartment cx is in. This
* global must not be explicitly included in the scope chain.
*/
extern JS_PUBLIC_API JSFunction* CompileFunction(
JSContext* cx, HandleObjectVector envChain,
const ReadOnlyCompileOptions& options, const char* name, unsigned nargs,
const char* const* argnames, SourceText<char16_t>& srcBuf);
/**
* Compile a function with envChain plus the global as its scope chain.
* envChain must contain objects in the current compartment of cx. The actual
* scope chain used for the function will consist of With wrappers for those
* objects, followed by the current global of the compartment cx is in. This
* global must not be explicitly included in the scope chain.
*/
extern JS_PUBLIC_API JSFunction* CompileFunction(
JSContext* cx, HandleObjectVector envChain,
const ReadOnlyCompileOptions& options, const char* name, unsigned nargs,
const char* const* argnames, SourceText<mozilla::Utf8Unit>& srcBuf);
/**
* Identical to the CompileFunction overload above for UTF-8, but with
* Rust-friendly ergonomics.
*/
extern JS_PUBLIC_API JSFunction* CompileFunctionUtf8(
JSContext* cx, HandleObjectVector envChain,
const ReadOnlyCompileOptions& options, const char* name, unsigned nargs,
const char* const* argnames, const char* utf8, size_t length);
/*
* For a script compiled with the hideScriptFromDebugger option, expose the
* script to the debugger by calling the debugger's onNewScript hook.
*/
extern JS_PUBLIC_API void ExposeScriptToDebugger(JSContext* cx,
Handle<JSScript*> script);
/*
* JSScripts have associated with them (via their ScriptSourceObjects) some
* metadata used by the debugger. The following API functions are used to set
* that metadata on scripts, functions and modules.
*
* The metadata consists of:
* - A privateValue, which is used to keep some object value associated
* with the script.
* - The elementAttributeName is used by Gecko
* - The introductionScript is used by the debugger to identify which
* script created which. Only set for dynamicaly generated scripts.
* - scriptOrModule is used to transfer private value metadata from
* script to script
*
* Callers using UpdateDebugMetaData need to have set deferDebugMetadata
* in the compile options; this hides the script from the debugger until
* the debug metadata is provided by the UpdateDebugMetadata call.
*/
extern JS_PUBLIC_API bool UpdateDebugMetadata(
JSContext* cx, Handle<JSScript*> script, const InstantiateOptions& options,
HandleValue privateValue, HandleString elementAttributeName,
HandleScript introScript, HandleScript scriptOrModule);
} /* namespace JS */
#endif /* js_CompilationAndEvaluation_h */
|
