Changes between Version 8 and Version 9 of JavaScriptingAPI

Timestamp:

05/11/09 21:12:08 (14 years ago)

Author:

astalla

Comment:

--

JavaScriptingAPI

@@ -11 +11 @@
 == !ScriptEngine ==
 
-The main interface defined by JSR-223, {{{javax.script.ScriptEngine}}}, is implemented by the class [http://trac.common-lisp.net/armedbear/browser/trunk/abcl/src/org/armedbear/lisp/scripting/AbclScriptEngine.java org.armedbear.lisp.scripting.AbclScriptEngine]. !AbclScriptEngine is intended to be a singleton, even if it has a public constructor - which will probably be made protected in future versions of the engine. You can obtain an instance of !AbclScriptEngine using the [http://trac.common-lisp.net/armedbear/browser/trunk/abcl/src/org/armedbear/lisp/scripting/AbclScriptEngineFactory.java AbclScriptEngineFactory] or by using the service provider mechanism through !ScriptEngineManager (refer to the javax.script documentation).
+The main interface defined by JSR-223, {{{javax.script.ScriptEngine}}}, is implemented by the class [http://trac.common-lisp.net/armedbear/browser/trunk/abcl/src/org/armedbear/lisp/scripting/AbclScriptEngine.java org.armedbear.lisp.scripting.AbclScriptEngine]. !AbclScriptEngine is intended to be a singleton, and as such it has a protected constructor. You can obtain an instance of !AbclScriptEngine using the [http://trac.common-lisp.net/armedbear/browser/trunk/abcl/src/org/armedbear/lisp/scripting/AbclScriptEngineFactory.java AbclScriptEngineFactory] or by using the service provider mechanism through !ScriptEngineManager (refer to the javax.script documentation).
 
 === Configuration file ===
@@ -26 +26 @@
  * {{{*swank-port*}}} The port where Swank will listen for connections. Must be set if {{{*launch-swank-at-startup*}}} is true.
    * Default value: 4005
- * {{{*compile-using-temp-files*}}} Controls whether the script engine, through the Compilable interface, will use the Lisp file compiler or the runtime compiler. See Compilation below.
-   * Default value: T
 
 === Evaluation ===
 
-Code is read and evaluated in the package ABCL-SCRIPT-USER. This packages USEs the COMMON-LISP and ABCL-SCRIPT packages. Future versions of the script engine might make this default package configurable.
+Code is read and evaluated in the package ABCL-SCRIPT-USER. This packages USEs the COMMON-LISP, JAVA and ABCL-SCRIPT packages. Future versions of the script engine might make this default package configurable. The load function is used under the hood for evaluating code, and thus the same behavior of load is guaranteed. This allows, among other things, in-package forms change the package in which the loaded code is read.
+
+It is possible to evaluate code in what JSR-223 calls a "!ScriptContext" (basically a flat environment of name->value pairs). This context is used to establish special bindings for all the variables defined in it; since variable names are strings from Java's point of view, they are first interned using READ-FROM-STRING with, as usual, ABCL-SCRIPT-USER as the default package. Variables are declared special because CL's load, eval and compile functions work in a null lexical environment and would ignore non-special bindings.
+
+Contrary to what the function load does, evaluation of multiple forms returns the value of the last form.
 
 === Compilation ===
 
-!AbclScriptEngine implements the {{{javax.script.Compilable}}} interface. It supports two modes of compilation: temp-file-based and runtime compilation. Which one is chosen depends on the value of the {{{*compile-using-temp-files*}}} variable. Be aware that the two modes are not equivalent - they correspond respectively to the "file compiler" and the "runtime compiler" specified in the ANSI Common Lisp specification; refer to it for details. The reason both modes are provided is that it is possible that ABCL will run in scenarios where it won't be able to write files, e.g. as an applet or a Java !WebStart restricted application (currently ABCL cannot work in such scenarios, but in the future it might). However, since compilation based on temporary files is the Right Thing wrt the ANSI spec, it is the default. Compiled code, returned as a {{{javax.script.CompiledScript}}}, is read, compiled and executed in the ABCL-SCRIPT-USER package, like evaluated code.
+!AbclScriptEngine implements the {{{javax.script.Compilable}}} interface. Currently as of 2009-05-11 it only supports compilation using temporary files. It used to support compilation in-memory using the Lisp runtime compiler, but it had some issues - its behavior could not be assimilated to the temp-file-based in all cases, and thus support for it has been dropped. Compiled code, returned as a {{{javax.script.CompiledScript}}}, is read, compiled and executed by default in the ABCL-SCRIPT-USER package, like evaluated code. Differently from compiled code, though, due to the way the ABCL compiler works, compiled code contains no reference to top-level self-evaluating objects (like numbers or strings). Thus, when evaluated, a piece of compiled code will return the value of the last non-self-evaluating form: for example the code "(do-something) 42" will return 42 when interpreted, but will return the result of (do-something) when compiled and later evaluated. To ensure consistency of behavior between interpreted and compiled code, make sure the last form is always a compound form - at least (identity some-literal-object). Note that this issue should not matter in real code (in fact, the Common Lisp load function always returns T upon success; with JSR-223 this policy has been changed to make evaluation of small code snippets feasible).
 
 === Invocation of functions and methods ===