DESIGN

=== Introduction

This document is supposed to be an overview of the current overall design,
not to be used for implementation details or specific algorithms. 
Feel free to discuss or amend any portion of this document.



=== The vision

To implement as much as possible in scheme; as little as possible in Go.

One of the reasons why (syntax-rules) was invented was to allow this.
Many parts of scheme expand to fundamental forms, such as: and, or,
case, cond, when, unless, etc. We should not implement these in Go.
However, pragmatism can be a good thing, so in a conflict between
generality and speed, speed should win.



=== The lexer

Traditionally, lisp and scheme lexers are customizable, allowing '#'
to be overridden to add syntax to the language, and while this may be
useful at some point, we may want a staged approach where this is
available to the end-user through some kind of preprocessing. I
don't think we should have full readtable support like in CL.

We might do something like replace number forms with procedures like this:

    #i... => (exact->inexact ...)
    #e... => (inexact->exact ...)
    #b... => (string->integer ... 2)
    #o... => (string->integer ... 8)
    #x... => (string->integer ... 16)
    ...+... => (make-rectangular ... ...)
    ...@... => (make-polar ... ...)
    .../... => (make/ ... ...)

before it gets to the parser, so as to simplify the grammar...



=== The parser

This would be implemented in "parse.y" and so should take the output
of the lexer and parse it. 



=== The program-interpreter

Must have current-environment, and a list of imported libraries,
and might even split the environment into 2 sections, one for
procedures and one for syntax, but I don't think thats a good idea.

Procedures should be evaluated using the same method as (eval),
and could either be implemented in Scheme or the FFI (see below).



=== The library-installer

This might be too early to think about libraries, the first few versions
should have some kind of builtin library for testing purposes.

Both R6RS/R7RS require that programs either
     - (import (rnrs)) ; R6RS
     - (import (scheme)) ; R7RS
to get the full functionality of the basic language.

The end goal should be a base language with only the following symbols:
    - define
    - if
    - import
    - lambda
    - quote
    - set!
available, until one of the above is imported. I'm not sure if it is
possible, but I'd like to find a way to implement quasiquote, unquote, 
and unquote-splicing using some kind of scheme code that's
run on the source tree at some point.

Another thing to consider is that there are hundreds of library syntaxes.
The way that Racket (DrScheme/MzScheme) solves this is it has a reader
syntax "#%module-begin" that is automatically wrapped around a library
before it is compiled/loaded. Any sub-language can write their own
definition of this syntax in order to make their library syntax conform
to Racket's builtin library syntax. Also, since Scheme has only had
libraries since R6RS, it is still evolving:
    - (library (my lib) ; R6RS
        (export f ...)
        (import ...)
        (define (f x) ...))
    - (define-library (my lib) ; R7RS
        (export f ...)
        (import ...)
        (begin
          (define (f x) ...)))
These two library syntaxes could be mapped to a droscheme-specific syntax
or we could pick one and convert the other to it.

Official description:

  ; R6RS

  (library <library name>
    (export <export spec> ...)
    (import <import spec> ...)
    <library body>)

  <export spec> =
    <identifier>
    (rename (<identifier1> <identifier2>) ...) -- I don't think we should support this

  <import spec> =
    <import set>
    (for <import set> <import level> ...) -- I don't think we should support this

  <import set> =
    <library name> -- must support
    <library reference> -- OMG so complicated, no version support
    (library <library reference>) -- I don't think we should support this
    (only <import set> <identifier> ...)    
    (except <import set> <identifier> ...)    
    (prefix <import set> <identifier> ...)    
    (rename <import set> (<identifier1> <identifier2>) ...)    

  ; R7RS

  (define-library <library name>
    <library declaration> ...)

  <library declaration> =
    (export <export spec> ...)
    (import <import spec> ...)
    (begin <library body>)
    (include <filename> ...)
    (include-ci <filename> ...)
    (cond-expand <cond-expand clause> ...)

  <export spec> =
    <identifier>
    (rename <identifier1> <identifier2>) -- I don't think we should support this

  <import spec> =
    <import set>

  <import set> =
    <library name>
    (only <import set> <identifier> ...)    
    (except <import set> <identifier> ...)    
    (prefix <import set> <identifier>)
    (rename <import set> (<identifier1> <identifier2>) ...)  

For example:

 (import
  (prefix
   (rename (only (scheme base) = < <= > >=)
           (= =?) (< <?) (<= <=?) (> >?) (>= >=?))
   fx))

would import the identifiers: fx=? fx<? fx<=? fx>? fx>=?
into the current library being defined.

There should be at least two libraries that have all builtin things,
and the rest of the libraries should match R6RS or R7RS:

(ds base) -- Droscheme derived procedures and syntaxes
(ds base syntax)
(ds builtin) -- core procedures and syntaxes -- NOT automatically imported
(ds builtin syntax) -- no need to import, it's builtin
(ds io)
(ds math)
(scheme base) ; R7RS draft
(scheme case-lambda)
(scheme char normalization)
(scheme char)
(scheme complex)
(scheme division)
(scheme eval)
(scheme file)
(scheme inexact)
(scheme lazy)
(scheme load)
(scheme process-context)
(scheme read)
(scheme repl)
(scheme time)
(scheme write)
(scheme)
(srfi 0)
(srfi 1)
(srfi 9)
(srfi 16)
(srfi 99)
(rnrs base) ; R6RS final
(rnrs arithmetic bitwise)
(rnrs arithmetic fixnums)
(rnrs arithmetic flonums)
(rnrs bytevectors)
(rnrs conditions)
(rnrs control)
(rnrs enums)
(rnrs exceptions)
(rnrs files)
(rnrs hashtables)
(rnrs io ports)
(rnrs io simple)
(rnrs lists)
(rnrs programs)
(rnrs records inspection)
(rnrs records procedural)
(rnrs records syntactic)
(rnrs sorting)
(rnrs syntax-case)
(rnrs unicode)
(rnrs)
(rnrs eval)
(rnrs mutable-pairs)
(rnrs mutable-strings)
(rnrs r5rs)



=== The foreign-function-interface

This will probably be needed to bootstrap anyways, so we might as well
make it well-designed for the end-user. The primary difference here
with other schemes is that this will be an FFI to Go, not C.

Every builtin function has the following function signature:

      func (Any) Any

the rationale behind this is that every scheme definition has the option
of giving a 'rest' parameter, either at the beginning, or at the end of the
formal parameter list, which must be a list structure.
.



=== Porting other scheme code

One posibility to get a lot of usability is to port SLIB or something similar
to be able to work in droscheme.



=== Multi-line REPL

There should be two conditions for an incomplete line:

  (1) Paren mismatch
  (2) Eval() error

the reason for this is that an error can occur with matching parens,
and a paren mismatch may eval without errors (e.g. (write "(")).



=== Error management

There are currently three techniques for error management:

  (1) second return
  (2) panic/recover
  (3) global variables

Of these three, I would prefer sticking with the first two, or even
explicitly preferring them in this order. yyParse() seems to require
global variables, so there may not be a choice there, and any builtin
function will require a panic instead of a second return. Another thing
to consider is that it is possible to convert between (1) and (2).

To convert from (1) to (2):

  func f() Any {
    ...
    thing, myerr := g()
    if myerr != nil { panic(err) }
    ...
  }

To convert from (2) to (1):

  func g() (value Any, err error) {
    defer func(){
      myerr := recover()
      if myerr != nil { err = myerr }
    }()
    ...
  }



=== Data Model

Ds type Go type	Scm type
-----   -------	-------
SBool	bool	boolean?
SChar	rune	char?
SNull   struct	null?
SPair   struct	pair?
SBinary []byte	bytevector?
SString []rune	string?
SSymbol string	symbol?
SVector []Any   vector?
SValues []Any   values?
STable  map[Any]Any

*Pair
*Env

SPrimSyntax
SCaseSyntax
SRuleSyntax
SPrim struct
SProc struct
SType struct
SBytePort
SCharPort
SFilePort