commit 33b9ea42aa3e55f10a331f77519ea826b45c6e6e
parent ded2cdb286d6516cad54df4d19379b403390c557
Author: Yuval Langer <yuval.langer@gmail.com>
Date: Sun, 28 Jan 2024 23:32:18 +0200
Add some @example and @code.
Diffstat:
1 file changed, 175 insertions(+), 17 deletions(-)
diff --git a/doc/r7rs-small/r7rs-small.texinfo b/doc/r7rs-small/r7rs-small.texinfo
@@ -1381,6 +1381,8 @@ If all <test>s evaluate to #f, and there is no else clause, then the result of t
expression is unspecified; if there is an else clause, then its <expression>s are evaluated in
order, and the values of the last one are returned.
+@example
+
(cond ((> 3 2) 'greater)
((< 3 2) 'less)) ⟹ greater
@@ -1391,6 +1393,8 @@ order, and the values of the last one are returned.
(cond ((assv 'b '((a 1) (b 2))) => cadr)
(else #f)) ⟹ 2
+@end example
+
syntax: (case <key> <clause1> <clause2> …)
Syntax: <Key> can be any expression. Each <clause> has the form
@@ -1417,6 +1421,8 @@ evaluated. It is an error if its value is not a procedure accepting one argument
procedure is then called on the value of the <key> and the values returned by this
procedure are returned by the case expression.
+@example
+
(case (* 2 3)
((2 3 5 7) 'prime)
((1 4 6 8 9) 'composite)) ⟹ composite
@@ -1428,6 +1434,8 @@ procedure are returned by the case expression.
((w y) 'semivowel)
(else => (lambda (x) x))) ⟹ c
+@end example
+
syntax: (and <test1> …)
Semantics: The <test> expressions are evaluated from left to right, and if any expression
@@ -1435,11 +1443,15 @@ evaluates to #f (see section 6.3), then #f is returned. Any remaining expression
evaluated. If all the expressions evaluate to true values, the values of the last expression
are returned. If there are no expressions, then #t is returned.
+@example
+
(and (= 2 2) (> 2 1)) ⟹ #t
(and (= 2 2) (< 2 1)) ⟹ #f
(and 1 2 'c '(f g)) ⟹ (f g)
(and) ⟹ #t
+@end example
+
syntax: (or <test1> …)
Semantics: The <test> expressions are evaluated from left to right, and the value of the
@@ -1447,12 +1459,16 @@ first expression that evaluates to a true value (see section 6.3) is returned. A
expressions are not evaluated. If all expressions evaluate to #f or if there are no
expressions, then #f is returned.
+@example
+
(or (= 2 2) (> 2 1)) ⟹ #t
(or (= 2 2) (< 2 1)) ⟹ #t
(or #f #f #f) ⟹ #f
(or (memq 'b '(a b c))
(/ 3 0)) ⟹ (b c)
+@end example
+
syntax: (when <test> <expression1> <expression2> …)
Syntax: The <test> is an expression.
@@ -1460,11 +1476,15 @@ Syntax: The <test> is an expression.
Semantics: The test is evaluated, and if it evaluates to a true value, the expressions are
evaluated in order. The result of the when expression is unspecified.
+@example
+
(when (= 1 1.0)
(display "1")
(display "2")) ⟹ unspecified
and prints 12
+@end example
+
syntax: (unless <test> <expression1> <expression2> …)
Syntax: The <test> is an expression.
@@ -1472,11 +1492,15 @@ Syntax: The <test> is an expression.
Semantics: The test is evaluated, and if it evaluates to #f, the expressions are evaluated in
order. The result of the unless expression is unspecified.
+@example
+
(unless (= 1 1.0)
(display "1")
(display "2")) ⟹ unspecified
and prints nothing
+@end example
+
syntax: (cond-expand <ce-clause1> <ce-clause2> …)
Syntax: The cond-expand expression type provides a way to statically expand different
@@ -1544,6 +1568,8 @@ order), the <variable>s are bound to fresh locations holding the results, the <b
evaluated in the extended environment, and the values of the last expression of <body>
are returned. Each binding of a <variable> has <body> as its region.
+@example
+
(let ((x 2) (y 3))
(* x y)) ⟹ 6
@@ -1552,6 +1578,8 @@ are returned. Each binding of a <variable> has <body> as its region.
(z (+ x y)))
(* z x))) ⟹ 35 See also “named let,” section 4.2.4.
+@end example
+
syntax: (let* <bindings> <body>)
Syntax: <Bindings> has the form
@@ -1565,11 +1593,15 @@ is that part of the let* expression to the right of the binding. Thus the second
done in an environment in which the first binding is visible, and so on. The <variable>s
need not be distinct.
+@example
+
(let ((x 2) (y 3))
(let* ((x 7)
(z (+ x y)))
(* z x))) ⟹ 70
+@end example
+
syntax: (letrec <bindings> <body>)
Syntax: <Bindings> has the form
@@ -1585,6 +1617,8 @@ the resulting environment, and the values of the last expression in <body> are r
Each binding of a <variable> has the entire letrec expression as its region, making it
possible to define mutually recursive procedures.
+@example
+
(letrec ((even?
(lambda (n)
(if (zero? n)
@@ -1596,7 +1630,11 @@ possible to define mutually recursive procedures.
#f
(even? (- n 1))))))
(even? 88))
-⟹ #t One restriction on letrec is very important: if it is not possible to evaluate each <init>
+⟹ #t
+
+@end example
+
+One restriction on letrec is very important: if it is not possible to evaluate each <init>
without assigning or referring to the value of any <variable>, it is an error. The restriction
is necessary because letrec is defined in terms of a procedure call where a lambda
expression binds the <variable>s to the values of the <init>s. In the most common uses of
@@ -1622,6 +1660,8 @@ the corresponding <variable> or the <variable> of any of the bindings that follo
<bindings>, it is an error. Another restriction is that it is an error to invoke the
continuation of an <init> more than once.
+@example
+
;; Returns the arithmetic, geometric, and
;; harmonic means of a nested list of numbers
(define (means ton)
@@ -1641,6 +1681,9 @@ continuation of an <init> more than once.
(values (mean values values)
(mean exp log)
(mean / /))))
+
+@end example
+
Evaluating (means '(3 (1 4))) returns three values: 8/3, 2.28942848510666 (approximately),
and 36/19.
@@ -1663,9 +1706,13 @@ are returned. Each binding of a <variable> has <body> as its region.
It is an error if the <formals> do not match the number of values returned by the
corresponding <init>.
+@example
+
(let-values (((root rem) (exact-integer-sqrt 32)))
(* root rem)) ⟹ 35
+@end example
+
syntax: (let*-values <mv binding spec> <body>)
Syntax: <Mv binding spec> has the form
@@ -1680,11 +1727,15 @@ each <formals> including the <init>s to its right as well as <body>. Thus the se
is evaluated in an environment in which the first set of bindings is visible and initialized,
and so on.
+@example
+
(let ((a 'a) (b 'b) (x 'x) (y 'y))
(let*-values (((a b) (values x y))
((x y) (values a b)))
(list a b x y))) ⟹ (x y x y)
+@end example
+
@node Sequencing
@subsection Sequencing
@@ -1709,6 +1760,8 @@ evaluated sequentially from left to right, and the values of the last <expressio
returned. This expression type is used to sequence side effects such as assignments or
input and output.
+@example
+
(define x 0)
(and (= x 0)
@@ -1716,8 +1769,9 @@ input and output.
(+ x 1))) ⟹ 6
(begin (display "4 plus 1 equals ")
- (display (+ 4 1))) ⟹ unspecified
- and prints 4 plus 1 equals 5
+ (display (+ 4 1))) ⟹ unspecified and prints 4 plus 1 equals 5
+
+@end example
Note that there is a third form of begin used as a library declaration: see section 5.6.1.
@@ -1758,6 +1812,8 @@ variables.
A <step> can be omitted, in which case the effect is the same as if (<variable> <init>
<variable>) had been written instead of (<variable> <init>).
+@example
+
(do ((vec (make-vector 5))
(i 0 (+ i 1)))
((= i 5) vec)
@@ -1768,6 +1824,8 @@ A <step> can be omitted, in which case the effect is the same as if (<variable>
(sum 0 (+ sum (car x))))
((null? x) sum))) ⟹ 25
+@end example
+
syntax: (let <variable> <bindings> <body>)
Semantics: “Named let” is a variant on the syntax of let which provides a more general
@@ -1777,6 +1835,8 @@ procedure whose formal arguments are the bound variables and whose body is <body
Thus the execution of <body> can be repeated by invoking the procedure named by
<variable>.
+@example
+
(let loop ((numbers '(3 -2 1 6 -5))
(nonneg '())
(neg '()))
@@ -1791,6 +1851,8 @@ Thus the execution of <body> can be repeated by invoking the procedure named by
(cons (car numbers) neg)))))
⟹ ((6 1 3) (-5 -2))
+@end example
+
@node Delayed evaluation
@subsection Delayed evaluation
@@ -1829,6 +1891,8 @@ values and exception handler of the call to force which first requested its valu
promise is not a promise, it may be returned unchanged.
+@example
+
(force (delay (+ 1 2))) ⟹ 3
(let ((p (delay (+ 1 2))))
(list (force p) (force p)))
@@ -1845,13 +1909,19 @@ promise is not a promise, it may be returned unchanged.
(lambda (stream) (cdr (force stream))))
(head (tail (tail integers)))
- ⟹ 2 The following example is a mechanical transformation of a lazy
+ ⟹ 2
+
+@end example
+
+The following example is a mechanical transformation of a lazy
stream-filtering algorithm into Scheme. Each call to a constructor is wrapped in delay, and
each argument passed to a deconstructor is wrapped in force. The use of (delay-force ...)
instead of (delay (force ...)) around the body of the procedure ensures that an
ever-growing sequence of pending promises does not exhaust available storage, because
force will in effect force such sequences iteratively.
+@example
+
(define (stream-filter p? s)
(delay-force
(if (null? (force s))
@@ -1863,11 +1933,17 @@ force will in effect force such sequences iteratively.
(stream-filter p? t))))))
(head (tail (tail (stream-filter odd? integers))))
- ⟹ 5 The following examples are not intended to illustrate good
+ ⟹ 5
+
+@end example
+
+The following examples are not intended to illustrate good
programming style, as delay, force, and delay-force are mainly intended for programs
written in the functional style. However, they do illustrate the property that only one value
is computed for a promise, no matter how many times it is forced.
+@example
+
(define count 0)
(define p
(delay (begin (set! count (+ count 1))
@@ -1879,7 +1955,11 @@ p ⟹ a promise
(force p) ⟹ 6
p ⟹ a promise, still
(begin (set! x 10)
- (force p)) ⟹ 6 Various extensions to this semantics of delay, force and delay-force
+ (force p)) ⟹ 6
+
+@end example
+
+Various extensions to this semantics of delay, force and delay-force
are supported in some implementations:
* Calling force on an object that is not a promise may simply return the object.
@@ -1895,10 +1975,14 @@ are supported in some implementations:
However, procedures that operate uniformly on their arguments, like list, must not
force them.
- (+ (delay (* 3 7)) 13) ⟹ unspecified
+@example
+
+(+ (delay (* 3 7)) 13) ⟹ unspecified
(car
(list (delay (* 3 7)) 13)) ⟹ a promise
+@end example
+
lazy library procedure: (promise?
obj)
@@ -1978,6 +2062,8 @@ thread and threads created inside <body>.
Parameter objects can be used to specify configurable settings for a computation
without the need to pass the value to every procedure in the call chain explicitly.
+@example
+
(define radix
(make-parameter
10
@@ -1998,6 +2084,8 @@ without the need to pass the value to every procedure in the call chain explicit
(parameterize ((radix 0))
(f 12)) ⟹ error
+@end example
+
@node Exception handling
@subsection Exception handling
@@ -2018,6 +2106,8 @@ of the guard expression.
See section 6.11 for a more complete discussion of exceptions.
+@example
+
(guard (condition
((assq 'a condition) => cdr)
((assq 'b condition)))
@@ -2030,6 +2120,8 @@ See section 6.11 for a more complete discussion of exceptions.
(raise (list (cons 'b 23))))
⟹ (b . 23)
+@end example
+
@node Quasiquotation
@subsection Quasiquotation
@@ -2057,6 +2149,7 @@ or vector <qq template>.
comma at-sign sequence.
@example
+
`(list ,(+ 1 2) 4) ⟹ (list 3 4)
(let ((name 'a)) `(list ,name ',name))
⟹ (list a (quote a))
@@ -2069,6 +2162,7 @@ or vector <qq template>.
(let ((foo '(foo bar)) (@@baz 'baz))
`(list ,@@foo , @@baz))
⟹ (list foo bar baz)
+
@end example
Quasiquote expressions can be nested. Substitutions are made only
@@ -2076,36 +2170,56 @@ for unquoted components appearing at the same nesting level as the outermost
quasiquote. The nesting level increases by one inside each successive quasiquotation, and
decreases by one inside each unquotation.
+@example
+
`(a `(b ,(+ 1 2) ,(foo ,(+ 1 3) d) e) f)
⟹ (a `(b ,(+ 1 2) ,(foo 4 d) e) f)
(let ((name1 'x)
(name2 'y))
`(a `(b ,,name1 ,',name2 d) e))
-⟹ (a `(b ,x ,'y d) e) A quasiquote expression may return either newly allocated, mutable
+⟹ (a `(b ,x ,'y d) e)
+
+@end example
+
+A quasiquote expression may return either newly allocated, mutable
objects or literal structure for any structure that is constructed at run time during the
evaluation of the expression. Portions that do not need to be rebuilt are always literal.
-Thus,
-
-(let ((a 3)) `((1 2) ,a ,4 ,'five 6)) may be treated as equivalent to either of the following
+Thus, @code{(let ((a 3)) `((1 2) ,a ,4 ,'five 6))} may be treated as equivalent to either of the following
expressions:
+@example
+
`((1 2) 3 4 five 6)
(let ((a 3))
(cons '(1 2)
- (cons a (cons 4 (cons 'five '(6)))))) However, it is not equivalent to this expression:
+ (cons a (cons 4 (cons 'five '(6))))))
+
+@end example
+
+However, it is not equivalent to this expression:
+
+@example
-(let ((a 3)) (list (list 1 2) a 4 'five 6)) The two notations `<qq template> and (quasiquote <qq
+(let ((a 3)) (list (list 1 2) a 4 'five 6))
+
+@end example
+
+The two notations `<qq template> and (quasiquote <qq
template>) are identical in all respects. ,<expression> is identical to (unquote
<expression>), and ,@@<expression> is identical to (unquote-splicing <expression>). The
write procedure may output either format.
+@example
+
(quasiquote (list (unquote (+ 1 2)) 4))
⟹ (list 3 4)
'(quasiquote (list (unquote (+ 1 2)) 4))
⟹ `(list ,(+ 1 2) 4)
i.e., (quasiquote (list (unquote (+ 1 2)) 4))
+@end example
+
It is an error if any of the identifiers quasiquote, unquote, or unquote-splicing appear in
positions within a <qq template> otherwise than as described above.
@@ -2128,6 +2242,8 @@ results of the procedure call.
It is an error for the arguments not to agree with the <formals> of any <clause>.
+@example
+
(define range
(case-lambda
((e) (range 0 e))
@@ -2138,6 +2254,8 @@ It is an error for the arguments not to agree with the <formals> of any <clause>
(range 3) ⟹ (0 1 2)
(range 3 5) ⟹ (3 4)
+@end example
+
@node Macros
@section Macros
@@ -2206,6 +2324,8 @@ the syntactic environment of the let-syntax expression with macros whose keyword
the <keyword>s, bound to the specified transformers. Each binding of a <keyword> has
<body> as its region.
+@example
+
(let-syntax ((given-that (syntax-rules ()
((given-that test stmt1 stmt2 ...)
(if test
@@ -2220,6 +2340,8 @@ the <keyword>s, bound to the specified transformers. Each binding of a <keyword>
(let ((x 'inner))
(m)))) ⟹ outer
+@end example
+
syntax: (letrec-syntax <bindings> <body>)
Syntax: Same as for let-syntax.
@@ -2231,6 +2353,8 @@ has the <transformer spec>s as well as the <body> within its region, so the tran
can transcribe expressions into uses of the macros introduced by the letrec-syntax
expression.
+@example
+
(letrec-syntax
((my-or (syntax-rules ()
((my-or) #f)
@@ -2250,6 +2374,8 @@ expression.
(if y)
y))) ⟹ 7
+@end example
+
@node Pattern language
@subsection Pattern language
@@ -2370,6 +2496,8 @@ within <template> are treated as ordinary identifiers. In particular, the templa
(<ellipsis> <ellipsis>) produces a single <ellipsis>. This allows syntactic abstractions to
expand into code containing ellipses.
+@example
+
(define-syntax be-like-begin
(syntax-rules ()
((be-like-begin name)
@@ -2379,20 +2507,42 @@ expand into code containing ellipses.
(begin expr (... ...))))))))
(be-like-begin sequence)
-(sequence 1 2 3 4) ⟹ 4 As an example, if let and cond are defined as in section 7.3 then
+(sequence 1 2 3 4) ⟹ 4
+
+@end example
+
+As an example, if let and cond are defined as in section 7.3 then
they are hygienic (as required) and the following is not an error.
+@example
+
(let ((=> #f))
- (cond (#t => 'ok))) ⟹ ok The macro transformer for cond recognizes => as a local
+ (cond (#t => 'ok))) ⟹ ok
+
+@end example
+
+The macro transformer for cond recognizes @code{=>} as a local
variable, and hence an expression, and not as the base identifier =>, which the macro
transformer treats as a syntactic keyword. Thus the example expands into
+@example
+
(let ((=> #f))
- (if #t (begin => 'ok))) instead of
+ (if #t (begin => 'ok)))
+
+@end example
+
+instead of
+
+@example
(let ((=> #f))
(let ((temp #t))
- (if temp ('ok temp)))) which would result in an invalid procedure call.
+ (if temp ('ok temp))))
+
+@end example
+
+which would result in an invalid procedure call.
@node Signaling errors in macro transformers
@subsection Signaling errors in macro transformers
@@ -2407,6 +2557,8 @@ invalid use of the macro, which can provide more descriptive error messages.
information. Applications cannot count on being able to catch syntax errors with
exception handlers or guards.
+@example
+
(define-syntax simple-let
(syntax-rules ()
((_ (head ... ((x . y) val) . tail)
@@ -2418,6 +2570,8 @@ exception handlers or guards.
((lambda (name ...) body1 body2 ...)
val ...))))
+@end example
+
@node Program structure
@chapter Program structure
@@ -2547,12 +2701,16 @@ However, if <variable> is not bound, or is a syntactic keyword, then the definit
<variable> to a new location before performing the assignment, whereas it would be an
error to perform a set! on an unboundvariable.
+@example
+
(define add3
(lambda (x) (+ x 3)))
(add3 3) ⟹ 6
(define first car)
(first '(1 2)) ⟹ 1
+@end example
+
@node Internal definitions
@subsection Internal definitions
