[[R6rsChapter]]

R6RS Standard Libraries
-----------------------

This chapter explains which features of the R6RS standard
libraries are available in each of Larceny's major modes
of execution.

Larceny was the first substantially complete implementation
of the R6RS.  Any R6RS features that are missing from
Larceny's R6RS mode
are missing because of bugs or because the features are
deprecated in Larceny.
////////////////////////////////////////////////////////////////
The most up-to-date listing of Larceny's known deviations
from the R6RS standard can be found on the web page
that describes the current status of
https://github.com/larcenists/larceny/wiki/DargoMode[Larceny's R6RS-compatible mode].
////////////////////////////////////////////////////////////////

Larceny is R6RS-compatible but not R6RS-conforming.
When Larceny is said to support a feature of the R6RS,
that means the feature is present and will behave as
specified by the R6RS so long as no exception is raised
or expected.
Larceny does not always raise the specific conditions
specified by the R6RS, and does not perform all of the
checking for portability problems that is mandated by
the R6RS.  These deviations do not affect the execution
of production code, and do not compromise Larceny's
traditional safety.

For example, Larceny has extended the R6RS `library` syntax to
allow R6RS libraries to import R7RS libraries even when the
names of those imported libraries use the more liberal R7RS
syntax.

Furthermore, Larceny has extended several R6RS procedures so
they behave as specified by the newer R7RS (small) standard.
In Larceny, for example, the `utf8->string` procedure
accepts one, two, or three arguments,
and the `finite?` procedure accepts any object as its argument.
According to the R6RS, `utf8->string` _must_ raise an
exception when passed more than one argument, and
`finite?` _must_ raise an exception if it detects an
argument that is not a real number.  Although the R6RS
says these exceptions are "absolute requirements", they
interfere with interoperability between R6RS and R7RS code,
and are best honored in the breach.


[[R6rsBaseSection]]

Base library
~~~~~~~~~~~~

R7RS and R6RS modes support all procedures and syntaxes
exported by the `(rnrs base)` library.

Larceny's R5RS mode does not support `library`, `import`, or
`identifier-syntax`.

[NOTE]
================================================================
As of v0.99, Larceny ignores the R6RS `for` and `meta` keywords
of R6RS `library` syntax, which were intended to enforce proper
phasing in libraries and programs that define `syntax-case` macros.
Several other implementations of the R6RS have been ignoring those
keywords, and there is growing consensus that they are unnecessary
and unhelpful.
================================================================

[NOTE]
================================================================
The semantics of `quasiquote`, `let-syntax`, and `letrec-syntax`
differ between the R5RS, R6RS, and R7RS.  Larceny's R5RS mode
still supports the R5RS semantics.  R7RS and R6RS modes support
the R6RS semantics.
================================================================


[[R6rsUnicodeSection]]

Unicode
~~~~~~~

All of Larceny's modes support all features of the `(rnrs unicode)`
library.

Larceny v1.3 conforms to
<<Standards, The Unicode Standard>>, Version 7.0.


[[BytevectorsLibrary]]
[[R6rsBytevectorsSection]]

Bytevectors
~~~~~~~~~~~

R7RS and R6RS modes support all procedures and syntaxes
exported by `(rnrs bytevectors)`, but the `endianness`
syntax is deprecated because it is redundant with `quote`.
Larceny's R5RS mode does not support `endianness`.

In Larceny, any symbol names a supported endianness.
The symbols `big` and `little` have their expected meanings.
All other symbols mean `(native-endianness)` with respect
to integer operations, but mean the opposite of
`(native-endianness)` with respect to
<<Standards, IEEE-754>> operations.
For string operations, the endianness must be the symbol
`big` or the symbol `little`.  All of these extensions are
permitted by the R6RS standard.

Larceny's `utf16->string` and `utf32->string` accept one,
two, or three arguments.  The R6RS specification of these
procedures does not allow them to accept a single argument,
but that is believed to be an error in the R6RS.


[[R6rsListsSection]]

Lists
~~~~~

All of Larceny's modes support all features of the
`(rnrs lists)` library.


[[R6rsSortingSection]]

Sorting
~~~~~~~

All of Larceny's modes support all features of the
`(rnrs sorting)` library.


[[R6rsControlSection]]

Control
~~~~~~~

All of Larceny's modes support all features of the
`(rnrs control)` library.


[[R6rsRecordsSection]]

Records
~~~~~~~

R7RS and R6RS modes support all procedures and syntaxes
exported by
`(rnrs records procedural)`,
`(rnrs records inspection)`, and
`(rnrs records syntactic)`.

Those libraries are deprecated, however;
the `make-record-constructor-descriptor` procedure does
not simplify unusually complex cases enough to justify
the complexity it adds to typical cases, and
the entire syntactic layer is gratuitously incompatible
with the procedural layer.

Larceny extends the R7RS `define-record-type` syntax exported
by `(scheme base)` to accept the deprecated R6RS syntax, and
extends the deprecated `define-record-type` syntax exported
by `(rnrs records syntactic)` to accept R7RS syntax.
Larceny's unification of the two syntaxes within a single
implementation of `define-record-type` allows libraries and
programs to import both `(scheme base)` and `(rnrs)` without
having to rename one version of `define-record-type`.

Larceny also extends its unified R7RS/R6RS `define-record-type`
to support all features of `(srfi :99 records syntactic)` and
`(srfi 131)`.
So long as the deprecated R6RS syntax is not used, Larceny's
`define-record-type` is fully compatible with the procedural
layers defined by `(srfi :99 records procedural)` and by
`(rnrs records procedural)`.

Larceny's R5RS mode supports all features of the deprecated
`(rnrs records procedural)` and `(rnrs records inspection)`
libraries.  R5RS mode does not support `(rnrs records syntactic)`.

All of Larceny's modes support all features of the
<<Err5rsRecordsProceduralSection, `(err5rs records procedural)`>>
and
<<Err5rsRecordsInspectionSection, `(err5rs records inspection)`>>
libraries.  R7RS and R6RS modes also support the
<<Err5rsRecordsSyntacticSection, `(err5rs records syntactic)`>>
library.
These libraries are equivalent to the
`(srfi :99 records procedural)`,
`(srfi :99 records inspection)`, and
`(srfi :99 records syntactic)` libraries.

The record definition syntax of
http://srfi.schemers.org/srfi-9/[SRFI 9]
is a proper subset
of the syntax provided by the `(err5rs records syntactic)`
library.  In R5RS mode, SRFI 9 can be loaded dynamically
using the
<<require, `require`>> procedure:

----------------------------------------------------------------
    > (require 'srfi-9)
----------------------------------------------------------------

We recommend the R7RS, SRFI 9, and/or SRFI 131 libraries be used instead
of the corresponding R6RS libraries.

[WARNING]
================================================================
The R6RS spouts some tendentious nonsense about procedural
records being slower than syntactic records, but this is not
true of Larceny's records, and is unlikely to be true of other
implementations either.
================================================================

[WARNING]
================================================================
Larceny continues to support its old-style
records, which are almost but not quite compatible
with R7RS and R6RS records.  This can be confusing,
since some of Larceny's procedures have the same names
as R6RS procedures.  That has made it necessary to overload
those procedures to work with both old-style and R6RS
records.  We apologize for the mess.
================================================================


[[R6rsExceptionsSection]]
[[R6rsConditionsSection]]

Exceptions and conditions
~~~~~~~~~~~~~~~~~~~~~~~~~

All of Larceny's modes support all features of the
`(rnrs exceptions)` and `(rnrs conditions)` libraries.


[[R6rsIoSection]]

Input and output
~~~~~~~~~~~~~~~~

R7RS and R6RS modes support all names exported by the
`(rnrs io ports)`, `(rnrs io simple)`, and
`(rnrs files)` libraries.

The `buffer-mode`, `eol-style`, and `error-handling-mode`
syntaxes are deprecated because they are redundant
with `quote`.  Larceny may provide these deprecated syntaxes
in the form of procedures rather than syntax, but this
deviation from R6RS semantics cannot be detected by
portable R6RS programs.

Larceny's R5RS mode supports all non-deprecated features
of those libraries.

Larceny supports four distinct buffer modes: `none`,
`line`, `datum`, and `block`.  The R6RS requires
the `buffer-mode` syntax to raise an exception for the
`datum` buffer mode, which is the buffer mode Larceny
uses for interactive output ports.

In Larceny, any symbol names a supported end-of-line
style.  All end-of-line and error-handling-mode symbols
whose meanings are not described by the R6RS have
locale-dependent meanings, which is an extension
permitted by the R6RS standard.

Although Larceny supports the UTF-16 codec, it is not
really useful on Windows machines (where it should be
most useful) because Larceny's low-level file system
mimics a byte-oriented Unix file system even on
Windows.  This problem should be addressed in some
future version of Larceny.

The most up-to-date list of known deviations from R6RS
io semantics can be found on the web page
that describes the current status of
https://github.com/larcenists/larceny/wiki/DargoMode[Larceny's R6RS-compatible mode].


[[R6rsProgramsSection]]

Programs
~~~~~~~~

R7RS and R6RS modes support the `(rnrs programs)` library.

Larceny's R5RS mode provides the `exit` procedure but
not the `command-line` procedure of that library.
Larceny's traditional `command-line-arguments` procedure
can be used to implement an approximation to `command-line`.
For a definition, see `lib/R6RS/rnrs/programs.sls`.


[[R6rsArithmeticSection]]

Arithmetic
~~~~~~~~~~

All of Larceny's modes support all features of the
`(rnrs arithmetic fixnums)`,
`(rnrs arithmetic flonums)`, and
`(rnrs arithmetic bitwise)`
libraries.

[NOTE]
================================================================
R6RS fixnum and flonum operations may be slower than the
corresponding generic operations, since the fixnum and flonum
operations are required to check their arguments and may also
have to check their results.
Isolated operations in small micro-benchmarks are likely to
be slower than groups of similar operations in larger programs,
however, because Larceny's compiler removes redundant checks
and propagates type information.
================================================================


[[R6rsSyntaxCaseSection]]

Syntax-case
~~~~~~~~~~~

R7RS and R6RS modes support the `(rnrs syntax-case)` library.
Larceny's R5RS mode does not.


[[R6rsHashtablesSection]]

Hashtables
~~~~~~~~~~

All of Larceny's modes support all features of the
`(rnrs hashtables)` library.

[NOTE]
================================================================
Larceny's traditional `make-hashtable` procedure has been
renamed to `make-oldstyle-hashtable`.
================================================================

[NOTE]
================================================================
When you use Larceny's R5RS or R7RS mode to dump a heap image
that contains `eq?` or `eqv?` hashtables you have created, they
are automatically reset so they will
rehash themselves whenever you begin a new session with the
dumped heap.
================================================================


[[R6rsEnumerationsSection]]

Enumeration sets
~~~~~~~~~~~~~~~~

R7RS and R6RS modes support the `(rnrs enums)` library.
Larceny's R5RS mode provides all of the procedures exported by
`(rnrs enums)` but does not provide the `define-enumeration`
syntax.


[[R6rsEvalSection]]

Eval
~~~~

R7RS and R6RS modes support the `(rnrs eval)` library.
Larceny's R5RS mode provides an R5RS-compatible eval procedure,
not an R6RS-compatible eval procedure, and does not provide the
`environment` procedure.


[[R6rsMutablePairsSection]]
[[R6rsMutableStringsSection]]

Mutable pairs and strings
~~~~~~~~~~~~~~~~~~~~~~~~~

All of Larceny's modes support all features of the
`(rnrs mutable-pairs)` and `(rnrs mutable-strings)` libraries.


[[R6rsR5rsSection]]

R5RS
~~~~

All of Larceny's modes support all features of the
`(rnrs r5rs)` library.


