Moosky v0.1
A lightweight Scheme^6 to Javascript compiler written in Javascript.


COPYRIGHT

Copyright 2010 Pat M. Lasswell.  All rights reserved.


LICENSE

Moosky is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

Moosky is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Moosky.  If not, see <http://www.gnu.org/licenses/>.



CONTENTS

1. Differences From R6RS
  1.1 Features Not Supported
  1.2 Extensions
    1.2.1 Dotted Symbols
    1.2.2 Javascript/Scheme Interleaving
    1.2.3 syntax/define-macro

2. Usage
  2.1 Requirements
  2.2 Client
  2.3 Server

3. Components
  3.1 Moosky
  3.2 Moosky.Cons
  3.3 Moosky.read
  3.4 Moosky.compile
  3.5 Moosky.Top
  3.6 Moosky.TokenClasses

4. Implementation
  4.1 Frames and Scope
  4.2 Internal Representation
  4.3 Object Code
  4.4 Relationship With Javascript


5. TODO



1. Differences From R6RS


1.1 Features Not Supported

Continuations
Ports
Numeric Tower (in particular, rationals and complex numbers)
Hygienic macros: define-syntax, etc

1.2 Extensions


1.2.1 Dotted Symbols

In R6RS foo.bar is an acceptible symbol with no special handling.  In
Moosky, to allow easy access to Javascript objects, symbols with a '.'
in them are assumed to refer to objects in the Javascript namespace.
Hence 'Hello, World!' can be as simple as

(window.alert "Hello, World!")


1.2.2 Javascript/Scheme Interleaving

Javascript can be inserted directly into Scheme code by quoting with
braces.  Both simple inline quotes and extended multiline quotes are
supported.  Furthermore, Scheme can be inserted into these blocks
using @( ) or @^( ) expressions.

Single line Javscript starts with an open brace.

(define foo { new Foo() })

Nested braces are not allowed.  Thus

(map { function(a) { return a.split(','); } } args)

won't fly, but

(map #{ function(a) { return a.split(','); } }# args)

is just fine.  Nesting of #{ }# is not currently supported.

To interpolate scheme code into javascript code, use @( ) or @^( ). A
few examples will probably suffice to demonstrate how this works:

{ @(parent-of elem).nextSibling }

will evaluate (parent-of elem) and access the nextSibling member of
the resulting object.  To get next sibling of elem, use the splicing
interpolator @^( ):

{ @^(elem).nextSibling }

This evaluates elem (as opposed to (elem), which would treat elem as a
procedure), and returns the nextSibling member of that object.  One
last item of note is splicing a list:

{ str.splice(@^(start end)) }

start and end will be evaluated, and the results interpolated
separated by ', ', making it simple to build argument lists.  Note,
however, that this a syntatic conversion, not a runtime-value
conversion, so that if we have

{ str.splice(@^(params)) }

where params evaluates to a list, then the result will NOT be a
comma separated list, but a reference to a Moosky list.


1.2.3 define-macro

R6RS specifies a hygienic macro system using define-syntax,
syntax-rules, let-syntax, and letrec-syntax.  It is very powerful, and
relatively easy to use, but at the cost of being a rather large chunk
of software.  The old define-macro system, while having some rather
nasty sharp edges, is lightweight, genuinely simple, and compact.
I've included (gensym [label]) as well.  I have a hygienic macro
package written in Scheme, and I'll add it later as an optional
package.


2. Usage

Add scripts to your page with type="text/moosky".  If they precede
moosky.js in the header, they will be automatically executed once
Moosky loads.

5. TODO

5.1 Misc

investigate using iframes to install REPL in arbitrary web page
  1. using bookmarklet insert iframe with href to moosky.org
    and a parameter indicating the domain of the target page
  2. load moosky source from moosky.org, instantiate moosky.
  3. change document domain to hosting page
  4. create repl

(compile "file://home/pat/src/moosky/r6rs-list.ss")
  produces a new div with text of the result, suitable for uploading
  without full Moosky.

provide quasiquote facility that respects syntax

History
  commands
  results

Keymap
  key --> fn

Console
  keymap
  history
  prompt

Display
  element
  commands
  caret control
  add text
  insert/delete

Create moosky-runtime.js.
  1. strip out lexer, parser, emitter, html.
  2. reduce remainder to what is actually used by compile code
  3. offer runtime w/ error checking and w/o
  ==> 3 versions runtime-debug (included with lexer, parser, etc)
                 runtime-checked (with asserts and errors)
                 runtime-bare (all limits checking removed)

(let loop ...) --> (function () { while () { ... } })()
  where all (loop ...) are in tail position
  (loop ...) --> set! ... {continue;}
  (begin
    (form) ...
    (loop ...)
  --> (emitted form), ...;
      set! ...
      continue;

  (if (test)
    (form)
    (loop ...)
  --> (if (emitted test)
          return (emitted form)

  and/or ... reduce to if


error
assertion-violation
assert
moosky.org
basic website


5.2 Libraries

R6RS Records
DOM
CSS
XHR

6 Architecture and Design

6.1 Bare and Safe

Basic functionality is implemented with two safety levels.  Bare
provides no error checking and throws no exceptions other than those
provided by the browser's script engine.  Safe wraps the bare code
with error checking and exception handling.  It is intended that safe
be used for development and testing, and once the code has been
thoroughly checked, that bare be used for deployment.  Safe and bare
have identical api and identical semantics, save for the exceptions
thrown by safe.  Therefore, code intended for bare deployment should
not rely on exceptions thrown by safe.

7. Coding Standards

Generally, indentation is with spaces, not tabs. In Javascript/ES6,
indents are 4 spaces wide. In scheme, they are whatever Emacs/paredit
indents them to.

7.1 Javascript

Files ending in ".js" are in plain old Javascript, archaic version.
This project started in 2010 when Node.js was less than a year old,
when most everything was hand rolled. That style will persist there.

7.2 ES6

ES6 files have the ".mjs" extension and may include modules, classes,
the arrow operator, const and all that.