summaryrefslogtreecommitdiffstats
path: root/js/public/CompilationAndEvaluation.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--js/public/CompilationAndEvaluation.h233
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 */