diff options
author | Julian Graham <julian.graham@aya.yale.edu> | 2010-06-23 23:44:24 -0400 |
---|---|---|
committer | Julian Graham <julian.graham@aya.yale.edu> | 2010-06-23 23:44:43 -0400 |
commit | 5b379729bb5f5d06ceb02c4e96ccc62cf61f9c62 (patch) | |
tree | 2e5b14896370afff227d453872f9efc69a69de19 /doc/ref/r6rs.texi | |
parent | ff87b2bd7c8a421333fa2182837388e6421df88e (diff) | |
download | guile-5b379729bb5f5d06ceb02c4e96ccc62cf61f9c62.tar.gz |
Edits to R6RS standard libraries documentation proposed by Ludovic Courtès.
* doc/ref/r6rs.texi: Fix erroneous usage of @pxref; add pointers from
`(rnrs conditions)' and `(rnrs arithmetic bitwise)' to SRFI-35 and
SRFI-60 sections; remove reference to `fold'.
Diffstat (limited to 'doc/ref/r6rs.texi')
-rw-r--r-- | doc/ref/r6rs.texi | 120 |
1 files changed, 66 insertions, 54 deletions
diff --git a/doc/ref/r6rs.texi b/doc/ref/r6rs.texi index afe9ba409..2752b2701 100644 --- a/doc/ref/r6rs.texi +++ b/doc/ref/r6rs.texi @@ -28,7 +28,7 @@ find one that is not on this list. @item The R6RS specifies many situations in which a conforming implementation must signal a specific error. Guile doesn't really care about that too -much --- if a correct R6RS program would not hit that error, we don't +much---if a correct R6RS program would not hit that error, we don't bother checking for it. @item @@ -38,7 +38,7 @@ does not restore it. This is a bug. @item A @code{set!} to a variable transformer may only expand to an -expression, not a definition --- even if the original @code{set!} +expression, not a definition---even if the original @code{set!} expression was in definition context. @end itemize @@ -110,9 +110,8 @@ Guile implements the R6RS `library' form as a transformation to a native Guile module definition. As a consequence of this, all of the libraries described in the following subsections, in addition to being available for use by R6RS libraries and top-level programs, can also be imported -as if they were normal Guile modules --- for example, via a -@code{use-modules} form. For example, the R6RS ``composite'' library -can be imported by: +as if they were normal Guile modules---via a @code{use-modules} form, +say. For example, the R6RS ``composite'' library can be imported by: @lisp (import (rnrs (6))) @@ -339,8 +338,7 @@ grouped below by the existing manual sections to which they correspond. @xref{Comparison}, for documentation. @end deffn -@deffn {Scheme Procedure} fold f lst1 lst2 ... -@deffnx {Scheme Procedure} for-each f lst1 lst2 ... +@deffn {Scheme Procedure} for-each f lst1 lst2 ... @xref{SRFI-1 Fold and Map}, for documentation. @end deffn @@ -524,10 +522,10 @@ manipulating Unicode characters and strings. These procedures translate their arguments from one Unicode character set to another. @code{char-upcase}, @code{char-downcase}, and @code{char-titlecase} are identical to their counterparts in the -Guile core library; see (@pxref{Characters}) for documentation. +Guile core library; @xref{Characters}, for documentation. @code{char-foldcase} returns the result of applying @code{char-upcase} -to its argument, followed by @code{char-downcase} --- except in the case +to its argument, followed by @code{char-downcase}---except in the case of the Turkic characters @code{U+0130} and @code{U+0131}, for which the procedure acts as the identity function. @end deffn @@ -612,7 +610,7 @@ defined by SRFI-1; the @code{exists} procedure is identical to SRFI-1's @deffnx {Scheme Procedure} partition proc list These procedures are identical to the ones provided by SRFI-1. @xref{List Modification}, for a description of @code{filter}; -(@pxref{SRFI-1 Filtering and Partitioning}) for @code{partition}. +@xref{SRFI-1 Filtering and Partitioning}, for @code{partition}. @end deffn @deffn {Scheme Procedure} fold-left combine nil list1 list2 ... listn @@ -628,9 +626,9 @@ documentation. @deffnx {Scheme Procedure} remq obj list @code{remove}, @code{remv}, and @code{remq} are identical to the @code{delete}, @code{delv}, and @code{delq} procedures provided by -Guile's core library; (@pxref{List Modification}) for their -documentation. @code{remp} is identical to the alternate @code{remove} -procedure provided by SRFI-1; @xref{SRFI-1 Deleting}. +Guile's core library, (@pxref{List Modification}). @code{remp} is +identical to the alternate @code{remove} procedure provided by SRFI-1; +@xref{SRFI-1 Deleting}. @end deffn @deffn {Scheme Procedure} memp proc list @@ -638,9 +636,9 @@ procedure provided by SRFI-1; @xref{SRFI-1 Deleting}. @deffnx {Scheme Procedure} memv obj list @deffnx {Scheme Procedure} memq obj list @code{member}, @code{memv}, and @code{memq} are identical to the -procedures provided by Guile's core library; (@pxref{List Searching}) -for their documentation. @code{memp} uses the specified predicate -function @code{proc} to test elements of the list @var{list} --- it +procedures provided by Guile's core library; @xref{List Searching}, +for their documentation. @code{memp} uses the specified predicate +function @code{proc} to test elements of the list @var{list}---it behaves similarly to @code{find}, except that it returns the first sublist of @var{list} whose @code{car} satisfies @var{proc}. @end deffn @@ -651,7 +649,7 @@ sublist of @var{list} whose @code{car} satisfies @var{proc}. @deffnx {Scheme Procedure} assq obj alist @code{assoc}, @code{assv}, and @code{assq} are identical to the procedures provided by Guile's core library; -(@pxref{Alist Key Equality}) for their documentation. @code{assp} uses +@xref{Alist Key Equality}, for their documentation. @code{assp} uses the specified predicate function @code{proc} to test keys in the association list @var{alist}. @end deffn @@ -727,7 +725,7 @@ The manual sections below describe Guile's implementation of R6RS records, which provide support for user-defined data types. The R6RS records API provides a superset of the features provided by Guile's ``native'' records, as well as those of the SRFI-9 records API; -(@pxref{Records}) and (@pxref{SRFI-9}) for a description of those +@xref{Records}, and @ref{SRFI-9}, for a description of those interfaces. As with SRFI-9 and Guile's native records, R6RS records are constructed @@ -781,9 +779,10 @@ that produce chains of delegating constructors glued together by the helper procedure @var{n}. An R6RS record type may be declared to be @dfn{nongenerative} via the -use of a unique generated or user-supplied symbol --- or @dfn{uid} --- -such that subsequent record type declarations with the same uid and -attributes will return the previously-declared record-type descriptor. +use of a unique generated or user-supplied symbol---or +@dfn{uid}---such that subsequent record type declarations with the same +uid and attributes will return the previously-declared record-type +descriptor. R6RS record types may also be declared to be @dfn{opaque}, in which case the various predicates and introspection procedures defined in @@ -1005,9 +1004,9 @@ descriptor @var{rtd} (and not any of its sub- or supertypes) is mutable. The @code{(rnrs exceptions (6))} library provides functionality related to signaling and handling exceptional situations. This functionality is similar to the exception handling systems provided by Guile's core -library (@pxref{Exceptions}) and by the SRFI-18 and SRFI-34 -modules --- (@pxref{SRFI-18 Exceptions}) and (@pxref{SRFI-34}), -respectively --- but there are some key differences in concepts and +library @xref{Exceptions}, and by the SRFI-18 and SRFI-34 +modules---@xref{SRFI-18 Exceptions}, and @ref{SRFI-34}, +respectively---but there are some key differences in concepts and behavior. A raised exception may be @dfn{continuable} or @dfn{non-continuable}. @@ -1041,11 +1040,11 @@ provided by Guile's code library; (@pxref{Throw Handlers}). Evaluates the expression given by @var{body}, first creating an ad hoc exception handler that binds a raised exception to @var{variable} and then evaluates the specified @var{clause}s as if they were part of a -@code{cond} expression (@pxref{if cond case}), with the value of the -first matching clause becoming the value of the @code{guard} expression. -If none of the clause's test expressions evaluates to @code{#t}, the -exception is re-raised, with the exception handler that was current -before the evaluation of the @code{guard} form. +@code{cond} expression, with the value of the first matching clause +becoming the value of the @code{guard} expression +(@pxref{if cond case}). If none of the clause's test expressions +evaluates to @code{#t}, the exception is re-raised, with the exception +handler that was current before the evaluation of the @code{guard} form. For example, the expression @@ -1081,7 +1080,7 @@ exceptional situations. Conditions are records of a subtype of the Conditions may be manipulated singly, as @dfn{simple conditions}, or when composed with other conditions to form @dfn{compound conditions}. -Compound conditions do not ``nest'' --- constructing a new compound +Compound conditions do not ``nest''---constructing a new compound condition out of existing compound conditions will ``flatten'' them into their component simple conditions. For example, making a new condition out of a @code{&message} condition and a compound condition @@ -1096,6 +1095,14 @@ component simple condition of the appropriate type; the field accessors return the requisite fields from the first component simple condition found to be of the appropriate type. +This library is quite similar to the SRFI-35 conditions module +(@pxref{SRFI-35}). Among other minor differences, the +@code{(rnrs conditions)} library features slightly different semantics +around condition field accessors, and comes with a larger number of +pre-defined condition types. The two APIs are not currently compatible, +however; the @code{condition?} predicate from one API will return +@code{#f} when applied to a condition object created in the other. + @deffn &condition @deffnx condition? obj The base record type for conditions. @@ -1409,9 +1416,10 @@ performing arithmetic operations on an implementation-dependent range of exact integer values, which R6RS refers to as @dfn{fixnums}. In Guile, the size of a fixnum is determined by the size of the @code{SCM} type; a single SCM struct is guaranteed to be able to hold an entire fixnum, -making fixnum computations particularly efficient --- -(@pxref{The SCM Type}). On 32-bit systems, the most negative and most -positive fixnum values are, respectively, -536870912 and 536870911. +making fixnum computations particularly +efficient---(@pxref{The SCM Type}). On 32-bit systems, the most +negative and most positive fixnum values are, respectively, -536870912 +and 536870911. Unless otherwise specified, all of the procedures below take fixnums as arguments, and will raise an @code{&assertion} condition if passed a @@ -1477,7 +1485,7 @@ fixnum. @deffnx {Scheme Procedure} fxdiv0 fx1 fx2 @deffnx {Scheme Procedure} fxmod0 fx1 fx2 These procedures implement number-theoretic division on fixnums; -(@pxref{(rnrs base)}) for a description for their semantics. +@xref{(rnrs base)}, for a description of their semantics. @end deffn @deffn {Scheme Procedure} fx+/carry fx1 fx2 fx3 @@ -1663,7 +1671,7 @@ Returns the absolute value of @var{fl}. @deffnx {Scheme Procedure} fldiv0 fl1 fl2 @deffnx {Scheme Procedure} flmod0 fl1 fl2 These procedures implement number-theoretic division on flonums; -(@pxref{(rnrs base)}) for a description for their semantics. +@xref{(rnrs base)}, for a description for their semantics. @end deffn @deffn {Scheme Procedure} flnumerator fl @@ -1735,7 +1743,11 @@ Returns the flonum that is numerically closest to the fixnum @var{fx}. The @code{(rnrs arithmetic bitwise (6))} library provides procedures for performing bitwise arithmetic operations on the two's complement -representations of fixnums. +representations of fixnums. + +This library and the procedures it exports share functionality with +SRFI-60, which provides support for bitwise manipulation of integers +(@pxref{SRFI-60}). @deffn {Scheme Procedure} bitwise-not ei @deffnx {Scheme Procedure} bitwise-and ei1 ... @@ -1816,7 +1828,7 @@ The @code{(rnrs syntax-case (6))} library provides access to the @code{syntax-case} system for writing hygienic macros. With one exception, all of the forms and procedures exported by this library are ``re-exports'' of Guile's native support for @code{syntax-case}; -(@pxref{Syntax Case}) for documentation, examples, and rationale. +@xref{Syntax Case}, for documentation, examples, and rationale. @deffn {Scheme Procedure} make-variable-transformer proc Creates a new variable transformer out of @var{proc}, a procedure that @@ -1838,7 +1850,7 @@ The @code{syntax-case} pattern matching form. These forms allow references to be made in the body of a syntax-case output expression subform to datum and non-datum values. They are identical to the forms provided by Guile's core library; -(@pxref{Syntax Case}) for documentation. +@xref{Syntax Case}, for documentation. @end deffn @deffn {Scheme Procedure} identifier? obj @@ -1889,15 +1901,15 @@ A @code{&syntax} condition with the specified @var{form} and optional The @code{(rnrs hashtables (6))} library provides structures and procedures for creating and accessing hash tables. The hash tables API defined by R6RS is substantially similar to both Guile's native hash -tables implementation (@pxref{Hash Tables}) as well as the one -provided by SRFI-69 (@pxref{SRFI-69}). Note that you can write -portable R6RS library code that manipulates SRFI-69 hash tables (by -importing the @code{(srfi :69)} library); however, hash tables created -by one API cannot be used by another. - -Like SRFI-69 hash tables --- and unlike Guile's native ones --- R6RS -hash tables associate hash and equality functions with a hash table at -the time of its creation. Additionally, R6RS allows for the creation +tables implementation as well as the one provided by SRFI-69; +@xref{Hash Tables}, and @ref{SRFI-69}, respectively. Note that you can +write portable R6RS library code that manipulates SRFI-69 hash tables +(by importing the @code{(srfi :69)} library); however, hash tables +created by one API cannot be used by another. + +Like SRFI-69 hash tables---and unlike Guile's native ones---R6RS hash +tables associate hash and equality functions with a hash table at the +time of its creation. Additionally, R6RS allows for the creation (via @code{hashtable-copy}; see below) of immutable hash tables. @deffn {Scheme Procedure} make-eq-hashtable @@ -1961,7 +1973,7 @@ association for the key @var{key}, @code{#f} otherwise. Associates with @var{key} in the hash table @var{hashtable} the result of calling @var{proc}, which must be a procedure that takes one argument, on the value currently associated @var{key} in -@var{hashtable} --- or on @var{default} if no such association exists. +@var{hashtable}---or on @var{default} if no such association exists. An @code{&assertion} condition is raised if @var{hashtable} is immutable. @end deffn @@ -1987,9 +1999,9 @@ Returns a vector of the keys with associations in the hash table @end deffn @deffn {Scheme Procedure} hashtable-entries hashtable -Return two values --- a vector of the keys with associations in the -hash table @var{hashtable}, and a vector of the values to which these -keys are mapped, in corresponding but unspecified order. +Return two values---a vector of the keys with associations in the hash +table @var{hashtable}, and a vector of the values to which these keys +are mapped, in corresponding but unspecified order. @end deffn @deffn {Scheme Procedure} hashtable-equivalence-function hashtable @@ -2124,8 +2136,8 @@ condition is raised. @subsubsection rnrs The @code{(rnrs (6))} library is a composite of all of the other R6RS -standard libraries --- it imports and re-exports all of their exported -procedures and syntactic forms --- with the exception of the following +standard libraries---it imports and re-exports all of their exported +procedures and syntactic forms---with the exception of the following libraries: @itemize @bullet @@ -2145,7 +2157,7 @@ The @code{(rnrs eval (6)} library provides procedures for performing Evaluates @var{expression}, which must be a datum representation of a valid Scheme expression, in the environment specified by @var{environment}. This procedure is identical to the one provided by -Guile's code library; (@pxref{Fly Evaluation}) for documentation. +Guile's code library; @xref{Fly Evaluation}, for documentation. @end deffn @deffn {Scheme Procedure} environment import-spec ... |