JavaScript

_JavaScript_
_javascript_

The JavaScript Collection

This collection provides an implementation of the EcmaScript language
specified by ECMA-262, Edition 3, better known as JavaScript.

For license information, please see the file COPYING.LIB.


INSTALLATION ===================================================================

To use the JavaScript language level, simply install the PLaneT package from the
command-line with `planet -i' (see the PLaneT command-line tool docs).

To use the language level, restart DrScheme and select "JavaScript" from the
"Language..." menu.


DOCUMENTATION ==================================================================

Sorry I don't have any high-level documentation yet. Have you looked
at ECMA-262 Edition 3?

http://www.ecma-international.org/publications/standards/Ecma-262.htm


KNOWN LIMITATIONS ==============================================================

Likely to be fixed eventually:

- `eval' is not yet implemented
- the `toString' method for functions doesn't produce their source yet
- semantics of exceptions is probably not quite right (cf. the subtle
  issue of try-finally with no catch and a return in the finally)
- standard library virtually non-existent
- proper tail recursion is not yet implemented
- needs lots more unit tests

Unlikely to be fixed any time soon:

- numbers are probably not entirely faithful to spec
- regular expressions don't yet work at all
- there are absolutely no compiler optimizations yet -- should be
  spectacularly inefficient


DESIGN DECISIONS ===============================================================

REF TYPE: no expressions ever evaluate to refs at runtime. The spec
allows for the *possibility* that some implementations may allow
arbitrary expressions (particularly function calls) to evaluate to
refs, which means that all evaluation points that expect non-ref
values must explicitly dereference their inputs. But the spec does not
*require* an implementation to allow for this possibility. In the
interest of both a more efficient evaluation model and one which more
closely matches that of Scheme (the target of the compiler), only
those syntactic forms that explicitly produce references (variable
references, object property references, and computed object property
references) may be used on the left-hand side of an assignment. All
other expression forms appearing on the left-hand side of an
assignment are treated as compile-time errors.

BINDINGS AND `with': code that does not syntactically occur underneath
the `with' form is compiled to a much more efficient form that closely
matches Scheme's binding forms: almost all variables are lexically
scoped, with the notable exception of top-level bindings, which are
looked up dynamically in the global object. The compilation of `with'
is still faithful to the spec, but it results in much more inefficient
code: when evaluating the body of a `with' statement, the entire
lexical environment is copied into a runtime scope chain which
correctly contains the given object as a frame. Subsequent variable
references that syntactically occur within that `with' form are looked
up dynamically in this scope chain.


AVAILABLE MODULES ==============================================================

An input-source is one of:
  - path
  - string
  - input-port

_eval.ss_

(require (planet "eval.ss" ("dherman" "javascript.plt" <maj> <min>)))

> (make-javascript-namespace) :: -> javascript-namespace

Creates a new namespace that can be used as the optional argument to
the eval-* functions.

> (reset-javascript-namespace! ns) :: javascript-namespace -> any

Resets the standard library and global object to their initial state
within a given JavaScript namespace.

> (eval-javascript-string in [ns]) :: input-source * [javascript-namespace] -> any

Evaluates a JavaScript program from textual source.

> (eval-javascript-sexp sexp [ns]) :: s-expression * [javascript-namespace] -> any

Evaluates a JavaScript program in S-expression syntax.

> (eval-compiled-javascript stx [ns]) :: syntax * [javascript-namespace] -> any

Evaluates a compiled JavaScript program, as produced by
e.g. _compile-script_ from compiler/compile.ss.

_syntax/parse.ss_

(require (planet "parse.ss" ("dherman" "javascript.plt" <maj> <min>) "syntax"))

> parser<%> :: interface

The parser<%> interface defines the following methods:

> (parse-source-element) :: -> SourceElement

Parse a single source element.

> (parse-source-elements) :: -> (listof SourceElement)

Parse a list of source elements.

> (parse-expression) :: -> Expression

Parse a single expression.

> (skip-empty-tokens) :: -> any

Skip past any insignificant layout tokens.

The parser% class implements the parser<%> interface.

> parser% :: (implementationof parser<%>)

> (input-source? x) :: any -> boolean

> (input-source->input-port in) :: input-source -> input-port

> (input-source->parser in) :: input-source -> (instanceof parser<%>)

> (parse-script in) :: input-source -> (listof SourceElement)

> (parse-expression in) :: input-source -> Expression

> (parse-source-element in) :: input-source -> SourceElement

_syntax/ast.ss_

(require (planet "ast.ss" ("dherman" "javascript.plt" <maj> <min>) "syntax"))

Provides the data definitions for the JavaScript AST. See the source
for details.

_syntax/sexp.ss_

(require (planet "sexp.ss" ("dherman" "javascript.plt" <maj> <min>) "syntax"))

> (sexp? x) :: any -> boolean

Is the given argument an s-expresion?

The sexp.ss module provides the three following S-expression
"pretty-printers":

> (Expression->sexp expr) :: Expresion -> sexp
> (Statement->sexp stmt) :: Statement -> sexp
> (SourceElement->sexp elt) :: SourceElement -> sexp

The sexp.ss module provides the three following S-expression parsers:

> (sexp->Expression sexp) :: sexp -> Expression
> (sexp->Statement sexp) :: sexp -> Statement
> (sexp->SourceElement sexp) :: sexp -> SourceElement

MORE DOCUMENTATION COMING SOON:

_compiler/compile.ss_
_compiler/hoist.ss_


RELEASE HISTORY ================================================================

Version 0.9
2006-07-12

Created `eval-*' functions for interpreting JavaScript.
Should soon be able to implement JavaScript `eval'.
Improved tests.

Version 0.8
2006-07-12

Fixed bug involving nested `with' forms.
Corrected implementation of binding of `catch' variables.
Implemented all `let' forms.

Version 0.7
2006-07-11

Fixed some small type-related bugs with hoisting and compilation.

Version 0.6
2006-07-11

Fixed nested `with' bug.

Version 0.5
2006-07-11

New implementation of binding: no more evaluating to refs!
Nested `with' forms are broken.
Binding arrows are broken for top-level.

Version 0.4
2006-07-06

Got rid of unnecessary PLTCOLLECTS hack for testing.
Fixed bugs in sexp and pretty-print due to changed AST types.
Hoisting for ES4 `let' corrected.

Version 0.3
2006-06-28

Drastically improved binding implementation.
Addressed serious bugs in implementation of functions.
Began implementation for debug console (still disabled).

Version 0.2
2006-06-22

Added newly required `capability-value' to language level interface.
Bug fixed for pretty-printer (thanks to Jay).
Serialized language level settings.
Broke `let'.
(Internally: hoisting for ES4 `let' in place.)

Version 0.1
2006-02-23

Initial release.
Implements most of ECMA-262 Edition 3.
Primary limitations:
 Lack of regular expressions
 Lack of standard library
 No reflection or function reification