diff options
author | Andy Wingo <wingo@pobox.com> | 2019-11-17 15:26:23 +0100 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2019-11-17 15:30:59 +0100 |
commit | b634071dd4c2401616c78d2a20471698123a23ca (patch) | |
tree | 2c1987cad64e7477ed5f6ab686dffce0e07f32b7 | |
parent | 72a2c742f6675e870421c61e66c5aec134398a5a (diff) | |
download | guile-b634071dd4c2401616c78d2a20471698123a23ca.tar.gz |
Add R7RS documentation and --r7rs command-line optionwip-r7rs
* 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.
-rw-r--r-- | doc/ref/Makefile.am | 3 | ||||
-rw-r--r-- | doc/ref/api-binding.texi | 10 | ||||
-rw-r--r-- | doc/ref/guile-invoke.texi | 5 | ||||
-rw-r--r-- | doc/ref/guile.texi | 2 | ||||
-rw-r--r-- | doc/ref/intro.texi | 58 | ||||
-rw-r--r-- | doc/ref/r7rs.texi | 137 | ||||
-rw-r--r-- | doc/ref/scheme-intro.texi | 8 | ||||
-rw-r--r-- | 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 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))) |