js-vm: Javascript virtual machine for Racket

js-vm provides tools to develop Racket programs that run in Javascript. It provides a Javascript runtime that interprets Racket bytecode, functions for building and testing packages of translated code, and libraries to use features of a web-browser’s environment.

This project is intimately related with Moby Scheme, as Moby Scheme uses js-vm as its underlying runtime.

1 Quick Start

This program is in a language that has been enriched with Javascript-specific functions. It can be partially evaluated in plain Racket, but evaluation will halt at the call to image-url because image-url constructs a image DOM element and needs to run in an Javascript context.

Once the program is saved, create a new file called "run.rkt" in the same working directory with the following contents:

#lang racket

(require (planet dyoo/js-vm:1:5))

(run-in-browser "test.rkt")

(read-line)

When this program is executed, run-in-browser will take "test.rkt" and translate it to run on the browser; a temporary web-server will opened and your browser’s window will open with the running program.

Finally, you can create zip packages by using create-zip-package. For example, modify "run.rkt" to be:

#lang racket

(require dyoo/js-vm:1:5)

(create-zip-package "test.rkt" "test.zip")

2 Examples

2.1 Falling ball

#lang planet dyoo/js-vm:1:5

; Simple falling ball example. A red ball falls down the screen

; until hitting the bottom.

(define-struct world (radius y))

; The dimensions of the screen:

(define WIDTH 320)

(define HEIGHT 480)

; The radius of the red circle.

(define RADIUS 15)

; The world is the distance from the top of the screen.

(define INITIAL-WORLD (make-world RADIUS 0))

; tick: world -> world

; Moves the ball down.

(define (tick w)

(make-world RADIUS (+ (world-y w) 5)))

; hits-floor?: world -> boolean

; Returns true when the distance reaches the screen height.

(define (hits-floor? w)

(>= (world-y w) HEIGHT))

; We have some simple test cases.

(check-expect (hits-floor? (make-world RADIUS 0)) false)

(check-expect (hits-floor? (make-world RADIUS HEIGHT)) true)

; render: world -> scene

; Produces a scene with the circle at a height described by the world.

(define (render w)

(place-image (circle RADIUS "solid" "red") (/ WIDTH 2) (world-y w)

(empty-scene WIDTH HEIGHT)))

; Start up a big bang, 15 frames a second.

(check-expect (big-bang INITIAL-WORLD

(on-tick tick 1/15)

(to-draw render)

(stop-when hits-floor?))

(make-world 15 480))

3 Running js-vm

At the moment, js-vm currently supports programs written in the (planet dyoo/js-vm:1:5/lang/wescheme) and (planet dyoo/js-vm:1:5/lang/base) languages; further development on js-vm will work toward supporting modules written in full Racket. require should work as long as the required modules, too, are in the supported languages.

4 WeScheme

It provides the bindings from (planet dyoo/js-vm:1:5/lang/base), (planet dyoo/js-vm:1:5/lang/posn), (planet dyoo/js-vm:1:5/image/image), (planet dyoo/js-vm:1:5/jsworld/jsworld), and (planet dyoo/js-vm:1:5/check-expect/check-expect). It also adds open-image-url and js-big-bang as aliases for image-url and big-bang respectively.

5 Jsworld

jsworld provides a world programming library that allows simple animation and games, as well as reactive HTML graphical user interfaces.

(require (planet dyoo/js-vm:1:5/jsworld/jsworld))

By default, the page that’s displayed contains a rendering of the world value. In the presence of an to-draw or to-draw-page handler, big-bang will show a customized view.

The majority of the handlers register different stimuli that can trigger changes to the world. One instance is on-tick, which registers a function to update the world on a clock tick.

When the big-bang computation terminates through a stop-when, the final world is returned as its value.

#lang planet dyoo/js-vm:1:5

(define WIDTH 320)

(define HEIGHT 480)

(define RADIUS 15)

(define INITIAL-WORLD 0)

(define (tick w)

(+ w 5))

(define (hits-floor? w)

(>= w HEIGHT))

(check-expect (hits-floor? 0) false)

(check-expect (hits-floor? HEIGHT) true)

(define (render w)

(place-image (circle RADIUS "solid" "red") (/ WIDTH 2) w

(empty-scene WIDTH HEIGHT)))

(big-bang INITIAL-WORLD

(on-tick tick 1/15)

(to-draw render)

(stop-when hits-floor?))

5.1 Jsworld Types

A dom-sexp describes the structure of a web page:

dom-sexp

=

(list dom-element dom-sexp ...)

a css-sexp describes the structure of a page’s styling:

css-sexp

=

(listof (cons (or dom-element string)               (listof attrib)))

Each of the dom-elements can take in an optional attribute list to assign to the new dom element; the common useful attribute is a key-value binding for an "id", which can be used to identify an element in the css-drawing function.

5.2 HTML user interface constructors

Here are the dom-element constructors.

6 Images

This module provides functions for creating images. The design of the library is meant to follow 2htdp/image.

(ellipse) → image?

(put-pinhole img x y) → image?

img : image?

x : real?

y : real?

Colors can be specified either by an RGB color structure, or by string name. Both are described now.

6.1 Available colors

7 Implementing Javascript Modules

Warning: the material in this section is unstable and likely to change.

7.1 Module Implementation in Javascript

// double.js

EXPORTS['double'] =

new types.PrimProc('double', 1, false, false, function(x) {

return jsnums.multiply(x, 2)});

Any module implemented with (planet dyoo/js-vm:1:5/lang/js-impl/js-impl) will provide bindings that require a Javascript context.

7.2 Conditional Module Implmentation in javascript

(require (planet dyoo/js-vm:1:5/lang/js-impl/js-conditional))

Any module implemented with (planet dyoo/js-vm:1:5/lang/js-conditional/js-conditional) can run either in a Racket or Javascript context.

8 Foreign Function Interface

9 Base language