ABOUT ERR5RS

ERR5RS is an expeditious revision of the R5RS to fill part
of the gap that lies between the R5RS and R6RS [1,2,3].
ERR5RS extends the R5RS by adding

  * R6RS-compatible library and import syntax
  * dynamic loading of libraries
  * dynamic importing of libraries
  * repl-friendly semantics for top-level programs
  * a subset of R6RS lexical syntax
  * R6RS-compatible records, but with superior APIs

The most important thing to know about ERR5RS is that it is
a supplement to the R6RS, not a replacement.  ERR5RS makes
the most important innovations of the R6RS available for use
in read/eval-print loops and R5RS-style dynamic programs,
which are outside the scope of the R6RS.

The second most important thing to know about ERR5RS is that
it is being designed with portability in mind.  Its statement
of requirements and goals mentions several different aspects
of portability:

  * portability/reuse between R5RS and ERR5RS (backward compatibility)
  * portability/reuse between different implementations of ERR5RS
  * portability/reuse between ERR5RS and R6RS programs
  * ease of understanding
  * ease of implementation

ERR5RS libraries are portable because the mapping between
library names and files is not left up to implementations,
but is specified by the extended semantics of loading and
importing.

Portability of ERR5RS libraries and programs also depends
upon the availability and quality of ERR5RS-compatible
implementations.  Larceny v0.95 was the first implementation
of ERR5RS, and Larceny's users have a great opportunity to
influence the continuing evolution and acceptance of ERR5RS.


COMPILING THE ERR5RS/R6RS RUNTIME

If you are using Petit Larceny, you must pre-compile the
ERR5RS/R6RS runtime and standard libraries before you can
use Larceny's ERR5RS mode.  Follow the instructions for
step 4 of the process described in HOWTO-BUILD.

If you are using a binary distribution of native Larceny,
the ERR5RS/R6RS runtime and standard libraries should work
out of the box.  If you touch or modify any of the source
files in lib/R6RS, however, then your next attempt to run
Larceny in ERR5RS or R6RS mode is likely to generate a
warning about "loading source in favor of stale fasl file".
This message may be followed by a long series of error
messages about syntactic keywords used as a variable,
ending with the kind of error you'd expect to see when a
large R6RS program is fed to a Scheme compiler that was
expecting to see R5RS-compatible code.  To fix the
problem, repeat step 4 of HOWTO-BUILD.


ERR5RS MODE

To interact with Larceny's ERR5RS read/eval/print loop,
specify the -err5rs option on Larceny's command line:

    % larceny -err5rs
    Larceny v0.96 "Fluoridation" (...)
    ERR5RS mode (no libraries have been imported)

Since no libraries have been imported, the only forms you
can evaluate are constant literals, variable references
(but no variables have been imported!), procedure calls
(but no procedure values are accessible!), library
definitions, and import forms.  The first thing you'll
want to do is to import some of the pre-loaded libraries,
such as:

    > (import (rnrs base) (rnrs lists) (rnrs io simple))

Once you have imported (rnrs base) or a composite library
that includes it, you can evaluate definitions and use
all other syntax and variables you have imported:

    > (define two^7 (expt 2 (+ 3 4)))
    > two^7
    128


LIBRARY PATH

As an extension to ERR5RS, Larceny automatically loads
libraries when they are first imported, provided Larceny
can find the libraries in its library search path.  The
library search path defaults to a path that contains
the predefined libraries listed below, but one additional
directory can be added to the library search path using
Larceny's --path command-line option.

Autoloaded libraries must be defined in files that follow
Larceny's standard naming conventions for ERR5RS/R6RS
library files.  These naming conventions are described
in Larceny's user manual (see doc/user-manual.*).


DYNAMIC LOADING

To load top-level programs or unadorned R5RS-style code
from a file, you must first import a suitable load procedure:

    > (import (err5rs load))

Loading a library does not automatically import it:

    > (load "lib/R6RS/benchmarking.sch")
    > (time (vector-for-each + (make-vector 1000000 0)))

    Error: Undefined global variable "time".
    Entering debugger; type "?" for help.
    debug> q

To use the variables and syntax that are exported by an
explicitly loaded library, you must import that library
explicitly:

    > (import (larceny benchmarking))
    > (time (vector-for-each + (make-vector 1000000 0)))
    Words allocated: 3095752
    Words reclaimed: 0
    Elapsed time...: 111 ms (User: 104 ms; System: 8 ms)
    Elapsed GC time: 4 ms (CPU: 4 in 8 collections.)

Before you import a library or load a top-level program,
you must first load any nonstandard libraries it imports
unless those libraries will be found using Larceny's
library search path.

You do not have to import those libraries into the ERR5RS
top level, however, unless you want to use the variables
and syntax exported by those libraries in the expressions
and definitions you evaluate at the top level.


PREDEFINED LIBRARIES

For your convenience, Larceny pre-loads or autoloads all
of the standard R6RS libraries and several other libraries
besides, so you can import from those libraries without
having to load them yourself.  The predefined libraries
include:

  R6RS standard libraries:

    (rnrs base (6))                  ; R6RS chapter 9
    (rnrs unicode (6))               ; R6RS library chapter 1
    (rnrs bytevectors (6))           ; R6RS library chapter 2
    (rnrs lists (6))                 ; R6RS library chapter 3
    (rnrs sorting (6))               ; R6RS library chapter 4
    (rnrs control (6))               ; R6RS library chapter 5
    (rnrs exceptions (6))            ; R6RS library section 7.1
    (rnrs conditions (6))            ; R6RS library sections 7.2 and 7.3
    (rnrs io ports (6))              ; R6RS library sections 8.1 and 8.2
    (rnrs io simple (6))             ; R6RS library sections 8.1 and 8.3
    (rnrs files (6))                 ; R6RS library chapter 9
    (rnrs programs (6))              ; R6RS library chapter 10
    (rnrs arithmetic fixnums (6))    ; R6RS library section 11.2
    (rnrs arithmetic flonums (6))    ; R6RS library section 11.3
    (rnrs arithmetic bitwise (6))    ; R6RS library section 11.4
    (rnrs syntax-case (6))           ; R6RS library chapter 12
    (rnrs hashtables (6))            ; R6RS library chapter 13
    (rnrs enums)                     ; R6RS library chapter 14
    (rnrs (6))                       ; R6RS library chapter 15
    (rnrs eval (6))                  ; R6RS library chapter 16
    (rnrs mutable-pairs (6))         ; R6RS library chapter 17
    (rnrs mutable-strings (6))       ; R6RS library chapter 18
    (rnrs r5rs (6))                  ; R6RS library chapter 19

  R6RS standard libraries that are pre-loaded but deprecated in Larceny:

    (rnrs records procedural (6))    ; R6RS library section 6.3 (deprecated)
    (rnrs records inspection (6))    ; R6RS library section 6.4 (deprecated)
    (rnrs records syntactic)         ; R6RS library section 6.2 (deprecated)

  Other pre-loaded libraries:

    (err5rs records procedural)      ; ERR5RS records (procedural API)
    (err5rs records inspection)      ; ERR5RS records (inspection API)
    (err5rs records syntactic)       ; ERR5RS records (syntactic API)
    (err5rs load)                    ; ERR5RS load procedure
    (rnrs load)                      ; equivalent to (err5rs load)
    (larceny load)                   ; extension of (err5rs load)
    (larceny compiler)               ; separate compilation for ERR5RS/R6RS
    (larceny benchmarking)           ; timing facilities
    (r5rs)                           ; approximates the R5RS top level
    (explicit-renaming)              ; a macro system with explicit renaming


ACCESS TO LARCENY PROCEDURES

Larceny supports an extension to the ERR5RS that allows an
import form to import any R5RS procedure from Larceny's
R5RS-conforming top-level environment.  For examples of its
use, see lib/R6RS/larceny/benchmarking.sls.


PRECOMPILING ERR5RS/R6RS FILES

Larceny v0.96 allows separate compilation of ERR5RS/R6RS
libraries, top-level programs, and Scheme scripts.  The
compile-stale script will compile all .sls files that
reside within the directory from which it is invoked.
That is awkward to do manually, since a file should not
be compiled until all of the libraries that it imports
have been compiled.

For more information on separate compilation of ERR5RS
libraries and programs, see Larceny's user manual.

--------

[1] http://scheme-punks.org/wiki/index.php?title=ERR5RS:Charter
[2] http://www.schemers.org/Documents/Standards/R5RS/
[3] http://www.r6rs.org/
