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