js/public/CompilationAndEvaluation.h

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