#lang scribble/doc @begin[(require scribble/manual) (require scribble/eval) (require scribble/basic) (require (for-label "../main.ss")) (require "utils.ss")] @title[#:tag "intro"]{JavaScript for PLT Scheme} This package is an implementation of the ECMAScript language specified by @link["http://www.ecma-international.org/publications/standards/Ecma-262.htm"]{ECMA-262 Edition 3}, better known as JavaScript. @section[#:tag "started"]{Getting Started} The easiest way to get started using JavaScript for PLT Scheme is with the main module: @defmodule[(planet dherman/javascript:6)] This module provides everything in the entire package. Subsequent sections of this manual describe the functionality of the individual libraries included, which can also be required individually. @examples[(require (planet dherman/javascript:6)) (js-eval "print(40 + 2)") (require (planet dherman/pprint:4)) (pretty-print (format-term (parse-source-element "while (true) { print('break!'); break }")))] @section[#:tag "libraries"]{Libraries Provided by this Package} This package includes: @itemize[ @item{A library for lexing and parsing JavaScript--see @secref["parse"]} @item{An extensible hierarchy of structure definitions for representing JavaScript abstract syntax--see @secref["ast"]} @item{A library for pretty-printing JavaScript to text--see @secref["print"]} @item{A library for compiling JavaScript to PLT Scheme--see @secref["compile"]} @item{A library implementing the JavaScript runtime, including a representation of JavaScript values in Scheme as well as the standard JavaScript library--see @secref["runtime"]} @item{A library for evaluating JavaScript programs--see @secref["eval"]} @item{A library of configuration parameters--see @secref["config"]} ] @section[#:tag "language"]{JavaScript Language for DrScheme} Installing this PLaneT package also automatically registers a DrScheme language called @tt{JavaScript}, filed under @tt{Experimental Languages}. Selecting the @tt{JavaScript} language from DrScheme's @tt{Language} menu allows you to create and load JavaScript programs and interact with JavaScript at the REPL. @section[#:tag "design"]{Design Choices} @itemize[ @item{@bold{Ref type}: no expressions ever evaluate to refs at runtime. The standard allows for this possibility, but does not require it. This allows for a more efficient model of variable reference and assignment, one which matches Scheme's more closely.} @item{@bold{Bindings and @tt{with}}: code that does not occur in the syntactic context of a @tt{with} statement is compiled more efficiently, using Scheme's lexical scope. Compilation of @tt{with} still complies with the standard, but is compiled to a much more inefficient form that creates a runtime representation of the environment as a linked list of objects.} @item{@bold{Proto}: I have not exposed the internal @tt{[[Prototype]]} property of objects, e.g. via a @tt{__proto__} property. I may choose to do so in a read-only form later. See @bugref[41].} ] @section[#:tag "limitations"]{Known Limitations} Some limitations that are likely to be fixed eventually: @itemize[ @item{The @tt{toString} method for functions doesn't produce their source (see @bugref[34]).} @item{There may be some semantic issues with exceptions (see @bugref[35]): @itemize[ @item{@tt{return} from @tt{finally} blocks} @item{suspicious uses of @scheme[dynamic-wind]}]} @item{The JavaScript standard library is stubbed but mostly unimplemented (see @bugref[36]).} @item{Proper tail recursion is not implemented (see @bugref[37]).} ] Some limitations that are less likely to be fixed any time soon: @itemize[ @item{Numbers are not faithful to the spec; they are just represented as Scheme bignums (see @bugref[38]).} @item{Regular expressions don't work at all (see @bugref[39]).} @item{I've not done any profiling or optimizing.} ] @section[#:tag "feedback"]{Feedback and Bug Reports} Before sending feedback or bug reports, please consult the @link["http://planet.plt-scheme.org/trac/query?status=accepted&status=assigned&status=needinfo&status=new&status=reopened&component=dherman%2Fjavascript.plt&order=priority&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component" "current set of registered issues"]. If you cannot find your issue there, feel free to @link["http://planet.plt-scheme.org/trac/newticket?component=dherman/javascript.plt&owner=dherman"]{file a new bug report} in the online issue database. Any other feedback may be emailed to me, Dave Herman, at @link["mailto:dherman@ccs.neu.edu" "dherman@ccs.neu.edu"]. @section[#:tag "acknowledgments"]{Acknowledgments} This package was developed by me, Dave Herman. I thank Michael Greenberg, Dave Gurnell, Leo Meyerovich, and Jay McCarthy for their helpful feedback. I also thank Richard Cobbe, Ryan Culpepper, and Sam Tobin-Hochstadt for helping me with my many technical questions. @include-section["history.scrbl"]