summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ref/Makefile.am3
-rw-r--r--doc/ref/api-binding.texi10
-rw-r--r--doc/ref/guile-invoke.texi5
-rw-r--r--doc/ref/guile.texi2
-rw-r--r--doc/ref/intro.texi58
-rw-r--r--doc/ref/r7rs.texi137
-rw-r--r--doc/ref/scheme-intro.texi8
-rw-r--r--module/ice-9/command-line.scm6
8 files changed, 201 insertions, 28 deletions
diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index 05393cd96..2f4b8ca88 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 557e7e124..60f034a0e 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 d7b3d8a5f..90f1f496b 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 7f77cb430..32575dbf6 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 28da4ac3c..aec07ba93 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 000000000..c8ee83c9c
--- /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 b8a502475..cab452758 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 a74f7e7f8..13dfa0182 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)))