Document host-defined realm/script API (#644)

Define the expected behavior of new host-defined utilities. These will
facilitate forthcoming tests that concern cross-realm and cross-script
semantics (which are currently untestable using standard ECMAScript
alone).

1 files changed, 26 insertions, 0 deletions

diff --git a/INTERPRETING.md b/INTERPRETING.md
index ed76fae8e..8ebaa8e47 100644
--- a/INTERPRETING.md
+++ b/INTERPRETING.md
@@ -34,6 +34,32 @@ properties of the global scope prior to test execution.
 - **`print`** A function that exposes the string value of its first argument to
   the test runner. This is used as a communication mechanism for asynchronous
   tests (via the `async` flag, described below).
+- **`$`** An ordinary object with the following properties:
+  - **`createRealm`** - a function which creates a new [ECMAScript
+    Realm](https://tc39.github.io/ecma262/2016/#sec-code-realms),
+    defines this API on the new realm's global object, and returns the `$`
+    property of the new realm's global object
+  - **`detachArrayBuffer`** - a function which implements [the
+    DetachArrayBuffer abstract
+    operation](https://tc39.github.io/ecma262/2016/#sec-detacharraybuffer)
+  - **`evalScript`** - a function which accepts a string value as its first
+    argument and executes is as [an ECMAScript
+    script](https://tc39.github.io/ecma262/2016/#sec-scripts) according to the
+    following algorithm:
+
+        1. Let hostDefined be any host-defined values for the provided
+           sourceText (obtained in an implementation dependent manner)
+        2. Let realm be the current Realm Record.
+        3. Let s be ParseScript(sourceText, realm, hostDefined).
+        4. If s is a List of errors, then
+           a. Let error be the first element of s.
+           b. Return
+              Completion{[[Type]]: throw, [[Value]]: error, [[Target]]: empty}.
+        5. Let status be ScriptEvaluation(s).
+        6. Return Completion(status).
+
+  - **`global`** - a reference to the global object on which `$` was initially
+    defined
 
 ### Strict Mode