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