[Guile-commits] 01/01: Add R7RS documentation and --r7rs command-line option

[Andy Wingo]

wingo pushed a commit to branch wip-r7rs
in repository guile.

commit b634071dd4c2401616c78d2a20471698123a23ca
Author: Andy Wingo <address@hidden>
Date:   Sun Nov 17 15:26:23 2019 +0100

    Add R7RS documentation and --r7rs command-line option
    
    * doc/ref/Makefile.am: Add r7rs.texi.
    * doc/ref/guile-invoke.texi (Command-line Options): Document --r7rs.
    * doc/ref/guile.texi (Guile Modules): Link to R7RS.
    * doc/ref/intro.texi (Guile and Scheme): Update for R7RS support.
    * doc/ref/r7rs.texi: New file.
    * doc/ref/scheme-intro.texi (Guile Scheme): Update for R7RS.
    * module/ice-9/command-line.scm (*usage*, compile-shell-switches): Add
      --r7rs option.
---
 doc/ref/Makefile.am           |   3 +-
 doc/ref/api-binding.texi      |  10 +--
 doc/ref/guile-invoke.texi     |   5 ++
 doc/ref/guile.texi            |   2 +
 doc/ref/intro.texi            |  58 ++++++++++++------
 doc/ref/r7rs.texi             | 137 ++++++++++++++++++++++++++++++++++++++++++
 doc/ref/scheme-intro.texi     |   8 +--
 module/ice-9/command-line.scm |   6 ++
 8 files changed, 201 insertions(+), 28 deletions(-)

diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index 05393cd..2f4b8ca 100644
--- a/doc/ref/Makefile.am
+++ b/doc/ref/Makefile.am
@@ -1,7 +1,7 @@
 ## Process this file with Automake to create Makefile.in
 ##
 ##   Copyright (C) 1998, 2004, 2006, 2008, 2009, 2010,
-##     2011, 2013, 2014 Free Software Foundation, Inc.
+##     2011, 2013, 2014, 2019 Free Software Foundation, Inc.
 ##
 ##   This file is part of GUILE.
 ##
@@ -73,6 +73,7 @@ guile_TEXINFOS = preface.texi                 \
                 repl-modules.texi              \
                 srfi-modules.texi              \
                 r6rs.texi                      \
+                r7rs.texi                      \
                 match.texi                     \
                 misc-modules.texi              \
                 libguile-autoconf.texi         \
diff --git a/doc/ref/api-binding.texi b/doc/ref/api-binding.texi
index 557e7e1..60f034a 100644
--- a/doc/ref/api-binding.texi
+++ b/doc/ref/api-binding.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2011,
-@c   2014 Free Software Foundation, Inc.
+@c Copyright (C) 1996-1997,2000-2004,2009-2011,2013-2014,2019
+@c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
 @node Binding Constructs
@@ -304,9 +304,9 @@ is equivalent to
 
 Another noteworthy difference to top level definitions is that within
 one group of internal definitions all variable names must be distinct.
-That means where on the top level a second define for a given variable
-acts like a @code{set!}, an exception is thrown for internal definitions
-with duplicate bindings.
+Whereas on the top level a second define for a given variable acts like
+a @code{set!}, for internal definitions, duplicate bound identifiers
+signals an error.
 
 As a historical note, it used to be that internal bindings were expanded
 in terms of @code{letrec}, not @code{letrec*}. This was the situation
diff --git a/doc/ref/guile-invoke.texi b/doc/ref/guile-invoke.texi
index d7b3d8a..90f1f49 100644
--- a/doc/ref/guile-invoke.texi
+++ b/doc/ref/guile-invoke.texi
@@ -142,6 +142,11 @@ guile --use-srfi=8,13
 Adapt Guile's initial environment to better support R6RS.  @xref{R6RS
 Incompatibilities}, for some caveats.
 
+@item --r7rs
+@cindex r7rs (command line)
+Adapt Guile's initial environment to better support R7RS.  @xref{R7RS
+Incompatibilities}, for some caveats.
+
 @item --debug
 @cindex debugging virtual machine (command line)
 Start with the debugging virtual machine (VM) engine.  Using the
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index 7f77cb4..32575db 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -360,6 +360,7 @@ available through both Scheme and C interfaces.
 * getopt-long::                 Command line handling.
 * SRFI Support::                Support for various SRFIs.
 * R6RS Support::                Modules defined by the R6RS.
+* R7RS Support::                Modules defined by the R7RS.
 * Pattern Matching::            Generic pattern matching constructs.
 * Readline Support::            Module for using the readline library.
 * Pretty Printing::             Nicely formatting Scheme objects for output.
@@ -383,6 +384,7 @@ available through both Scheme and C interfaces.
 @include mod-getopt-long.texi
 @include srfi-modules.texi
 @include r6rs.texi
+@include r7rs.texi
 @include match.texi
 @include repl-modules.texi
 @include misc-modules.texi
diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi
index 28da4ac..aec07ba 100644
--- a/doc/ref/intro.texi
+++ b/doc/ref/intro.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010, 2011, 
2013
+@c Copyright (C)  1996-1997,2000-2004,2006,2008-2011,2013,2019
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -71,23 +71,45 @@ dynamic linking, a foreign function call interface, 
powerful string
 processing, and many other features needed for programming in the real
 world.
 
-The Scheme community has recently agreed and published R6RS, the
-latest installment in the RnRS series.  R6RS significantly expands the
-core Scheme language, and standardises many non-core functions that
-implementations---including Guile---have previously done in
-different ways.  Guile has been updated to incorporate some of the
-features of R6RS, and to adjust some existing features to conform to
-the R6RS specification, but it is by no means a complete R6RS
-implementation. @xref{R6RS Support}.
-
-Between R5RS and R6RS, the SRFI process (@url{http://srfi.schemers.org/})
-standardised interfaces for many practical needs, such as multithreaded
-programming and multidimensional arrays.  Guile supports many SRFIs, as
-documented in detail in @ref{SRFI Support}.
-
-In summary, so far as relationship to the Scheme standards is
-concerned, Guile is an R5RS implementation with many extensions, some
-of which conform to SRFIs or to the relevant parts of R6RS.
+In 2010, the Scheme community agreed upon and published R6RS, a
+significant installment in the RnRS series.  R6RS expands the core
+Scheme language, and standardises many non-core functions that
+implementations---including Guile---have previously done in different
+ways.  Over time, Guile has been updated to incorporate almost all of
+the features of R6RS, and to adjust some existing features to conform to
+the R6RS specification.  @xref{R6RS Support}, for full details.
+
+In parallel to official standardization efforts, the SRFI process
+(@url{http://srfi.schemers.org/}) standardises interfaces for many
+practical needs, such as multithreaded programming and multidimensional
+arrays.  Guile supports many SRFIs, as documented in detail in @ref{SRFI
+Support}.
+
+The process that led to the R6RS standard brought a split in the Scheme
+community to the surface.  The implementors that wrote R6RS considered
+that it was impossible to write useful, portable programs in R5RS, and
+that only an ambitious standard could solve this problem.  However, part
+of the Scheme world saw the R6RS effort as too broad, and as having
+included some components that would never be adopted by more
+minimalistic Scheme implementations.  This second group succeeded in
+taking control of the official Scheme standardization track and in 2013
+released a more limited R7RS, essentially consisting of R5RS, plus a
+module system.  Guile supports R7RS also.  @xref{R7RS Support}.
+
+With R6RS and R7RS, the unified Scheme standardization process appears
+to have more or less run its course.  There will continue to be more
+code written in terms of both systems, and modules defined using the
+SRFI process, and Guile will support both.  However for future
+directions, Guile takes inspiration from other related language
+communities: Racket, Clojure, Concurrent ML, and so on.
+
+In summary, Guile supports writing and running code written to the R5RS,
+R6RS, and R7RS Scheme standards, and also supports a number of SRFI
+modules.  However for most users, until a need for cross-implementation
+portability has been identified, we recommend using the parts of Guile
+that are useful in solving the problem at hand, regardless of whether
+they proceed from a standard or whether they are Guile-specific.
+
 
 @node Combining with C
 @section Combining with C Code
diff --git a/doc/ref/r7rs.texi b/doc/ref/r7rs.texi
new file mode 100644
index 0000000..c8ee83c
--- /dev/null
+++ b/doc/ref/r7rs.texi
@@ -0,0 +1,137 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C)  2010, 2011, 2012, 2013,
+@c   2014, 2019 Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@node R7RS Support
+@section R7RS Support
+@cindex R7RS
+
+The R7RS standard is essentially R5RS (directly supported by Guile),
+plus a module facility, plus an organization of bindings into a standard
+set of modules.
+
+Happily, the syntax for R7RS modules was chosen to be compatible with
+R6RS, and so Guile's documentation there applies.  @xref{R6RS
+Libraries}, for more information on how to define R6RS libraries, and
+their integration with Guile modules.  @xref{Library Usage}, also.
+
+@menu
+* R7RS Incompatibilities::              Guile mostly implements R7RS.
+* R7RS Standard Libraries::             Modules defined by the R7RS.
+@end menu
+
+@node R7RS Incompatibilities
+@subsection Incompatibilities with the R7RS
+
+As the R7RS is a much less ambitious standard than the R6RS
+(@pxref{Guile and Scheme}), it is very easy for Guile to support.  As
+such, Guile is a fully conforming implementation of R7RS, with the
+exception of the occasional bug and a couple of unimplemented features:
+
+@itemize
+@item
+@cindex datum labels
+The R7RS specifies a syntax for reading circular data structures using
+@dfn{datum labels}, such as @code{#0=(1 2 3 . #0#)}.  Guile's reader
+does not support this syntax currently;
+@url{https://bugs.gnu.org/38236}.
+
+@item
+As with R6RS, a number of lexical features of R7RS conflict with Guile's
+historical syntax.  In addition to @code{r6rs-hex-escapes} and
+@code{hungry-eol-escapes} (@pxref{R6RS Incompatibilities}), the
+@code{r7rs-symbols} reader feature needs to be explicitly enabled.
+@end itemize
+
+Guile exposes a procedure in the root module to choose R7RS defaults
+over Guile's historical defaults.
+
+@deffn {Scheme Procedure} install-r7rs!
+Alter Guile's default settings to better conform to the R7RS.
+
+While Guile's defaults may evolve over time, the current changes that
+this procedure imposes are to add @code{.sls} and @code{.guile.sls} to
+the set of supported @code{%load-extensions}, to better support R7RS
+conventions.  @xref{Load Paths}.  @code{install-r7rs!} will also enable
+the reader options mentioned above.
+@end deffn
+
+Finally, note that the @code{--r7rs} command-line argument will call
+@code{install-r7rs!} before calling user code.  R7RS users probably want
+to pass this argument to their Guile.
+
+@node R7RS Standard Libraries
+@subsection R7RS Standard Libraries
+
+The R7RS organizes the definitions from R5RS into modules, and also adds
+a few new definitions.
+
+We do not attempt to document these libraries fully here, as unlike
+R6RS, there are few new definitions in R7RS relative to R5RS.  Most of
+their functionality is already in Guile's standard environment.  Again,
+the expectation is that most Guile users will use the well-known and
+well-documented Guile modules; these R7RS libraries are mostly useful to
+users who want to port their code to other R7RS systems.
+
+As a brief overview, we note that the libraries defined by the R7RS are
+as follows:
+
+@itemize @code
+@item (scheme base)
+The core functions, mostly corresponding to R5RS minus the elements
+listed separately below, but plus SRFI-34 error handling
+(@pxref{SRFI-34}), bytevectors and bytevector ports
+(@pxref{Bytevectors}), and some miscellaneous other new procedures.
+@item (scheme case-lambda)
+@code{case-lambda}.
+@item (scheme char)
+Converting strings and characters to upper or lower case, predicates for
+if a characer is numeric, and so on.
+@item (scheme complex)
+Constructors and accessors for complex numbers.
+@item (scheme cxr)
+@code{cddr}, @code{cadadr}, and all that.
+@item (scheme eval)
+@code{eval}, but also an @code{environment} routine allowing a user to
+specify an environment using a module import set.
+@item (scheme file)
+@code{call-with-input-file} and so on.
+@item (scheme inexact)
+Routines that operate on inexact numbers: @code{sin}, @code{finite?},
+and so on.
+@item (scheme lazy)
+Promises.
+@item (scheme load)
+The @code{load} procedure.
+@item (scheme process-context)
+Environment variables.  @xref{SRFI-98}.  Also, @code{commmand-line},
+@code{emergency-exit} (like Guile's @code{primitive-_exit}), and
+@code{exit}.
+@item (scheme r5rs)
+The precise set of bindings exported by @code{r5rs}, but without
+@code{transcript-off} / @code{transcript-on}, and also with the
+auxiliary syntax definitions like @code{_} or @code{else}.  @xref{Syntax
+Rules}, for more on auxiliary syntax.
+@item (scheme read)
+The @code{read} procedure.
+@item (scheme repl)
+The @code{interaction-environment} procedure.
+@item (scheme time)
+@code{current-second}, as well as @code{current-jiffy} and
+@code{jiffies-per-second}.  Guile uses the term ``internal time unit''
+for what R7RS calls ``jiffies''.
+@item (scheme write)
+@code{display}, @code{write}, as well as @code{write-shared} and
+@code{write-simple}.
+@end itemize
+
+For complete documentation, we advise the interested user to consult the
+R7RS directly (@pxref{R7RS,,, r7rs, The Revised^7 Report on the
+Algorithmic Language Scheme}).
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End:
diff --git a/doc/ref/scheme-intro.texi b/doc/ref/scheme-intro.texi
index b8a5024..cab4527 100644
--- a/doc/ref/scheme-intro.texi
+++ b/doc/ref/scheme-intro.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2019
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -15,11 +15,11 @@ series of reports known as @dfn{RnRS}.  @dfn{RnRS} is 
shorthand for the
 @ifnottex
 @dfn{Revised^n Report on the Algorithmic Language Scheme}.
 @end ifnottex
-Guile complies fully with R5RS (@pxref{Top,
-,Introduction,r5rs,R5RS}), and implements some aspects of R6RS.
+Guile complies fully with R5RS (@pxref{Top, ,Introduction,r5rs,R5RS}),
+and is largely compliant with R6RS and R7RS.
 
 Guile also has many extensions that go beyond these reports.  Some of
-the areas where Guile extends R5RS are:
+the areas where Guile extends standard Scheme are:
 
 @itemize @bullet
 @item
diff --git a/module/ice-9/command-line.scm b/module/ice-9/command-line.scm
index a74f7e7..13dfa01 100644
--- a/module/ice-9/command-line.scm
+++ b/module/ice-9/command-line.scm
@@ -140,6 +140,8 @@ If FILE begins with `-' the -s switch is mandatory.
                  which is a list of numbers like \"2,13,14\"
   --r6rs         change initial Guile environment to better support
                  R6RS
+  --r7rs         change initial Guile environment to better support
+                 R7RS
   -h, --help     display this help and exit
   -v, --version  display version information and exit
   \\              read arguments from following script lines"))
@@ -376,6 +378,10 @@ If FILE begins with `-' the -s switch is mandatory.
             (parse args
                    (cons '(install-r6rs!) out)))
 
+           ((string=? "--r7rs" arg)
+            (parse args
+                   (cons '(install-r7rs!) out)))
+
            ((string=? arg "--listen")   ; start a repl server
             (parse args
                    (cons '((@@ (system repl server) spawn-server)) out)))