Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 233 insertions, 0 deletions

diff --git a/js/public/CompilationAndEvaluation.h b/js/public/CompilationAndEvaluation.h
new file mode 100644
index 0000000000..ce0090dea9
--- /dev/null
+++ b/js/public/CompilationAndEvaluation.h
@@ -0,0 +1,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 */