From 68868ec34862282b4095cb79e2b33257eeec3a02 Mon Sep 17 00:00:00 2001 From: Chris Hanson Date: Tue, 20 Nov 2001 19:37:44 +0000 Subject: [PATCH] Eliminate the "+" notation for MIT Scheme extensions. This is ridiculous; virtually the entire manual is an extension. First partial draft of parser-language section. This covers the introduction and the subsection on *MATCHER. --- v7/doc/ref-manual/scheme.texinfo | 2836 +++++++++++++++++------------- 1 file changed, 1656 insertions(+), 1180 deletions(-) diff --git a/v7/doc/ref-manual/scheme.texinfo b/v7/doc/ref-manual/scheme.texinfo index 14b0527d9..c421af451 100644 --- a/v7/doc/ref-manual/scheme.texinfo +++ b/v7/doc/ref-manual/scheme.texinfo @@ -2,7 +2,7 @@ @iftex @finalout @end iftex -@comment $Id: scheme.texinfo,v 1.102 2001/11/17 06:01:20 cph Exp $ +@comment $Id: scheme.texinfo,v 1.103 2001/11/20 19:37:44 cph Exp $ @comment %**start of header (This is for running Texinfo on a region.) @setfilename scheme.info @settitle MIT Scheme Reference @@ -298,6 +298,7 @@ Input/Output * Prompting:: * Port Primitives:: * Parser Buffers:: +* Parser Language:: Port Primitives @@ -308,6 +309,12 @@ Port Primitives * Blocking Mode:: * Terminal Mode:: +Parser Language + +* *Matcher:: +* *Parser:: +* Parser-language Macros:: + Operating-System Interface * Pathnames:: @@ -644,24 +651,9 @@ procedure begins with one or more header lines in this format: @end deffn @noindent -where @var{category} specifies the kind of item (``variable'', ``special -form'', or ``procedure''), and how the item conforms to standard Scheme, as -follows: - -@table @asis -@item @var{category} -@var{Category}, with no extra marking, indicates that the item is described -in the @cite{Revised^4 Report on the Algorithmic Language Scheme}. - -@item @var{category}+ -A plus sign after @var{category} indicates that the item is an MIT -Scheme extension. -@cindex + in entries -@cindex plus sign, in entries -@end table - -@noindent -The form of @var{template} is interpreted depending on @var{category}. +where @var{category} specifies the kind of item (``variable'', +``special form'', or ``procedure''). The form of @var{template} is +interpreted depending on @var{category}. @table @asis @item Variable @@ -1689,7 +1681,7 @@ Some examples of @code{lambda} expressions: @end example @end deffn -@deffn {special form+} named-lambda formals expression expression @dots{} +@deffn {special form} named-lambda formals expression expression @dots{} @cindex named lambda (defn) The @code{named-lambda} special form is similar to @code{lambda}, except that the first ``required parameter'' in @var{formals} is not a @@ -1855,7 +1847,7 @@ the restriction is satisfied automatically. @node Dynamic Binding, Definitions, Lexical Binding, Special Forms @section Dynamic Binding -@deffn {special form+} fluid-let ((@var{variable} @var{init}) @dots{}) expression expression @dots{} +@deffn {special form} fluid-let ((@var{variable} @var{init}) @dots{}) expression expression @dots{} @cindex binding expression, dynamic (or fluid) @cindex fluid binding @cindex dynamic binding @@ -2745,7 +2737,7 @@ This section provides examples and describes the options and syntax of summarized at the end of this section. For more information, see Steele's Common Lisp book. -@deffn {special form+} define-structure (name structure-option @dots{}) slot-description @dots{} +@deffn {special form} define-structure (name structure-option @dots{}) slot-description @dots{} Each @var{slot-description} takes one of the following forms: @example @@ -3806,9 +3798,9 @@ quantity. For any Scheme number, precisely one of these predicates is true. @end deffn -@deffn {procedure+} exact-integer? object -@deffnx {procedure+} exact-nonnegative-integer? object -@deffnx {procedure+} exact-rational? object +@deffn procedure exact-integer? object +@deffnx procedure exact-nonnegative-integer? object +@deffnx procedure exact-rational? object These procedures test for some very common types of numbers. These tests could be written in terms of simpler predicates, but are more efficient. @@ -3922,8 +3914,8 @@ their argument. @end example @end deffn -@deffn {procedure+} 1+ z -@deffnx {procedure+} -1+ z +@deffn procedure 1+ z +@deffnx procedure -1+ z @code{(1+ z)} is equivalent to @code{(+ z 1)}; @code{(-1+ z)} is equivalent to @code{(- z 1)}. @end deffn @@ -4017,10 +4009,10 @@ the @code{modulo} always has the sign of the divisor: Note that @code{quotient} is the same as @code{integer-truncate}. @end deffn -@deffn {procedure+} integer-floor n1 n2 -@deffnx {procedure+} integer-ceiling n1 n2 -@deffnx {procedure+} integer-truncate n1 n2 -@deffnx {procedure+} integer-round n1 n2 +@deffn procedure integer-floor n1 n2 +@deffnx procedure integer-ceiling n1 n2 +@deffnx procedure integer-truncate n1 n2 +@deffnx procedure integer-round n1 n2 These procedures combine integer division with rounding. For example, the following are equivalent: @@ -4039,9 +4031,9 @@ result. Note that @code{integer-truncate} is the same as @code{quotient}. @end deffn -@deffn {procedure+} integer-divide n1 n2 -@deffnx {procedure+} integer-divide-quotient qr -@deffnx {procedure+} integer-divide-remainder qr +@deffn procedure integer-divide n1 n2 +@deffnx procedure integer-divide-quotient qr +@deffnx procedure integer-divide-remainder qr @findex quotient @findex remainder @code{integer-divide} is equivalent to performing both @code{quotient} @@ -4140,10 +4132,10 @@ the procedures below). @end example @end deffn -@deffn {procedure+} floor->exact x -@deffnx {procedure+} ceiling->exact x -@deffnx {procedure+} truncate->exact x -@deffnx {procedure+} round->exact x +@deffn procedure floor->exact x +@deffnx procedure ceiling->exact x +@deffnx procedure truncate->exact x +@deffnx procedure round->exact x These procedures are similar to the preceding procedures except that they always return an exact result. For example, the following are equivalent @@ -4160,7 +4152,7 @@ except that the former is faster and has fewer range restrictions. @end deffn @deffn procedure rationalize x y -@deffnx {procedure+} rationalize->exact x y +@deffnx procedure rationalize->exact x y @cindex simplest rational (defn) @cindex rational, simplest (defn) @code{rationalize} returns the @emph{simplest} rational number differing @@ -4186,8 +4178,8 @@ simplest rational of all. it always returns an exact result. @end deffn -@deffn {procedure+} simplest-rational x y -@deffnx {procedure+} simplest-exact-rational x y +@deffn procedure simplest-rational x y +@deffnx procedure simplest-exact-rational x y @code{simplest-rational} returns the simplest rational number between @var{x} and @var{y} inclusive; @code{simplest-exact-rational} is similar except that it always returns an exact result. @@ -4287,7 +4279,7 @@ $0^0$ is defined to be equal to 1. @deffnx procedure imag-part z @deffnx procedure magnitude z @deffnx procedure angle z -@deffnx {procedure+} conjugate z +@deffnx procedure conjugate z Suppose @var{x1}, @var{x2}, @var{x3}, and @var{x4} are real numbers and @var{z} is a complex number such that @tex @@ -4379,7 +4371,7 @@ satisfied by a result containing a decimal point. The unspecified case allows for infinities, NaNs, and non-flonum representations. @end deffn -@defvr {variable+} flonum-parser-fast? +@defvr variable flonum-parser-fast? This variable controls the behavior of @code{string->number} when parsing inexact numbers. Specifically, it allows the user to trade off accuracy against speed. @@ -4391,7 +4383,7 @@ in the result. The errors affect a few of the least-significant bits of the result, and consequently can be tolerated by many applications. @end defvr -@defvr {variable+} flonum-unparser-cutoff +@defvr variable flonum-unparser-cutoff This variable controls the action of @code{number->string} when @var{number} is a flonum (and consequently controls all printing of flonums). The value of this variable is normally a list of three items: @@ -4540,7 +4532,7 @@ always encoded as fixnums --- in other words, any exact integer that is not a fixnum is too big to be encoded as such. For this reason, small constants such as @code{0} or @code{1} are guaranteed to be fixnums. -@deffn {procedure+} fix:fixnum? object +@deffn procedure fix:fixnum? object @cindex type predicate, for fixnum Returns @code{#t} if @var{object} is a fixnum; otherwise returns @code{#f}. @@ -4560,19 +4552,19 @@ Here is an expression that determines the largest fixnum: @noindent A similar expression determines the smallest fixnum. -@deffn {procedure+} fix:= fixnum fixnum -@deffnx {procedure+} fix:< fixnum fixnum -@deffnx {procedure+} fix:> fixnum fixnum -@deffnx {procedure+} fix:<= fixnum fixnum -@deffnx {procedure+} fix:>= fixnum fixnum +@deffn procedure fix:= fixnum fixnum +@deffnx procedure fix:< fixnum fixnum +@deffnx procedure fix:> fixnum fixnum +@deffnx procedure fix:<= fixnum fixnum +@deffnx procedure fix:>= fixnum fixnum @cindex equivalence predicate, for fixnums These are the standard order and equality predicates on fixnums. When compiled, they do not check the types of their arguments. @end deffn -@deffn {procedure+} fix:zero? fixnum -@deffnx {procedure+} fix:positive? fixnum -@deffnx {procedure+} fix:negative? fixnum +@deffn procedure fix:zero? fixnum +@deffnx procedure fix:positive? fixnum +@deffnx procedure fix:negative? fixnum These procedures compare their argument to zero. When compiled, they do not check the type of their argument. The code produced by the following expressions is identical: @@ -4589,14 +4581,14 @@ Similarly, @code{fix:positive?} and @code{fix:negative?} produce code identical to equivalent expressions using @code{fix:>} and @code{fix:<}. @end deffn -@deffn {procedure+} fix:+ fixnum fixnum -@deffnx {procedure+} fix:- fixnum fixnum -@deffnx {procedure+} fix:* fixnum fixnum -@deffnx {procedure+} fix:quotient fixnum fixnum -@deffnx {procedure+} fix:remainder fixnum fixnum -@deffnx {procedure+} fix:gcd fixnum fixnum -@deffnx {procedure+} fix:1+ fixnum -@deffnx {procedure+} fix:-1+ fixnum +@deffn procedure fix:+ fixnum fixnum +@deffnx procedure fix:- fixnum fixnum +@deffnx procedure fix:* fixnum fixnum +@deffnx procedure fix:quotient fixnum fixnum +@deffnx procedure fix:remainder fixnum fixnum +@deffnx procedure fix:gcd fixnum fixnum +@deffnx procedure fix:1+ fixnum +@deffnx procedure fix:-1+ fixnum These procedures are the standard arithmetic operations on fixnums. When compiled, they do not check the types of their arguments. Furthermore, they do not check to see if the result can be encoded as a @@ -4605,7 +4597,7 @@ malformed object is returned, with potentially disastrous effect on the garbage collector. @end deffn -@deffn {procedure+} fix:divide fixnum fixnum +@deffn procedure fix:divide fixnum fixnum @findex integer-divide @findex integer-divide-quotient @findex integer-divide-remainder @@ -4618,7 +4610,7 @@ and its results must be fixnums. It should be used in conjunction with @cindex bitwise-logical operations, on fixnums The following are @dfn{bitwise-logical} operations on fixnums. -@deffn {procedure+} fix:not fixnum +@deffn procedure fix:not fixnum This returns the bitwise-logical inverse of its argument. When compiled, it does not check the type of its argument. @@ -4632,7 +4624,7 @@ compiled, it does not check the type of its argument. @end example @end deffn -@deffn {procedure+} fix:and fixnum fixnum +@deffn procedure fix:and fixnum fixnum This returns the bitwise-logical ``and'' of its arguments. When compiled, it does not check the types of its arguments. @@ -4644,7 +4636,7 @@ compiled, it does not check the types of its arguments. @end example @end deffn -@deffn {procedure+} fix:andc fixnum fixnum +@deffn procedure fix:andc fixnum fixnum Returns the bitwise-logical ``and'' of the first argument with the bitwise-logical inverse of the second argument. When compiled, it does not check the types of its arguments. @@ -4657,7 +4649,7 @@ not check the types of its arguments. @end example @end deffn -@deffn {procedure+} fix:or fixnum fixnum +@deffn procedure fix:or fixnum fixnum This returns the bitwise-logical ``inclusive or'' of its arguments. When compiled, it does not check the types of its arguments. @@ -4669,7 +4661,7 @@ When compiled, it does not check the types of its arguments. @end example @end deffn -@deffn {procedure+} fix:xor fixnum fixnum +@deffn procedure fix:xor fixnum fixnum This returns the bitwise-logical ``exclusive or'' of its arguments. When compiled, it does not check the types of its arguments. @@ -4681,7 +4673,7 @@ When compiled, it does not check the types of its arguments. @end example @end deffn -@deffn {procedure+} fix:lsh fixnum1 fixnum2 +@deffn procedure fix:lsh fixnum1 fixnum2 This procedure returns the result of logically shifting @var{fixnum1} by @var{fixnum2} bits. If @var{fixnum2} is positive, @var{fixnum1} is shifted left; if negative, it is shifted right. When compiled, it does @@ -4706,35 +4698,35 @@ floating-point number. In MIT Scheme, all inexact real numbers are flonums. For this reason, constants such as @code{0.} and @code{2.3} are guaranteed to be flonums. -@deffn {procedure+} flo:flonum? object +@deffn procedure flo:flonum? object @cindex type predicate, for flonum Returns @code{#t} if @var{object} is a flonum; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} flo:= flonum1 flonum2 -@deffnx {procedure+} flo:< flonum1 flonum2 -@deffnx {procedure+} flo:> flonum1 flonum2 +@deffn procedure flo:= flonum1 flonum2 +@deffnx procedure flo:< flonum1 flonum2 +@deffnx procedure flo:> flonum1 flonum2 @cindex equivalence predicate, for flonums These procedures are the standard order and equality predicates on flonums. When compiled, they do not check the types of their arguments. @end deffn -@deffn {procedure+} flo:zero? flonum -@deffnx {procedure+} flo:positive? flonum -@deffnx {procedure+} flo:negative? flonum +@deffn procedure flo:zero? flonum +@deffnx procedure flo:positive? flonum +@deffnx procedure flo:negative? flonum Each of these procedures compares its argument to zero. When compiled, they do not check the type of their argument. @end deffn -@deffn {procedure+} flo:+ flonum1 flonum2 -@deffnx {procedure+} flo:- flonum1 flonum2 -@deffnx {procedure+} flo:* flonum1 flonum2 -@deffnx {procedure+} flo:/ flonum1 flonum2 +@deffn procedure flo:+ flonum1 flonum2 +@deffnx procedure flo:- flonum1 flonum2 +@deffnx procedure flo:* flonum1 flonum2 +@deffnx procedure flo:/ flonum1 flonum2 These procedures are the standard arithmetic operations on flonums. When compiled, they do not check the types of their arguments. @end deffn -@deffn {procedure+} flo:finite? flonum +@deffn procedure flo:finite? flonum @vindex +inf @vindex -inf @vindex NaN @@ -4748,36 +4740,36 @@ special ``numbers'': positive infinity (@code{+inf}), negative infinity is any other floating-point number. @end deffn -@deffn {procedure+} flo:negate flonum +@deffn procedure flo:negate flonum This procedure returns the negation of its argument. When compiled, it does not check the type of its argument. Equivalent to @code{(flo:- 0. @var{flonum})}. @end deffn -@deffn {procedure+} flo:abs flonum -@deffnx {procedure+} flo:exp flonum -@deffnx {procedure+} flo:log flonum -@deffnx {procedure+} flo:sin flonum -@deffnx {procedure+} flo:cos flonum -@deffnx {procedure+} flo:tan flonum -@deffnx {procedure+} flo:asin flonum -@deffnx {procedure+} flo:acos flonum -@deffnx {procedure+} flo:atan flonum -@deffnx {procedure+} flo:sqrt flonum -@deffnx {procedure+} flo:expt flonum1 flonum2 -@deffnx {procedure+} flo:floor flonum -@deffnx {procedure+} flo:ceiling flonum -@deffnx {procedure+} flo:truncate flonum -@deffnx {procedure+} flo:round flonum -@deffnx {procedure+} flo:floor->exact flonum -@deffnx {procedure+} flo:ceiling->exact flonum -@deffnx {procedure+} flo:truncate->exact flonum -@deffnx {procedure+} flo:round->exact flonum +@deffn procedure flo:abs flonum +@deffnx procedure flo:exp flonum +@deffnx procedure flo:log flonum +@deffnx procedure flo:sin flonum +@deffnx procedure flo:cos flonum +@deffnx procedure flo:tan flonum +@deffnx procedure flo:asin flonum +@deffnx procedure flo:acos flonum +@deffnx procedure flo:atan flonum +@deffnx procedure flo:sqrt flonum +@deffnx procedure flo:expt flonum1 flonum2 +@deffnx procedure flo:floor flonum +@deffnx procedure flo:ceiling flonum +@deffnx procedure flo:truncate flonum +@deffnx procedure flo:round flonum +@deffnx procedure flo:floor->exact flonum +@deffnx procedure flo:ceiling->exact flonum +@deffnx procedure flo:truncate->exact flonum +@deffnx procedure flo:round->exact flonum These procedures are flonum versions of the corresponding procedures. When compiled, they do not check the types of their arguments. @end deffn -@deffn {procedure+} flo:atan2 flonum1 flonum2 +@deffn procedure flo:atan2 flonum1 flonum2 @findex atan This is the flonum version of @code{atan} with two arguments. When compiled, it does not check the types of its arguments. @@ -4801,7 +4793,7 @@ while retaining the same interface. The interface described here is very similar to that of Common Lisp. -@deffn {procedure+} random modulus [state] +@deffn procedure random modulus [state] @var{Modulus} must be a positive real number. @code{random} returns a pseudo-random number between zero (inclusive) and @var{modulus} (exclusive). The exactness of the returned number is the same as the @@ -4830,7 +4822,7 @@ pseudo-random-number generator and is altered as a side effect of the @end example @end deffn -@deffn {procedure+} flo:random-unit state +@deffn procedure flo:random-unit state @var{State} must be a random-state object. @code{flo:random-unit} returns a pseudo-random number between zero inclusive and one exclusive; the returned number is always a flonum and therefore an inexact real @@ -4845,7 +4837,7 @@ specifically designed so that they can be saved to disk using the procedure. This allows a particular random-state object to be saved in order to replay a particular pseudo-random sequence. -@defvr {variable+} *random-state* +@defvr variable *random-state* This variable holds a data structure, a random-state object, that encodes the internal state of the random-number generator that @code{random} uses by default. A call to @code{random} will perform a @@ -4853,7 +4845,7 @@ side effect on this data structure. This variable may be changed, using @code{set!} or @code{fluid-let}, to hold a new random-state object. @end defvr -@deffn {procedure+} make-random-state [state] +@deffn procedure make-random-state [state] This procedure returns a new random-state object, suitable for use as the value of the variable @code{*random-state*}, or as the @var{state} argument to @code{random}. If @var{state} is not given or @code{#f}, @@ -4865,7 +4857,7 @@ random-state object is returned that has been ``randomly'' initialized by some means (such as by a time-of-day clock). @end deffn -@deffn {procedure+} random-state? object +@deffn procedure random-state? object Returns @code{#t} if @var{object} is a random-state object, otherwise returns @code{#f}. @end deffn @@ -5006,7 +4998,7 @@ DEL @end group @end example -@deffn {procedure+} char->name char [slashify?] +@deffn procedure char->name char [slashify?] Returns a string corresponding to the printed representation of @var{char}. This is the @var{character} or @var{character-name} component of the external representation, combined with the appropriate @@ -5035,7 +5027,7 @@ representation of @var{char}: If @var{slashify?} is not specified, it defaults to @code{#f}. @end deffn -@deffn {procedure+} name->char string +@deffn procedure name->char string Converts a string that names a character into the character specified. If @var{string} does not name any character, @code{name->char} signals an error. @@ -5119,7 +5111,7 @@ return a character @var{char2} such that @code{(char-ci=? @var{char} @var{char2})}. @end deffn -@deffn {procedure+} char->digit char [radix] +@deffn procedure char->digit char [radix] If @var{char} is a character representing a digit in the given @var{radix}, returns the corresponding integer value. If you specify @var{radix} (which must be an exact integer between 2 and 36 inclusive), @@ -5139,7 +5131,7 @@ Note that this procedure is insensitive to the alphabetic case of @end example @end deffn -@deffn {procedure+} digit->char digit [radix] +@deffn procedure digit->char digit [radix] Returns a character that represents @var{digit} in the radix given by @var{radix}. @var{Radix} must be an exact integer between 2 and 36 (inclusive), and defaults to 10. @var{Digit}, which must be an @@ -5181,7 +5173,7 @@ contain the @acronym{ISO-8859-1} representation for the character. The representation is expanded in order to allow for the use of @acronym{UTF-16} in the future. -@deffn {procedure+} make-char code bucky-bits +@deffn procedure make-char code bucky-bits @cindex construction, of character Builds a character from @var{code} and @var{bucky-bits}. Both @var{code} and @var{bucky-bits} must be exact non-negative integers in @@ -5212,7 +5204,7 @@ For example, @end example @end deffn -@deffn {procedure+} char-bits char +@deffn procedure char-bits char @cindex selection, of character component @cindex component selection, of character Returns the exact integer representation of @var{char}'s bucky bits. @@ -5228,7 +5220,7 @@ For example, @end example @end deffn -@deffn {procedure+} char-code char +@deffn procedure char-code char Returns the character code of @var{char}, an exact integer. For example, @@ -5240,8 +5232,8 @@ example, @end example @end deffn -@defvr {variable+} char-code-limit -@defvrx {variable+} char-bits-limit +@defvr variable char-code-limit +@defvrx variable char-bits-limit These variables define the (exclusive) upper limits for the character code and bucky bits (respectively). The character code and bucky bits are always exact non-negative integers, and are strictly less than the @@ -5294,7 +5286,7 @@ the corresponding result. This is a very useful way to denote unusual character constants or @acronym{ASCII} codes. @end deffn -@defvr {variable+} char-integer-limit +@defvr variable char-integer-limit The range of @code{char->integer} is defined to be the exact non-negative integers that are less than the value of this variable (exclusive). @@ -5321,7 +5313,7 @@ For historical reasons, the procedures that manipulate @acronym{ISO-8859-1} characters use the word ``@acronym{ASCII}'' rather than ``@acronym{ISO-8859-1}''. -@deffn {procedure+} char-ascii? char +@deffn procedure char-ascii? char Returns the @acronym{ISO-8859-1} code for @var{char} if @var{char} has an @acronym{ISO-8859-1} representation; otherwise returns @code{#f}. @@ -5330,14 +5322,14 @@ predicate are those in which the bucky bits are turned off, and for which the character code is less than 256. @end deffn -@deffn {procedure+} char->ascii char +@deffn procedure char->ascii char Returns the @acronym{ISO-8859-1} code for @var{char}. An error @code{condition-type:bad-range-argument} is signalled if @var{char} doesn't have an @acronym{ISO-8859-1} representation. @findex condition-type:bad-range-argument @end deffn -@deffn {procedure+} ascii->char code +@deffn procedure ascii->char code @var{Code} must be the exact integer representation of an @acronym{ISO-8859-1} code. This procedure returns the character corresponding to @var{code}. @@ -5358,22 +5350,22 @@ There is no meaningful external representation for character sets; use present) no specific equivalence predicate for character sets; use @code{equal?} for this purpose. -@deffn {procedure+} char-set? object +@deffn procedure char-set? object @cindex type predicate, for character set Returns @code{#t} if @var{object} is a character set; otherwise returns @code{#f}. @end deffn -@defvr {variable+} char-set:upper-case -@defvrx {variable+} char-set:lower-case -@defvrx {variable+} char-set:alphabetic -@defvrx {variable+} char-set:numeric -@defvrx {variable+} char-set:alphanumeric -@defvrx {variable+} char-set:whitespace -@defvrx {variable+} char-set:not-whitespace -@defvrx {variable+} char-set:graphic -@defvrx {variable+} char-set:not-graphic -@defvrx {variable+} char-set:standard +@defvr variable char-set:upper-case +@defvrx variable char-set:lower-case +@defvrx variable char-set:alphabetic +@defvrx variable char-set:numeric +@defvrx variable char-set:alphanumeric +@defvrx variable char-set:whitespace +@defvrx variable char-set:not-whitespace +@defvrx variable char-set:graphic +@defvrx variable char-set:not-graphic +@defvrx variable char-set:standard These variables contain predefined character sets. To see the contents of one of these sets, use @code{char-set-members}. @@ -5421,42 +5413,42 @@ a b c d e f g h i j k l m n o p q r s t u v w x y z @deffnx {procedure} char-lower-case? char @deffnx {procedure} char-alphabetic? char @deffnx {procedure} char-numeric? char -@deffnx {procedure+} char-alphanumeric? char +@deffnx procedure char-alphanumeric? char @deffnx {procedure} char-whitespace? char -@deffnx {procedure+} char-graphic? char -@deffnx {procedure+} char-standard? object +@deffnx procedure char-graphic? char +@deffnx procedure char-standard? object These predicates are defined in terms of the respective character sets defined above. @end deffn -@deffn {procedure+} char-set-members char-set +@deffn procedure char-set-members char-set Returns a newly allocated list of the characters in @var{char-set}. @end deffn -@deffn {procedure+} char-set-member? char-set char +@deffn procedure char-set-member? char-set char Returns @code{#t} if @var{char} is in @var{char-set}; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} char-set char @dots{} +@deffn procedure char-set char @dots{} @cindex construction, of character set Returns a character set consisting of the specified @acronym{ISO-8859-1} characters. With no arguments, @code{char-set} returns an empty character set. @end deffn -@deffn {procedure+} chars->char-set chars +@deffn procedure chars->char-set chars Returns a character set consisting of @var{chars}, which must be a list of @acronym{ISO-8859-1} characters. This is equivalent to @code{(apply char-set @var{chars})}. @end deffn -@deffn {procedure+} string->char-set string +@deffn procedure string->char-set string Returns a character set consisting of all the characters that occur in @var{string}. @end deffn -@deffn {procedure+} ascii-range->char-set lower upper +@deffn procedure ascii-range->char-set lower upper @var{Lower} and @var{upper} must be exact non-negative integers representing @acronym{ISO-8859-1} character codes, and @var{lower} must be less than or equal to @var{upper}. This procedure creates and @@ -5468,29 +5460,29 @@ For historical reasons, the name of this procedure refers to ``@acronym{ASCII}'' rather than ``@acronym{ISO-8859-1}''. @end deffn -@deffn {procedure+} predicate->char-set predicate +@deffn procedure predicate->char-set predicate @var{Predicate} must be a procedure of one argument. @code{predicate->char-set} creates and returns a character set consisting of the @acronym{ISO-8859-1} characters for which @var{predicate} is true. @end deffn -@deffn {procedure+} char-set-difference char-set1 char-set2 +@deffn procedure char-set-difference char-set1 char-set2 Returns a character set consisting of the characters that are in @var{char-set1} but aren't in @var{char-set2}. @end deffn -@deffn {procedure+} char-set-intersection char-set @dots{} +@deffn procedure char-set-intersection char-set @dots{} Returns a character set consisting of the characters that are in all of the @var{char-set}s. @end deffn -@deffn {procedure+} char-set-union char-set @dots{} +@deffn procedure char-set-union char-set @dots{} Returns a character set consisting of the characters that are in at least one o the @var{char-set}s. @end deffn -@deffn {procedure+} char-set-invert char-set +@deffn procedure char-set-invert char-set Returns a character set consisting of the @acronym{ISO-8859-1} characters that are not in @var{char-set}. @end deffn @@ -5638,7 +5630,7 @@ satisfy the predicate @code{char-ascii?}. @end example @end deffn -@deffn {procedure+} string char @dots{} +@deffn procedure string char @dots{} Returns a newly allocated string consisting of the specified characters. The arguments must all satisfy @code{char-ascii?}. @@ -5772,9 +5764,9 @@ str @result{} "Log" @cindex comparison, of strings @deffn procedure string=? string1 string2 -@deffnx {procedure+} substring=? string1 start end string2 start end +@deffnx procedure substring=? string1 start end string2 start end @deffnx {procedure} string-ci=? string1 string2 -@deffnx {procedure+} substring-ci=? string1 start end string2 start end +@deffnx procedure substring-ci=? string1 start end string2 start end @cindex equivalence predicate, for strings Returns @code{#t} if the two strings (substrings) are the same length and contain the same characters in the same (relative) positions; @@ -5793,12 +5785,12 @@ but @code{string=?} and @code{substring=?} do. @end deffn @deffn procedure string? string1 string2 @deffnx procedure string<=? string1 string2 @deffnx procedure string>=? string1 string2 @deffnx {procedure} string-ci? string1 string2 @deffnx {procedure} string-ci<=? string1 string2 @deffnx {procedure} string-ci>=? string1 string2 @@ -5819,8 +5811,8 @@ longer string. @end example @end deffn -@deffn {procedure+} string-compare string1 string2 if-eq if-lt if-gt -@deffnx {procedure+} string-compare-ci string1 string2 if-eq if-lt if-gt +@deffn procedure string-compare string1 string2 if-eq if-lt if-gt +@deffnx procedure string-compare-ci string1 string2 if-eq if-lt if-gt @var{If-eq}, @var{if-lt}, and @var{if-gt} are procedures of no arguments (thunks). The two strings are compared; if they are equal, @var{if-eq} is applied, if @var{string1} is less than @var{string2}, @var{if-lt} is @@ -5842,8 +5834,8 @@ thunk that is applied. @end example @end deffn -@deffn {procedure+} string-hash string -@deffnx {procedure+} string-hash-mod string k +@deffn procedure string-hash string +@deffnx procedure string-hash-mod string k @cindex hashing, of string @findex string=? @findex = @@ -5873,8 +5865,8 @@ the result to a particular range based on the exact non-negative integer @cindex uppercase, in string @cindex lowercase, in string -@deffn {procedure+} string-capitalized? string -@deffnx {procedure+} substring-capitalized? string start end +@deffn procedure string-capitalized? string +@deffnx procedure substring-capitalized? string start end These procedures return @code{#t} if the first word in the string (substring) is capitalized, and any subsequent words are either lower case or capitalized. Otherwise, they return @code{#f}. A word is @@ -5891,10 +5883,10 @@ and all its remaining letters are lower case. @end example @end deffn -@deffn {procedure+} string-upper-case? string -@deffnx {procedure+} substring-upper-case? string start end -@deffnx {procedure+} string-lower-case? string -@deffnx {procedure+} substring-lower-case? string start end +@deffn procedure string-upper-case? string +@deffnx procedure substring-upper-case? string start end +@deffnx procedure string-lower-case? string +@deffnx procedure substring-lower-case? string start end These procedures return @code{#t} if all the letters in the string (substring) are of the correct case, otherwise they return @code{#f}. The string (substring) must contain at least one letter or the @@ -5908,9 +5900,9 @@ procedures return @code{#f}. @end example @end deffn -@deffn {procedure+} string-capitalize string -@deffnx {procedure+} string-capitalize! string -@deffnx {procedure+} substring-capitalize! string start end +@deffn procedure string-capitalize string +@deffnx procedure string-capitalize! string +@deffnx procedure substring-capitalize! string start end @code{string-capitalize} returns a newly allocated copy of @var{string} in which the first alphabetic character is uppercase and the remaining alphabetic characters are lowercase. For example, @code{"abcDEF"} @@ -5920,9 +5912,9 @@ an unspecified value. @code{substring-capitalize!} destructively capitalizes the specified part of @var{string}. @end deffn -@deffn {procedure+} string-downcase string -@deffnx {procedure+} string-downcase! string -@deffnx {procedure+} substring-downcase! string start end +@deffn procedure string-downcase string +@deffnx procedure string-downcase! string +@deffnx procedure substring-downcase! string start end @code{string-downcase} returns a newly allocated copy of @var{string} in which all uppercase letters are changed to lowercase. @code{string-downcase!} is the destructive version of @@ -5939,9 +5931,9 @@ str @result{} "ABCdeFG" @end example @end deffn -@deffn {procedure+} string-upcase string -@deffnx {procedure+} string-upcase! string -@deffnx {procedure+} substring-upcase! string start end +@deffn procedure string-upcase string +@deffnx procedure string-upcase! string +@deffnx procedure substring-upcase! string start end @code{string-upcase} returns a newly allocated copy of @var{string} in which all lowercase letters are changed to uppercase. @code{string-upcase!} is the destructive version of @@ -5988,7 +5980,7 @@ with @var{end} (exclusive). @end example @end deffn -@deffn {procedure+} string-head string end +@deffn procedure string-head string end Returns a newly allocated copy of the initial substring of @var{string}, up to but excluding @var{end}. It could have been defined by: @@ -6000,7 +5992,7 @@ up to but excluding @var{end}. It could have been defined by: @end example @end deffn -@deffn {procedure+} string-tail string start +@deffn procedure string-tail string start Returns a newly allocated copy of the final substring of @var{string}, starting at index @var{start} and going to the end of @var{string}. It could have been defined by: @@ -6015,8 +6007,8 @@ could have been defined by: @end example @end deffn -@deffn {procedure+} string-pad-left string k [char] -@deffnx {procedure+} string-pad-right string k [char] +@deffn procedure string-pad-left string k [char] +@deffnx procedure string-pad-right string k [char] @cindex padding, of string @findex #\space These procedures return a newly allocated string created by padding @@ -6039,9 +6031,9 @@ indices). @end example @end deffn -@deffn {procedure+} string-trim string [char-set] -@deffnx {procedure+} string-trim-left string [char-set] -@deffnx {procedure+} string-trim-right string [char-set] +@deffn procedure string-trim string [char-set] +@deffnx procedure string-trim-left string [char-set] +@deffnx procedure string-trim-right string [char-set] @cindex trimming, of string @findex char-set:whitespace Returns a newly allocated string created by removing all characters that @@ -6077,8 +6069,8 @@ short patterns of less than 4 characters, the naive string-search algorithm is used. For longer patterns, the Boyer-Moore string-search algorithm is used. -@deffn {procedure+} string-search-forward pattern string -@deffnx {procedure+} substring-search-forward pattern string start end +@deffn procedure string-search-forward pattern string +@deffnx procedure substring-search-forward pattern string start end @var{Pattern} must be a string. Searches @var{string} for the leftmost occurrence of the substring @var{pattern}. If successful, the index of the first character of the matched substring is returned; otherwise, @@ -6102,8 +6094,8 @@ substring of @var{string}; @code{string-search-forward} searches all of @end example @end deffn -@deffn {procedure+} string-search-backward pattern string -@deffnx {procedure+} substring-search-backward pattern string start end +@deffn procedure string-search-backward pattern string +@deffnx procedure substring-search-backward pattern string start end @var{Pattern} must be a string. Searches @var{string} for the rightmost occurrence of the substring @var{pattern}. If successful, the index to the right of the last character of the matched substring is returned; @@ -6127,8 +6119,8 @@ substring of @var{string}; @code{string-search-backward} searches all of @end example @end deffn -@deffn {procedure+} string-search-all pattern string -@deffnx {procedure+} substring-search-all pattern string start end +@deffn procedure string-search-all pattern string +@deffnx procedure substring-search-all pattern string start end @var{Pattern} must be a string. Searches @var{string} to find all occurrences of the substring @var{pattern}. Returns a list of the occurrences; each element of the list is an index pointing to the first @@ -6151,7 +6143,7 @@ of @var{string}; @code{string-search-all} searches all of @var{string}. @end example @end deffn -@deffn {procedure+} substring? pattern string +@deffn procedure substring? pattern string @var{Pattern} must be a string. Searches @var{string} to see if it contains the substring @var{pattern}. Returns @code{#t} if @var{pattern} is a substring of @var{string}, otherwise returns @@ -6169,10 +6161,10 @@ contains the substring @var{pattern}. Returns @code{#t} if @end example @end deffn -@deffn {procedure+} string-find-next-char string char -@deffnx {procedure+} substring-find-next-char string start end char -@deffnx {procedure+} string-find-next-char-ci string char -@deffnx {procedure+} substring-find-next-char-ci string start end char +@deffn procedure string-find-next-char string char +@deffnx procedure substring-find-next-char string start end char +@deffnx procedure string-find-next-char-ci string char +@deffnx procedure substring-find-next-char-ci string start end char Returns the index of the first occurrence of @var{char} in the string (substring); returns @code{#f} if @var{char} does not appear in the string. For the substring procedures, the index returned is relative to @@ -6188,8 +6180,8 @@ don't distinguish uppercase and lowercase letters. @end example @end deffn -@deffn {procedure+} string-find-next-char-in-set string char-set -@deffnx {procedure+} substring-find-next-char-in-set string start end char-set +@deffn procedure string-find-next-char-in-set string char-set +@deffnx procedure substring-find-next-char-in-set string start end char-set Returns the index of the first character in the string (or substring) that is also in @var{char-set}, or returns @code{#f} if none of the characters in @var{char-set} occur in @var{string}. @@ -6209,10 +6201,10 @@ index returned is relative to the entire string, not just the substring. @end example @end deffn -@deffn {procedure+} string-find-previous-char string char -@deffnx {procedure+} substring-find-previous-char string start end char -@deffnx {procedure+} string-find-previous-char-ci string char -@deffnx {procedure+} substring-find-previous-char-ci string start end char +@deffn procedure string-find-previous-char string char +@deffnx procedure substring-find-previous-char string start end char +@deffnx procedure string-find-previous-char-ci string char +@deffnx procedure substring-find-previous-char-ci string start end char Returns the index of the last occurrence of @var{char} in the string (substring); returns @code{#f} if @var{char} doesn't appear in the string. For the substring procedures, the index returned is relative to @@ -6220,8 +6212,8 @@ the entire string, not just the substring. The @code{-ci} procedures don't distinguish uppercase and lowercase letters. @end deffn -@deffn {procedure+} string-find-previous-char-in-set string char-set -@deffnx {procedure+} substring-find-previous-char-in-set string start end char-set +@deffn procedure string-find-previous-char-in-set string char-set +@deffnx procedure substring-find-previous-char-in-set string start end char-set Returns the index of the last character in the string (substring) that is also in @var{char-set}. For the substring procedure, the index returned is relative to the entire string, not just the substring. @@ -6231,10 +6223,10 @@ returned is relative to the entire string, not just the substring. @section Matching Strings @cindex matching, of strings -@deffn {procedure+} string-match-forward string1 string2 -@deffnx {procedure+} substring-match-forward string1 start end string2 start end -@deffnx {procedure+} string-match-forward-ci string1 string2 -@deffnx {procedure+} substring-match-forward-ci string1 start end string2 start end +@deffn procedure string-match-forward string1 string2 +@deffnx procedure substring-match-forward string1 start end string2 start end +@deffnx procedure string-match-forward-ci string1 string2 +@deffnx procedure substring-match-forward-ci string1 start end string2 start end Compares the two strings (substrings), starting from the beginning, and returns the number of characters that are the same. If the two strings (substrings) start differently, returns 0. The @code{-ci} procedures @@ -6248,10 +6240,10 @@ don't distinguish uppercase and lowercase letters. @end example @end deffn -@deffn {procedure+} string-match-backward string1 string2 -@deffnx {procedure+} substring-match-backward string1 start end string2 start end -@deffnx {procedure+} string-match-backward-ci string1 string2 -@deffnx {procedure+} substring-match-backward-ci string1 start end string2 start end +@deffn procedure string-match-backward string1 string2 +@deffnx procedure substring-match-backward string1 start end string2 start end +@deffnx procedure string-match-backward-ci string1 string2 +@deffnx procedure substring-match-backward-ci string1 start end string2 start end Compares the two strings (substrings), starting from the end and matching toward the front, returning the number of characters that are the same. If the two strings (substrings) end differently, returns 0. @@ -6266,10 +6258,10 @@ letters. @end example @end deffn -@deffn {procedure+} string-prefix? string1 string2 -@deffnx {procedure+} substring-prefix? string1 start1 end1 string2 start2 end2 -@deffnx {procedure+} string-prefix-ci? string1 string2 -@deffnx {procedure+} substring-prefix-ci? string1 start1 end1 string2 start2 end2 +@deffn procedure string-prefix? string1 string2 +@deffnx procedure substring-prefix? string1 start1 end1 string2 start2 end2 +@deffnx procedure string-prefix-ci? string1 string2 +@deffnx procedure substring-prefix-ci? string1 start1 end1 string2 start2 end2 @cindex prefix, of string These procedures return @code{#t} if the first string (substring) forms the prefix of the second; otherwise returns @code{#f}. The @code{-ci} @@ -6283,10 +6275,10 @@ procedures don't distinguish uppercase and lowercase letters. @end example @end deffn -@deffn {procedure+} string-suffix? string1 string2 -@deffnx {procedure+} substring-suffix? string1 start1 end1 string2 start2 end2 -@deffnx {procedure+} string-suffix-ci? string1 string2 -@deffnx {procedure+} substring-suffix-ci? string1 start1 end1 string2 start2 end2 +@deffn procedure string-suffix? string1 string2 +@deffnx procedure substring-suffix? string1 start1 end1 string2 start2 end2 +@deffnx procedure string-suffix-ci? string1 string2 +@deffnx procedure substring-suffix-ci? string1 start1 end1 string2 start2 end2 @cindex suffix, of string These procedures return @code{#t} if the first string (substring) forms the suffix of the second; otherwise returns @code{#f}. The @code{-ci} @@ -6350,8 +6342,8 @@ Supplying @code{#f} for (or omitting) @var{syntax-table} will select the default character syntax, equivalent to Edwin's @code{fundamental} mode. -@deffn {procedure+} re-string-match regexp string [case-fold? [syntax-table]] -@deffnx {procedure+} re-substring-match regexp string start end [case-fold? [syntax-table]] +@deffn procedure re-string-match regexp string [case-fold? [syntax-table]] +@deffnx procedure re-substring-match regexp string start end [case-fold? [syntax-table]] These procedures match @var{regexp} against the respective string or substring, returning @code{#f} for no match, or a set of match registers (see below) if the match succeeds. Here is an example showing how to @@ -6366,8 +6358,8 @@ extract the matched substring: @end example @end deffn -@deffn {procedure+} re-string-search-forward regexp string [case-fold? [syntax-table]] -@deffnx {procedure+} re-substring-search-forward regexp string start end [case-fold? [syntax-table]] +@deffn procedure re-string-search-forward regexp string [case-fold? [syntax-table]] +@deffnx procedure re-substring-search-forward regexp string start end [case-fold? [syntax-table]] Searches @var{string} for the leftmost substring matching @var{regexp}. Returns a set of match registers (see below) if the search is successful, or @code{#f} if it is unsuccessful. @@ -6377,8 +6369,8 @@ substring of @var{string}; @code{re-string-search-forward} searches all of @var{string}. @end deffn -@deffn {procedure+} re-string-search-backward regexp string [case-fold? [syntax-table]] -@deffnx {procedure+} re-substring-search-backward regexp string start end [case-fold? [syntax-table]] +@deffn procedure re-string-search-backward regexp string [case-fold? [syntax-table]] +@deffnx procedure re-substring-search-backward regexp string start end [case-fold? [syntax-table]] Searches @var{string} for the rightmost substring matching @var{regexp}. Returns a set of match registers (see below) if the search is successful, or @code{#f} if it is unsuccessful. @@ -6398,8 +6390,8 @@ from @code{1} to @code{9}, corresponding left-to-right to the grouping operators in the expression. Additionally, register @code{0} corresponds to the entire substring matching the regular expression. -@deffn {procedure+} re-match-start-index n registers -@deffnx {procedure+} re-match-end-index n registers +@deffn procedure re-match-start-index n registers +@deffnx procedure re-match-end-index n registers @var{N} must be an exact integer between @code{0} and @code{9} inclusive. @var{Registers} must be a match-registers object as returned by one of the regular-expression match or search procedures above. @@ -6408,7 +6400,7 @@ regular-expression register, and @code{re-match-end-index} returns the corresponding end index. @end deffn -@deffn {procedure+} re-match-extract string registers n +@deffn procedure re-match-extract string registers n @var{Registers} must be a match-registers object as returned by one of the regular-expression match or search procedures above. @var{String} must be the string that was passed as an argument to the procedure that @@ -6430,7 +6422,7 @@ to the following expression: @end example @end deffn -@deffn {procedure+} regexp-group alternative @dots{} +@deffn procedure regexp-group alternative @dots{} Each @var{alternative} must be a regular expression. The returned value is a new regular expression that consists of the @var{alternative}s combined by a grouping operator. For example: @@ -6465,7 +6457,7 @@ structure of regular expressions explicit, and that it simplifies the description of complex regular expressions by allowing them to be built up using straightforward combinators. -@deffn {procedure+} rexp? object +@deffn procedure rexp? object Returns @code{#t} if @var{object} is a @acronym{REXP} expression, or @code{#f} otherwise. A @acronym{REXP} is one of: a string, which represents the pattern matching that string; a character set, which @@ -6473,12 +6465,12 @@ represents the pattern matching a character in that set; or an object returned by calling one of the procedures defined here. @end deffn -@deffn {procedure+} rexp->regexp rexp +@deffn procedure rexp->regexp rexp Converts @var{rexp} to standard regular-expression notation, returning a newly-allocated string. @end deffn -@deffn {procedure+} rexp-compile rexp +@deffn procedure rexp-compile rexp Converts @var{rexp} to standard regular-expression notation, then compiles it and returns the compiled result. Equivalent to @@ -6487,57 +6479,57 @@ compiles it and returns the compiled result. Equivalent to @end example @end deffn -@deffn {procedure+} rexp-any-char +@deffn procedure rexp-any-char Returns a @acronym{REXP} that matches any single character except a newline. This is equivalent to the @code{.} construct. @end deffn -@deffn {procedure+} rexp-line-start +@deffn procedure rexp-line-start Returns a @acronym{REXP} that matches the start of a line. This is equivalent to the @code{^} construct. @end deffn -@deffn {procedure+} rexp-line-end +@deffn procedure rexp-line-end Returns a @acronym{REXP} that matches the end of a line. This is equivalent to the @code{$} construct. @end deffn -@deffn {procedure+} rexp-string-start +@deffn procedure rexp-string-start Returns a @acronym{REXP} that matches the start of the text being matched. This is equivalent to the @code{\`} construct. @end deffn -@deffn {procedure+} rexp-string-end +@deffn procedure rexp-string-end Returns a @acronym{REXP} that matches the end of the text being matched. This is equivalent to the @code{\'} construct. @end deffn -@deffn {procedure+} rexp-word-edge +@deffn procedure rexp-word-edge Returns a @acronym{REXP} that matches the start or end of a word. This is equivalent to the @code{\b} construct. @end deffn -@deffn {procedure+} rexp-not-word-edge +@deffn procedure rexp-not-word-edge Returns a @acronym{REXP} that matches anywhere that is not the start or end of a word. This is equivalent to the @code{\B} construct. @end deffn -@deffn {procedure+} rexp-word-start +@deffn procedure rexp-word-start Returns a @acronym{REXP} that matches the start of a word. This is equivalent to the @code{\<} construct. @end deffn -@deffn {procedure+} rexp-word-end +@deffn procedure rexp-word-end Returns a @acronym{REXP} that matches the end of a word. This is equivalent to the @code{\>} construct. @end deffn -@deffn {procedure+} rexp-word-char +@deffn procedure rexp-word-char Returns a @acronym{REXP} that matches any word-constituent character. This is equivalent to the @code{\w} construct. @end deffn -@deffn {procedure+} rexp-not-word-char +@deffn procedure rexp-not-word-char Returns a @acronym{REXP} that matches any character that isn't a word constituent. This is equivalent to the @code{\W} construct. @end deffn @@ -6560,31 +6552,31 @@ equivalent character used in standard regular-expression notation. @code{comment-start} (@code{<}), @code{comment-end} (@code{>}). -@deffn {procedure+} rexp-syntax-char syntax-type +@deffn procedure rexp-syntax-char syntax-type Returns a @acronym{REXP} that matches any character of type @var{syntax-type}. This is equivalent to the @code{\s} construct. @end deffn -@deffn {procedure+} rexp-not-syntax-char syntax-type +@deffn procedure rexp-not-syntax-char syntax-type Returns a @acronym{REXP} that matches any character not of type @var{syntax-type}. This is equivalent to the @code{\S} construct. @end deffn -@deffn {procedure+} rexp-sequence rexp @dots{} +@deffn procedure rexp-sequence rexp @dots{} Returns a @acronym{REXP} that matches each @var{rexp} argument in sequence. If no @var{rexp} argument is supplied, the result matches the null string. This is equivalent to concatenating the regular expressions corresponding to each @var{rexp} argument. @end deffn -@deffn {procedure+} rexp-alternatives rexp @dots{} +@deffn procedure rexp-alternatives rexp @dots{} Returns a @acronym{REXP} that matches any of the @var{rexp} arguments. This is equivalent to concatenating the regular expressions corresponding to each @var{rexp} argument, separating them by the @code{\|} construct. @end deffn -@deffn {procedure+} rexp-group rexp @dots{} +@deffn procedure rexp-group rexp @dots{} @code{rexp-group} is like @code{rexp-sequence}, except that the result is marked as a match group. This is equivalent to the @code{\(} ... @code{\)} construct. @@ -6596,25 +6588,25 @@ converted into a single argument by @code{rexp-group}. Note, however, that if only one @acronym{REXP} argument is supplied, and it's very simple, no grouping occurs. -@deffn {procedure+} rexp* rexp @dots{} +@deffn procedure rexp* rexp @dots{} Returns a @acronym{REXP} that matches zero or more instances of the pattern matched by the @var{rexp} arguments. This is equivalent to the @code{*} construct. @end deffn -@deffn {procedure+} rexp+ rexp @dots{} +@deffn procedure rexp+ rexp @dots{} Returns a @acronym{REXP} that matches one or more instances of the pattern matched by the @var{rexp} arguments. This is equivalent to the @code{+} construct. @end deffn -@deffn {procedure+} rexp-optional rexp @dots{} +@deffn procedure rexp-optional rexp @dots{} Returns a @acronym{REXP} that matches zero or one instances of the pattern matched by the @var{rexp} arguments. This is equivalent to the @code{?} construct. @end deffn -@deffn {procedure+} rexp-case-fold rexp +@deffn procedure rexp-case-fold rexp Returns a @acronym{REXP} that matches the same pattern as @var{rexp}, but is insensitive to character case. This has no equivalent in standard regular-expression notation. @@ -6627,10 +6619,10 @@ standard regular-expression notation. @cindex filling, of string @cindex moving, of string elements -@deffn {procedure+} string-replace string char1 char2 -@deffnx {procedure+} substring-replace string start end char1 char2 -@deffnx {procedure+} string-replace! string char1 char2 -@deffnx {procedure+} substring-replace! string start end char1 char2 +@deffn procedure string-replace string char1 char2 +@deffnx procedure substring-replace string start end char1 char2 +@deffnx procedure string-replace! string char1 char2 +@deffnx procedure substring-replace! string start end char1 char2 These procedures replace all occurrences of @var{char1} with @var{char2} in the original string (substring). @code{string-replace} and @code{substring-replace} return a newly allocated string containing the @@ -6654,7 +6646,7 @@ Stores @var{char} in every element of @var{string} and returns an unspecified value. @end deffn -@deffn {procedure+} substring-fill! string start end char +@deffn procedure substring-fill! string start end char Stores @var{char} in elements @var{start} (inclusive) to @var{end} (exclusive) of @var{string} and returns an unspecified value. @@ -6667,8 +6659,8 @@ s @result{} " ****** " @end example @end deffn -@deffn {procedure+} substring-move-left! string1 start1 end1 string2 start2 -@deffnx {procedure+} substring-move-right! string1 start1 end1 string2 start2 +@deffn procedure substring-move-left! string1 start1 end1 string2 start2 +@deffnx procedure substring-move-right! string1 start1 end1 string2 start2 @findex eqv? Copies the characters from @var{start1} to @var{end1} of @var{string1} into @var{string2} at the @var{start2}-th position. The characters are @@ -6703,10 +6695,10 @@ answer @result{} "start-end" @end example @end deffn -@deffn {procedure+} reverse-string string -@deffnx {procedure+} reverse-substring string start end -@deffnx {procedure+} reverse-string! string -@deffnx {procedure+} reverse-substring! string start end +@deffn procedure reverse-string string +@deffnx procedure reverse-substring string start end +@deffnx procedure reverse-string! string +@deffnx procedure reverse-substring! string start end Reverses the order of the characters in the given string or substring. @code{reverse-string} and @code{reverse-substring} return newly allocated strings; @code{reverse-string!} and @code{reverse-substring!} @@ -6742,7 +6734,7 @@ the string's allocation.) After the string is allocated, the operation @code{set-string-length!} can be used to alter the string's length to any value between 0 and the string's maximum length, inclusive. -@deffn {procedure+} string-maximum-length string +@deffn procedure string-maximum-length string Returns the maximum length of @var{string}. The following is guaranteed: @@ -6757,7 +6749,7 @@ guaranteed: The maximum length of a string never changes. @end deffn -@deffn {procedure+} set-string-length! string k +@deffn procedure set-string-length! string k Alters the length of @var{string} to be @var{k}, and returns an unspecified value. @var{K} must be less than or equal to the maximum length of @var{string}. @code{set-string-length!} does not change the @@ -6775,7 +6767,7 @@ MIT Scheme implements strings as packed vectors of 8-bit @code{string-ref}, coerce these 8-bit codes into character objects. However, some lower-level operations are made available for use. -@deffn {procedure+} vector-8b-ref string k +@deffn procedure vector-8b-ref string k Returns character @var{k} of @var{string} as an @acronym{ISO-8859-1} code. @var{K} must be a valid index of @var{string}. @@ -6786,20 +6778,20 @@ code. @var{K} must be a valid index of @var{string}. @end example @end deffn -@deffn {procedure+} vector-8b-set! string k code +@deffn procedure vector-8b-set! string k code Stores @var{code} in element @var{k} of @var{string} and returns an unspecified value. @var{K} must be a valid index of @var{string}, and @var{code} must be a valid @acronym{ISO-8859-1} code. @end deffn -@deffn {procedure+} vector-8b-fill! string start end code +@deffn procedure vector-8b-fill! string start end code Stores @var{code} in elements @var{start} (inclusive) to @var{end} (exclusive) of @var{string} and returns an unspecified value. @var{Code} must be a valid @acronym{ISO-8859-1} code. @end deffn -@deffn {procedure+} vector-8b-find-next-char string start end code -@deffnx {procedure+} vector-8b-find-next-char-ci string start end code +@deffn procedure vector-8b-find-next-char string start end code +@deffnx procedure vector-8b-find-next-char-ci string start end code Returns the index of the first occurrence of @var{code} in the given substring; returns @code{#f} if @var{code} does not appear. The index returned is relative to the entire string, not just the substring. @@ -6809,8 +6801,8 @@ returned is relative to the entire string, not just the substring. lowercase letters. @end deffn -@deffn {procedure+} vector-8b-find-previous-char string start end code -@deffnx {procedure+} vector-8b-find-previous-char-ci string start end code +@deffn procedure vector-8b-find-previous-char string start end code +@deffnx procedure vector-8b-find-previous-char-ci string start end code Returns the index of the last occurrence of @var{code} in the given substring; returns @code{#f} if @var{code} does not appear. The index returned is relative to the entire string, not just the substring. @@ -7088,7 +7080,7 @@ example, @code{caddr} could be defined by @end example @end deffn -@deffn {procedure+} general-car-cdr object path +@deffn procedure general-car-cdr object path This procedure is a generalization of @code{car} and @code{cdr}. @var{Path} encodes a particular sequence of @code{car} and @code{cdr} operations, which @code{general-car-cdr} executes on @var{object}. @@ -7125,7 +7117,7 @@ Here is a partial table of path/operation equivalents: @end example @end deffn -@deffn {procedure+} tree-copy tree +@deffn procedure tree-copy tree @cindex copying, of tree @cindex tree, copying This copies an arbitrary @var{tree} constructed from pairs, copying both @@ -7166,13 +7158,13 @@ These expressions are equivalent: @end example @end deffn -@deffn {procedure+} make-list k [element] +@deffn procedure make-list k [element] This procedure returns a newly allocated list of length @var{k}, whose elements are all @var{element}. If @var{element} is not supplied, it defaults to the empty list. @end deffn -@deffn {procedure+} cons* object object @dots{} +@deffn procedure cons* object object @dots{} @findex list @code{cons*} is similar to @code{list}, except that @code{cons*} conses together the last two arguments rather than consing the last argument @@ -7199,7 +7191,7 @@ These expressions are equivalent: @end example @end deffn -@deffn {procedure+} list-copy list +@deffn procedure list-copy list Returns a newly allocated copy of @var{list}. This copies each of the pairs comprising @var{list}. This could have been defined by @@ -7215,7 +7207,7 @@ pairs comprising @var{list}. This could have been defined by @end deffn @deffn procedure vector->list vector -@deffnx {procedure+} subvector->list vector start end +@deffnx procedure subvector->list vector start end @cindex vector, converting to list @findex list->vector @code{vector->list} returns a newly allocated list of the elements of @@ -7251,7 +7243,7 @@ elements of the given substring. The inverse of @code{string->list} is @cindex selection, of list component @cindex component selection, of list -@deffn {procedure+} list? object +@deffn procedure list? object @cindex type predicate, for list @cindex circular list Returns @code{#t} if @var{object} is a list, otherwise returns @@ -7327,16 +7319,16 @@ less than the length of the list. The first element of a list has index (list-tail @var{list} @var{k}))}. @end deffn -@deffn {procedure+} first list -@deffnx {procedure+} second list -@deffnx {procedure+} third list -@deffnx {procedure+} fourth list -@deffnx {procedure+} fifth list -@deffnx {procedure+} sixth list -@deffnx {procedure+} seventh list -@deffnx {procedure+} eighth list -@deffnx {procedure+} ninth list -@deffnx {procedure+} tenth list +@deffn procedure first list +@deffnx procedure second list +@deffnx procedure third list +@deffnx procedure fourth list +@deffnx procedure fifth list +@deffnx procedure sixth list +@deffnx procedure seventh list +@deffnx procedure eighth list +@deffnx procedure ninth list +@deffnx procedure tenth list Returns the specified element of @var{list}. It is an error if @var{list} is not long enough to contain the specified element (for example, if the argument to @code{seventh} is a list that contains only @@ -7348,7 +7340,7 @@ six elements). @cindex cutting, of list @cindex pasting, of lists -@deffn {procedure+} sublist list start end +@deffn procedure sublist list start end @var{Start} and @var{end} must be exact integers satisfying @example @@ -7360,7 +7352,7 @@ of @var{list} beginning at index @var{start} (inclusive) and ending at @var{end} (exclusive). @end deffn -@deffn {procedure+} list-head list k +@deffn procedure list-head list k Returns a newly allocated list consisting of the first @var{k} elements of @var{list}. @var{K} must not be greater than the length of @var{list}. @@ -7409,7 +7401,7 @@ not a proper list. @end example @end deffn -@deffn {procedure+} append! list @dots{} +@deffn procedure append! list @dots{} Returns a list that is the argument @var{list}s concatenated together. The arguments are changed rather than copied. (Compare this with @code{append}, which copies arguments rather than destroying them.) For @@ -7428,7 +7420,7 @@ z @result{} (g h) @end example @end deffn -@deffn {procedure+} last-pair list +@deffn procedure last-pair list Returns the last pair in @var{list}, which may be an improper list. @code{last-pair} could have been defined this way: @@ -7443,8 +7435,8 @@ Returns the last pair in @var{list}, which may be an improper list. @end example @end deffn -@deffn {procedure+} except-last-pair list -@deffnx {procedure+} except-last-pair! list +@deffn procedure except-last-pair list +@deffnx procedure except-last-pair! list These procedures remove the last pair from @var{list}. @var{List} may be an improper list, except that it must consist of at least one pair. @code{except-last-pair} returns a newly allocated copy of @var{list} @@ -7459,8 +7451,8 @@ procedure. @cindex filtering, of list @cindex deletion, of list element -@deffn {procedure+} keep-matching-items list predicate -@deffnx {procedure+} delete-matching-items list predicate +@deffn procedure keep-matching-items list predicate +@deffnx procedure delete-matching-items list predicate These procedures return a newly allocated copy of @var{list} containing only the elements for which @var{predicate} is (respectively) true or false. @var{Predicate} must be a procedure of one argument. @@ -7479,17 +7471,17 @@ alias for @code{keep-matching-items}, and @code{list-transform-negative} is an alias for @code{delete-matching-items}. @end deffn -@deffn {procedure+} keep-matching-items! list predicate -@deffnx {procedure+} delete-matching-items! list predicate +@deffn procedure keep-matching-items! list predicate +@deffnx procedure delete-matching-items! list predicate These procedures are exactly like @code{keep-matching-items} and @code{delete-matching-items}, respectively, except that they destructively modify the @var{list} argument rather than allocating a new result. @end deffn -@deffn {procedure+} delq element list -@deffnx {procedure+} delv element list -@deffnx {procedure+} delete element list +@deffn procedure delq element list +@deffnx procedure delv element list +@deffnx procedure delete element list @findex eq? @findex eqv? @findex equal? @@ -7499,9 +7491,9 @@ Returns a newly allocated copy of @var{list} with all entries equal to @code{eqv?}, and @code{delete} uses @code{equal?}. @end deffn -@deffn {procedure+} delq! element list -@deffnx {procedure+} delv! element list -@deffnx {procedure+} delete! element list +@deffn procedure delq! element list +@deffnx procedure delv! element list +@deffnx procedure delete! element list @findex eq? @findex eqv? @findex equal? @@ -7532,7 +7524,7 @@ x @result{} (a c) @end example @end deffn -@deffn {procedure+} delete-member-procedure deletor predicate +@deffn procedure delete-member-procedure deletor predicate @findex list-deletor @findex list-deletor! @findex delv @@ -7565,8 +7557,8 @@ Here are some examples that demonstrate how @end example @end deffn -@deffn {procedure+} list-deletor predicate -@deffnx {procedure+} list-deletor! predicate +@deffn procedure list-deletor predicate +@deffnx procedure list-deletor! predicate These procedures each return a procedure that deletes elements from lists. @var{Predicate} must be a procedure of one argument. The returned procedure accepts exactly one argument, which must be a proper @@ -7583,7 +7575,7 @@ with the appropriate elements removed. The procedure returned by @section Searching Lists @cindex searching, of list -@deffn {procedure+} find-matching-item list predicate +@deffn procedure find-matching-item list predicate Returns the first element in @var{list} for which @var{predicate} is true; returns @code{#f} if it doesn't find such an element. (This means that if @var{predicate} is true for @code{#f}, it may be impossible to @@ -7626,7 +7618,7 @@ return useful values rather than just @code{#t} or @code{#f}.} @end example @end deffn -@deffn {procedure+} member-procedure predicate +@deffn procedure member-procedure predicate Returns a procedure similar to @code{memq}, except that @var{predicate}, which must be an equivalence predicate, is used instead of @code{eq?}. This could be used to define @code{memv} as follows: @@ -7664,7 +7656,7 @@ applied to the elements of the @var{list}s is unspecified; use @end example @end deffn -@deffn {procedure+} map* initial-value procedure list1 list2 @dots{} +@deffn procedure map* initial-value procedure list1 list2 @dots{} Similar to @code{map}, except that the resulting list is terminated by @var{initial-value} rather than the empty list. The following are equivalent: @@ -7677,8 +7669,8 @@ equivalent: @end example @end deffn -@deffn {procedure+} append-map procedure list list @dots{} -@deffnx {procedure+} append-map* initial-value procedure list list @dots{} +@deffn procedure append-map procedure list list @dots{} +@deffnx procedure append-map* initial-value procedure list list @dots{} @findex append Similar to @code{map} and @code{map*}, respectively, except that the results of applying @var{procedure} to the elements of @var{list}s are @@ -7693,8 +7685,8 @@ following are equivalent, except that the former is more efficient: @end example @end deffn -@deffn {procedure+} append-map! procedure list list @dots{} -@deffnx {procedure+} append-map*! initial-value procedure list list @dots{} +@deffn procedure append-map! procedure list list @dots{} +@deffnx procedure append-map*! initial-value procedure list list @dots{} @findex append! Similar to @code{map} and @code{map*}, respectively, except that the results of applying @var{procedure} to the elements of @var{list}s are @@ -7732,7 +7724,7 @@ is unspecified. @section Reduction of Lists @cindex reduction, of list -@deffn {procedure+} reduce procedure initial list +@deffn procedure reduce procedure initial list Combines all the elements of @var{list} using the binary operation @var{procedure}. For example, using @code{+} one can add up all the elements: @@ -7758,7 +7750,7 @@ are reduced in a left-associative fashion. For example: @end example @end deffn -@deffn {procedure+} reduce-right procedure initial list +@deffn procedure reduce-right procedure initial list Like @code{reduce} except that it is right-associative. @example @@ -7766,7 +7758,7 @@ Like @code{reduce} except that it is right-associative. @end example @end deffn -@deffn {procedure+} fold-right procedure initial list +@deffn procedure fold-right procedure initial list Combines all of the elements of @var{list} using the binary operation @var{procedure}. Unlike @code{reduce} and @code{reduce-right}, @var{initial} is always used: @@ -7804,7 +7796,7 @@ the simple versions that take a fixed number of arguments: @end example @end deffn -@deffn {procedure+} fold-left procedure initial list +@deffn procedure fold-left procedure initial list Combines all the elements of @var{list} using the binary operation @var{procedure}. Elements are combined starting with @var{initial} and then the elements of @var{list} from left to right. Whereas @@ -7825,7 +7817,7 @@ is iterative in nature, combining the elements as the list is traversed. @end example @end deffn -@deffn {procedure+} there-exists? list predicate +@deffn procedure there-exists? list predicate @var{Predicate} must be a procedure of one argument. Applies @var{predicate} to each element of @var{list}, in order from left to right. If @var{predicate} is true for any element of @var{list}, the @@ -7835,7 +7827,7 @@ remaining elements of @var{list}. If @var{predicate} returns @code{#f} for all of the elements of @var{list}, then @code{#f} is returned. @end deffn -@deffn {procedure+} for-all? list predicate +@deffn procedure for-all? list predicate @var{Predicate} must be a procedure of one argument. Applies @var{predicate} to each element of @var{list}, in order from left to right. If @var{predicate} returns @code{#f} for any element of @@ -7848,8 +7840,8 @@ elements of @var{list}, then @code{#t} is returned. @node Miscellaneous List Operations, , Reduction of Lists, Lists @section Miscellaneous List Operations -@deffn {procedure+} circular-list object @dots{} -@deffnx {procedure+} make-circular-list k [element] +@deffn procedure circular-list object @dots{} +@deffnx procedure make-circular-list k [element] @cindex circular list @cindex construction, of circular list @findex list @@ -7879,7 +7871,7 @@ Returns a newly allocated list consisting of the top-level elements of @end example @end deffn -@deffn {procedure+} reverse! list +@deffn procedure reverse! list Returns a list consisting of the top-level elements of @var{list} in reverse order. @code{reverse!} is like @code{reverse}, except that it destructively modifies @var{list}. Because the result may not be @@ -7887,9 +7879,9 @@ destructively modifies @var{list}. Because the result may not be @code{(set! x (reverse! x))}. @end deffn -@deffn {procedure+} sort sequence procedure -@deffnx {procedure+} merge-sort sequence procedure -@deffnx {procedure+} quick-sort sequence procedure +@deffn procedure sort sequence procedure +@deffnx procedure merge-sort sequence procedure +@deffnx procedure quick-sort sequence procedure @cindex total ordering (defn) @var{Sequence} must be either a list or a vector. @var{Procedure} must be a procedure of two arguments that defines a @dfn{total ordering} on the @@ -8017,7 +8009,7 @@ Returns a newly allocated vector whose elements are the given arguments. @end example @end deffn -@deffn {procedure+} vector-copy vector +@deffn procedure vector-copy vector @cindex copying, of vector Returns a newly allocated vector that is a copy of @var{vector}. @end deffn @@ -8033,7 +8025,7 @@ Returns a newly allocated vector initialized to the elements of @end example @end deffn -@deffn {procedure+} make-initialized-vector k initialization +@deffn procedure make-initialized-vector k initialization Similar to @code{make-vector}, except that the elements of the result are determined by calling the procedure @var{initialization} on the indices. For example: @@ -8046,7 +8038,7 @@ indices. For example: @end example @end deffn -@deffn {procedure+} vector-grow vector k +@deffn procedure vector-grow vector k @cindex growing, of vector @var{K} must be greater than or equal to the length of @var{vector}. Returns a newly allocated vector of length @var{k}. The first @@ -8055,7 +8047,7 @@ initialized from the corresponding elements of @var{vector}. The remaining elements of the result are unspecified. @end deffn -@deffn {procedure+} vector-map procedure vector +@deffn procedure vector-map procedure vector @cindex mapping, of vector @var{Procedure} must be a procedure of one argument. @code{vector-map} applies @var{procedure} element-wise to the elements of @var{vector} and @@ -8112,20 +8104,20 @@ unspecified value. @var{K} must be a valid index of @end example @end deffn -@deffn {procedure+} vector-first vector -@deffnx {procedure+} vector-second vector -@deffnx {procedure+} vector-third vector -@deffnx {procedure+} vector-fourth vector -@deffnx {procedure+} vector-fifth vector -@deffnx {procedure+} vector-sixth vector -@deffnx {procedure+} vector-seventh vector -@deffnx {procedure+} vector-eighth vector +@deffn procedure vector-first vector +@deffnx procedure vector-second vector +@deffnx procedure vector-third vector +@deffnx procedure vector-fourth vector +@deffnx procedure vector-fifth vector +@deffnx procedure vector-sixth vector +@deffnx procedure vector-seventh vector +@deffnx procedure vector-eighth vector These procedures access the first several elements of @var{vector} in the obvious way. It is an error if the implicit index of one of these procedurs is not a valid index of @var{vector}. @end deffn -@deffn {procedure+} vector-binary-search vector keybit-string length integer +@deffn procedure unsigned-integer->bit-string length integer Both @var{length} and @var{integer} must be exact non-negative integers. Converts @var{integer} into a newly allocated bit string of @var{length} bits. Signals an error of type @code{condition-type:bad-range-argument} @@ -8512,7 +8504,7 @@ if @var{integer} is too large to be represented in @var{length} bits. @findex condition-type:bad-range-argument @end deffn -@deffn {procedure+} signed-integer->bit-string length integer +@deffn procedure signed-integer->bit-string length integer @var{Length} must be an exact non-negative integer, and @var{integer} may be any exact integer. Converts @var{integer} into a newly allocated bit string of @var{length} bits, using two's complement encoding for @@ -8522,8 +8514,8 @@ to be represented in @var{length} bits. @findex condition-type:bad-range-argument @end deffn -@deffn {procedure+} bit-string->unsigned-integer bit-string -@deffnx {procedure+} bit-string->signed-integer bit-string +@deffn procedure bit-string->unsigned-integer bit-string +@deffnx procedure bit-string->signed-integer bit-string Converts @var{bit-string} into an exact integer. @code{bit-string->signed-integer} regards @var{bit-string} as a two's complement representation of a signed integer, and produces an integer @@ -8589,8 +8581,8 @@ t @error{} Unbound variable @end group @end example -@defvr {variable+} false -@defvrx {variable+} true +@defvr variable false +@defvrx variable true These variables are bound to the objects @code{#f} and @code{#t} respectively. The compiler, given the @code{usual-integrations} declaration, replaces references to these variables with their @@ -8614,7 +8606,7 @@ otherwise returns @code{#f}. @end deffn @deffn procedure not object -@deffnx {procedure+} false? object +@deffnx procedure false? object @cindex false, predicate for @cindex inverse, of boolean object These procedures return @code{#t} if @var{object} is false; otherwise @@ -8632,7 +8624,7 @@ different to give different connotations to the test. @end example @end deffn -@deffn {procedure+} boolean=? obj1 obj2 +@deffn procedure boolean=? obj1 obj2 @cindex boolean object, equivalence predicate @cindex equivalence predicate, for boolean objects @cindex comparison, of boolean objects @@ -8640,12 +8632,12 @@ This predicate is true iff @var{obj1} and @var{obj2} are either both true or both false. @end deffn -@deffn {procedure+} boolean/and object @dots{} +@deffn procedure boolean/and object @dots{} This procedure returns @code{#t} if none of its arguments are @code{#f}. Otherwise it returns @code{#f}. @end deffn -@deffn {procedure+} boolean/or object @dots{} +@deffn procedure boolean/or object @dots{} This procedure returns @code{#f} if all of its arguments are @code{#f}. Otherwise it returns @code{#t}. @end deffn @@ -8779,7 +8771,7 @@ procedure. Note that two distinct uninterned symbols can have the same name. @end deffn -@deffn {procedure+} intern string +@deffn procedure intern string @cindex interning, of symbols @cindex construction, of symbols Returns the interned symbol whose name is @var{string}. Converts @@ -8797,7 +8789,7 @@ identifiers (@pxref{Identifiers}), otherwise the resulting symbol cannot be read as itself. @end deffn -@deffn {procedure+} intern-soft string +@deffn procedure intern-soft string Returns the interned symbol whose name is @var{string}. Converts @var{string} to the standard alphabetic case before generating the symbol. If no such interned symbol exists, returns @code{#f}. @@ -8831,7 +8823,7 @@ symbols because they cannot be read as themselves. See @end example @end deffn -@deffn {procedure+} string->uninterned-symbol string +@deffn procedure string->uninterned-symbol string Returns a newly allocated uninterned symbol whose name is @var{string}. It is unimportant what case or characters are used in @var{string}. @@ -8839,7 +8831,7 @@ It is unimportant what case or characters are used in Note: this is the fastest way to make a symbol. @end deffn -@deffn {procedure+} generate-uninterned-symbol [object] +@deffn procedure generate-uninterned-symbol [object] @cindex gensym (see uninterned symbol) @findex eq? Returns a newly allocated uninterned symbol that is guaranteed to be @@ -8884,7 +8876,7 @@ If @var{object} is a symbol, its name is used as the prefix. @end example @end deffn -@deffn {procedure+} symbol-append symbol @dots{} +@deffn procedure symbol-append symbol @dots{} @cindex appending, of symbols @cindex pasting, of symbols Returns the interned symbol whose name is formed by concatenating the @@ -8904,7 +8896,7 @@ non-standard case, the result will also have non-standard case. @end example @end deffn -@deffn {procedure+} symbol-hash symbol +@deffn procedure symbol-hash symbol @cindex hashing, of symbol @findex string-hash Returns a hash number for @var{symbol}, which is computed by calling @@ -8912,7 +8904,7 @@ Returns a hash number for @var{symbol}, which is computed by calling non-negative integer. @end deffn -@deffn {procedure+} symbol-hash-mod symbol modulus +@deffn procedure symbol-hash-mod symbol modulus @var{Modulus} must be an exact positive integer. Equivalent to @example @@ -8927,7 +8919,7 @@ build hash tables keyed by symbols, because @code{eq?} hash tables are much faster. @end deffn -@deffn {procedure+} symbolstream list +@deffn procedure list->stream list @cindex list, converting to stream Returns a newly allocated stream whose elements are the elements of @var{list}. Equivalent to @code{(apply stream @var{list})}. @end deffn -@deffn {procedure+} stream->list stream +@deffn procedure stream->list stream @cindex stream, converting to list Returns a newly allocated list whose elements are the elements of @var{stream}. If @var{stream} has infinite length this procedure will @@ -9296,12 +9288,12 @@ not terminate. This could have been defined by @end example @end deffn -@deffn {special form+} cons-stream object expression +@deffn {special form} cons-stream object expression Returns a newly allocated stream pair. Equivalent to @code{(cons @var{object} (delay @var{expression}))}. @end deffn -@deffn {procedure+} stream-pair? object +@deffn procedure stream-pair? object @cindex type predicate, for stream pair Returns @code{#t} if @var{object} is a pair whose cdr contains a promise. Otherwise returns @code{#f}. This could have been defined by @@ -9315,23 +9307,23 @@ promise. Otherwise returns @code{#f}. This could have been defined by @end example @end deffn -@deffn {procedure+} stream-car stream -@deffnx {procedure+} stream-first stream +@deffn procedure stream-car stream +@deffnx procedure stream-first stream @findex car Returns the first element in @var{stream}. @code{stream-car} is equivalent to @code{car}. @code{stream-first} is a synonym for @code{stream-car}. @end deffn -@deffn {procedure+} stream-cdr stream -@deffnx {procedure+} stream-rest stream +@deffn procedure stream-cdr stream +@deffnx procedure stream-rest stream @findex force @findex cdr Returns the first tail of @var{stream}. Equivalent to @code{(force (cdr @var{stream}))}. @code{stream-rest} is a synonym for @code{stream-cdr}. @end deffn -@deffn {procedure+} stream-null? stream +@deffn procedure stream-null? stream @cindex empty stream, predicate for @findex null? Returns @code{#t} if @var{stream} is the end-of-stream marker; otherwise @@ -9339,7 +9331,7 @@ returns @code{#f}. This is equivalent to @code{null?}, but should be used whenever testing for the end of a stream. @end deffn -@deffn {procedure+} stream-length stream +@deffn procedure stream-length stream @cindex length, of stream Returns the number of elements in @var{stream}. If @var{stream} has an infinite number of elements this procedure will not terminate. Note @@ -9347,7 +9339,7 @@ that this procedure forces all of the promises that comprise @var{stream}. @end deffn -@deffn {procedure+} stream-ref stream k +@deffn procedure stream-ref stream k @cindex selecting, of stream component @cindex component selection, of stream Returns the element of @var{stream} that is indexed by @var{k}; that is, @@ -9355,20 +9347,20 @@ the @var{k}th element. @var{K} must be an exact non-negative integer strictly less than the length of @var{stream}. @end deffn -@deffn {procedure+} stream-head stream k +@deffn procedure stream-head stream k Returns the first @var{k} elements of @var{stream} as a list. @var{K} must be an exact non-negative integer strictly less than the length of @var{stream}. @end deffn -@deffn {procedure+} stream-tail stream k +@deffn procedure stream-tail stream k Returns the tail of @var{stream} that is indexed by @var{k}; that is, the @var{k}th tail. This is equivalent to performing @code{stream-cdr} @var{k} times. @var{K} must be an exact non-negative integer strictly less than the length of @var{stream}. @end deffn -@deffn {procedure+} stream-map procedure stream stream @dots{} +@deffn procedure stream-map procedure stream stream @dots{} @cindex mapping, of stream Returns a newly allocated stream, each element being the result of invoking @var{procedure} with the corresponding elements of the @@ -9390,25 +9382,25 @@ normally by any other data structure, it will be garbage-collected. Note: weak pairs are @emph{not} pairs; that is, they do not satisfy the predicate @code{pair?}. -@deffn {procedure+} weak-pair? object +@deffn procedure weak-pair? object @cindex type predicate, for weak pair Returns @code{#t} if @var{object} is a weak pair; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} weak-cons car cdr +@deffn procedure weak-cons car cdr @cindex construction, of weak pair Allocates and returns a new weak pair, with components @var{car} and @var{cdr}. The @var{car} component is held weakly. @end deffn -@deffn {procedure+} weak-pair/car? weak-pair +@deffn procedure weak-pair/car? weak-pair This predicate returns @code{#f} if the car of @var{weak-pair} has been garbage-collected; otherwise returns @code{#t}. In other words, it is true if @var{weak-pair} has a valid car component. @end deffn -@deffn {procedure+} weak-car weak-pair +@deffn procedure weak-car weak-pair @cindex selection, of weak pair component @cindex component selection, of weak pair Returns the car component of @var{weak-pair}. If the car component has @@ -9448,16 +9440,16 @@ it won't matter, because @code{#f} will never be garbage-collected. And in the latter case, it also won't matter, because the car component no longer exists and cannot be affected by the garbage collector. -@deffn {procedure+} weak-set-car! weak-pair object +@deffn procedure weak-set-car! weak-pair object Sets the car component of @var{weak-pair} to @var{object} and returns an unspecified result. @end deffn -@deffn {procedure+} weak-cdr weak-pair +@deffn procedure weak-cdr weak-pair Returns the cdr component of @var{weak-cdr}. @end deffn -@deffn {procedure+} weak-set-cdr! weak-pair object +@deffn procedure weak-set-cdr! weak-pair object Sets the cdr component of @var{weak-pair} to @var{object} and returns an unspecified result. @end deffn @@ -9558,7 +9550,7 @@ entries to the front of the alist.@footnote{This introduction is taken from @cite{Common Lisp, The Language}, second edition, p.@: 431.} @comment **** end CLTL **** -@deffn {procedure+} alist? object +@deffn procedure alist? object @cindex type predicate, for alist @findex list? Returns @code{#t} if @var{object} is an association list (including the @@ -9599,7 +9591,7 @@ or @code{#f}.} @end example @end deffn -@deffn {procedure+} association-procedure predicate selector +@deffn procedure association-procedure predicate selector Returns an association procedure that is similar to @code{assv}, except that @var{selector} (a procedure of one argument) is used to select the key from the association, and @var{predicate} (an equivalence predicate) @@ -9620,9 +9612,9 @@ Another example is a ``reverse association'' procedure: @end example @end deffn -@deffn {procedure+} del-assq object alist -@deffnx {procedure+} del-assv object alist -@deffnx {procedure+} del-assoc object alist +@deffn procedure del-assq object alist +@deffnx procedure del-assv object alist +@deffnx procedure del-assoc object alist @cindex deletion, of alist element @findex eq? @findex eqv? @@ -9650,9 +9642,9 @@ association pairs that are the elements of the list are shared with @end example @end deffn -@deffn {procedure+} del-assq! object alist -@deffnx {procedure+} del-assv! object alist -@deffnx {procedure+} del-assoc! object alist +@deffn procedure del-assq! object alist +@deffnx procedure del-assv! object alist +@deffnx procedure del-assoc! object alist @findex eq? @findex eqv? @findex equal? @@ -9665,7 +9657,7 @@ while @code{del-assv!} uses @code{eqv?} and @code{del-assoc!} uses destructively modify @var{alist}. @end deffn -@deffn {procedure+} delete-association-procedure deletor predicate selector +@deffn procedure delete-association-procedure deletor predicate selector @findex list-deletor @findex list-deletor! This returns a deletion procedure similar to @code{del-assv} or @@ -9685,7 +9677,7 @@ For example, here is a possible implementation of @code{del-assv}: @end example @end deffn -@deffn {procedure+} alist-copy alist +@deffn procedure alist-copy alist @cindex copying, of alist @findex list-copy Returns a newly allocated copy of @var{alist}. This is similar to @@ -9725,11 +9717,11 @@ a 1D table can be stored in one of the vector's slots. Under these circumstances, accessing items in a 1D table will be comparable in performance to using a property list in a conventional Lisp. -@deffn {procedure+} make-1d-table +@deffn procedure make-1d-table Returns a newly allocated empty 1D table. @end deffn -@deffn {procedure+} 1d-table? object +@deffn procedure 1d-table? object @cindex type predicate, for 1D table @findex list? Returns @code{#t} if @var{object} is a 1D table, otherwise returns @@ -9737,22 +9729,22 @@ Returns @code{#t} if @var{object} is a 1D table, otherwise returns @code{list?}. @end deffn -@deffn {procedure+} 1d-table/put! 1d-table key datum +@deffn procedure 1d-table/put! 1d-table key datum Creates an association between @var{key} and @var{datum} in @var{1d-table}. Returns an unspecified value. @end deffn -@deffn {procedure+} 1d-table/remove! 1d-table key +@deffn procedure 1d-table/remove! 1d-table key Removes any association for @var{key} in @var{1d-table} and returns an unspecified value. @end deffn -@deffn {procedure+} 1d-table/get 1d-table key default +@deffn procedure 1d-table/get 1d-table key default Returns the @var{datum} associated with @var{key} in @var{1d-table}. If there is no association for @var{key}, @var{default} is returned. @end deffn -@deffn {procedure+} 1d-table/lookup 1d-table key if-found if-not-found +@deffn procedure 1d-table/lookup 1d-table key if-found if-not-found @var{If-found} must be a procedure of one argument, and @var{if-not-found} must be a procedure of no arguments. If @var{1d-table} contains an association for @var{key}, @var{if-found} is @@ -9762,7 +9754,7 @@ result of the invoked procedure is returned as the result of @code{1d-table/lookup}. @end deffn -@deffn {procedure+} 1d-table/alist 1d-table +@deffn procedure 1d-table/alist 1d-table Returns a newly allocated association list that contains the same information as @var{1d-table}. @end deffn @@ -9785,22 +9777,22 @@ Think of the association table as a matrix: a single datum can be accessed using both keys, a column using @var{x-key} only, and a row using @var{y-key} only. -@deffn {procedure+} 2d-put! x-key y-key datum +@deffn procedure 2d-put! x-key y-key datum Makes an entry in the association table that associates @var{datum} with @var{x-key} and @var{y-key}. Returns an unspecified result. @end deffn -@deffn {procedure+} 2d-remove! x-key y-key +@deffn procedure 2d-remove! x-key y-key If the association table has an entry for @var{x-key} and @var{y-key}, it is removed. Returns an unspecified result. @end deffn -@deffn {procedure+} 2d-get x-key y-key +@deffn procedure 2d-get x-key y-key Returns the @var{datum} associated with @var{x-key} and @var{y-key}. Returns @code{#f} if no such association exists. @end deffn -@deffn {procedure+} 2d-get-alist-x x-key +@deffn procedure 2d-get-alist-x x-key Returns an association list of all entries in the association table that are associated with @var{x-key}. The result is a list of @code{(@var{y-key} . @var{datum})} pairs. Returns the empty list if no @@ -9815,7 +9807,7 @@ entries for @var{x-key} exist. @end example @end deffn -@deffn {procedure+} 2d-get-alist-y y-key +@deffn procedure 2d-get-alist-y y-key Returns an association list of all entries in the association table that are associated with @var{y-key}. The result is a list of @code{(@var{x-key} . @var{datum})} pairs. Returns the empty list if no @@ -9886,14 +9878,14 @@ prevents its keys from being reclaimed by the garbage collector, it is said to hold its keys @dfn{strongly}; otherwise it holds its keys @dfn{weakly} (@pxref{Weak Pairs}). -@deffn {procedure+} make-eq-hash-table [initial-size] +@deffn procedure make-eq-hash-table [initial-size] @findex eq? Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with @code{eq?}. The keys are held weakly. These are the fastest of the standard hash tables. @end deffn -@deffn {procedure+} make-eqv-hash-table [initial-size] +@deffn procedure make-eqv-hash-table [initial-size] @findex eqv? Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with @code{eqv?}. The keys are held @@ -9902,7 +9894,7 @@ These hash tables are a little slower than those made by @code{make-eq-hash-table}. @end deffn -@deffn {procedure+} make-equal-hash-table [initial-size] +@deffn procedure make-equal-hash-table [initial-size] @findex equal? Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with @code{equal?}. The keys are held @@ -9910,7 +9902,7 @@ strongly. These hash tables are quite a bit slower than those made by @code{make-eq-hash-table}. @end deffn -@deffn {procedure+} make-string-hash-table [initial-size] +@deffn procedure make-string-hash-table [initial-size] @findex string=? Returns a newly allocated hash table that accepts character strings as keys, and compares them with @code{string=?}. The keys are held @@ -9922,8 +9914,8 @@ All of the above hash table constructors, with the exception of @code{make-eqv-hash-table}, could have been created by calls to these ``constructor-constructors''; see the examples below. -@deffn {procedure+} strong-hash-table/constructor key-hash key=? [rehash-after-gc?] -@deffnx {procedure+} weak-hash-table/constructor key-hash key=? [rehash-after-gc?] +@deffn procedure strong-hash-table/constructor key-hash key=? [rehash-after-gc?] +@deffnx procedure weak-hash-table/constructor key-hash key=? [rehash-after-gc?] @cindex hashing, of key in hash table @cindex modulus, of hashing procedure Each of these procedures accepts two arguments and returns a hash-table @@ -9973,7 +9965,7 @@ The following procedure is sometimes useful in conjunction with weak hash tables. Normally it is not needed, because such hash tables clean themselves automatically as they are used. -@deffn {procedure+} hash-table/clean! hash-table +@deffn procedure hash-table/clean! hash-table If @var{hash-table} is a type of hash table that holds its @var{key}s weakly, this procedure recovers any space that was being used to record associations for objects that have been reclaimed by the garbage @@ -9989,37 +9981,37 @@ hash tables. They provide the functionality most often needed by programmers. Subsequent sections describe other operations that provide additional functionality needed by some applications. -@deffn {procedure+} hash-table? object +@deffn procedure hash-table? object @cindex type predicate, for hash table Returns @code{#t} if @var{object} is a hash table, otherwise returns @code{#f}. @end deffn -@deffn {procedure+} hash-table/put! hash-table key datum +@deffn procedure hash-table/put! hash-table key datum Associates @var{datum} with @var{key} in @var{hash-table} and returns an unspecified result. The average time required by this operation is bounded by a constant. @end deffn -@deffn {procedure+} hash-table/get hash-table key default +@deffn procedure hash-table/get hash-table key default Returns the datum associated with @var{key} in @var{hash-table}. If there is no association for @var{key}, @var{default} is returned. The average time required by this operation is bounded by a constant. @end deffn -@deffn {procedure+} hash-table/remove! hash-table key +@deffn procedure hash-table/remove! hash-table key If @var{hash-table} has an association for @var{key}, removes it. Returns an unspecified result. The average time required by this operation is bounded by a constant. @end deffn -@deffn {procedure+} hash-table/clear! hash-table +@deffn procedure hash-table/clear! hash-table Removes all associations in @var{hash-table} and returns an unspecified result. The average and worst-case times required by this operation are bounded by a constant. @end deffn -@deffn {procedure+} hash-table/count hash-table +@deffn procedure hash-table/count hash-table Returns the number of associations in @var{hash-table} as an exact non-negative integer. If @var{hash-table} holds its keys weakly, this is a conservative upper bound that may count some associations whose @@ -10028,7 +10020,7 @@ and worst-case times required by this operation are bounded by a constant. @end deffn -@deffn {procedure+} hash-table->alist hash-table +@deffn procedure hash-table->alist hash-table Returns the contents of @var{hash-table} as a newly allocated alist. Each element of the alist is a pair @code{(@var{key} . @var{datum})} where @var{key} is one of the keys of @var{hash-table}, and @var{datum} @@ -10037,13 +10029,13 @@ this operation are linear in the number of associations in the table. @end deffn -@deffn {procedure+} hash-table/key-list hash-table +@deffn procedure hash-table/key-list hash-table Returns a newly allocated list of the keys in @var{hash-table}. The average and worst-case times required by this operation are linear in the number of associations in the table. @end deffn -@deffn {procedure+} hash-table/datum-list hash-table +@deffn procedure hash-table/datum-list hash-table Returns a newly allocated list of the datums in @var{hash-table}. Each element of the list corresponds to one of the associations in @var{hash-table}; if the table contains multiple associations with the @@ -10052,7 +10044,7 @@ required by this operation are linear in the number of associations in the table. @end deffn -@deffn {procedure+} hash-table/for-each hash-table procedure +@deffn procedure hash-table/for-each hash-table procedure @var{Procedure} must be a procedure of two arguments. Invokes @var{procedure} once for each association in @var{hash-table}, passing the association's @var{key} and @var{datum} as arguments, in that order. @@ -10065,7 +10057,7 @@ The following procedure is an alternate form of @code{hash-table/get} that is useful in some situations. Usually, @code{hash-table/get} is preferable because it is faster. -@deffn {procedure+} hash-table/lookup hash-table key if-found if-not-found +@deffn procedure hash-table/lookup hash-table key if-found if-not-found @var{If-found} must be a procedure of one argument, and @var{if-not-found} must be a procedure of no arguments. If @var{hash-table} contains an association for @var{key}, @var{if-found} @@ -10218,17 +10210,17 @@ times, but increases the physical size of the table for a given usable size. The default rehash threshold of a newly constructed hash table is @code{1}. -@deffn {procedure+} hash-table/size hash-table +@deffn procedure hash-table/size hash-table Returns the usable size of @var{hash-table} as an exact positive integer. This is the number of associations that @var{hash-table} can hold before it will grow. @end deffn -@deffn {procedure+} hash-table/rehash-size hash-table +@deffn procedure hash-table/rehash-size hash-table Returns the rehash size of @var{hash-table}. @end deffn -@deffn {procedure+} set-hash-table/rehash-size! hash-table x +@deffn procedure set-hash-table/rehash-size! hash-table x @var{X} must be either an exact positive integer, or a real number that is greater than one. Sets the rehash size of @var{hash-table} to @var{x} and returns an unspecified result. This operation adjusts the @@ -10236,11 +10228,11 @@ is greater than one. Sets the rehash size of @var{hash-table} to of associations is less than the new threshold. @end deffn -@deffn {procedure+} hash-table/rehash-threshold hash-table +@deffn procedure hash-table/rehash-threshold hash-table Returns the rehash threshold of @var{hash-table}. @end deffn -@deffn {procedure+} set-hash-table/rehash-threshold! hash-table x +@deffn procedure set-hash-table/rehash-threshold! hash-table x @var{X} must be a real number between zero exclusive and one inclusive. Sets the rehash threshold of @var{hash-table} to @var{x} and returns an unspecified result. This operation does not change the usable size of @@ -10269,9 +10261,9 @@ argument to the ``constructor-constructor'' procedure) that the hash numbers computed by your key-hashing procedure must be recomputed after a garbage collection. -@deffn {procedure+} eq-hash object -@deffnx {procedure+} eqv-hash object -@deffnx {procedure+} equal-hash object +@deffn procedure eq-hash object +@deffnx procedure eqv-hash object +@deffnx procedure equal-hash object These procedures return a hash number for @var{object}. The result is always a non-negative integer, and in the case of @code{eq-hash}, a non-negative fixnum. Two objects that are equivalent according to @@ -10283,17 +10275,17 @@ that the garbage collector does not run during or between the two calls. The following procedures are the key-hashing procedures used by the standard address-hash-based hash tables. -@deffn {procedure+} eq-hash-mod object modulus +@deffn procedure eq-hash-mod object modulus This procedure is the key-hashing procedure used by @code{make-eq-hash-table}. @end deffn -@deffn {procedure+} eqv-hash-mod object modulus +@deffn procedure eqv-hash-mod object modulus This procedure is the key-hashing procedure used by @code{make-eqv-hash-table}. @end deffn -@deffn {procedure+} equal-hash-mod object modulus +@deffn procedure equal-hash-mod object modulus This procedure is the key-hashing procedure used by @code{make-equal-hash-table}. @end deffn @@ -10309,7 +10301,7 @@ structure to maintain the association. In this section, the data structure that represents an association in a hash table is called an @dfn{entry}. -@deffn {procedure+} hash-table/constructor key-hash key=? make-entry entry-valid? entry-key entry-datum set-entry-datum! [rehash-after-gc?] +@deffn procedure hash-table/constructor key-hash key=? make-entry entry-valid? entry-key entry-datum set-entry-datum! [rehash-after-gc?] Creates and returns a hash-table constructor procedure (@pxref{Construction of Hash Tables}). The arguments define the characteristics of the hash table as follows: @@ -10387,13 +10379,13 @@ be defined: @end group @end example -@deffn {procedure+} hash-table/key-hash hash-table -@deffnx {procedure+} hash-table/key=? hash-table -@deffnx {procedure+} hash-table/make-entry hash-table -@deffnx {procedure+} hash-table/entry-valid? hash-table -@deffnx {procedure+} hash-table/entry-key hash-table -@deffnx {procedure+} hash-table/entry-datum hash-table -@deffnx {procedure+} hash-table/set-entry-datum! hash-table +@deffn procedure hash-table/key-hash hash-table +@deffnx procedure hash-table/key=? hash-table +@deffnx procedure hash-table/make-entry hash-table +@deffnx procedure hash-table/entry-valid? hash-table +@deffnx procedure hash-table/entry-key hash-table +@deffnx procedure hash-table/entry-datum hash-table +@deffnx procedure hash-table/set-entry-datum! hash-table Each procedure returns the value of the corresponding argument that was used to construct @var{hash-table}. @end deffn @@ -10404,11 +10396,11 @@ newly allocated, the entries themselves are not copied. Since hash table operations can modify these entries, the entries should be copied if it is desired to keep them while continuing to modify the table. -@deffn {procedure+} hash-table/entries-list hash-table +@deffn procedure hash-table/entries-list hash-table Returns a newly allocated list of the entries in @var{hash-table}. @end deffn -@deffn {procedure+} hash-table/entries-vector hash-table +@deffn procedure hash-table/entries-vector hash-table Returns a newly allocated vector of the entries in @var{hash-table}. Equivalent to @@ -10436,7 +10428,7 @@ argument must be an object-hash table as constructed by @code{hash-table/make} (see below). If not given, a default table is used. -@deffn {procedure+} hash object [table] +@deffn procedure hash object [table] @findex eq? @code{hash} associates an exact non-negative integer with @var{object} and returns that integer. If @code{hash} was previously called with @@ -10446,7 +10438,7 @@ objects (in the sense of @code{eq?}) are associated with distinct integers. @end deffn -@deffn {procedure+} unhash k [table] +@deffn procedure unhash k [table] @code{unhash} takes an exact non-negative integer @var{k} and returns the object associated with that integer. If there is no object associated with @var{k}, or if the object previously associated with @@ -10475,12 +10467,12 @@ reclaimed) object will signal an error. @end group @end example -@deffn {procedure+} object-hashed? object [table] +@deffn procedure object-hashed? object [table] This predicate is true if @var{object} has an associated hash number. Otherwise it is false. @end deffn -@deffn {procedure+} valid-hash-number? k [table] +@deffn procedure valid-hash-number? k [table] This predicate is true if @var{k} is the hash number associated with some object. Otherwise it is false. @end deffn @@ -10488,7 +10480,7 @@ some object. Otherwise it is false. The following two procedures provide a lower-level interface to the object-hashing mechanism. -@deffn {procedure+} object-hash object [table [insert?]] +@deffn procedure object-hash object [table [insert?]] @findex eq? @code{object-hash} is like @code{hash}, except that it accepts an additional optional argument, @var{insert?}. If @var{insert?}@: is @@ -10505,7 +10497,7 @@ an error rather than returning @code{#f}. Likewise, @code{valid-hash-number?} will return @code{#f} for this integer. @end deffn -@deffn {procedure+} object-unhash k [table] +@deffn procedure object-unhash k [table] @code{object-unhash} is like @code{unhash}, except that when @var{k} is not associated with any object or was previously associated with an object that has been reclaimed, @code{object-unhash} returns @code{#f}. @@ -10517,7 +10509,7 @@ any object at all. Finally, this procedure makes new object-hash tables: -@deffn {procedure+} hash-table/make +@deffn procedure hash-table/make This procedure creates and returns a new, empty object-hash table that is suitable for use as the optional @var{table} argument to the above procedures. The returned table contains no associations. @@ -10578,7 +10570,7 @@ red-black trees, execute @noindent once before calling any of the procedures defined here. -@deffn {procedure+} make-rb-tree key=? keyalist rb-tree +@deffn procedure rb-tree->alist rb-tree Returns the contents of @var{rb-tree} as a newly allocated alist. Each element of the alist is a pair @code{(@var{key} . @var{datum})} where @var{key} is one of the keys of @var{rb-tree}, and @var{datum} is its @@ -10624,14 +10616,14 @@ time required by this operation is proportional to the number of associations in the tree. @end deffn -@deffn {procedure+} rb-tree/key-list rb-tree +@deffn procedure rb-tree/key-list rb-tree Returns a newly allocated list of the keys in @var{rb-tree}. The list is sorted by key according to the @var{keyrb-tree alist key=? keyrb-tree alist key=? keywt-tree tree-type alist +@deffn procedure alist->wt-tree tree-type alist Returns a newly allocated weight-balanced tree that contains the same associations as @var{alist}. This procedure is equivalent to: @@ -10957,22 +10949,22 @@ trees. These operations are the usual tree operations for insertion, deletion and lookup, some predicates and a procedure for determining the number of associations in a tree. -@deffn {procedure+} wt-tree? object +@deffn procedure wt-tree? object Returns @code{#t} if @var{object} is a weight-balanced tree, otherwise returns @code{#f}. @end deffn -@deffn {procedure+} wt-tree/empty? wt-tree +@deffn procedure wt-tree/empty? wt-tree Returns @code{#t} if @var{wt-tree} contains no associations, otherwise returns @code{#f}. @end deffn -@deffn {procedure+} wt-tree/size wt-tree +@deffn procedure wt-tree/size wt-tree Returns the number of associations in @var{wt-tree}, an exact non-negative integer. This operation takes constant time. @end deffn -@deffn {procedure+} wt-tree/add wt-tree key datum +@deffn procedure wt-tree/add wt-tree key datum Returns a new tree containing all the associations in @var{wt-tree} and the association of @var{datum} with @var{key}. If @var{wt-tree} already had an association for @var{key}, the new association overrides the old. @@ -10981,7 +10973,7 @@ proportional to the logarithm of the number of associations in @var{wt-tree}. @end deffn -@deffn {procedure+} wt-tree/add! wt-tree key datum +@deffn procedure wt-tree/add! wt-tree key datum Associates @var{datum} with @var{key} in @var{wt-tree} and returns an unspecified value. If @var{wt-tree} already has an association for @var{key}, that association is replaced. The average and worst-case @@ -10989,14 +10981,14 @@ times required by this operation are proportional to the logarithm of the number of associations in @var{wt-tree}. @end deffn -@deffn {procedure+} wt-tree/member? key wt-tree +@deffn procedure wt-tree/member? key wt-tree Returns @code{#t} if @var{wt-tree} contains an association for @var{key}, otherwise returns @code{#f}. The average and worst-case times required by this operation are proportional to the logarithm of the number of associations in @var{wt-tree}. @end deffn -@deffn {procedure+} wt-tree/lookup wt-tree key default +@deffn procedure wt-tree/lookup wt-tree key default Returns the datum associated with @var{key} in @var{wt-tree}. If @var{wt-tree} doesn't contain an association for @var{key}, @var{default} is returned. The average and worst-case times required by @@ -11004,7 +10996,7 @@ this operation are proportional to the logarithm of the number of associations in @var{wt-tree}. @end deffn -@deffn {procedure+} wt-tree/delete wt-tree key +@deffn procedure wt-tree/delete wt-tree key Returns a new tree containing all the associations in @var{wt-tree}, except that if @var{wt-tree} contains an association for @var{key}, it is removed from the result. The average and worst-case times required @@ -11012,7 +11004,7 @@ by this operation are proportional to the logarithm of the number of associations in @var{wt-tree}. @end deffn -@deffn {procedure+} wt-tree/delete! wt-tree key +@deffn procedure wt-tree/delete! wt-tree key If @var{wt-tree} contains an association for @var{key} the association is removed. Returns an unspecified value. The average and worst-case times required by this operation are proportional to the logarithm of @@ -11026,7 +11018,7 @@ In the following the @emph{size} of a tree is the number of associations that the tree contains, and a @emph{smaller} tree contains fewer associations. -@deffn {procedure+} wt-tree/split< wt-tree bound +@deffn procedure wt-tree/split< wt-tree bound Returns a new tree containing all and only the associations in @var{wt-tree} that have a key that is less than @var{bound} in the ordering relation of the tree type of @var{wt-tree}. The average and @@ -11034,7 +11026,7 @@ worst-case times required by this operation are proportional to the logarithm of the size of @var{wt-tree}. @end deffn -@deffn {procedure+} wt-tree/split> wt-tree bound +@deffn procedure wt-tree/split> wt-tree bound Returns a new tree containing all and only the associations in @var{wt-tree} that have a key that is greater than @var{bound} in the ordering relation of the tree type of @var{wt-tree}. The average and @@ -11042,7 +11034,7 @@ worst-case times required by this operation are proportional to the logarithm of the size of @var{wt-tree}. @end deffn -@deffn {procedure+} wt-tree/union wt-tree-1 wt-tree-2 +@deffn procedure wt-tree/union wt-tree-1 wt-tree-2 Returns a new tree containing all the associations from both trees. This operation is asymmetric: when both trees have an association for the same key, the returned tree associates the datum from @var{wt-tree-2} @@ -11057,7 +11049,7 @@ the other tree then the worst-case time required is proportional to the logarithm of the size of the larger tree. @end deffn -@deffn {procedure+} wt-tree/intersection wt-tree-1 wt-tree-2 +@deffn procedure wt-tree/intersection wt-tree-1 wt-tree-2 Returns a new tree containing all and only those associations from @var{wt-tree-1} that have keys appearing as the key of an association in @var{wt-tree-2}. Thus the associated data in the result are those @@ -11069,7 +11061,7 @@ The worst-case time required by this operation is proportional to the sum of the sizes of the trees. @end deffn -@deffn {procedure+} wt-tree/difference wt-tree-1 wt-tree-2 +@deffn procedure wt-tree/difference wt-tree-1 wt-tree-2 Returns a new tree containing all and only those associations from @var{wt-tree-1} that have keys that @emph{do not} appear as the key of an association in @var{wt-tree-2}. If the trees are viewed as sets the @@ -11080,7 +11072,7 @@ The worst-case time required by this operation is proportional to the sum of the sizes of the trees. @end deffn -@deffn {procedure+} wt-tree/subset? wt-tree-1 wt-tree-2 +@deffn procedure wt-tree/subset? wt-tree-1 wt-tree-2 Returns @code{#t} iff the key of each association in @var{wt-tree-1} is the key of some association in @var{wt-tree-2}, otherwise returns @code{#f}. Viewed as a set operation, @code{wt-tree/subset?} is the improper subset @@ -11101,7 +11093,7 @@ required by this operation is proportional to the size of @var{wt-tree-1}. @end deffn -@deffn {procedure+} wt-tree/set-equal? wt-tree-1 wt-tree-2 +@deffn procedure wt-tree/set-equal? wt-tree-1 wt-tree-2 Returns @code{#t} iff for every association in @var{wt-tree-1} there is an association in @var{wt-tree-2} that has the same key, and @emph{vice versa}. @@ -11124,7 +11116,7 @@ In the worst case the time required by this operation is proportional to the size of the smaller tree. @end deffn -@deffn {procedure+} wt-tree/fold combiner initial wt-tree +@deffn procedure wt-tree/fold combiner initial wt-tree This procedure reduces @var{wt-tree} by combining all the associations, using an reverse in-order traversal, so the associations are visited in reverse order. @var{Combiner} is a procedure of three arguments: a key, @@ -11154,7 +11146,7 @@ The data in the associations can be summed like this: @end example @end deffn -@deffn {procedure+} wt-tree/for-each action wt-tree +@deffn procedure wt-tree/for-each action wt-tree This procedure traverses @var{wt-tree} in order, applying @var{action} to each association. The associations are processed in increasing order of their keys. @@ -11174,7 +11166,7 @@ The example prints the tree: @end example @end deffn -@deffn {procedure+} wt-tree/union-merge wt-tree-1 wt-tree-2 merge +@deffn procedure wt-tree/union-merge wt-tree-1 wt-tree-2 merge Returns a new tree containing all the associations from both trees. If both trees have an association for the same key, the datum associated with that key in the result tree is computed by applying the procedure @@ -11238,9 +11230,9 @@ sequence of associations. Elements of the sequence can be accessed by position, and the position of an element in the sequence can be determined, both in logarthmic time. -@deffn {procedure+} wt-tree/index wt-tree index -@deffnx {procedure+} wt-tree/index-datum wt-tree index -@deffnx {procedure+} wt-tree/index-pair wt-tree index +@deffn procedure wt-tree/index wt-tree index +@deffnx procedure wt-tree/index-datum wt-tree index +@deffnx procedure wt-tree/index-pair wt-tree index Returns the 0-based @var{index}th association of @var{wt-tree} in the sorted sequence under the tree's ordering relation on the keys. @code{wt-tree/index} returns the @var{index}th key, @@ -11271,7 +11263,7 @@ maximum: (wt-tree/index @var{wt-tree} @end example @end deffn -@deffn {procedure+} wt-tree/rank wt-tree key +@deffn procedure wt-tree/rank wt-tree key Determines the 0-based position of @var{key} in the sorted sequence of the keys under the tree's ordering relation, or @code{#f} if the tree has no association with for @var{key}. This procedure returns either an @@ -11280,9 +11272,9 @@ times required by this operation are proportional to the logarithm of the number of associations in the tree. @end deffn -@deffn {procedure+} wt-tree/min wt-tree -@deffnx {procedure+} wt-tree/min-datum wt-tree -@deffnx {procedure+} wt-tree/min-pair wt-tree +@deffn procedure wt-tree/min wt-tree +@deffnx procedure wt-tree/min-datum wt-tree +@deffnx procedure wt-tree/min-pair wt-tree Returns the association of @var{wt-tree} that has the least key under the tree's ordering relation. @code{wt-tree/min} returns the least key, @code{wt-tree/min-datum} returns the datum associated with the @@ -11306,7 +11298,7 @@ They could have been written @end example @end deffn -@deffn {procedure+} wt-tree/delete-min wt-tree +@deffn procedure wt-tree/delete-min wt-tree Returns a new tree containing all of the associations in @var{wt-tree} except the association with the least key under the @var{wt-tree}'s ordering relation. An error is signalled if the tree is empty. The @@ -11319,7 +11311,7 @@ operation is equivalent to @end example @end deffn -@deffn {procedure+} wt-tree/delete-min! wt-tree +@deffn procedure wt-tree/delete-min! wt-tree Removes the association with the least key under the @var{wt-tree}'s ordering relation. An error is signalled if the tree is empty. The average and worst-case times required by this operation are proportional @@ -11423,7 +11415,7 @@ The initial @var{object}s may be any objects, but the last @var{object} @end example @end deffn -@deffn {procedure+} procedure? object +@deffn procedure procedure? object @cindex type predicate, for procedure Returns @code{#t} if @var{object} is a procedure; otherwise returns @code{#f}. If @code{#t} is returned, exactly one of the following @@ -11431,19 +11423,19 @@ predicates is satisfied by @var{object}: @code{compiled-procedure?}, @code{compound-procedure?}, or @code{primitive-procedure?}. @end deffn -@deffn {procedure+} compiled-procedure? object +@deffn procedure compiled-procedure? object @cindex type predicate, for compiled procedure Returns @code{#t} if @var{object} is a compiled procedure; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} compound-procedure? object +@deffn procedure compound-procedure? object @cindex type predicate, for compound procedure Returns @code{#t} if @var{object} is a compound (i.e.@: interpreted) procedure; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} primitive-procedure? object +@deffn procedure primitive-procedure? object @cindex type predicate, for primitive procedure Returns @code{#t} if @var{object} is a primitive procedure; otherwise returns @code{#f}. @@ -11466,12 +11458,12 @@ arguments is not one: (lambda arguments (apply car arguments)) @end example -@deffn {procedure+} procedure-arity-valid? procedure k +@deffn procedure procedure-arity-valid? procedure k Returns @code{#t} if @var{procedure} accepts @var{k} arguments; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} procedure-arity procedure +@deffn procedure procedure-arity procedure Returns a description of the number of arguments that @var{procedure} accepts. The result is a newly allocated pair whose car field is the minimum number of arguments, and whose cdr field is the maximum @@ -11492,7 +11484,7 @@ that the procedure has no maximum number of arguments. @end example @end deffn -@deffn {procedure+} procedure-environment procedure +@deffn procedure procedure-environment procedure Returns the closing environment of @var{procedure}. Signals an error if @var{procedure} is a primitive procedure, or if @var{procedure} is a compiled procedure for which the debugging information is unavailable. @@ -11501,7 +11493,7 @@ compiled procedure for which the debugging information is unavailable. @node Primitive Procedures, Continuations, Procedure Operations, Procedures @section Primitive Procedures -@deffn {procedure+} make-primitive-procedure name [arity] +@deffn procedure make-primitive-procedure name [arity] @var{Name} must be a symbol. @var{Arity} must be an exact non-negative integer, @code{-1}, @code{#f}, or @code{#t}; if not supplied it defaults to @code{#f}. Returns the primitive procedure called @var{name}. May @@ -11523,7 +11515,7 @@ accepts any number of arguments. @end table @end deffn -@deffn {procedure+} primitive-procedure-name primitive-procedure +@deffn procedure primitive-procedure-name primitive-procedure Returns the name of @var{primitive-procedure}, a symbol. @example @@ -11531,7 +11523,7 @@ Returns the name of @var{primitive-procedure}, a symbol. @end example @end deffn -@deffn {procedure+} implemented-primitive-procedure? primitive-procedure +@deffn procedure implemented-primitive-procedure? primitive-procedure Returns @code{#t} if @var{primitive-procedure} is implemented; otherwise returns @code{#f}. Useful because the code that implements a particular primitive procedure is not necessarily linked into the executable Scheme @@ -11612,13 +11604,13 @@ deal explicitly with continuations, procedure that acts just like the current continuation. @end deffn -@deffn {procedure+} continuation? object +@deffn procedure continuation? object @cindex type predicate, for continuation Returns @code{#t} if @var{object} is a continuation; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} within-continuation continuation thunk +@deffn procedure within-continuation continuation thunk @cindex continuation, alternate invocation @cindex escape procedure, alternate invocation @var{Thunk} must be a procedure of no arguments. Conceptually,@* @@ -11628,7 +11620,7 @@ of @var{continuation}. In other words, the ``current'' continuation is abandoned before @var{thunk} is invoked. @end deffn -@deffn {procedure+} dynamic-wind before thunk after +@deffn procedure dynamic-wind before thunk after Calls @var{thunk} without arguments, returning the result(s) of this call. @var{Before} and @var{after} are called, also without arguments, as required by the following rules (note that in the absence of calls to @@ -11706,7 +11698,7 @@ extent of a call to @var{before} or @var{after} is undefined. The following two procedures support multiple values. -@deffn {procedure+} call-with-values thunk procedure +@deffn procedure call-with-values thunk procedure @cindex multiple values, from procedure @cindex values, multiple @var{Thunk} must be a procedure of no arguments, and @var{procedure} @@ -11719,7 +11711,7 @@ multiple values as its arguments. The result yielded by @var{procedure} is returned as the result of @code{call-with-values}. @end deffn -@deffn {procedure+} values object @dots{} +@deffn procedure values object @dots{} Returns multiple values. The continuation in effect when this procedure is called must be a multiple-value continuation that was created by @code{call-with-values}. Furthermore it must accept as many values as @@ -11754,60 +11746,60 @@ its procedure component. An apply hook is considered to accept the same number of arguments as its procedure, while an entity is considered to accept one less argument than its procedure. -@deffn {procedure+} make-apply-hook procedure object +@deffn procedure make-apply-hook procedure object Returns a newly allocated apply hook with a procedure component of @var{procedure} and an extra component of @var{object}. @end deffn -@deffn {procedure+} apply-hook? object +@deffn procedure apply-hook? object @cindex type predicate, for apply hook Returns @code{#t} if @var{object} is an apply hook; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} apply-hook-procedure apply-hook +@deffn procedure apply-hook-procedure apply-hook Returns the procedure component of @var{apply-hook}. @end deffn -@deffn {procedure+} set-apply-hook-procedure! apply-hook procedure +@deffn procedure set-apply-hook-procedure! apply-hook procedure Changes the procedure component of @var{apply-hook} to be @var{procedure}. Returns an unspecified value. @end deffn -@deffn {procedure+} apply-hook-extra apply-hook +@deffn procedure apply-hook-extra apply-hook Returns the extra component of @var{apply-hook}. @end deffn -@deffn {procedure+} set-apply-hook-extra! apply-hook object +@deffn procedure set-apply-hook-extra! apply-hook object Changes the extra component of @var{apply-hook} to be @var{object}. Returns an unspecified value. @end deffn -@deffn {procedure+} make-entity procedure object +@deffn procedure make-entity procedure object Returns a newly allocated entity with a procedure component of @var{procedure} and an extra component of @var{object}. @end deffn -@deffn {procedure+} entity? object +@deffn procedure entity? object @cindex type predicate, for entity Returns @code{#t} if @var{object} is an entity; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} entity-procedure entity +@deffn procedure entity-procedure entity Returns the procedure component of @var{entity}. @end deffn -@deffn {procedure+} set-entity-procedure! entity procedure +@deffn procedure set-entity-procedure! entity procedure Changes the procedure component of @var{entity} to be @var{procedure}. Returns an unspecified value. @end deffn -@deffn {procedure+} entity-extra entity +@deffn procedure entity-extra entity Returns the extra component of @var{entity}. @end deffn -@deffn {procedure+} set-entity-extra! entity object +@deffn procedure set-entity-extra! entity object Changes the extra component of @var{entity} to be @var{object}. Returns an unspecified value. @end deffn @@ -11832,29 +11824,29 @@ frame-like structure of environments by permitting you to examine the bindings of a particular environment separately from those of its parent. -@deffn {procedure+} environment? object +@deffn procedure environment? object @cindex type predicate, for environment Returns @code{#t} if @var{object} is an environment; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} environment-has-parent? environment +@deffn procedure environment-has-parent? environment Returns @code{#t} if @var{environment} has a parent environment; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} environment-parent environment +@deffn procedure environment-parent environment Returns the parent environment of @var{environment}. It is an error if @var{environment} has no parent. @end deffn -@deffn {procedure+} environment-bound-names environment +@deffn procedure environment-bound-names environment Returns a newly allocated list of the names (symbols) that are bound by @var{environment}. This does not include the names that are bound by the parent environment of @var{environment}. @end deffn -@deffn {procedure+} environment-bindings environment +@deffn procedure environment-bindings environment Returns a newly allocated list of the bindings of @var{environment}; does not include the bindings of the parent environment. Each element of this list takes one of two forms: @code{(@var{name})} @@ -11863,29 +11855,29 @@ indicates that @var{name} is bound but unassigned, while its value is @var{object}. @end deffn -@deffn {procedure+} environment-bound? environment symbol +@deffn procedure environment-bound? environment symbol Returns @code{#t} if @var{symbol} is bound in @var{environment} or one of its ancestor environments; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} environment-lookup environment symbol +@deffn procedure environment-lookup environment symbol @var{Symbol} must be bound in @var{environment} or one of its ancestor environments. Returns the value to which it is bound. @end deffn -@deffn {procedure+} environment-assignable? environment symbol +@deffn procedure environment-assignable? environment symbol @var{Symbol} must be bound in @var{environment} or one of its ancestor environments. Returns @code{#t} if the binding may be modified by side effect. @end deffn -@deffn {procedure+} environment-assign! environment symbol object +@deffn procedure environment-assign! environment symbol object @var{Symbol} must be bound in @var{environment} or one of its ancestor environments, and must be assignable. Modifies the binding to have @var{object} as its value, and returns an unspecified result. @end deffn -@deffn {procedure+} eval expression environment +@deffn procedure eval expression environment @cindex s-expression @cindex evaluation, of s-expression Evaluates @var{expression}, a list-structure representation (sometimes @@ -11917,14 +11909,14 @@ new bindings that you create in the @sc{rep} loop (with @code{define} forms or by loading files containing @code{define} forms) occur in @code{user-initial-environment}. -@defvr {variable+} system-global-environment +@defvr variable system-global-environment The variable @code{system-global-environment} is bound to the environment that's the parent of the @code{user-initial-environment}. Primitives and system procedures are bound (and sometimes closed) in this environment. @end defvr -@defvr {variable+} user-initial-environment +@defvr variable user-initial-environment The variable @code{user-initial-environment} is bound to the default environment in which typed expressions are evaluated by the top-level @sc{rep} loop. @@ -11943,14 +11935,14 @@ see the original definition. @node REPL Environment, Interpreter Environments, Environment Variables, Environments @section REPL Environment -@deffn {procedure+} nearest-repl/environment +@deffn procedure nearest-repl/environment @findex user-initial-environment Returns the current @sc{rep} loop environment (i.e.@: the current environment of the closest enclosing @sc{rep} loop). When Scheme first starts up, this is the same as @code{user-initial-environment}. @end deffn -@deffn {procedure+} ge environment +@deffn procedure ge environment Changes the current @sc{rep} loop environment to @var{environment}. @var{Environment} can be either an environment or a procedure object. If it's a procedure, the environment in which that procedure was closed @@ -11976,7 +11968,7 @@ macros, which are incompatible with non-top-level instances of @code{make-environment} and @code{the-environment}. At that time, other uses of these constructs will be disallowed. -@deffn {special form+} make-environment expression @dots{} +@deffn {special form} make-environment expression @dots{} @cindex construction, of environment Produces a new environment that is a child of the environment in which it is executed, evaluates the @var{expression}s sequentially in the new @@ -11998,11 +11990,11 @@ is equivalent to: @end example @end deffn -@deffn {special form+} the-environment +@deffn {special form} the-environment Returns the current environment. @end deffn -@deffn {procedure+} interpreter-environment? object +@deffn procedure interpreter-environment? object @cindex type predicate, for interpreter environment Returns @code{#t} if @var{object} is an interpreter environment; otherwise returns @code{#f}. @@ -12031,6 +12023,7 @@ custom ports and high-performance @sc{i/o}. * Prompting:: * Port Primitives:: * Parser Buffers:: +* Parser Language:: @end menu @node Ports, File Ports, Input/Output, Input/Output @@ -12072,7 +12065,7 @@ All ports read or write only @acronym{ISO-8859-1} characters. Every port is either an input port, an output port, or both. The following predicates distinguish all of the possible cases. -@deffn {procedure+} port? object +@deffn procedure port? object @cindex type predicate, for port Returns @code{#t} if @var{object} is a port, otherwise returns @code{#f}. @@ -12090,17 +12083,17 @@ Returns @code{#t} if @var{object} is an output port, otherwise returns @code{port?}. @end deffn -@deffn {procedure+} i/o-port? object +@deffn procedure i/o-port? object Returns @code{#t} if @var{object} is both an input port and an output port, otherwise returns @code{#f}. Any object satisfying this predicate also satisfies @code{port?}, @code{input-port?}, and @code{output-port?}. @end deffn -@deffn {procedure+} guarantee-port object -@deffnx {procedure+} guarantee-input-port object -@deffnx {procedure+} guarantee-output-port object -@deffnx {procedure+} guarantee-i/o-port object +@deffn procedure guarantee-port object +@deffnx procedure guarantee-input-port object +@deffnx procedure guarantee-output-port object +@deffnx procedure guarantee-i/o-port object These procedures check the type of @var{object}, signalling an error of type@* @code{condition-type:wrong-type-argument} if it is not a port, input port, output port, or @sc{i/o} port, respectively. Otherwise they @@ -12130,7 +12123,7 @@ output procedures. Initially, @code{current-output-port} returns the value of @code{console-i/o-port}. @end deffn -@deffn {procedure+} notification-output-port +@deffn procedure notification-output-port Returns an output port suitable for generating ``notifications'', that is, messages to the user that supply interesting information about the execution of a program. For example, the @code{load} procedure writes @@ -12139,25 +12132,25 @@ Initially, @code{notification-output-port} returns the value of @code{console-i/o-port}. @end deffn -@deffn {procedure+} trace-output-port +@deffn procedure trace-output-port Returns an output port suitable for generating ``tracing'' information about a program's execution. The output generated by the @code{trace} procedure is sent to this port. Initially, @code{trace-output-port} returns the value of @code{console-i/o-port}. @end deffn -@deffn {procedure+} interaction-i/o-port +@deffn procedure interaction-i/o-port Returns an @sc{i/o} port suitable for querying or prompting the user. The standard prompting procedures use this port by default (@pxref{Prompting}). Initially, @code{interaction-i/o-port} returns the value of @code{console-i/o-port}. @end deffn -@deffn {procedure+} with-input-from-port input-port thunk -@deffnx {procedure+} with-output-to-port output-port thunk -@deffnx {procedure+} with-notification-output-port output-port thunk -@deffnx {procedure+} with-trace-output-port output-port thunk -@deffnx {procedure+} with-interaction-i/o-port i/o-port thunk +@deffn procedure with-input-from-port input-port thunk +@deffnx procedure with-output-to-port output-port thunk +@deffnx procedure with-notification-output-port output-port thunk +@deffnx procedure with-trace-output-port output-port thunk +@deffnx procedure with-interaction-i/o-port i/o-port thunk @var{Thunk} must be a procedure of no arguments. Each of these procedures binds one of the standard ports to its first argument, calls @var{thunk} with no arguments, restores the port to its original value, @@ -12173,17 +12166,17 @@ port, @code{with-trace-output-port} binds the ``trace'' output port, and @code{with-interaction-i/o-port} binds the ``interaction'' @sc{i/o} port. @end deffn -@deffn {procedure+} set-current-input-port! input-port -@deffnx {procedure+} set-current-output-port! output-port -@deffnx {procedure+} set-notification-output-port! output-port -@deffnx {procedure+} set-trace-output-port! output-port -@deffnx {procedure+} set-interaction-i/o-port! i/o-port +@deffn procedure set-current-input-port! input-port +@deffnx procedure set-current-output-port! output-port +@deffnx procedure set-notification-output-port! output-port +@deffnx procedure set-trace-output-port! output-port +@deffnx procedure set-interaction-i/o-port! i/o-port Each of these procedures alters the binding of one of the standard ports and returns an unspecified value. The binding that is modified corresponds to the name of the procedure. @end deffn -@defvr {variable+} console-i/o-port +@defvr variable console-i/o-port @cindex port, console @cindex console, port @cindex input port, console @@ -12197,7 +12190,7 @@ This variable is rarely used; instead programs should use one of the standard ports defined above. This variable should not be modified. @end defvr -@deffn {procedure+} close-port port +@deffn procedure close-port port @cindex closing, of port Closes @var{port} and returns an unspecified value. If @var{port} is a file port, the file is closed. @@ -12275,7 +12268,7 @@ the end of the existing contents. If the file does not exist, append mode creates the file and writes to it in the normal way. @end deffn -@deffn {procedure+} open-i/o-file filename +@deffn procedure open-i/o-file filename @cindex construction, of file input port Takes a filename referring to an existing file and returns an @sc{i/o} port capable of both reading and writing the file. If the file cannot @@ -12288,15 +12281,15 @@ unix this procedure can be used to open terminal device files, @sc{pty} device files, and named pipes. @end deffn -@deffn {procedure+} open-binary-input-file filename -@deffnx {procedure+} open-binary-output-file filename [append?] -@deffnx {procedure+} open-binary-i/o-file filename +@deffn procedure open-binary-input-file filename +@deffnx procedure open-binary-output-file filename [append?] +@deffnx procedure open-binary-i/o-file filename These procedures open files in binary mode. In all other respects they are identical to @code{open-input-file}, @code{open-output-file}, and @code{open-i/o-file}, respectively. @end deffn -@deffn {procedure+} close-all-open-files +@deffn procedure close-all-open-files @cindex closing, of file port This procedure closes all file ports that are open at the time that it is called, and returns an unspecified value. @@ -12320,8 +12313,8 @@ both @code{call-with-current-continuation} and @code{call-with-input-file} or @code{call-with-output-file}.} @end deffn -@deffn {procedure+} call-with-binary-input-file filename procedure -@deffnx {procedure+} call-with-binary-output-file filename procedure +@deffn procedure call-with-binary-input-file filename procedure +@deffnx procedure call-with-binary-output-file filename procedure These procedures open files in binary mode. In all other respects they are identical to @code{call-with-input-file} and @code{call-with-output-file}, respectively. @@ -12346,8 +12339,8 @@ implementation-dependent; in that situation MIT Scheme leaves the files open. @end deffn -@deffn {procedure+} with-input-from-binary-file filename thunk -@deffnx {procedure+} with-output-to-binary-file filename thunk +@deffn procedure with-input-from-binary-file filename thunk +@deffnx procedure with-output-to-binary-file filename thunk These procedures open files in binary mode. In all other respects they are identical to @code{with-input-from-file} and @code{with-output-to-file}, respectively. @@ -12367,7 +12360,7 @@ their output and return it as a string. It also describes ``truncating'' output ports, which can limit the length of the resulting string to a given value. -@deffn {procedure+} string->input-port string [start [end]] +@deffn procedure string->input-port string [start [end]] @cindex string, converting to input port @cindex construction, of string input port Returns a new string port that delivers characters from @var{string}. @@ -12377,7 +12370,7 @@ that the string port delivers characters from a substring of @var{end} defaults to @code{(string-length @var{string})}. @end deffn -@deffn {procedure+} with-input-from-string string thunk +@deffn procedure with-input-from-string string thunk @cindex current input port, rebinding @var{Thunk} must be a procedure of no arguments. @code{with-input-from-string} creates a new input port that reads from @@ -12397,14 +12390,14 @@ Note: this procedure is equivalent to: @end example @end deffn -@deffn {procedure+} with-string-output-port procedure +@deffn procedure with-string-output-port procedure @var{Procedure} is called with one argument, an output port. The value yielded by @var{procedure} is ignored. When @var{procedure} returns, @code{with-string-output-port} returns the port's accumulated output as a newly allocated string. @end deffn -@deffn {procedure+} with-output-to-string thunk +@deffn procedure with-output-to-string thunk @cindex current output port, rebinding @cindex construction, of string output port @findex current-output-port @@ -12435,7 +12428,7 @@ Note: this procedure is equivalent to: @end example @end deffn -@deffn {procedure+} with-output-to-truncated-string k thunk +@deffn procedure with-output-to-truncated-string k thunk Similar to @code{with-output-to-string}, except that the output is limited to @var{k} characters. If @var{thunk} attempts to write more than @var{k} characters, it will be aborted by invoking an escape @@ -12464,7 +12457,7 @@ example: @end example @end deffn -@deffn {procedure+} write-to-string object [k] +@deffn procedure write-to-string object [k] Writes @var{object} to a string output port, and returns the resulting newly allocated string. If @var{k} is supplied and not @code{#f}, this procedure is equivalent to @@ -12580,7 +12573,7 @@ Returns @code{#t} if @var{object} is an end-of-file object; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} read-char-no-hang [input-port] +@deffn procedure read-char-no-hang [input-port] If @var{input-port} can deliver a character without blocking, this procedure acts exactly like @code{read-char}, immediately returning that character. Otherwise, @code{#f} is returned, unless @var{input-port} is @@ -12588,7 +12581,7 @@ a file port at end of file, in which case an end-of-file object is returned. In no case will this procedure block waiting for input. @end deffn -@deffn {procedure+} read-string char-set [input-port] +@deffn procedure read-string char-set [input-port] @cindex string, input from port Reads characters from @var{input-port} until it finds a terminating character that is a member of @var{char-set} (@pxref{Character Sets}) or @@ -12625,7 +12618,7 @@ following equivalent code using @code{peek-char} and @code{read-char}: @end example @end deffn -@deffn {procedure+} read-line [input-port] +@deffn procedure read-line [input-port] @code{read-line} reads a single line of text from @var{input-port}, and returns that line as a newly allocated string. The @code{#\newline} terminating the line, if any, is discarded and does not appear in the @@ -12637,8 +12630,8 @@ encountered before any characters are read, an end-of-file object is returned. @end deffn -@deffn {procedure+} read-string! string [input-port] -@deffnx {procedure+} read-substring! string start end [input-port] +@deffn procedure read-string! string [input-port] +@deffnx procedure read-substring! string start end [input-port] @code{read-string!} and @code{read-substring!} fill the specified region of @var{string} with characters read from @var{input-port} until the region is full or else there are no more characters available from the @@ -12686,7 +12679,7 @@ amounts of data. The following variables may be dynamically bound to change the behavior of the @code{read} procedure. -@defvr {variable+} *parser-radix* +@defvr variable *parser-radix* This variable defines the radix used by the reader when it parses numbers. This is similar to passing a radix argument to @code{string->number}. The value of this variable must be one of @@ -12704,7 +12697,7 @@ than the default. The default value of this variable is @code{10}. @end defvr -@defvr {variable+} *parser-canonicalize-symbols?* +@defvr variable *parser-canonicalize-symbols?* This variable controls how the parser handles case-sensitivity of symbols. If it is bound to its default value of @code{#t}, symbols read by the parser are converted to lower case before being interned. @@ -12752,7 +12745,7 @@ the character) to @var{output-port}, performs discretionary output flushing, and returns an unspecified value. @end deffn -@deffn {procedure+} write-string string [output-port] +@deffn procedure write-string string [output-port] @cindex string, output to port Writes @var{string} to @var{output-port}, performs discretionary output flushing, and returns an unspecified value. This is equivalent to @@ -12760,7 +12753,7 @@ writing the contents of @var{string}, one character at a time using @code{write-char}, except that it is usually much faster. @end deffn -@deffn {procedure+} write-substring string start end [output-port] +@deffn procedure write-substring string start end [output-port] @cindex string, output to port Writes the substring defined by @var{string}, @var{start}, and @var{end} to @var{output-port}, performs discretionary output flushing, and @@ -12801,7 +12794,7 @@ output flushing, and returns an unspecified value. Equivalent to @code{(write-char #\newline @var{output-port})}. @end deffn -@deffn {procedure+} fresh-line [output-port] +@deffn procedure fresh-line [output-port] Most output ports are able to tell whether or not they are at the beginning of a line of output. If @var{output-port} is such a port, this procedure writes an end-of-line to the port only if the port is not @@ -12811,20 +12804,20 @@ port, this procedure is identical to @code{newline}. In either case, unspecified value. @end deffn -@deffn {procedure+} write-line object [output-port] +@deffn procedure write-line object [output-port] Like @code{write}, except that it writes an end-of-line to @var{output-port} after writing @var{object}'s representation. This procedure performs discretionary output flushing and returns an unspecified value. @end deffn -@deffn {procedure+} flush-output [output-port] +@deffn procedure flush-output [output-port] If @var{output-port} is buffered, this causes the contents of its buffer to be written to the output device. Otherwise it has no effect. Returns an unspecified value. @end deffn -@deffn {procedure+} beep [output-port] +@deffn procedure beep [output-port] @cindex console, ringing the bell @cindex ringing the console bell @cindex bell, ringing on console @@ -12836,7 +12829,7 @@ the screen. On most output ports, e.g.@: file and string output ports, this does nothing. @end deffn -@deffn {procedure+} clear [output-port] +@deffn procedure clear [output-port] @cindex console, clearing @cindex display, clearing @cindex screen, clearing @@ -12848,7 +12841,7 @@ window, this has a well-defined effect. On other output ports, e.g.@: file and string output ports, this does nothing. @end deffn -@deffn {procedure+} pp object [output-port [as-code?]] +@deffn procedure pp object [output-port [as-code?]] @cindex pretty printer @code{pp} prints @var{object} in a visually appealing and structurally revealing manner on @var{output-port}. If object is a procedure, @@ -12861,14 +12854,14 @@ performs discretionary output flushing and returns an unspecified value. The following variables may be dynamically bound to change the behavior of the @code{write} and @code{display} procedures. -@defvr {variable+} *unparser-radix* +@defvr variable *unparser-radix* This variable specifies the default radix used to print numbers. Its value must be one of the exact integers @code{2}, @code{8}, @code{10}, or @code{16}; the default is @code{10}. If @code{*unparser-radix*} is not @code{10}, numbers are prefixed to indicate their radix. @end defvr -@defvr {variable+} *unparser-list-breadth-limit* +@defvr variable *unparser-list-breadth-limit* This variable specifies a limit on the length of the printed representation of a list or vector; for example, if the limit is @code{4}, only the first four elements of any list are printed, followed @@ -12888,7 +12881,7 @@ limit; the default is @code{#f}. @end example @end defvr -@defvr {variable+} *unparser-list-depth-limit* +@defvr variable *unparser-list-depth-limit* This variable specifies a limit on the nesting of lists and vectors in the printed representation. If lists (or vectors) are more deeply nested than the limit, the part of the representation that exceeds the @@ -12908,7 +12901,7 @@ is @code{#f}. @end example @end defvr -@defvr {variable+} *unparser-string-length-limit* +@defvr variable *unparser-string-length-limit* This variable specifies a limit on the length of the printed representation of strings. If a string's length exceeds this limit, the part of the printed representation for the characters exceeding the @@ -12928,7 +12921,7 @@ is @code{#f}. @end example @end defvr -@defvr {variable+} *unparse-with-maximum-readability?* +@defvr variable *unparse-with-maximum-readability?* This variable, which takes a boolean value, tells the printer to use a special printed representation for objects that normally print in a form that cannot be recognized by @code{read}. These objects are printed @@ -12964,7 +12957,7 @@ directives.@footnote{This description of @code{format} is adapted from @noindent once before calling it. -@deffn {procedure+} format destination control-string argument @dots{} +@deffn procedure format destination control-string argument @dots{} @findex write-string @cindex format directive (defn) @cindex directive, format (defn) @@ -13089,7 +13082,7 @@ elements (@pxref{Vectors}), and pairs that have special tags in their car fields (@pxref{Lists}). There is a different procedure for specifying the written representation of each of these types. -@deffn {procedure+} set-record-type-unparser-method! record-type unparser-method +@deffn procedure set-record-type-unparser-method! record-type unparser-method Changes the unparser method of the type represented by @var{record-type} to be @var{unparser-method}, and returns an unspecified value. Subsequently, when the unparser encounters a record of this type, it @@ -13097,7 +13090,7 @@ will invoke @var{unparser-method} to generate the written representation. @end deffn -@deffn {procedure+} unparser/set-tagged-vector-method! tag unparser-method +@deffn procedure unparser/set-tagged-vector-method! tag unparser-method Changes the unparser method of the vector type represented by @var{tag} to be @var{unparser-method}, and returns an unspecified value. Subsequently, when the unparser encounters a vector with @var{tag} as @@ -13105,7 +13098,7 @@ its zero-th element, it will invoke @var{unparser-method} to generate the written representation. @end deffn -@deffn {procedure+} unparser/set-tagged-pair-method! tag unparser-method +@deffn procedure unparser/set-tagged-pair-method! tag unparser-method Changes the unparser method of the pair type represented by @var{tag} to be @var{unparser-method}, and returns an unspecified value. Subsequently, when the unparser encounters a pair with @var{tag} in its @@ -13132,7 +13125,7 @@ encourage the use of the first method, as it results in a more uniform appearance for objects. Many predefined datatypes, for example procedures and environments, already have this appearance. -@deffn {procedure+} standard-unparser-method name procedure +@deffn procedure standard-unparser-method name procedure Returns a standard unparser method. @var{Name} may be any object, and is used as the name of the type with which the unparser method is associated; @var{name} is usually a symbol. @var{Procedure} must be @@ -13195,7 +13188,7 @@ The closing bracket is written to the output port. The following procedure is useful for writing more general kinds of unparser methods. -@deffn {procedure+} with-current-unparser-state unparser-state procedure +@deffn procedure with-current-unparser-state unparser-state procedure This procedure calls @var{procedure} with one argument, the output port from @var{unparser-state}. Additionally, it arranges for the remaining components of @var{unparser-state} to be given to the printer when they @@ -13227,7 +13220,7 @@ which if given must be an @sc{i/o} port. If not given, this port defaults to the value of @code{(interaction-i/o-port)}; this is initially the console @sc{i/o} port. -@deffn {procedure+} prompt-for-command-expression prompt [port] +@deffn procedure prompt-for-command-expression prompt [port] Prompts the user for an expression that is to be executed as a command. This is the procedure called by the @sc{rep} loop to read the user's expressions. @@ -13249,7 +13242,7 @@ for input using specific editor commands. The first expression that is submitted is returned as the value of this procedure. @end deffn -@deffn {procedure+} prompt-for-command-char prompt [port] +@deffn procedure prompt-for-command-char prompt [port] @findex char-graphic? Prompts the user for a single character that is to be executed as a command; the returned character is guaranteed to satisfy @@ -13280,7 +13273,7 @@ as input. After this mode change, the first such character submitted is returned as the value of this procedure. @end deffn -@deffn {procedure+} prompt-for-expression prompt [port] +@deffn procedure prompt-for-expression prompt [port] Prompts the user for an expression. The prompt string is formed by appending a colon and a space to @@ -13294,14 +13287,14 @@ object and return it. Under Edwin and Emacs, the expression is read in the minibuffer. @end deffn -@deffn {procedure+} prompt-for-evaluated-expression prompt [environment [port]] +@deffn procedure prompt-for-evaluated-expression prompt [environment [port]] Prompts the user for an evaluated expression. Calls @code{prompt-for-expression} to read an expression, then evaluates the expression using @var{environment}; if @var{environment} is not given, the @sc{rep} loop environment is used. @end deffn -@deffn {procedure+} prompt-for-confirmation prompt [port] +@deffn procedure prompt-for-confirmation prompt [port] Prompts the user for confirmation. The result yielded by this procedure is a boolean. @@ -13384,7 +13377,7 @@ prepared to deal with ports that do not implement them. The procedures in this section provide means for constructing port types with standard and custom operations, and accessing their operations. -@deffn {procedure+} make-port-type operations port-type +@deffn procedure make-port-type operations port-type @cindex construction, of port type Creates and returns a new port type. @var{Operations} must be a list; each element is a list of two elements, @@ -13412,27 +13405,27 @@ input operations defined in @var{port-type} are ignored. Likewise, if standard operations without having to enumerate them. @end deffn -@deffn {procedure+} port-type? object -@deffnx {procedure+} input-port-type? object -@deffnx {procedure+} output-port-type? object -@deffnx {procedure+} i/o-port-type? object +@deffn procedure port-type? object +@deffnx procedure input-port-type? object +@deffnx procedure output-port-type? object +@deffnx procedure i/o-port-type? object These predicates return @code{#t} if @var{object} is a port type, input-port type, output-port type, or @sc{i/o}-port type, respectively. Otherwise, they return @code{#f}. @end deffn -@deffn {procedure+} port-type/operations port-type +@deffn procedure port-type/operations port-type Returns a newly allocated list containing all of the operations implemented by @var{port-type}. Each element of the list is a list of two elements --- the name and its associated operation. @end deffn -@deffn {procedure+} port-type/operation-names port-type +@deffn procedure port-type/operation-names port-type Returns a newly allocated list whose elements are the names of the operations implemented by @var{port-type}. @end deffn -@deffn {procedure+} port-type/operation port-type symbol +@deffn procedure port-type/operation port-type symbol Returns the operation named @var{symbol} in @var{port-type}. If @var{port-type} has no such operation, returns @code{#f}. @end deffn @@ -13443,26 +13436,26 @@ Returns the operation named @var{symbol} in @var{port-type}. If The procedures in this section provide means for constructing ports, accessing the type of a port, and manipulating the state of a port. -@deffn {procedure+} make-port port-type state +@deffn procedure make-port port-type state Returns a new port with type @var{port-type} and the given @var{state}. The port will be an input, output, or @sc{i/o} port according to @var{port-type}. @end deffn -@deffn {procedure+} port/type port +@deffn procedure port/type port Returns the port type of @var{port}. @end deffn -@deffn {procedure+} port/state port +@deffn procedure port/state port Returns the state component of @var{port}. @end deffn -@deffn {procedure+} set-port/state! port object +@deffn procedure set-port/state! port object Changes the state component of @var{port} to be @var{object}. Returns an unspecified value. @end deffn -@deffn {procedure+} port/operation port symbol +@deffn procedure port/operation port symbol Equivalent to @example @@ -13470,7 +13463,7 @@ Equivalent to @end example @end deffn -@deffn {procedure+} port/operation-names port +@deffn procedure port/operation-names port Equivalent to @example @@ -13478,7 +13471,7 @@ Equivalent to @end example @end deffn -@deffn {procedure+} make-eof-object input-port +@deffn procedure make-eof-object input-port @cindex EOF object, construction @cindex construction, of EOF object @findex eof-object? @@ -13493,7 +13486,7 @@ is sometimes useful when building input ports. This section describes the standard operations on input ports. Following that, some useful custom operations are described. -@defop {operation+} {input port} read-char input-port +@defop operation {input port} read-char input-port @cindex character, input from port Removes the next character available from @var{input-port} and returns it. If @var{input-port} has no more characters and will never have any @@ -13504,20 +13497,20 @@ typed recently), and it is in non-blocking mode, @code{#f} is returned; otherwise the operation hangs until input is available. @end defop -@defop {operation+} {input port} peek-char input-port +@defop operation {input port} peek-char input-port Reads the next character available from @var{input-port} and returns it. The character is @emph{not} removed from @var{input-port}, and a subsequent attempt to read from the port will get that character again. In other respects this operation behaves like @code{read-char}. @end defop -@defop {operation+} {input port} discard-char input-port +@defop operation {input port} discard-char input-port Discards the next character available from @var{input-port} and returns an unspecified value. In other respects this operation behaves like @code{read-char}. @end defop -@defop {operation+} {input port} char-ready? input-port k +@defop operation {input port} char-ready? input-port k @code{char-ready?} returns @code{#t} if at least one character is available to be read from @var{input-port}. If no characters are available, the operation waits up to @var{k} milliseconds before @@ -13525,8 +13518,8 @@ returning @code{#f}, returning immediately if any characters become available while it is waiting. @end defop -@defop {operation+} {input port} read-string input-port char-set -@defopx {operation+} {input port} discard-chars input-port char-set +@defop operation {input port} read-string input-port char-set +@defopx operation {input port} discard-chars input-port char-set @cindex string, input from port These operations are like @code{read-char} and @code{discard-char}, except that they read or discard multiple characters at once. This can @@ -13541,7 +13534,7 @@ before any input characters, @code{read-string} returns an end-of-file object. @end defop -@defop {operation+} {input port} read-substring input-port string start end +@defop operation {input port} read-substring input-port string start end Reads characters from @var{input-port} into the substring defined by @var{string}, @var{start}, and @var{end} until either the substring has been filled or there are no more characters available. Returns the @@ -13557,13 +13550,13 @@ operation returns @code{#f} immediately. This is an extremely fast way to read characters from a port. @end defop -@deffn {procedure+} input-port/read-char input-port -@deffnx {procedure+} input-port/peek-char input-port -@deffnx {procedure+} input-port/discard-char input-port -@deffnx {procedure+} input-port/char-ready? input-port k -@deffnx {procedure+} input-port/read-string input-port char-set -@deffnx {procedure+} input-port/discard-chars input-port char-set -@deffnx {procedure+} input-port/read-substring input-port string start end +@deffn procedure input-port/read-char input-port +@deffnx procedure input-port/peek-char input-port +@deffnx procedure input-port/discard-char input-port +@deffnx procedure input-port/char-ready? input-port k +@deffnx procedure input-port/read-string input-port char-set +@deffnx procedure input-port/discard-chars input-port char-set +@deffnx procedure input-port/read-substring input-port string start end Each of these procedures invokes the respective operation on @var{input-port}. For example, the following are equivalent: @@ -13578,29 +13571,29 @@ Each of these procedures invokes the respective operation on The following custom operations are implemented for input ports to files, and will also work with some other kinds of input ports: -@defop {operation+} {input port} eof? input-port +@defop operation {input port} eof? input-port Returns @code{#t} if @var{input-port} is known to be at end of file, otherwise it returns @code{#f}. @end defop -@defop {operation+} {input port} chars-remaining input-port +@defop operation {input port} chars-remaining input-port Returns an estimate of the number of characters remaining to be read from @var{input-port}. This is useful only when @var{input-port} is a file port in binary mode; in other cases, it returns @code{#f}. @end defop -@defop {operation+} {input port} buffered-input-chars input-port +@defop operation {input port} buffered-input-chars input-port Returns the number of unread characters that are stored in @var{input-port}'s buffer. This will always be less than or equal to the buffer's size. @end defop -@defop {operation+} {input port} input-buffer-size input-port +@defop operation {input port} input-buffer-size input-port Returns the maximum number of characters that @var{input-port}'s buffer can hold. @end defop -@defop {operation+} {input port} set-input-buffer-size input-port size +@defop operation {input port} set-input-buffer-size input-port size Resizes @var{input-port}'s buffer so that it can hold at most @var{size} characters. Characters in the buffer are discarded. @var{Size} must be an exact non-negative integer. @@ -13613,12 +13606,12 @@ an exact non-negative integer. This section describes the standard operations on output ports. Following that, some useful custom operations are described. -@defop {operation+} {output port} write-char output-port char +@defop operation {output port} write-char output-port char @cindex character, output to port Writes @var{char} to @var{output-port} and returns an unspecified value. @end defop -@defop {operation+} {output port} write-substring output-port string start end +@defop operation {output port} write-substring output-port string start end @cindex substring, output to port Writes the substring specified by @var{string}, @var{start}, and @var{end} to @var{output-port} and returns an unspecified value. @@ -13626,7 +13619,7 @@ Equivalent to writing the characters of the substring, one by one, to @var{output-port}, but is implemented very efficiently. @end defop -@defop {operation+} {output port} fresh-line output-port +@defop operation {output port} fresh-line output-port Most output ports are able to tell whether or not they are at the beginning of a line of output. If @var{output-port} is such a port, end-of-line is written to the port only if the port is not already at @@ -13635,21 +13628,21 @@ end-of-line is unconditionally written to the port. Returns an unspecified value. @end defop -@defop {operation+} {output port} flush-output output-port +@defop operation {output port} flush-output output-port If @var{output-port} is buffered, this causes its buffer to be written out. Otherwise it has no effect. Returns an unspecified value. @end defop -@defop {operation+} {output port} discretionary-flush-output output-port +@defop operation {output port} discretionary-flush-output output-port Normally, this operation does nothing. However, ports that support discretionary output flushing implement this operation identically to @code{flush-output}. @end defop -@deffn {procedure+} output-port/write-char output-port char -@deffnx {procedure+} output-port/write-substring output-port string start end -@deffnx {procedure+} output-port/fresh-line output-port -@deffnx {procedure+} output-port/flush-output output-port -@deffnx {procedure+} output-port/discretionary-flush-output output-port +@deffn procedure output-port/write-char output-port char +@deffnx procedure output-port/write-substring output-port string start end +@deffnx procedure output-port/fresh-line output-port +@deffnx procedure output-port/flush-output output-port +@deffnx procedure output-port/discretionary-flush-output output-port Each of these procedures invokes the respective operation on @var{output-port}. For example, the following are equivalent: @@ -13662,7 +13655,7 @@ Each of these procedures invokes the respective operation on @end example @end deffn -@deffn {procedure+} output-port/write-string output-port string +@deffn procedure output-port/write-string output-port string Writes @var{string} to @var{output-port}. Equivalent to @example @@ -13677,36 +13670,36 @@ Writes @var{string} to @var{output-port}. Equivalent to The following custom operations are generally useful. -@defop {operation+} {output port} buffered-output-chars output-port +@defop operation {output port} buffered-output-chars output-port Returns the number of unwritten characters that are stored in @var{output-port}'s buffer. This will always be less than or equal to the buffer's size. @end defop -@defop {operation+} {output port} output-buffer-size output-port +@defop operation {output port} output-buffer-size output-port Returns the maximum number of characters that @var{output-port}'s buffer can hold. @end defop -@defop {operation+} {output port} set-output-buffer-size output-port size +@defop operation {output port} set-output-buffer-size output-port size Resizes @var{output-port}'s buffer so that it can hold at most @var{size} characters. Characters in the buffer are discarded. @var{Size} must be an exact non-negative integer. @end defop -@defop {operation+} {output port} x-size output-port +@defop operation {output port} x-size output-port Returns an exact positive integer that is the width of @var{output-port} in characters. If @var{output-port} has no natural width, e.g.@: if it is a file port, @code{#f} is returned. @end defop -@defop {operation+} {output port} y-size output-port +@defop operation {output port} y-size output-port Returns an exact positive integer that is the height of @var{output-port} in characters. If @var{output-port} has no natural height, e.g.@: if it is a file port, @code{#f} is returned. @end defop -@deffn {procedure+} output-port/x-size output-port +@deffn procedure output-port/x-size output-port This procedure invokes the custom operation whose name is the symbol @code{x-size}, if it exists. If the @code{x-size} operation is both defined and returns a value other than @code{#f}, that value is returned @@ -13720,7 +13713,7 @@ reasonable default width to work with, and this procedure provides exactly that. @end deffn -@deffn {procedure+} output-port/y-size output-port +@deffn procedure output-port/y-size output-port This procedure invokes the custom operation whose name is the symbol @code{y-size}, if it exists. If the @code{y-size} operation is defined, the value it returns is returned as the result of this procedure; @@ -13760,16 +13753,16 @@ to any of these procedures may be any port, even if that port does not support blocking mode; in that case, the port is not modified in any way. -@deffn {procedure+} port/input-blocking-mode port +@deffn procedure port/input-blocking-mode port Returns the input blocking mode of @var{port}. @end deffn -@deffn {procedure+} port/set-input-blocking-mode port mode +@deffn procedure port/set-input-blocking-mode port mode Changes the input blocking mode of @var{port} to be @var{mode}. Returns an unspecified value. @end deffn -@deffn {procedure+} port/with-input-blocking-mode port mode thunk +@deffn procedure port/with-input-blocking-mode port mode thunk @var{Thunk} must be a procedure of no arguments. @code{port/with-input-blocking-mode} binds the input blocking mode of @var{port} to be @var{mode}, executes @@ -13780,16 +13773,16 @@ by @code{dynamic-wind}, which guarantees that the input blocking mode is restored if @var{thunk} escapes from its continuation. @end deffn -@deffn {procedure+} port/output-blocking-mode port +@deffn procedure port/output-blocking-mode port Returns the output blocking mode of @var{port}. @end deffn -@deffn {procedure+} port/set-output-blocking-mode port mode +@deffn procedure port/set-output-blocking-mode port mode Changes the output blocking mode of @var{port} to be @var{mode}. Returns an unspecified value. @end deffn -@deffn {procedure+} port/with-output-blocking-mode port mode thunk +@deffn procedure port/with-output-blocking-mode port mode thunk @var{Thunk} must be a procedure of no arguments. @code{port/with-output-blocking-mode} binds the output blocking mode of @var{port} to be @var{mode}, executes @@ -13844,16 +13837,16 @@ values. A @var{port} argument to any of these procedures may be any port, even if that port does not support terminal mode; in that case, the port is not modified in any way. -@deffn {procedure+} port/input-terminal-mode port +@deffn procedure port/input-terminal-mode port Returns the input terminal mode of @var{port}. @end deffn -@deffn {procedure+} port/set-input-terminal-mode port mode +@deffn procedure port/set-input-terminal-mode port mode Changes the input terminal mode of @var{port} to be @var{mode}. Returns an unspecified value. @end deffn -@deffn {procedure+} port/with-input-terminal-mode port mode thunk +@deffn procedure port/with-input-terminal-mode port mode thunk @var{Thunk} must be a procedure of no arguments. @code{port/with-input-terminal-mode} binds the input terminal mode of @var{port} to be @var{mode}, executes @@ -13864,16 +13857,16 @@ by @code{dynamic-wind}, which guarantees that the input terminal mode is restored if @var{thunk} escapes from its continuation. @end deffn -@deffn {procedure+} port/output-terminal-mode port +@deffn procedure port/output-terminal-mode port Returns the output terminal mode of @var{port}. @end deffn -@deffn {procedure+} port/set-output-terminal-mode port mode +@deffn procedure port/set-output-terminal-mode port mode Changes the output terminal mode of @var{port} to be @var{mode}. Returns an unspecified value. @end deffn -@deffn {procedure+} port/with-output-terminal-mode port mode thunk +@deffn procedure port/with-output-terminal-mode port mode thunk @var{Thunk} must be a procedure of no arguments. @code{port/with-output-terminal-mode} binds the output terminal mode of @var{port} to be @var{mode}, executes @@ -13884,7 +13877,7 @@ by @code{dynamic-wind}, which guarantees that the output terminal mode is restored if @var{thunk} escapes from its continuation. @end deffn -@node Parser Buffers, , Port Primitives, Input/Output +@node Parser Buffers, Parser Language, Port Primitives, Input/Output @section Parser Buffers @cindex Parser buffer @@ -13908,22 +13901,22 @@ the @acronym{UTF-8} encoding. There are several constructors for parser buffers: -@deffn {procedure+} input-port->parser-buffer port +@deffn procedure input-port->parser-buffer port Returns a parser buffer that buffers characters read from @var{port}. @end deffn -@deffn {procedure+} substring->parser-buffer string start end +@deffn procedure substring->parser-buffer string start end Returns a parser buffer that buffers the characters in the argument substring. This is equivalent to creating a string input port and calling @code{input-port->parser-buffer}, but it runs faster and uses less memory. @end deffn -@deffn {procedure+} string->parser-buffer string +@deffn procedure string->parser-buffer string Like @code{substring->parser-buffer} but buffers the entire string. @end deffn -@deffn {procedure+} source->parser-buffer source +@deffn procedure source->parser-buffer source Returns a parser buffer that buffers the characters returned by calling @var{source}. @var{Source} is a procedure of three arguments: a string, a start index, and an end index (in other words, a substring @@ -13936,12 +13929,12 @@ zero. It must not return zero in any other circumstance. Parser buffers and parser-buffer pointers may be distinguished from other objects: -@deffn {procedure+} parser-buffer? object +@deffn procedure parser-buffer? object Return @code{#t} if @var{object} is a parser buffer, otherwise return @code{#f}. @end deffn -@deffn {procedure+} parser-buffer-pointer? object +@deffn procedure parser-buffer-pointer? object Return @code{#t} if @var{object} is a parser-buffer pointer, otherwise return @code{#f}. @end deffn @@ -13954,20 +13947,20 @@ look at characters arbitrarily far ahead in the stream. It is this buffering capability that facilitates complex matching and backtracking. -@deffn {procedure+} read-parser-buffer-char buffer +@deffn procedure read-parser-buffer-char buffer Return the next character in @var{buffer}, advancing the internal pointer past that character. If there are no more characters available, @code{#f} is returned and the internal pointer is unchanged. @end deffn -@deffn {procedure+} peek-parser-buffer-char buffer +@deffn procedure peek-parser-buffer-char buffer Return the next character in @var{buffer}, or @code{#f} if no characters are available. The internal pointer is unchanged by this operation. @end deffn -@deffn {procedure+} parser-buffer-ref buffer index +@deffn procedure parser-buffer-ref buffer index Return a character in @var{buffer}. @var{Index} is a non-negative integer specifying the character to be returned. If @var{index} is zero, return the next available character; if it is one, return the @@ -13978,12 +13971,12 @@ internal pointer is unchanged by this operation. The internal pointer of a parser buffer can be read or written: -@deffn {procedure+} get-parser-buffer-pointer buffer +@deffn procedure get-parser-buffer-pointer buffer Return a parser-buffer pointer object corresponding to the internal pointer of @var{buffer}. @end deffn -@deffn {procedure+} set-parser-buffer-pointer! buffer pointer +@deffn procedure set-parser-buffer-pointer! buffer pointer Set the internal pointer of @var{buffer} to the position specified by @var{pointer}. @var{Pointer} must have been returned from a previous call of @code{get-parser-buffer-pointer} on @var{buffer}. @@ -13992,7 +13985,7 @@ by @code{discard-parser-buffer-head!}, @var{pointer} must be outside the range that was discarded. @end deffn -@deffn {procedure+} get-parser-buffer-tail buffer pointer +@deffn procedure get-parser-buffer-tail buffer pointer Return a newly-allocated string consisting of all of the characters in @var{buffer} that fall between @var{pointer} and @var{buffer}'s internal pointer. @var{Pointer} must have been returned from a @@ -14002,7 +13995,7 @@ by @code{discard-parser-buffer-head!}, @var{pointer} must be outside the range that was discarded. @end deffn -@deffn {procedure+} discard-parser-buffer-head! buffer +@deffn procedure discard-parser-buffer-head! buffer Discard all characters in @var{buffer} that have already been read; in other words, all characters prior to the internal pointer. After this operation has completed, it is no longer possible to move the internal @@ -14016,62 +14009,62 @@ relative to the buffer's internal pointer, so the first character to be matched against is the next character that would be returned by @code{peek-parser-buffer-char}. The returned value is always @code{#t} for a successful match, and @code{#f} otherwise. For -procedures whose names do not end in @code{-no-advance}, a successful +procedures whose names do not end in @samp{-no-advance}, a successful match also moves the internal pointer of the buffer forward to the end of the matched text; otherwise the internal pointer is unchanged. -@deffn {procedure+} match-parser-buffer-char buffer char -@deffnx {procedure+} match-parser-buffer-char-ci buffer char -@deffnx {procedure+} match-parser-buffer-not-char buffer char -@deffnx {procedure+} match-parser-buffer-not-char-ci buffer char -@deffnx {procedure+} match-parser-buffer-char-no-advance buffer char -@deffnx {procedure+} match-parser-buffer-char-ci-no-advance buffer char -@deffnx {procedure+} match-parser-buffer-not-char-no-advance buffer char -@deffnx {procedure+} match-parser-buffer-not-char-ci-no-advance buffer char +@deffn procedure match-parser-buffer-char buffer char +@deffnx procedure match-parser-buffer-char-ci buffer char +@deffnx procedure match-parser-buffer-not-char buffer char +@deffnx procedure match-parser-buffer-not-char-ci buffer char +@deffnx procedure match-parser-buffer-char-no-advance buffer char +@deffnx procedure match-parser-buffer-char-ci-no-advance buffer char +@deffnx procedure match-parser-buffer-not-char-no-advance buffer char +@deffnx procedure match-parser-buffer-not-char-ci-no-advance buffer char Each of these procedures compares a single character in @var{buffer} to @var{char}. The basic comparison @code{match-parser-buffer-char} compares the character to @var{char} using @code{char=?}. The -procedures whose names contain the @code{-ci} modifier do +procedures whose names contain the @samp{-ci} modifier do case-insensitive comparison (i.e.@: they use @code{char-ci=?}). The -procedures whose names contain the @code{not-} modifier are successful +procedures whose names contain the @samp{not-} modifier are successful if the character @emph{doesn't} match @var{char}. @end deffn -@deffn {procedure+} match-parser-buffer-char-in-set buffer char-set -@deffnx {procedure+} match-parser-buffer-char-in-set-no-advance buffer char-set +@deffn procedure match-parser-buffer-char-in-set buffer char-set +@deffnx procedure match-parser-buffer-char-in-set-no-advance buffer char-set These procedures compare the next character in @var{buffer} against @var{char-set} using @code{char-set-member?}. @end deffn -@deffn {procedure+} match-parser-buffer-string buffer string -@deffnx {procedure+} match-parser-buffer-string-ci buffer string -@deffnx {procedure+} match-parser-buffer-string-no-advance buffer string -@deffnx {procedure+} match-parser-buffer-string-ci-no-advance buffer string +@deffn procedure match-parser-buffer-string buffer string +@deffnx procedure match-parser-buffer-string-ci buffer string +@deffnx procedure match-parser-buffer-string-no-advance buffer string +@deffnx procedure match-parser-buffer-string-ci-no-advance buffer string These procedures match @var{string} against @var{buffer}'s contents. -The @code{-ci} procedures do case-insensitive matching. +The @samp{-ci} procedures do case-insensitive matching. @end deffn -@deffn {procedure+} match-parser-buffer-substring buffer string start end -@deffnx {procedure+} match-parser-buffer-substring-ci buffer string start end -@deffnx {procedure+} match-parser-buffer-substring-no-advance buffer string start end -@deffnx {procedure+} match-parser-buffer-substring-ci-no-advance buffer string start end +@deffn procedure match-parser-buffer-substring buffer string start end +@deffnx procedure match-parser-buffer-substring-ci buffer string start end +@deffnx procedure match-parser-buffer-substring-no-advance buffer string start end +@deffnx procedure match-parser-buffer-substring-ci-no-advance buffer string start end These procedures match the specified substring against @var{buffer}'s -contents. The @code{-ci} procedures do case-insensitive matching. +contents. The @samp{-ci} procedures do case-insensitive matching. @end deffn -@deffn {procedure+} match-utf8-char-in-alphabet buffer alphabet +@deffn procedure match-utf8-char-in-alphabet buffer alphabet This procedure treats @var{buffer}'s contents as @acronym{UTF-8} encoded Unicode characters and matches the next such character against -@var{alphabet}, which must be a Unicode alphabet object -(@pxref{Unicode}). @acronym{UTF-8} represents characters with 1 to 6 -bytes, so a successful match can move the internal pointer forward by -as many as 6 bytes. +@var{alphabet}, which must be a Unicode alphabet (@pxref{Unicode}). +@acronym{UTF-8} represents characters with 1 to 6 bytes, so a +successful match can move the internal pointer forward by as many as 6 +bytes. @end deffn The remaining procedures provide information that can be used to identify locations in a parser buffer's stream. -@deffn {procedure+} parser-buffer-position-string pointer +@deffn procedure parser-buffer-position-string pointer Return a string describing the location of @var{pointer} in terms of its character and line indexes. This resulting string is meant to be presented to an end user in order to direct their attention to a @@ -14082,12 +14075,495 @@ presented as one-based numbers. is equivalent to having specified the buffer's internal pointer. @end deffn -@deffn {procedure+} parser-buffer-pointer-index pointer -@deffnx {procedure+} parser-buffer-pointer-line pointer +@deffn procedure parser-buffer-pointer-index pointer +@deffnx procedure parser-buffer-pointer-line pointer Return the character or line index, respectively, of @var{pointer}. Both indexes are zero-based. @end deffn +@node Parser Language, , Parser Buffers, Input/Output +@section Parser Language + +@cindex Parser language +Although it is possible to write parsers using the parser-buffer +abstraction (@pxref{Parser Buffers}), it is tedious. The problem is +that the abstraction isn't closely matched to the way that people +think about syntactic structures. In this section, we introduce a +higher-level mechanism that greatly simplifies the implementation of a +parser. + +The @dfn{parser language} described here allows the programmer to +write @acronym{BNF}-like specifications that are translated into +efficient Scheme code at compile time. The language is declarative, +but it can be freely mixed with Scheme code; this allows the parsing +of grammars that aren't conveniently described in the language. + +@cindex Backtracking, in parser language +The language also provides backtracking. For example, this expression +matches any sequence of alphanumeric characters followed by a single +alphabetic character: + +@example +@group +(*matcher + (seq (* (char-set char-set:alphanumeric)) + (char-set char-set:alphabetic))) +@end group +@end example + +@noindent +The way that this works is that the matcher matches alphanumeric +characters in the input stream until it finds a non-alphanumeric +character. It then tries to match an alphabetic character, which of +course fails. At this point, if it matched at least one alphanumeric +character, it @emph{backtracks}: the last matched alphanumeric is +``unmatched'', and it again attempts to match an alphabetic +character. The backtracking can be arbitrarily deep; the matcher will +continue to back up until it finds a way to match the remainder of the +expression. + +So far, this sounds a lot like regular-expression matching +(@pxref{Regular Expressions}). However, there are some important +differences. + +@itemize @bullet +@item +The parser language uses a Scheme-like syntax that is easier to read +and write than regular-expression notation. + +@item +The language provides macros so that common syntactic constructs can +be abstracted. + +@item +The language mixes easily with Scheme code, allowing the full power of +Scheme to be applied to program around limitations in the parser +language. + +@item +The language provides expressive facilities for converting syntax into +parsed structure. It also makes it easy to convert parsed strings +into meaningful objects (e.g.@: numbers). + +@item +The language is compiled into machine language; regular expressions +are usually interpreted. +@end itemize + +Here is an example that shows off several of the features of the +parser language. The example is a parser for @acronym{XML} start +tags: + +@anchor{with-pointer example} +@example +@group +(*parser + (with-pointer p + (seq "<" + parse-name + parse-attribute-list + (alt (match ">") + (match "/>") + (sexp + (lambda (b) + (error + (string-append + "Unterminated start tag at " + (parser-buffer-position-string p))))))))) +@end group +@end example + +@noindent +This shows that the basic description of a start tag is very similar +to its @acronym{BNF}. Non-terminal symbols @code{parse-name} and +@code{parse-attribute-list} do most of the work, and the noise strings +@code{"<"} and @code{">"} are the syntactic markers delimiting the +form. There are two alternate endings for start tags, and if the +parser doesn't find either of the endings, the Scheme code (wrapped in +@code{sexp}) is run to signal an error. The error procedure +@code{perror} takes a pointer @code{p}, which it uses to indicate the +position in the input stream at which the error occurred. In this +case, that is the beginning of the start tag, i.e.@: the position of +the leading @code{"<"} marker. + +This example still looks pretty complicated, mostly due to the +error-signalling code. In practice, this is abstracted into a macro, +after which the expression is quite succinct: + +@example +@group +(*parser + (bracket "start tag" + (seq (noise (string "<")) parse-name) + (match (alt (string ">") (string "/>"))) + parse-attribute-list)) +@end group +@end example + +@noindent +The @code{bracket} macro captures the pattern of a bracketed item, and +hides much of the detail. + +The parser language actually consists of two languages: one for +defining matchers, and one for defining parsers. The languages are +intentionally very similar, and are meant to be used together. Each +sub-language is described below in its own section. + +@cindex run-time-loadable option +@cindex option, run-time-loadable +The parser language is a run-time-loadable option; to use it, execute + +@example +(load-option '*parser) +@end example +@findex load-option + +@noindent +once before compiling any code that uses the language. + +@menu +* *Matcher:: +* *Parser:: +* Parser-language Macros:: +@end menu + +@node *Matcher, *Parser, Parser Language, Parser Language +@subsection *Matcher + +@cindex Matcher language +@cindex Matcher procedure +The @dfn{matcher language} is a declarative language for specifying a +@dfn{matcher procedure}. A matcher procedure is a procedure that +accepts a single parser-buffer argument and returns a boolean value +indicating whether the match it performs was successful. If the match +succeeds, the internal pointer of the parser buffer is moved forward +over the matched text. If the match fails, the internal pointer is +unchanged. + +For example, here is a matcher procedure that matches the character +@samp{a}: + +@example +(lambda (b) (match-parser-buffer-char b #\a)) +@end example + +@noindent +Here is another example that matches two given characters, @var{c1} +and @var{c2}, in sequence: + +@example +@group +(lambda (b) + (let ((p (get-parser-buffer-pointer b))) + (if (match-parser-buffer-char b @var{c1}) + (if (match-parser-buffer-char b @var{c2}) + #t + (begin + (set-parser-buffer-pointer! b p) + #f)) + #f))) +@end group +@end example + +@noindent +This is code is clear, but has lots of details that get in the way of +understanding what it is doing. Here is the same example in the +matcher language: + +@example +(*matcher (seq (char @var{c1}) (char @var{c2}))) +@end example + +@noindent +This is much simpler and more intuitive. And it generates virtually +the same code: + +@example +@group +(pp (*matcher (seq (char c1) (char c2)))) +@print{} (lambda (#[b1]) +@print{} (let ((#[p1] (get-parser-buffer-pointer #[b1]))) +@print{} (and (match-parser-buffer-char #[b1] c1) +@print{} (if (match-parser-buffer-char #[b1] c2) +@print{} #t +@print{} (begin +@print{} (set-parser-buffer-pointer! #[b1] #[p1]) +@print{} #f))))) +@end group +@end example + +Now that we have seen an example of the language, it's time to look at +the detail. The @code{*matcher} special form is the interface between +the matcher language and Scheme. + +@deffn {special form} *matcher mexp +The operand @var{mexp} is an expression in the matcher language. The +@code{*matcher} expression expands into Scheme code that implements a +matcher procedure. +@end deffn + +Here are the predefined matcher expressions. New matcher expressions +can be defined using the macro facility (@pxref{Parser-language +Macros}). We will start with the primitive expressions. + +@deffn {matcher expression} char expression +@deffnx {matcher expression} char-ci expression +@deffnx {matcher expression} not-char expression +@deffnx {matcher expression} not-char-ci expression +These expressions match a given character. In each case, the +@var{expression} operand is a Scheme expression that must evaluate to +a character at run time. The @samp{-ci} expressions do +case-insensitive matching. The @samp{not-} expressions match any +character other than the given one. +@end deffn + +@deffn {matcher expression} string expression +@deffnx {matcher expression} string-ci expression +These expressions match a given string. The @var{expression} operand +is a Scheme expression that must evaluate to a string at run time. +The @code{string-ci} expression does case-insensitive matching. +@end deffn + +@deffn {matcher expression} char-set expression +These expressions match a single character that is a member of a given +character set. The @var{expression} operand is a Scheme expression +that must evaluate to a character set at run time. +@end deffn + +@deffn {matcher expression} alphabet expression +These expressions match a single character that is a member of a given +Unicode alphabet (@pxref{Unicode}). The @var{expression} operand is a +Scheme expression that must evaluate to an alphabet at run time. +@end deffn + +@deffn {matcher expression} end-of-input +The @code{end-of-input} expression is successful only when there are +no more characters available to be matched. +@end deffn + +@deffn {matcher expression} discard-matched +The @code{discard-matched} expression always successfully matches the +null string. However, it isn't meant to be used as a matching +expression; it is used for its effect. @code{discard-matched} causes +all of the buffered text prior to this point to be discarded (i.e.@: +it calls @code{discard-parser-buffer-head!} on the parser buffer). + +Note that @code{discard-matched} may not be used in certain places in +a matcher expression. The reason for this is that it deliberately +discards information needed for backtracking, so it may not be used in +a place where subsequent backtracking will need to back over it. As a +rule of thumb, use @code{discard-matched} only in the last operand of +a @code{seq} or @code{alt} expression (including any @code{seq} or +@code{alt} expressions in which it is indirectly contained). +@end deffn + +In addition to the above primitive expressions, there are two +convenient abbreviations. A character literal (e.g.@: @samp{#\A}) is +a legal primitive expression, and is equivalent to a @code{char} +expression with that literal as its operand (e.g.@: @samp{(char +#\A)}). Likewise, a string literal is equivalent to a @code{string} +expression (e.g.@: @samp{(string "abc")}). + +Next there are several combinator expressions. These closely +correspond to similar combinators in regular expressions. Parameters +named @var{mexp} are arbitrary expressions in the matcher language. + +@deffn {matcher expression} seq mexp @dots{} +This matches each @var{mexp} operand in sequence. For example, + +@example +@group +(seq (char-set char-set:alphabetic) + (char-set char-set:numeric)) +@end group +@end example + +@noindent +matches an alphabetic character followed by a numeric character, such +as @samp{H4}. + +Note that if there are no @var{mexp} operands, the @code{seq} +expression successfully matches the null string. +@end deffn + +@deffn {matcher expression} alt mexp @dots{} +This attempts to match each @var{mexp} operand in order from left to +right. The first one that successfully matches becomes the match for +the entire @code{alt} expression. + +The @code{alt} expression participates in backtracking. If one of the +@var{mexp} operands matches, but the overall match in which this +expression is embedded fails, the backtracking mechanism will cause +the @code{alt} expression to try the remaining @var{mexp} operands. +For example, if the expression + +@example +(seq (alt "ab" "a") "b") +@end example + +@noindent +is matched against the text @samp{abc}, the @code{alt} expression will +initially match its first operand. But it will then fail to match the +second operand of the @code{seq} expression. This will cause the +@code{alt} to be restarted, at which time it will match @samp{a}, and +the overall match will succeed. + +Note that if there are no @var{mexp} operands, the @code{alt} match +will always fail. +@end deffn + +@deffn {matcher expression} * mexp +This matches zero or more occurrences of the @var{mexp} operand. +(Consequently this match always succeeds.) + +The @code{*} expression participates in backtracking; if it matches +@var{N} occurrences of @var{mexp}, but the overall match fails, it +will backtrack to @var{N-1} occurrences and continue. If the overall +match continues to fail, the @code{*} expression will continue to +backtrack until there are no occurrences left. +@end deffn + +@deffn {matcher expression} + mexp +This matches one or more occurrences of the @var{mexp} operand. It is +equivalent to + +@example +(seq @var{mexp} (* @var{mexp})) +@end example +@end deffn + +@deffn {matcher expression} ? mexp +This matches zero or one occurrences of the @var{mexp} operand. It is +equivalent to + +@example +(alt @var{mexp} (seq)) +@end example +@end deffn + +@deffn {matcher expression} sexp expression +The @code{sexp} expression allows arbitrary Scheme code to be embedded +inside a matcher. The @var{expression} operand must evaluate to a +matcher procedure at run time; the procedure is called to match the +parser buffer. For example, + +@example +@group +(*matcher + (seq "a" + (sexp parse-foo) + "b")) +@end group +@end example + +@noindent +expands to + +@example +@group +(lambda (#[b1]) + (let ((#[p1] (get-parser-buffer-pointer #[b1]))) + (and (match-parser-buffer-char #[b1] #\a) + (if (parse-foo #[b1]) + (if (match-parser-buffer-char #[b1] #\b) + #t + (begin + (set-parser-buffer-pointer! #[b1] #[p1]) + #f)) + (begin + (set-parser-buffer-pointer! #[b1] #[p1]) + #f))))) +@end group +@end example + +The case in which @var{expression} is a symbol is so common that it +has an abbreviation: @samp{(sexp @var{symbol})} may be abbreviated as +just @var{symbol}. +@end deffn + +@deffn {matcher expression} with-pointer identifier mexp +The @code{with-pointer} expression fetches the parser buffer's +internal pointer (using @code{get-parser-buffer-pointer}), binds it to +@var{identifier}, and then matches the pattern specified by +@var{mexp}. @var{Identifier} must be a symbol. + +This is meant to be used on conjunction with @code{sexp}, as a way to +capture a pointer to a part of the input stream that is outside the +@code{sexp} expression. An example of the use of @code{with-pointer} +appears above (@pxref{with-pointer example}). +@end deffn + +@node *Parser, Parser-language Macros, *Matcher, Parser Language +@subsection *Parser + +@deffn {special form} *parser pexp +@end deffn + +@deffn {parser expression} match pexp +@deffnx {parser expression} noise pexp +@end deffn + +@deffn {parser expression} alt pexp @dots{} +@end deffn + +@deffn {parser expression} seq pexp @dots{} +@end deffn + +@deffn {parser expression} * pexp +@end deffn + +@deffn {parser expression} + pexp +@end deffn + +@deffn {parser expression} ? pexp +@end deffn + +@deffn {parser expression} transform procedure pexp +@deffnx {parser expression} encapsulate procedure pexp +@deffnx {parser expression} map procedure pexp +@end deffn + +@deffn {parser expression} values expression @dots{} +@end deffn + +@deffn {parser expression} sexp expression +@end deffn + +@deffn {parser expression} with-pointer identifier pexp +@end deffn + +@deffn {parser expression} discard-matched +@end deffn + +@node Parser-language Macros, , *Parser, Parser Language +@subsection Parser-language Macros + +@deffn {special form} define-*matcher-macro formals expression +@deffnx {special form} define-*parser-macro formals expression +@end deffn + +@deffn procedure define-*matcher-expander identifier expander +@deffnx procedure define-*parser-expander identifier expander +@end deffn + +@deffn procedure make-parser-macros parent-macros +@end deffn + +@deffn procedure parser-macros? object +@end deffn + +@deffn procedure current-parser-macros +@end deffn + +@deffn procedure global-parser-macros +@end deffn + +@deffn procedure set-current-parser-macros! macros +@end deffn + +@deffn procedure with-current-parser-macros macros thunk +@end deffn + @node Operating-System Interface, Error System, Input/Output, Top @chapter Operating-System Interface @cindex Operating-System Interface @@ -14208,7 +14684,7 @@ Pathname objects are usually created by parsing filenames (character strings) into component parts. MIT Scheme provides operations that convert filenames into pathnames and vice versa. -@deffn {procedure+} ->pathname object +@deffn procedure ->pathname object @cindex construction, of pathname Returns a pathname that is the equivalent of @var{object}. @var{Object} must be a pathname or a string. If @var{object} is a pathname, it is @@ -14225,7 +14701,7 @@ to @code{(parse-namestring @var{object} #f #f)}. @end deffn -@deffn {procedure+} parse-namestring thing [host [defaults]] +@deffn procedure parse-namestring thing [host [defaults]] @cindex construction, of pathname This turns @var{thing} into a pathname. @var{Thing} must be a pathname or a string. @@ -14247,7 +14723,7 @@ used instead; if @var{defaults} is not given, the host component from @code{*default-pathname-defaults*} is used. @end deffn -@deffn {procedure+} ->namestring pathname +@deffn procedure ->namestring pathname @cindex conversion, pathname to string @code{->namestring} returns a newly allocated string that is the filename corresponding to @var{pathname}. @@ -14260,7 +14736,7 @@ filename corresponding to @var{pathname}. @end deffn -@deffn {procedure+} pathname-simplify pathname +@deffn procedure pathname-simplify pathname @cindex simplification, of pathname Returns a pathname that locates the same file or directory as @var{pathname}, but is in some sense simpler. Note that @@ -14452,7 +14928,7 @@ is not used and should be specified as @code{#f}. @cindex installed, as pathname component @end table -@deffn {procedure+} make-pathname host device directory name type version +@deffn procedure make-pathname host device directory name type version @cindex construction, of pathname Returns a pathname object whose components are the respective arguments. Each argument must satisfy the restrictions for the corresponding @@ -14471,12 +14947,12 @@ component, which were outlined above. @end example @end deffn -@deffn {procedure+} pathname-host pathname -@deffnx {procedure+} pathname-device pathname -@deffnx {procedure+} pathname-directory pathname -@deffnx {procedure+} pathname-name pathname -@deffnx {procedure+} pathname-type pathname -@deffnx {procedure+} pathname-version pathname +@deffn procedure pathname-host pathname +@deffnx procedure pathname-device pathname +@deffnx procedure pathname-directory pathname +@deffnx procedure pathname-name pathname +@deffnx procedure pathname-type pathname +@deffnx procedure pathname-version pathname Returns a particular component of @var{pathname}. @example @@ -14492,11 +14968,11 @@ Returns a particular component of @var{pathname}. @end example @end deffn -@deffn {procedure+} pathname-new-device pathname device -@deffnx {procedure+} pathname-new-directory pathname directory -@deffnx {procedure+} pathname-new-name pathname name -@deffnx {procedure+} pathname-new-type pathname type -@deffnx {procedure+} pathname-new-version pathname version +@deffn procedure pathname-new-device pathname device +@deffnx procedure pathname-new-directory pathname directory +@deffnx procedure pathname-new-name pathname name +@deffnx procedure pathname-new-type pathname type +@deffnx procedure pathname-new-version pathname version Returns a new copy of @var{pathname} with the respective component replaced by the second argument. @var{Pathname} is unchanged. Portable programs should not explicitly replace a component with @@ -14518,11 +14994,11 @@ p @end example @end deffn -@deffn {procedure+} pathname-default-device pathname device -@deffnx {procedure+} pathname-default-directory pathname directory -@deffnx {procedure+} pathname-default-name pathname name -@deffnx {procedure+} pathname-default-type pathname type -@deffnx {procedure+} pathname-default-version pathname version +@deffn procedure pathname-default-device pathname device +@deffnx procedure pathname-default-directory pathname directory +@deffnx procedure pathname-default-name pathname name +@deffnx procedure pathname-default-type pathname type +@deffnx procedure pathname-default-version pathname version These operations are similar to the @code{pathname-new-@var{component}} operations, except that they only change the specified @var{component} if it has the value @code{#f} in @var{pathname}. @@ -14531,13 +15007,13 @@ if it has the value @code{#f} in @var{pathname}. @node Operations on Pathnames, Miscellaneous Pathnames, Components of Pathnames, Pathnames @subsection Operations on Pathnames -@deffn {procedure+} pathname? object +@deffn procedure pathname? object @cindex type predicate, for pathname Returns @code{#t} if @var{object} is a pathname; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} pathname=? pathname1 pathname2 +@deffn procedure pathname=? pathname1 pathname2 @cindex equivalence predicate, for pathnames Returns @code{#t} if @var{pathname1} is equivalent to @var{pathname2}; otherwise returns @code{#f}. @@ -14550,7 +15026,7 @@ and pathnames that specify no file at all (e.g.@: name and directory components unspecified) may be equivalent. @end deffn -@deffn {procedure+} pathname-absolute? pathname +@deffn procedure pathname-absolute? pathname Returns @code{#t} if @var{pathname} is an absolute rather than relative pathname object; otherwise returns @code{#f}. Specifically, this procedure returns @code{#t} when the directory component of @@ -14560,7 +15036,7 @@ or relative, so if this procedure returns @code{#f}, the argument is a relative pathname. @end deffn -@deffn {procedure+} directory-pathname? pathname +@deffn procedure directory-pathname? pathname Returns @code{#t} if @var{pathname} has only directory components and no file components. This is roughly equivalent to @@ -14575,12 +15051,12 @@ file components. This is roughly equivalent to except that it is faster. @end deffn -@deffn {procedure+} pathname-wild? pathname +@deffn procedure pathname-wild? pathname Returns @code{#t} if @var{pathname} contains any wildcard components; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} merge-pathnames pathname [defaults [default-version]] +@deffn procedure merge-pathnames pathname [defaults [default-version]] @cindex merging, of pathnames @cindex defaulting, of pathname Returns a pathname whose components are obtained by combining those of @@ -14631,7 +15107,7 @@ nothing, or just a directory, the name, type and version will come over from @var{defaults} together. @end deffn -@defvr {variable+} *default-pathname-defaults* +@defvr variable *default-pathname-defaults* @cindex defaulting, of pathname This is the default pathname-defaults pathname; if any pathname primitive that needs a set of defaults is not given one, it uses this @@ -14640,7 +15116,7 @@ value, computed by merging the new working directory with the variable's old value. @end defvr -@deffn {procedure+} pathname-default pathname device directory name type version +@deffn procedure pathname-default pathname device directory name type version This procedure defaults all of the components of @var{pathname} simultaneously. It could have been defined by: @@ -14658,10 +15134,10 @@ simultaneously. It could have been defined by: @end example @end deffn -@deffn {procedure+} file-namestring pathname -@deffnx {procedure+} directory-namestring pathname -@deffnx {procedure+} host-namestring pathname -@deffnx {procedure+} enough-namestring pathname [defaults] +@deffn procedure file-namestring pathname +@deffnx procedure directory-namestring pathname +@deffnx procedure host-namestring pathname +@deffnx procedure enough-namestring pathname [defaults] @cindex conversion, pathname to string These procedures return a string corresponding to a subset of the @var{pathname} information. @code{file-namestring} returns a string @@ -14688,9 +15164,9 @@ the file named by @var{pathname} when considered relative to the @end example @end deffn -@deffn {procedure+} file-pathname pathname -@deffnx {procedure+} directory-pathname pathname -@deffnx {procedure+} enough-pathname pathname [defaults] +@deffn procedure file-pathname pathname +@deffnx procedure directory-pathname pathname +@deffnx procedure enough-pathname pathname [defaults] @cindex selection, components of pathname These procedures return a pathname corresponding to a subset of the @var{pathname} information. @@ -14709,7 +15185,7 @@ These procedures are similar to @code{file-namestring}, return pathnames instead of strings. @end deffn -@deffn {procedure+} directory-pathname-as-file pathname +@deffn procedure directory-pathname-as-file pathname @cindex file, converting pathname directory to Returns a pathname that is equivalent to @var{pathname}, but in which the directory component is represented as a file. @@ -14725,7 +15201,7 @@ This is the inverse operation to @code{pathname-as-directory}. @end example @end deffn -@deffn {procedure+} pathname-as-directory pathname +@deffn procedure pathname-as-directory pathname @cindex directory, converting pathname to Returns a pathname that is equivalent to @var{pathname}, but in which any file components have been converted to a directory component. If @@ -14751,24 +15227,24 @@ of directory components. This is the inverse operation to This section gives some standard operations on host objects, and some procedures that return some useful pathnames. -@defvr {variable+} local-host +@defvr variable local-host This variable has as its value the host object that describes the local host's file system. @end defvr -@deffn {procedure+} host? object +@deffn procedure host? object @cindex type predicate, for pathname host Returns @code{#t} if @var{object} is a pathname host; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} host=? host1 host2 +@deffn procedure host=? host1 host2 @cindex equivalence predicate, for pathname host Returns @code{#t} if @var{host1} and @var{host2} denote the same pathname host; otherwise returns @code{#f}. @end deffn -@deffn {procedure+} init-file-pathname [host] +@deffn procedure init-file-pathname [host] @cindex home directory, as pathname Returns a pathname for the user's initialization file on @var{host}. The @var{host} argument defaults to the value of @code{local-host}. If @@ -14780,7 +15256,7 @@ case, it is located in the user's home directory, which is computed by @code{user-homedir-pathname}. @end deffn -@deffn {procedure+} user-homedir-pathname [host] +@deffn procedure user-homedir-pathname [host] @cindex home directory, as pathname Returns a pathname for the user's ``home directory'' on @var{host}. The @var{host} argument defaults to the value of @code{local-host}. The @@ -14838,7 +15314,7 @@ directory. @end itemize @end deffn -@deffn {procedure+} system-library-pathname pathname +@deffn procedure system-library-pathname pathname @cindex library, system pathname Locates @var{pathname} in MIT Scheme's system library directory. An error of type @code{condition-type:file-operation-error} is signalled if @@ -14853,7 +15329,7 @@ error of type @code{condition-type:file-operation-error} is signalled if @end example @end deffn -@deffn {procedure+} system-library-directory-pathname pathname +@deffn procedure system-library-directory-pathname pathname @cindex library, system pathname Locates the pathname of an MIT Scheme system library directory. An error of type @code{condition-type:file-operation-error} is signalled if @@ -14886,8 +15362,8 @@ Scheme by calling the @code{pwd} procedure, and changed by calling the and inferior @sc{rep} loops initialize their working directory from the value in effect in their superior at the time they are created. -@deffn {procedure+} working-directory-pathname -@deffnx {procedure+} pwd +@deffn procedure working-directory-pathname +@deffnx procedure pwd Returns the current working directory as a pathname that has no name, type, or version components, just host, device, and directory components. @code{pwd} is an alias for @@ -14895,8 +15371,8 @@ components. @code{pwd} is an alias for programs and the short name for interactive use. @end deffn -@deffn {procedure+} set-working-directory-pathname! filename -@deffnx {procedure+} cd filename +@deffn procedure set-working-directory-pathname! filename +@deffnx procedure cd filename @findex ->pathname @findex pathname-as-directory Makes @var{filename} the current working directory and returns the new @@ -14938,7 +15414,7 @@ directory, before changing the working directory. @end example @end deffn -@deffn {procedure+} with-working-directory-pathname filename thunk +@deffn procedure with-working-directory-pathname filename thunk This procedure temporarily rebinds the current working directory to @var{filename}, invokes @var{thunk} (a procedure of no arguments), then restores the previous working directory and returns the value yielded by @@ -14962,9 +15438,9 @@ these procedures, it will be of type @code{condition-type:file-operation-error}. @findex condition-type:file-operation-error -@deffn {procedure+} file-exists? filename -@deffnx {procedure+} file-exists-direct? filename -@deffnx {procedure+} file-exists-indirect? filename +@deffn procedure file-exists? filename +@deffnx procedure file-exists-direct? filename +@deffnx procedure file-exists-indirect? filename @cindex existence, testing of file These procedures return @code{#t} if @var{filename} is an existing file or directory; otherwise they return @code{#f}. In operating systems @@ -14974,33 +15450,33 @@ that support symbolic links, if the file is a symbolic link, existence of the file pointed to by the link. @end deffn -@deffn {procedure+} copy-file source-filename target-filename +@deffn procedure copy-file source-filename target-filename @cindex copying, of file Makes a copy of the file named by @var{source-filename}. The copy is performed by creating a new file called @var{target-filename}, and filling it with the same data as @var{source-filename}. @end deffn -@deffn {procedure+} rename-file source-filename target-filename +@deffn procedure rename-file source-filename target-filename @cindex renaming, of file @cindex name, of file Changes the name of @var{source-filename} to be @var{target-filename}. In the unix implementation, this will not rename across file systems. @end deffn -@deffn {procedure+} delete-file filename +@deffn procedure delete-file filename @cindex deletion, of file Deletes the file named @var{filename}. @end deffn -@deffn {procedure+} delete-file-no-errors filename +@deffn procedure delete-file-no-errors filename Like @code{delete-file}, but returns a boolean value indicating whether an error occurred during the deletion. If no errors occurred, @code{#t} is returned. If an error of type @code{condition-type:file-error} or @code{condition-type:port-error} is signalled, @code{#f} is returned. @end deffn -@deffn {procedure+} hard-link-file source-filename target-filename +@deffn procedure hard-link-file source-filename target-filename @cindex linking (hard), of file @cindex hard linking, of file Makes a hard link from @var{source-filename} to @var{target-filename}. @@ -15012,7 +15488,7 @@ work only when @var{source-filename} and @var{target-filename} refer to names in the same file system. @end deffn -@deffn {procedure+} soft-link-file source-filename target-filename +@deffn procedure soft-link-file source-filename target-filename @cindex linking (soft), of file @cindex soft linking, of file @cindex symbolic linking, of file @@ -15028,18 +15504,18 @@ link's location at that time. This currently works only on unix systems. @end deffn -@deffn {procedure+} make-directory filename +@deffn procedure make-directory filename Creates a new directory named @var{filename}. Signals an error if @var{filename} already exists, or if the directory cannot be created. @end deffn -@deffn {procedure+} delete-directory filename +@deffn procedure delete-directory filename Deletes the directory named @var{filename}. Signals an error if the directory does not exist, is not a directory, or contains any files or subdirectories. @end deffn -@deffn {procedure+} ->truename filename +@deffn procedure ->truename filename @cindex truename, of input file This procedure attempts to discover and return the ``true name'' of the file associated with @var{filename} within the file system. An error of @@ -15048,7 +15524,7 @@ appropriate file cannot be located within the file system. @findex condition-type:file-operation-error @end deffn -@deffn {procedure+} call-with-temporary-file-pathname procedure +@deffn procedure call-with-temporary-file-pathname procedure Calls @code{temporary-file-pathname} to create a temporary file, then calls @var{procedure} with one argument, the pathname referring to that file. When @var{procedure} returns, if the temporary file still exists, @@ -15057,7 +15533,7 @@ If @var{procedure} escapes from its continuation, and the file still exists, it is deleted. @end deffn -@deffn {procedure+} temporary-file-pathname [directory] +@deffn procedure temporary-file-pathname [directory] Creates a new empty temporary file and returns a pathname referring to it. The temporary file is created with Scheme's default permissions, so barring unusual circumstances it can be opened for input and/or output @@ -15071,7 +15547,7 @@ file will be stored in the directory returned by @code{temporary-directory-pathname}. @end deffn -@deffn {procedure+} temporary-directory-pathname +@deffn procedure temporary-directory-pathname Returns the pathname of an existing directory that can be used to store temporary files. These directory names are tried, in order, until a writeable directory is found: @@ -15095,7 +15571,7 @@ Under OS/2 or Windows, the current directory, as specified by @end itemize @end deffn -@deffn {procedure+} file-directory? filename +@deffn procedure file-directory? filename @cindex directory, predicate for Returns @code{#t} if the file named @var{filename} exists and is a directory. Otherwise returns @code{#f}. In operating systems that @@ -15109,7 +15585,7 @@ This is equivalent to @end example @end deffn -@deffn {procedure+} file-regular? filename +@deffn procedure file-regular? filename @cindex file (regular), predicate for @cindex regular file, predicate for Returns @code{#t} if the file named @var{filename} exists and is a @@ -15125,7 +15601,7 @@ This is equivalent to @end example @end deffn -@deffn {procedure+} file-symbolic-link? filename +@deffn procedure file-symbolic-link? filename @cindex symbolic link, predicate for In operating systems that support symbolic links, if the file named @var{filename} exists and is a symbolic link, this procedure returns the @@ -15137,8 +15613,8 @@ the operating system does not support symbolic links, this procedure returns @code{#f}. @end deffn -@deffn {procedure+} file-type-direct filename -@deffnx {procedure+} file-type-indirect filename +@deffn procedure file-type-direct filename +@deffnx procedure file-type-indirect filename @cindex file type, procedure for If the file named @var{filename} exists, @code{file-type-direct} returns a symbol specifying what type of file it is. For example, if @@ -15168,17 +15644,17 @@ win32-named-pipe @end example @end deffn -@deffn {procedure+} file-readable? filename +@deffn procedure file-readable? filename Returns @code{#t} if @var{filename} names a file that can be opened for input; i.e.@: a @dfn{readable} file. Otherwise returns @code{#f}. @end deffn -@deffn {procedure+} file-writeable? filename +@deffn procedure file-writeable? filename Returns @code{#t} if @var{filename} names a file that can be opened for output; i.e.@: a @dfn{writeable} file. Otherwise returns @code{#f}. @end deffn -@deffn {procedure+} file-executable? filename +@deffn procedure file-executable? filename Returns @code{#t} if @var{filename} names a file that can be executed. Otherwise returns @code{#f}. Under unix, an executable file is identified by its mode bits. Under OS/2, an executable file has @@ -15187,7 +15663,7 @@ one of the file extensions @file{.exe}, @file{.com}, @file{.cmd}, or extensions @file{.exe}, @file{.com}, or @file{.bat}. @end deffn -@deffn {procedure+} file-access filename mode +@deffn procedure file-access filename mode @var{Mode} must be an exact integer between @code{0} and @code{7} inclusive; it is a bitwise-encoded predicate selector with @code{1} meaning ``executable'', @code{2} meaning ``writeable'', and @code{4} @@ -15199,14 +15675,14 @@ or if it does not satisfy the selected predicates, @code{#f} is returned. @end deffn -@deffn {procedure+} file-eq? filename1 filename2 +@deffn procedure file-eq? filename1 filename2 Determines whether @var{filename1} and @var{filename2} refer to the same file. Under unix, this is done by comparing the inodes and devices of the two files. Under OS/2 and Windows, this is done by comparing the filename strings. @end deffn -@deffn {procedure+} file-modes filename +@deffn procedure file-modes filename If @var{filename} names an existing file, @code{file-modes} returns an exact non-negative integer encoding the file's permissions. The encoding of this integer is operating-system dependent. Under unix, it @@ -15216,18 +15692,18 @@ attribute bits, which are described below. If @var{filename} does not name an existing file, @code{#f} is returned. @end deffn -@deffn {procedure+} set-file-modes! filename modes +@deffn procedure set-file-modes! filename modes @var{Filename} must name an existing file. @var{Modes} must be an exact non-negative integer that could have been returned by a call to @code{file-modes}. @code{set-file-modes!} modifies the file's permissions to be those encoded by @var{modes}. @end deffn -@defvr {variable+} os2-file-mode/read-only -@defvrx {variable+} os2-file-mode/hidden -@defvrx {variable+} os2-file-mode/system -@defvrx {variable+} os2-file-mode/directory -@defvrx {variable+} os2-file-mode/archived +@defvr variable os2-file-mode/read-only +@defvrx variable os2-file-mode/hidden +@defvrx variable os2-file-mode/system +@defvrx variable os2-file-mode/directory +@defvrx variable os2-file-mode/archived The values of these variables are the ``mode bits'' that comprise the value returned by @code{file-modes} under OS/2. These bits are small integers that are combined by adding to form a complete set of modes. @@ -15235,14 +15711,14 @@ The integer zero represents a set of modes in which none of these bits are set. @end defvr -@defvr {variable+} nt-file-mode/read-only -@defvrx {variable+} nt-file-mode/hidden -@defvrx {variable+} nt-file-mode/system -@defvrx {variable+} nt-file-mode/directory -@defvrx {variable+} nt-file-mode/archive -@defvrx {variable+} nt-file-mode/normal -@defvrx {variable+} nt-file-mode/temporary -@defvrx {variable+} nt-file-mode/compressed +@defvr variable nt-file-mode/read-only +@defvrx variable nt-file-mode/hidden +@defvrx variable nt-file-mode/system +@defvrx variable nt-file-mode/directory +@defvrx variable nt-file-mode/archive +@defvrx variable nt-file-mode/normal +@defvrx variable nt-file-mode/temporary +@defvrx variable nt-file-mode/compressed The values of these variables are the ``mode bits'' that comprise the value returned by @code{file-modes} under Windows. These bits are small integers that are combined by adding to form a complete set of modes. @@ -15250,7 +15726,7 @@ The integer zero represents a set of modes in which none of these bits are set. @end defvr -@deffn {procedure+} file-modification-time filename +@deffn procedure file-modification-time filename @cindex modification time, of file Returns the modification time of @var{filename} as an exact non-negative integer. The result may be compared to other file times using ordinary @@ -15269,7 +15745,7 @@ the link itself; in all other respects it is identical to @code{file-modification-time}. @end deffn -@deffn {procedure+} file-access-time filename +@deffn procedure file-access-time filename @cindex access time, of file Returns the access time of @var{filename} as an exact non-negative integer. The result may be compared to other file times using ordinary @@ -15287,7 +15763,7 @@ itself; in all other respects it is identical to is a synonym of @code{file-access-time}. @end deffn -@deffn {procedure+} set-file-times! filename access-time modification-time +@deffn procedure set-file-times! filename access-time modification-time @var{Filename} must name an existing file, while @var{access-time} and @var{modification-time} must be valid file times that might have been returned by @code{file-access-time} and @code{file-modification-time}, @@ -15299,13 +15775,13 @@ in this case the corresponding time is not changed. @code{set-file-times!} returns an unspecified value. @end deffn -@deffn {procedure+} current-file-time +@deffn procedure current-file-time Returns the current time as an exact non-negative integer, in the same format used by the above file-time procedures. This number can be compared to other file times using ordinary arithmetic operations. @end deffn -@deffn {procedure+} file-touch filename +@deffn procedure file-touch filename @dfn{Touches} the file named @var{filename}. If the file already exists, its modification time is set to the current file time and @code{#f} is returned. Otherwise, the file is created and @code{#t} is @@ -15313,12 +15789,12 @@ returned. This is an atomic test-and-set operation, so it is useful as a synchronization mechanism. @end deffn -@deffn {procedure+} file-length filename +@deffn procedure file-length filename Returns the length, in bytes, of the file named @var{filename} as an exact non-negative integer. @end deffn -@deffn {procedure+} file-attributes filename +@deffn procedure file-attributes filename @cindex attribute, of file This procedure determines if the file named @var{filename} exists, and returns information about it if so; if the file does not exist, it @@ -15339,57 +15815,57 @@ The information returned by @code{file-attributes} is decoded by accessor procedures. The following accessors are defined in all operating systems: -@deffn {procedure+} file-attributes/type attributes +@deffn procedure file-attributes/type attributes The file type: @code{#t} if the file is a directory, a character string (the name linked to) if a symbolic link, or @code{#f} for all other types of file. @end deffn -@deffn {procedure+} file-attributes/access-time attributes +@deffn procedure file-attributes/access-time attributes The last access time of the file, an exact non-negative integer. @end deffn -@deffn {procedure+} file-attributes/modification-time attributes +@deffn procedure file-attributes/modification-time attributes The last modification time of the file, an exact non-negative integer. @end deffn -@deffn {procedure+} file-attributes/change-time attributes +@deffn procedure file-attributes/change-time attributes The last change time of the file, an exact non-negative integer. @end deffn -@deffn {procedure+} file-attributes/length attributes +@deffn procedure file-attributes/length attributes The length of the file in bytes. @end deffn -@deffn {procedure+} file-attributes/mode-string attributes +@deffn procedure file-attributes/mode-string attributes The mode string of the file, a newly allocated string showing the file's mode bits. Under unix, this string is in unix format. Under OS/2 and Windows, this string shows the standard ``DOS'' attributes in their usual format. @end deffn -@deffn {procedure+} file-attributes/n-links attributes +@deffn procedure file-attributes/n-links attributes The number of links to the file, an exact positive integer. Under Windows and OS/2, this is always @code{1}. @end deffn The following additional accessors are defined under unix: -@deffn {procedure+} file-attributes/uid attributes +@deffn procedure file-attributes/uid attributes The user id of the file's owner, an exact non-negative integer. @end deffn -@deffn {procedure+} file-attributes/gid attributes +@deffn procedure file-attributes/gid attributes The group id of the file's group, an exact non-negative integer. @end deffn -@deffn {procedure+} file-attributes/inode-number attributes +@deffn procedure file-attributes/inode-number attributes The inode number of the file, an exact non-negative integer. @end deffn The following additional accessor is defined under OS/2 and Windows: -@deffn {procedure+} file-attributes/modes attributes +@deffn procedure file-attributes/modes attributes The attribute bits of the file. This is an exact non-negative integer containing the file's attribute bits, exactly as specified by the operating system's API. @@ -15397,7 +15873,7 @@ operating system's API. The following additional accessor is defined under OS/2: -@deffn {procedure+} file-attributes/allocated-length attributes +@deffn procedure file-attributes/allocated-length attributes The allocated length of the file, which can be larger than the length of the file due to fixed-length allocation units. @end deffn @@ -15406,7 +15882,7 @@ the file due to fixed-length allocation units. @section Directory Reader @cindex directory, reading -@deffn {procedure+} directory-read directory [sort?] +@deffn procedure directory-read directory [sort?] @var{Directory} must be an object that can be converted into a pathname by@* @code{->pathname}. The directory specified by @var{directory} is read, and the contents of the directory is returned as a newly allocated @@ -15479,7 +15955,7 @@ respectively required to be of the corresponding format. @node Universal Time, Decoded Time, Date and Time, Date and Time @subsection Universal Time -@deffn {procedure+} get-universal-time +@deffn procedure get-universal-time Return the current time in universal format. @example @@ -15487,7 +15963,7 @@ Return the current time in universal format. @end example @end deffn -@defvr {variable+} epoch +@defvr variable epoch @code{epoch} is the representation of midnight January 1, 1970 UTC in universal-time format. @@ -15507,7 +15983,7 @@ months between @code{1} and @code{12}; years are represented in ``four-digit'' form, in which 1999 is represented as @code{1999} --- @emph{not} @code{99}. -@deffn {procedure+} local-decoded-time +@deffn procedure local-decoded-time Return the current time in decoded format. The decoded time is represented in the local time zone. @@ -15528,7 +16004,7 @@ represented in the local time zone. @end example @end deffn -@deffn {procedure+} global-decoded-time +@deffn procedure global-decoded-time Return the current time in decoded format. The decoded time is represented in UTC. @@ -15549,7 +16025,7 @@ represented in UTC. @end example @end deffn -@deffn {procedure+} make-decoded-time second minute hour day month year [zone] +@deffn procedure make-decoded-time second minute hour day month year [zone] Return a new decoded-time object representing the given time. The arguments must be valid components according to the above rules, and must form a valid date. @@ -15596,12 +16072,12 @@ this will signal an error. @end example @end deffn -@deffn {procedure+} decoded-time/second decoded-time -@deffnx {procedure+} decoded-time/minute decoded-time -@deffnx {procedure+} decoded-time/hour decoded-time -@deffnx {procedure+} decoded-time/day decoded-time -@deffnx {procedure+} decoded-time/month decoded-time -@deffnx {procedure+} decoded-time/year decoded-time +@deffn procedure decoded-time/second decoded-time +@deffnx procedure decoded-time/minute decoded-time +@deffnx procedure decoded-time/hour decoded-time +@deffnx procedure decoded-time/day decoded-time +@deffnx procedure decoded-time/month decoded-time +@deffnx procedure decoded-time/year decoded-time Return the corresponding component of @var{decoded-time}. @example @@ -15613,7 +16089,7 @@ Return the corresponding component of @var{decoded-time}. @end example @end deffn -@deffn {procedure+} decoded-time/day-of-week decoded-time +@deffn procedure decoded-time/day-of-week decoded-time Return the day of the week on which @var{decoded-time} falls, encoded as an exact integer between @code{0} (Monday) and @code{6} (Sunday), inclusive. @@ -15623,7 +16099,7 @@ inclusive. @end example @end deffn -@deffn {procedure+} decoded-time/daylight-savings-time? decoded-time +@deffn procedure decoded-time/daylight-savings-time? decoded-time Return @code{#t} if @var{decoded-time} is represented using daylight savings time. Otherwise return @code{#f}. @@ -15633,7 +16109,7 @@ savings time. Otherwise return @code{#f}. @end example @end deffn -@deffn {procedure+} decoded-time/zone decoded-time +@deffn procedure decoded-time/zone decoded-time Return the time zone in which @var{decoded-time} is represented. This is an exact rational number between @code{-24} and @code{+24} inclusive, that when multiplied by @code{3600} is an integer. The value is the @@ -15644,7 +16120,7 @@ number of hours west of UTC. @end example @end deffn -@deffn {procedure+} time-zone? object +@deffn procedure time-zone? object Returns @code{#t} if @var{object} is an exact number between @code{-24} and @code{+24} inclusive, that when multiplied by @code{3600} is an integer. @@ -15658,7 +16134,7 @@ integer. @end example @end deffn -@deffn {procedure+} month/max-days month +@deffn procedure month/max-days month Returns the maximum number of days possible in @var{month}. @var{Month} must be an exact integer between @code{1} and @code{12} inclusive. @@ -15732,8 +16208,8 @@ file-time format. The procedures described in this section convert times from one format to another. -@deffn {procedure+} universal-time->local-decoded-time universal-time -@deffnx {procedure+} universal-time->global-decoded-time universal-time +@deffn procedure universal-time->local-decoded-time universal-time +@deffnx procedure universal-time->global-decoded-time universal-time Converts an argument in universal-time format to decoded-time format. The result is in the local time zone or UTC, respectively. @@ -15769,7 +16245,7 @@ The result is in the local time zone or UTC, respectively. @end example @end deffn -@deffn {procedure+} universal-time->file-time universal-time +@deffn procedure universal-time->file-time universal-time Converts an argument in universal-time format to file-time format. @example @@ -15780,8 +16256,8 @@ Converts an argument in universal-time format to file-time format. @end example @end deffn -@deffn {procedure+} universal-time->local-time-string universal-time -@deffnx {procedure+} universal-time->global-time-string universal-time +@deffn procedure universal-time->local-time-string universal-time +@deffnx procedure universal-time->global-time-string universal-time Converts an argument in universal-time format to a time string. The result is in the local time zone or UTC, respectively. @@ -15795,7 +16271,7 @@ result is in the local time zone or UTC, respectively. @end example @end deffn -@deffn {procedure+} decoded-time->universal-time decoded-time +@deffn procedure decoded-time->universal-time decoded-time Converts an argument in decoded-time format to universal-time format. @example @@ -15808,7 +16284,7 @@ Converts an argument in decoded-time format to universal-time format. @end example @end deffn -@deffn {procedure+} decoded-time->file-time decoded-time +@deffn procedure decoded-time->file-time decoded-time Converts an argument in decoded-time format to file-time format. @example @@ -15821,7 +16297,7 @@ Converts an argument in decoded-time format to file-time format. @end example @end deffn -@deffn {procedure+} decoded-time->string decoded-time +@deffn procedure decoded-time->string decoded-time Convert an argument in decoded-time format to a time string. @example @@ -15834,7 +16310,7 @@ Convert an argument in decoded-time format to a time string. @end example @end deffn -@deffn {procedure+} file-time->universal-time file-time +@deffn procedure file-time->universal-time file-time Converts an argument in universal-time format to file-time format. @example @@ -15845,8 +16321,8 @@ Converts an argument in universal-time format to file-time format. @end example @end deffn -@deffn {procedure+} file-time->local-decoded-time file-time -@deffnx {procedure+} file-time->global-decoded-time file-time +@deffn procedure file-time->local-decoded-time file-time +@deffnx procedure file-time->global-decoded-time file-time Converts an argument in file-time format to decoded-time format. The result is in the local time zone or UTC, respectively. @@ -15883,8 +16359,8 @@ result is in the local time zone or UTC, respectively. @end example @end deffn -@deffn {procedure+} file-time->local-time-string file-time -@deffnx {procedure+} file-time->global-time-string file-time +@deffn procedure file-time->local-time-string file-time +@deffnx procedure file-time->global-time-string file-time Converts an argument in file-time format to a time string. The result is in the local time zone or UTC, respectively. @@ -15898,7 +16374,7 @@ is in the local time zone or UTC, respectively. @end example @end deffn -@deffn {procedure+} string->universal-time time-string +@deffn procedure string->universal-time time-string Converts a time-string argument to universal-time format. @example @@ -15911,7 +16387,7 @@ Converts a time-string argument to universal-time format. @end example @end deffn -@deffn {procedure+} string->decoded-time time-string +@deffn procedure string->decoded-time time-string Converts a time-string argument to decoded-time format. @example @@ -15931,7 +16407,7 @@ Converts a time-string argument to decoded-time format. @end example @end deffn -@deffn {procedure+} string->file-time time-string +@deffn procedure string->file-time time-string Converts a time-string argument to file-time format. @example @@ -15950,8 +16426,8 @@ described above. The procedures in this section generate alternate external representations of time which are more verbose and may be more suitable for presentation to human readers. -@deffn {procedure+} decoded-time/date-string decoded-time -@deffnx {procedure+} decoded-time/time-string decoded-time +@deffn procedure decoded-time/date-string decoded-time +@deffnx procedure decoded-time/time-string decoded-time These procedures return strings containing external representations of the date and time, respectively, represented by @var{decoded-time}. The results are implicitly in local time. @@ -15966,8 +16442,8 @@ results are implicitly in local time. @end example @end deffn -@deffn {procedure+} day-of-week/long-string day-of-week -@deffnx {procedure+} day-of-week/short-string day-of-week +@deffn procedure day-of-week/long-string day-of-week +@deffnx procedure day-of-week/short-string day-of-week Returns a string representing the given @var{day-of-week}. The argument must be an exact non-negative integer between @code{0} and @code{6} inclusive. @code{day-of-week/long-string} returns a long string that @@ -15983,8 +16459,8 @@ returns a shortened string that abbreviates the day to three letters. @end example @end deffn -@deffn {procedure+} month/long-string month -@deffnx {procedure+} month/short-string month +@deffn procedure month/long-string month +@deffnx procedure month/short-string month Returns a string representing the given @var{month}. The argument must be an exact non-negative integer between @code{1} and @code{12} inclusive. @code{month/long-string} returns a long string that fully @@ -16000,7 +16476,7 @@ shortened string that abbreviates the month to three letters. @end example @end deffn -@deffn {procedure+} time-zone->string +@deffn procedure time-zone->string Returns a string corresponding to the given time zone. This string is the same string that is used to generate RFC-822 time strings. @@ -16028,7 +16504,7 @@ but can be converted to and from seconds by supplied procedures. A count in ticks is represented as an exact integer. At present each tick is one millisecond, but this may change in the future. -@deffn {procedure+} process-time-clock +@deffn procedure process-time-clock Returns the amount of process time, in ticks, that has elapsed since Scheme was started. Process time is measured by the operating system and is time during which the Scheme process is computing. It does not @@ -16040,7 +16516,7 @@ may include time used by subprocesses. @end example @end deffn -@deffn {procedure+} real-time-clock +@deffn procedure real-time-clock Returns the amount of real time, in ticks, that has elapsed since Scheme was started. Real time is the time measured by an ordinary clock. @@ -16049,7 +16525,7 @@ was started. Real time is the time measured by an ordinary clock. @end example @end deffn -@deffn {procedure+} internal-time/ticks->seconds ticks +@deffn procedure internal-time/ticks->seconds ticks Returns the number of seconds corresponding to @var{ticks}. The result is always a real number. @@ -16061,7 +16537,7 @@ is always a real number. @end example @end deffn -@deffn {procedure+} internal-time/seconds->ticks seconds +@deffn procedure internal-time/seconds->ticks seconds Returns the number of ticks corresponding to @var{seconds}. @var{Seconds} must be a real number. @@ -16073,7 +16549,7 @@ Returns the number of ticks corresponding to @var{seconds}. @end example @end deffn -@deffn {procedure+} system-clock +@deffn procedure system-clock Returns the amount of process time, in seconds, that has elapsed since Scheme was started. Roughly equivalent to: @@ -16089,7 +16565,7 @@ Example: @end example @end deffn -@deffn {procedure+} runtime +@deffn procedure runtime Returns the amount of process time, in seconds, that has elapsed since Scheme was started. However, it does not include time spent in garbage collection. @@ -16099,7 +16575,7 @@ collection. @end example @end deffn -@deffn {procedure+} with-timings thunk receiver +@deffn procedure with-timings thunk receiver Calls @var{thunk} with no arguments. After @var{thunk} returns, @var{receiver} is called with three arguments describing the time spent while computing @var{thunk}: the elapsed run time, the amount of time @@ -16124,7 +16600,7 @@ designed to have relatively low overhead. @end example @end deffn -@deffn {procedure+} measure-interval runtime? procedure +@deffn procedure measure-interval runtime? procedure Calls @var{procedure}, passing it the current process time, in seconds, as an argument. The result of this call must be another procedure. When @var{procedure} returns, the resulting procedure is @@ -16196,7 +16672,7 @@ and precise control of the command-line arguments passed to the program, but does not provide file globbing, I/O redirection, or other shell features. -@deffn {procedure+} run-shell-command command option @dots{} +@deffn procedure run-shell-command command option @dots{} Runs @var{command}, which must be a string. @var{Command} is passed to a command shell for interpretation; how the shell is chosen is detailed below. @@ -16210,7 +16686,7 @@ subprocess is killed or stopped, an error is signalled and the procedure does not return. @end deffn -@deffn {procedure+} run-synchronous-subprocess program arguments option @dots{} +@deffn procedure run-synchronous-subprocess program arguments option @dots{} Runs @var{program}, passing it the given command-line @var{arguments}. @var{Program} must be either the name of a program on the path, or else a pathname to a specific program. @var{Arguments} must be a list of @@ -16231,7 +16707,7 @@ does not return. If a subprocess spawned by one of the above procedures is killed or suspended, then one of the following errors will be signalled. -@deffn {condition type+} condition-type:subprocess-signalled subprocess reason +@deffn {condition type} condition-type:subprocess-signalled subprocess reason This condition type is a subtype of @code{condition-type:subprocess-abnormal-termination}. It is signalled when the subprocess is killed. @@ -16245,7 +16721,7 @@ that killed the process. On other systems it has a fixed value that conveys no useful information. @end deffn -@deffn {condition type+} condition-type:subprocess-stopped subprocess reason +@deffn {condition type} condition-type:subprocess-stopped subprocess reason This condition type is a subtype of @code{condition-type:subprocess-abnormal-termination}. It is signalled when the subprocess is stopped or suspended. @@ -16259,7 +16735,7 @@ that stopped the process. On other systems it has a fixed value that conveys no useful information. @end deffn -@deffn {condition type+} condition-type:subprocess-abnormal-termination subprocess reason +@deffn {condition type} condition-type:subprocess-abnormal-termination subprocess reason This condition type is a subtype of @code{condition-type:error}. This is an abstract type that is never signalled. It is provided so that condition handlers can be bound to it. @@ -16284,7 +16760,7 @@ options are passed as alternating keyword/value pairs, for example: The example shows a shell command being run with two options specified: @code{output} and @code{output-buffer-size}. -@deffn {subprocess option+} input port +@deffn {subprocess option} input port Specifies the standard input of the subprocess. @var{Port} may be an input port, in which case characters are read from @var{port} and fed to the subprocess until @var{port} reaches end-of-file. Alternatively, @@ -16302,7 +16778,7 @@ The default value of this option is @code{#f}. @end example @end deffn -@deffn {subprocess option+} input-line-translation line-ending +@deffn {subprocess option} input-line-translation line-ending Specifies how line-endings should be translated when writing characters to the subprocess. Ignored if the @code{input} option is @code{#f}. @var{Line-ending} must be either a string specifying the line ending, or @@ -16324,7 +16800,7 @@ The default value of this option is @code{default}. @end example @end deffn -@deffn {subprocess option+} input-buffer-size n +@deffn {subprocess option} input-buffer-size n Specifies the size of the input buffer for the standard input of the subprocess. (This is the buffer on the Scheme side, and has nothing to do with any buffering done on the subprocess side.) Ignored if the @@ -16344,7 +16820,7 @@ The default value of this option is @code{512}. @end example @end deffn -@deffn {subprocess option+} output port +@deffn {subprocess option} output port Specifies the standard output and standard error of the subprocess. @var{Port} may be an output port, in which case characters are read from the subprocess and fed to @var{port} until the subprocess finishes. @@ -16363,7 +16839,7 @@ The default value of this option is the value of @end example @end deffn -@deffn {subprocess option+} output-line-translation line-ending +@deffn {subprocess option} output-line-translation line-ending Specifies how line-endings should be translated when reading characters from the standard output of the subprocess. Ignored if the @code{output} option is @code{#f}. @var{Line-ending} must be either a @@ -16385,7 +16861,7 @@ The default value of this option is @code{default}. @end example @end deffn -@deffn {subprocess option+} output-buffer-size n +@deffn {subprocess option} output-buffer-size n Specifies the size of the output buffer for the standard output of the subprocess. (This is the buffer on the Scheme side, and has nothing to do with any buffering done on the subprocess side.) Ignored if the @@ -16405,7 +16881,7 @@ The default value of this option is @code{512}. @end example @end deffn -@deffn {subprocess option+} redisplay-hook thunk +@deffn {subprocess option} redisplay-hook thunk Specifies that @var{thunk} is to be run periodically when output from the subprocess is available. @var{Thunk} must be a procedure of no arguments, or @code{#f} indicating that no hook is supplied. This @@ -16425,7 +16901,7 @@ The default value of this option is @code{#f}. @end example @end deffn -@deffn {subprocess option+} environment environment +@deffn {subprocess option} environment environment Specifies the environment variables that are to be used for the subprocess. @var{Environment} must be either a vector of strings or @code{#f} indicating the default environment. If it is a vector of @@ -16452,7 +16928,7 @@ The default value of this option is @code{#f}. @end example @end deffn -@deffn {subprocess option+} working-directory pathname +@deffn {subprocess option} working-directory pathname Specifies the working directory in which the subprocess will run. The default value of this option is @code{(working-directory-pathname)}. @@ -16464,7 +16940,7 @@ The default value of this option is @code{(working-directory-pathname)}. @end example @end deffn -@deffn {subprocess option+} use-pty? boolean +@deffn {subprocess option} use-pty? boolean This option is meaningful only on unix systems; on other systems it is ignored. Specifies whether to communicate with the subprocess using @sc{pty} devices; if true, @sc{pty}s will be used, otherwise pipes will @@ -16479,7 +16955,7 @@ The default value of this option is @code{#f}. @end example @end deffn -@deffn {subprocess option+} shell-file-name pathname +@deffn {subprocess option} shell-file-name pathname Specifies the shell program to use for @code{run-shell-command}. The default value of this option is @code{(os/shell-file-name)}. This @@ -16547,7 +17023,7 @@ integer. Port strings are decoded by the operating system using a table; for example, on unix the table is in @file{/etc/services}. Usually you will use a port string rather than a number. -@deffn {procedure+} open-tcp-stream-socket host-name service [buffer-size [line-translation]] +@deffn procedure open-tcp-stream-socket host-name service [buffer-size [line-translation]] @code{open-tcp-stream-socket} opens a connection to the host specified by @var{host-name}. @var{Host-name} is looked up using the ordinary lookup rules for your computer. The connection is established to the @@ -16589,7 +17065,7 @@ the server socket; it continues to listen for additional client connections. You can have multiple client connections to the same server socket open simultaneously. -@deffn {procedure+} open-tcp-server-socket service [address] +@deffn procedure open-tcp-server-socket service [address] This procedure opens a server socket that listens for connections to @var{service}; the socket will continue to listen until you close it. The returned value is a server socket object. @@ -16607,7 +17083,7 @@ addresses for this machine. (This is equivalent to passing the result of calling @code{host-address-any}.) @end deffn -@deffn {procedure+} tcp-server-connection-accept server-socket block? peer-address +@deffn procedure tcp-server-connection-accept server-socket block? peer-address Checks to see if a client has connected to @var{server-socket}. If so, an @sc{i/o} port is returned. The returned port can be read and written using ordinary Scheme @sc{i/o} procedures such as @code{read-char} and @@ -16629,7 +17105,7 @@ that was opened by the call. To close @var{server-socket}, use @code{close-tcp-server-socket}. @end deffn -@deffn {procedure+} close-tcp-server-socket server-socket +@deffn procedure close-tcp-server-socket server-socket Closes the server socket @var{server-socket}. The operating system will cease listening for network connections to that service. Client connections to @var{server-socket} that have already been accepted will @@ -16642,8 +17118,8 @@ not be affected. This section contains assorted operating-system facilities that don't fit into other categories. -@defvr {variable+} microcode-id/operating-system -@defvrx {variable+} microcode-id/operating-system-name +@defvr variable microcode-id/operating-system +@defvrx variable microcode-id/operating-system-name @code{microcode-id/operating-system} is bound to a symbol that specifies the type of operating system that Scheme is running under. There are three possible values: @code{unix}, @code{os/2}, or @code{nt}. @@ -16653,7 +17129,7 @@ same name as @code{microcode-id/operating-system}; the latter is created by interning the former as a symbol. @end defvr -@defvr {variable+} microcode-id/operating-system-variant +@defvr variable microcode-id/operating-system-variant This variable is a string that identifies the particular variant of the operating system that Scheme is running under. Here are some of the possible values: @@ -16691,7 +17167,7 @@ name as a string, and an @acronym{IP} address as a byte vector of length (get-host-by-name "www.swiss") @result{} #("\022\027\000\020") @end example -@deffn {procedure+} get-host-by-name host-name +@deffn procedure get-host-by-name host-name Looks up the internet host name @var{host-name} using the @acronym{DNS}, returning a vector of @acronym{IP} addresses for the corresponding host, or @code{#f} if there is no such host. Usually the returned vector has @@ -16703,7 +17179,7 @@ vector might have more than one element. @end example @end deffn -@deffn {procedure+} get-host-by-address ip-address +@deffn procedure get-host-by-address ip-address Does a reverse @acronym{DNS} lookup on @var{ip-address}, returning the internet host name corresponding to that address, or @code{#f} if there is no such host. @@ -16713,7 +17189,7 @@ is no such host. @end example @end deffn -@deffn {procedure+} canonical-host-name host-name +@deffn procedure canonical-host-name host-name Finds the ``canonical'' internet host name for @var{host-name}. For example: @@ -16730,7 +17206,7 @@ to @var{host-name}. In the second example, @code{"www.swiss"} is an alias for another computer named @code{"swissnet"}. @end deffn -@deffn {procedure+} get-host-name +@deffn procedure get-host-name Returns the string that identifies the computer that MIT Scheme is running on. Usually this is an unqualified internet host name, i.e.@: the host name without the domain suffix: @@ -16740,7 +17216,7 @@ the host name without the domain suffix: @end example @end deffn -@deffn {procedure+} os/hostname +@deffn procedure os/hostname Returns the canonical internet host name of the computer that MIT Scheme is running on. So, in contrast to the example for @code{get-host-name}: @@ -16749,7 +17225,7 @@ is running on. So, in contrast to the example for @code{get-host-name}: @end example @end deffn -@deffn {procedure+} allocate-host-address +@deffn procedure allocate-host-address Allocates and returns an @acronym{IP} address object. This is just a string of a fixed length (current 4 bytes) into which an @acronym{IP} address may be stored. This procedure is used to generate an @@ -16761,7 +17237,7 @@ appropriate argument to be passed to @end example @end deffn -@deffn {procedure+} host-address-any +@deffn procedure host-address-any Return an @acronym{IP} address object that specifies ``any host''. This object is useful only when passed as the @var{address} argument to @code{open-tcp-server-socket}. @@ -16771,7 +17247,7 @@ object is useful only when passed as the @var{address} argument to @end example @end deffn -@deffn {procedure+} host-address-loopback +@deffn procedure host-address-loopback @cindex loopback interface Return an @acronym{IP} address object that specifies the local @dfn{loopback} network interface. The loopback interface is a software @@ -16951,7 +17427,7 @@ that it doesn't want to process that particular condition, it can signal the condition again. This is one way to allow other handlers to get a chance to see the condition. -@deffn {procedure+} error reason argument... +@deffn procedure error reason argument... @cindex REP loop @findex signal-condition @findex warn @@ -16982,7 +17458,7 @@ field containing the @var{reason} and the @var{irritants} field containing the @var{argument}s. @end deffn -@deffn {procedure+} warn reason argument... +@deffn procedure warn reason argument... @findex error @findex signal-condition @vindex condition-type:simple-warning @@ -17005,7 +17481,7 @@ prevent the generation of the warning message by calling unspecified. @end deffn -@deffn {procedure+} signal-condition condition +@deffn procedure signal-condition condition @cindex generalization, of condition types @cindex specialization, of condition types @findex break-on-signals @@ -17104,7 +17580,7 @@ Bad widget widget-32 within procedure invert-widget. Here are the operations supporting error messages: -@deffn {procedure+} format-error-message message irritants port +@deffn procedure format-error-message message irritants port @var{Message} is typically a string (although this is not required), @var{irritants} a list of irritant objects, and @var{port} an output port. Formats @var{message} and @var{irritants} to @var{port} in the @@ -17113,7 +17589,7 @@ breadth to which lists are printed are each limited to small numbers, to guarantee that the output from each irritant is not arbitrarily large. @end deffn -@deffn {procedure+} error-irritant/noise value +@deffn procedure error-irritant/noise value Creates and returns a noise object whose value is @var{value}. @end deffn @@ -17167,7 +17643,7 @@ is a condition that is a specialization of any of these types. The procedure @code{break-on-signals} establishes this set of condition types. -@deffn {procedure+} ignore-errors thunk +@deffn procedure ignore-errors thunk @findex error @vindex condition-type:error Executes @var{thunk} with a condition handler that intercepts the @@ -17184,7 +17660,7 @@ but conditions specialized from @code{condition-type:error} are trapped rather than propogated as they would be by default. @end deffn -@deffn {procedure+} bind-condition-handler condition-types handler thunk +@deffn procedure bind-condition-handler condition-types handler thunk @findex signal-condition Invokes @var{thunk} after adding @var{handler} as a condition handler for the conditions specified by @var{condition-types}. @@ -17197,7 +17673,7 @@ By special extension, if @var{condition-types} is the empty list then the @var{handler} is called for all conditions. @end deffn -@deffn {procedure+} bind-default-condition-handler condition-types handler +@deffn procedure bind-default-condition-handler condition-types handler @findex signal-condition Installs @var{handler} as a (permanent) condition handler for the conditions specified by @var{condition-types}. @var{Condition-types} @@ -17210,7 +17686,7 @@ By special extension, if @var{condition-types} is the empty list then the @var{handler} is called for all conditions. @end deffn -@deffn {procedure+} break-on-signals condition-types +@deffn procedure break-on-signals condition-types @findex signal-condition @cindex REP loop Arranges for @code{signal-condition} to create an interactive @sc{repl} @@ -17222,7 +17698,7 @@ signalled it is best to actually put a breakpoint on entry to @code{signal-condition}. @end deffn -@deffn {procedure+} standard-error-handler condition +@deffn procedure standard-error-handler condition @findex error @findex ignore-error @vindex standard-error-hook @@ -17235,7 +17711,7 @@ order to simulate the effect of calling @code{error}, code may call @code{standard-error-handler} if @code{signal-condition} returns. @end deffn -@defvr {variable+} standard-error-hook +@defvr variable standard-error-hook @findex standard-error-handler @cindex fluid binding @cindex dynamic binding @@ -17249,7 +17725,7 @@ changed to a procedure of one argument and will then be invoked (with @sc{repl}. It is passed one argument, the condition being signalled. @end defvr -@deffn {procedure+} standard-warning-handler condition +@deffn procedure standard-warning-handler condition @vindex standard-warning-hook @findex signal-condition @findex notification-output-port @@ -17270,7 +17746,7 @@ In order to simulate the effect of calling @code{warn}, code may call however. For that purpose an explicit restart must be provided.) @end deffn -@defvr {variable+} standard-warning-hook +@defvr variable standard-warning-hook @findex standard-warning-handler @cindex fluid binding @cindex dynamic binding @@ -17386,7 +17862,7 @@ equivalent to having specified the symbol @code{bound-restarts}. @node Establishing Restart Code, Invoking Standard Restart Code, Restarts, Restarts @subsection Establishing Restart Code -@deffn {procedure+} with-simple-restart name reporter thunk +@deffn procedure with-simple-restart name reporter thunk Invokes @var{thunk} in a dynamic environment created by adding a restart named @var{name} to the existing named restarts. @var{Reporter} may be used during the execution of @var{thunk} to produce a description of the @@ -17423,7 +17899,7 @@ value from the call to @code{with-simple-restart}. Otherwise @end group @end example -@deffn {procedure+} with-restart name reporter effector interactor thunk +@deffn procedure with-restart name reporter effector interactor thunk @findex invoke-restart Invokes @var{thunk} in a dynamic environment created by adding a restart named @var{name} to the existing named restarts. @var{Reporter} may be @@ -17491,7 +17967,7 @@ value. Each of these procedures accepts an optional argument @var{restarts}, which is described above in @ref{Restarts}. -@deffn {procedure+} abort [restarts] +@deffn procedure abort [restarts] @cindex REP loop Abort the computation, using the restart named @code{abort}. The corresponding effector takes no arguments and abandons the current line @@ -17502,14 +17978,14 @@ If there is no restart named @code{abort}, this procedure signals an error of type @code{condition-type:no-such-restart}. @end deffn -@deffn {procedure+} continue [restarts] +@deffn procedure continue [restarts] Continue the current computation, using the restart named @code{continue}. The corresponding effector takes no arguments and continues the computation beyond the point at which the condition was signalled. @end deffn -@deffn {procedure+} muffle-warning [restarts] +@deffn procedure muffle-warning [restarts] @findex warn Continue the current computation, using the restart named @code{muffle-warning}. The corresponding effector takes no arguments @@ -17523,7 +17999,7 @@ If there is no restart named @code{muffle-warning}, this procedure signals an error of type @code{condition-type:no-such-restart}. @end deffn -@deffn {procedure+} retry [restarts] +@deffn procedure retry [restarts] Retry the current computation, using the restart named @code{retry}. The corresponding effector takes no arguments and simply retries the same computation that triggered the condition. The condition may @@ -17534,7 +18010,7 @@ the missing file, since the computation is then likely to succeed if it is simply retried. @end deffn -@deffn {procedure+} store-value new-value [restarts] +@deffn procedure store-value new-value [restarts] Retry the current computation, using the restart named @code{store-value}, after first storing @var{new-value}. The corresponding effector takes one argument, @var{new-value}, and stores @@ -17546,7 +18022,7 @@ signals an ``unassigned variable'' error can be expected to supply a and continue the computation. @end deffn -@deffn {procedure+} use-value new-value [restarts] +@deffn procedure use-value new-value [restarts] @findex retry @findex store-value Retry the current computation, using the restart named @code{use-value}, @@ -17593,7 +18069,7 @@ invoked once the restart object has been located. In addition, there is a data abstraction that provides access to the information encapsulated in restart objects. -@deffn {procedure+} bound-restarts +@deffn procedure bound-restarts Returns a list of all currently active restart objects, most recently installed first. @code{bound-restarts} should be used with caution by condition-handling code, since it reveals all restarts that are active @@ -17603,7 +18079,7 @@ for inclusion in newly generated condition objects or for inspecting the current state of the system. @end deffn -@deffn {procedure+} find-restart name [restarts] +@deffn procedure find-restart name [restarts] Returns the first restart object named @var{name} in the list of @var{restarts} (permissible values for @var{restarts} are described above in @ref{Restarts}). When used in a condition handler, @@ -17615,7 +18091,7 @@ was created (usually the same as when it was signalled). If and these often include restarts added after the condition ocurred. @end deffn -@deffn {procedure+} invoke-restart restart argument... +@deffn procedure invoke-restart restart argument... @findex invoke-restart-interactively Calls the restart effector encapsulated in @var{restart}, passing the specified @var{argument}s to it. @code{invoke-restart} is intended for @@ -17629,7 +18105,7 @@ implemented by @var{restart}) @code{invoke-restart-interactively} should be used instead of @code{invoke-restart}. @end deffn -@deffn {procedure+} invoke-restart-interactively restart +@deffn procedure invoke-restart-interactively restart First calls the interactor encapsulated in @var{restart} to interactively gather the arguments needed for @var{restart}'s effector. It then calls the effector, passing these arguments to it. @@ -17648,18 +18124,18 @@ this behavior may change in the future. A restart object is very simple, since it encapsulates only a name, effector, interactor, and description. -@deffn {procedure+} restart? object +@deffn procedure restart? object Returns @code{#f} if and only if @var{object} is not a restart. @end deffn -@deffn {procedure+} restart/name restart +@deffn procedure restart/name restart @findex eq? Returns the name of @var{restart}. While the Scheme error system uses only symbols and the object @code{#f} for its predefined names, programs may use arbitrary objects (name equivalence is tested using @code{eq?}). @end deffn -@deffn {procedure+} restart/effector restart +@deffn procedure restart/effector restart @findex invoke-restart @findex invoke-restart-interactively Returns the effector encapsulated in @var{restart}. Normally this @@ -17668,7 +18144,7 @@ procedure is not used since @code{invoke-restart} and patterns. @end deffn -@deffn {procedure+} restart/interactor restart +@deffn procedure restart/interactor restart @findex invoke-restart-interactively Returns the interactor encapsulated in @var{restart}. This is either a procedure of no arguments or the object @code{#f}. Normally this @@ -17678,7 +18154,7 @@ a predicate to determine if @var{restart} is intended to be invoked interactively. @end deffn -@deffn {procedure+} write-restart-report restart port +@deffn procedure write-restart-report restart port Writes a description of @var{restart} to @var{port}. This works by either displaying (if it is a string) or calling (if it is a procedure) the @var{reporter} that was supplied when the restart was created. @@ -17736,7 +18212,7 @@ first-class; they may be created and never signalled, or they may be signalled more than once. Further notice that there are no procedures for modifying conditions; once created, a condition cannot be altered. -@deffn {procedure+} condition-constructor condition-type field-names +@deffn procedure condition-constructor condition-type field-names @findex condition/restarts @cindex bound-restarts @cindex restarts, bound @@ -17772,7 +18248,7 @@ irritants that caused the warning: @end example @end deffn -@deffn {procedure+} condition-accessor condition-type field-name +@deffn procedure condition-accessor condition-type field-name @cindex specialization, of condition types Returns a procedure that takes as input a condition object of type @var{condition-type} and extracts the contents of the specified @@ -17789,7 +18265,7 @@ using @code{condition-accessor} rather than using the (possibly more convenient, but slower) @code{access-condition} procedure. @end deffn -@deffn {procedure+} condition-predicate condition-type +@deffn procedure condition-predicate condition-type @cindex specialization, of condition types Returns a predicate procedure for testing whether an object is a condition of type @var{condition-type} or one of its specializations @@ -17797,7 +18273,7 @@ condition of type @var{condition-type} or one of its specializations @emph{not} a specialization of that type). @end deffn -@deffn {procedure+} condition-signaller condition-type field-names default-handler +@deffn procedure condition-signaller condition-type field-names default-handler Returns a signalling procedure with parameters @var{field-names}. When the signalling procedure is called it creates and signals a condition of type @var{condition-type}. If the condition isn't handled (i.e.@: if no @@ -17822,15 +18298,15 @@ procedure @code{standard-breakpoint-handler}. The condition data type is abstracted through a predicate @code{condition?} and a set of accessor procedures. -@deffn {procedure+} condition? object +@deffn procedure condition? object Returns @code{#f} if and only if @var{object} is not a condition. @end deffn -@deffn {procedure+} condition/type condition +@deffn procedure condition/type condition Returns the condition type of which @var{condition} is an instance. @end deffn -@deffn {procedure+} condition/error? condition +@deffn procedure condition/error? condition @vindex condition-type:error @cindex specialization, of condition types Returns @code{#t} if the @var{condition} is an instance of condition @@ -17838,18 +18314,18 @@ type @code{condition-type:error} or a specialization of it, @code{#f} otherwise. @end deffn -@deffn {procedure+} condition/restarts condition +@deffn procedure condition/restarts condition Returns the list of restarts specified when @var{condition} was created. @end deffn -@deffn {procedure+} condition/continuation condition +@deffn procedure condition/continuation condition Returns the continuation specified when @var{condition} was created. This is provided for inspecting the state of the system when the condition occurred, @emph{not} for continuing or restarting the computation. @end deffn -@deffn {procedure+} write-condition-report condition port +@deffn procedure write-condition-report condition port Writes a description of @var{condition} to @var{port}, using the reporter function from the condition type associated with @var{condition}. See also @code{condition/report-string}. @@ -17863,7 +18339,7 @@ more detailed abstraction of condition objects described above. While these procedures are sometimes easier to use, they are often less efficient. -@deffn {procedure+} make-condition condition-type continuation restarts field-plist +@deffn procedure make-condition condition-type continuation restarts field-plist @findex condition/restarts @cindex bound-restarts @cindex restarts, bound @@ -17879,7 +18355,7 @@ specified are set to @code{#f}. Once a condition object has been created there is no way to alter the values of these fields. @end deffn -@deffn {procedure+} access-condition condition field-name +@deffn procedure access-condition condition field-name @findex condition-accessor Returns the value stored in the field @var{field-name} within @var{condition}. @var{Field-name} must be one of the names returned by @@ -17890,7 +18366,7 @@ function if the same field is to be extracted from several instances of the same condition type. @end deffn -@deffn {procedure+} condition/report-string condition +@deffn procedure condition/report-string condition @findex write-condition-report Returns a string containing a report of the @var{condition}. This is generated by calling @code{write-condition-report} on @var{condition} @@ -17914,7 +18390,7 @@ relationship forms the taxonomic structure of the condition hierarchy The following procedures consititute the abstraction for condition types. -@deffn {procedure+} make-condition-type name generalization field-names reporter +@deffn procedure make-condition-type name generalization field-names reporter @cindex generalization, of condition types Creates and returns a (new) condition type that is a specialization of @var{generalization} (if it is a condition type) or is the root of a new @@ -17935,7 +18411,7 @@ is @code{#f}). The conventions used to form descriptions are spelled out in @ref{Error Messages}. @end deffn -@deffn {procedure+} condition-type/error? condition-type +@deffn procedure condition-type/error? condition-type @vindex condition-type:error @cindex specialization, of condition types Returns @code{#t} if the @var{condition-type} is @@ -17943,7 +18419,7 @@ Returns @code{#t} if the @var{condition-type} is otherwise. @end deffn -@deffn {procedure+} condition-type/field-names condition-type +@deffn procedure condition-type/field-names condition-type @cindex generalization, of condition types Returns a list of all of the field names for a condition of type @var{condition-type}. This is the set union of the fields specified @@ -17952,14 +18428,14 @@ when this @var{condition-type} was created with the @var{condition-type}. @end deffn -@deffn {procedure+} condition-type/generalizations condition-type +@deffn procedure condition-type/generalizations condition-type @cindex generalization, of condition types Returns a list of all of the generalizations of @var{condition-type}. Notice that every condition type is considered a generalization of itself. @end deffn -@deffn {procedure+} condition-type? object +@deffn procedure condition-type? object Returns @code{#f} if and only if @var{object} is not a condition type. @end deffn @@ -18022,17 +18498,17 @@ breakpoint @end group @end example -@deffn {condition type+} condition-type:serious-condition +@deffn {condition type} condition-type:serious-condition This is an abstract type. All serious conditions that require some form of intervention should inherit from this type. In particular, all errors inherit from this type. @end deffn -@deffn {condition type+} condition-type:error +@deffn {condition type} condition-type:error This is an abstract type. All errors should inherit from this type. @end deffn -@deffn {condition type+} condition-type:simple-error message irritants +@deffn {condition type} condition-type:simple-error message irritants This is the condition generated by the @code{error} procedure when its first argument is not a condition or condition type. The fields @var{message} and @var{irritants} are taken directly from the arguments @@ -18042,7 +18518,7 @@ uses @code{format-error-message} to generate its output from @var{message} and @var{irritants}. @end deffn -@deffn {condition type+} condition-type:illegal-datum datum +@deffn {condition type} condition-type:illegal-datum datum This is an abstract type. This type indicates the class of errors in which a program discovers an object that lacks specific required properties. Most commonly, the object is of the wrong type or is @@ -18050,7 +18526,7 @@ outside a specific range. The @var{datum} field contains the offending object. @end deffn -@deffn {condition type+} condition-type:wrong-type-datum datum type +@deffn {condition type} condition-type:wrong-type-datum datum type This type indicates the class of errors in which a program discovers an object that is of the wrong type. The @var{type} field contains a string describing the type that was expected, and the @var{datum} field @@ -18066,14 +18542,14 @@ contains the object that is of the wrong type. @end group @end example -@deffn {procedure+} error:wrong-type-datum datum type +@deffn procedure error:wrong-type-datum datum type This procedure signals a condition of type @code{condition-type:wrong-type-datum}. The @var{datum} and @var{type} fields of the condition are filled in from the corresponding arguments to the procedure. @end deffn -@deffn {condition type+} condition-type:wrong-type-argument datum type operator operand +@deffn {condition type} condition-type:wrong-type-argument datum type operator operand This type indicates that a procedure was passed an argument of the wrong type. The @var{operator} field contains the procedure (or a symbol naming the procedure), the @var{operand} field indicates the argument @@ -18101,7 +18577,7 @@ contains the offending argument. @end group @end example -@deffn {procedure+} error:wrong-type-argument datum type operator +@deffn procedure error:wrong-type-argument datum type operator This procedure signals a condition of type @code{condition-type:wrong-type-argument}. The @var{datum}, @var{type} and @var{operator} fields of the condition are filled in from the @@ -18109,7 +18585,7 @@ corresponding arguments to the procedure; the @var{operand} field of the condition is set to @code{#f}. @end deffn -@deffn {condition type+} condition-type:wrong-number-of-arguments datum type operands +@deffn {condition type} condition-type:wrong-number-of-arguments datum type operands This type indicates that a procedure was called with the wrong number of arguments. The @var{datum} field contains the procedure being called, the @var{type} field contains the number of arguments that the procedure @@ -18127,14 +18603,14 @@ that were passed to the procedure. @end group @end example -@deffn {procedure+} error:wrong-number-of-arguments datum type operands +@deffn procedure error:wrong-number-of-arguments datum type operands This procedure signals a condition of type @code{condition-type:wrong-number-of-arguments}. The @var{datum}, @var{type} and @var{operands} fields of the condition are filled in from the corresponding arguments to the procedure. @end deffn -@deffn {condition type+} condition-type:datum-out-of-range datum +@deffn {condition type} condition-type:datum-out-of-range datum This type indicates the class of errors in which a program discovers an object that is of the correct type but is otherwise out of range. Most often, this type indicates that an index to some data structure is @@ -18151,13 +18627,13 @@ field contains the offending object. @end group @end example -@deffn {procedure+} error:datum-out-of-range datum +@deffn procedure error:datum-out-of-range datum This procedure signals a condition of type @code{condition-type:datum-out-of-range}. The @var{datum} field of the condition is filled in from the corresponding argument to the procedure. @end deffn -@deffn {condition type+} condition-type:bad-range-argument datum operator operand +@deffn {condition type} condition-type:bad-range-argument datum operator operand This type indicates that a procedure was passed an argument that is of the correct type but is otherwise out of range. Most often, this type indicates that an index to some data structure is outside of the range @@ -18179,7 +18655,7 @@ either a symbol, a non-negative integer, or @code{#f}), and the @end group @end example -@deffn {procedure+} error:bad-range-argument datum operator +@deffn procedure error:bad-range-argument datum operator This procedure signals a condition of type @code{condition-type:bad-range-argument}. The @var{datum} and @var{operator} fields of the condition are filled in from the @@ -18187,7 +18663,7 @@ corresponding arguments to the procedure; the @var{operand} field of the condition is set to @code{#f}. @end deffn -@deffn {condition type+} condition-type:inapplicable-object datum operands +@deffn {condition type} condition-type:inapplicable-object datum operands This type indicates an error in which a program attempted to apply an object that is not a procedure. The object being applied is saved in the @var{datum} field, and the arguments being passed to the object are @@ -18204,14 +18680,14 @@ saved as a list in the @var{operands} field. @end group @end example -@deffn {condition type+} condition-type:file-error filename +@deffn {condition type} condition-type:file-error filename This is an abstract type. It indicates that an error associated with a file has occurred. For example, attempting to delete a nonexistent file will signal an error. The @var{filename} field contains a filename or pathname associated with the operation that failed. @end deffn -@deffn {condition type+} condition-type:file-operation-error filename verb noun reason operator operands +@deffn {condition type} condition-type:file-operation-error filename verb noun reason operator operands This is the most common condition type for file system errors. The @var{filename} field contains the filename or pathname that was being operated on. The @var{verb} field contains a string which is the verb @@ -18252,13 +18728,13 @@ and would generate a message like this: @end example @end deffn -@deffn {procedure+} error:file-operation-error filename verb noun reason operator operands +@deffn procedure error:file-operation-error filename verb noun reason operator operands This procedure signals a condition of type @code{condition-type:file-operation-error}. The fields of the condition are filled in from the corresponding arguments to the procedure. @end deffn -@deffn {condition type+} condition-type:derived-file-error filename condition +@deffn {condition type} condition-type:derived-file-error filename condition This is another kind of file error, which is generated by obscure file-system errors that do not fit into the standard categories. The @var{filename} field contains the filename or pathname that was being @@ -18267,14 +18743,14 @@ describing the error in more detail. Usually the @var{condition} field contains a condition of type @code{condition-type:system-call-error}. @end deffn -@deffn {procedure+} error:derived-file filename condition +@deffn procedure error:derived-file filename condition This procedure signals a condition of type @code{condition-type:derived-file-error}. The @var{filename} and @var{condition} fields of the condition are filled in from the corresponding arguments to the procedure. @end deffn -@deffn {condition type+} condition-type:port-error port +@deffn {condition type} condition-type:port-error port This is an abstract type. It indicates that an error associated with a I/O port has occurred. For example, writing output to a file port can signal an error if the disk containing the file is full; that error @@ -18282,7 +18758,7 @@ would be signalled as a port error. The @var{port} field contains the associated port. @end deffn -@deffn {condition type+} condition-type:derived-port-error port condition +@deffn {condition type} condition-type:derived-port-error port condition This is a concrete type that is signalled when port errors occur. The @var{port} field contains the port associated with the error, and the @var{condition} field contains a condition object that describes the @@ -18290,21 +18766,21 @@ error in more detail. Usually the @var{condition} field contains a condition of type @code{condition-type:system-call-error}. @end deffn -@deffn {procedure+} error:derived-port port condition +@deffn procedure error:derived-port port condition This procedure signals a condition of type @code{condition-type:derived-port-error}. The @var{port} and @var{condition} fields of the condition are filled in from the corresponding arguments to the procedure. @end deffn -@deffn {condition type+} condition-type:variable-error location environment +@deffn {condition type} condition-type:variable-error location environment This is an abstract type. It indicates that an error associated with a variable has occurred. The @var{location} field contains the name of the variable, and the @var{environment} field contains the environment in which the variable was referenced. @end deffn -@deffn {condition type+} condition-type:unbound-variable location environment +@deffn {condition type} condition-type:unbound-variable location environment This type is generated when a program attempts to access or modify a variable that is not bound. The @var{location} field contains the name of the variable, and the @var{environment} field contains the @@ -18322,7 +18798,7 @@ foo @error{} @end group @end example -@deffn {condition type+} condition-type:unassigned-variable location environment +@deffn {condition type} condition-type:unassigned-variable location environment This type is generated when a program attempts to access a variable that is not assigned. The @var{location} field contains the name of the variable, and the @var{environment} field contains the environment in @@ -18340,7 +18816,7 @@ foo @error{} @end group @end example -@deffn {condition type+} condition-type:arithmetic-error operator operands +@deffn {condition type} condition-type:arithmetic-error operator operands This is an abstract type. It indicates that a numerical operation was unable to complete because of an arithmetic error. (For example, division by zero.) The @var{operator} field contains the procedure that @@ -18349,7 +18825,7 @@ implements the operation (or a symbol naming the procedure), and the to the procedure. @end deffn -@deffn {condition type+} condition-type:divide-by-zero operator operands +@deffn {condition type} condition-type:divide-by-zero operator operands This type is generated when a program attempts to divide by zero. The @var{operator} field contains the procedure that implements the failing operation (or a symbol naming the procedure), and the @var{operands} @@ -18366,14 +18842,14 @@ procedure. @end group @end example -@deffn {procedure+} error:divide-by-zero operator operands +@deffn procedure error:divide-by-zero operator operands This procedure signals a condition of type @code{condition-type:divide-by-zero}. The @var{operator} and @var{operands} fields of the condition are filled in from the corresponding arguments to the procedure. @end deffn -@deffn {condition type+} condition-type:floating-point-overflow operator operands +@deffn {condition type} condition-type:floating-point-overflow operator operands This type is generated when a program performs an arithmetic operation that results in a floating-point overflow. The @var{operator} field contains the procedure that implements the operation (or a symbol naming @@ -18381,7 +18857,7 @@ the procedure), and the @var{operands} field contains a list of the arguments that were passed to the procedure. @end deffn -@deffn {condition type+} condition-type:floating-point-underflow operator operands +@deffn {condition type} condition-type:floating-point-underflow operator operands This type is generated when a program performs an arithmetic operation that results in a floating-point underflow. The @var{operator} field contains the procedure that implements the operation (or a symbol naming @@ -18389,7 +18865,7 @@ the procedure), and the @var{operands} field contains a list of the arguments that were passed to the procedure. @end deffn -@deffn {condition type+} condition-type:primitive-procedure-error operator operands +@deffn {condition type} condition-type:primitive-procedure-error operator operands This is an abstract type. It indicates that an error was generated by a primitive procedure call. Primitive procedures are distinguished from ordinary procedures in that they are not written in Scheme but instead @@ -18400,7 +18876,7 @@ field contains a list of the arguments that were passed to the procedure. @end deffn -@deffn {condition type+} condition-type:system-call-error operator operands system-call error-type +@deffn {condition type} condition-type:system-call-error operator operands system-call error-type This is the most common condition type generated by primitive procedures. A condition of this type indicates that the primitive made a system call to the operating system, and that the system call @@ -18418,12 +18894,12 @@ system call that was being made and the error that occurred, respectively; these symbols are completely operating-system dependent. @end deffn -@deffn {condition type+} condition-type:control-error +@deffn {condition type} condition-type:control-error This is an abstract type. It describes a class of errors relating to program control flow. @end deffn -@deffn {condition type+} condition-type:no-such-restart name +@deffn {condition type} condition-type:no-such-restart name This type indicates that a named restart was not active when it was expected to be. Conditions of this type are signalled by several procedures that look for particular named restarts, for example @@ -18440,13 +18916,13 @@ being searched for. @end group @end example -@deffn {procedure+} error:no-such-restart name +@deffn procedure error:no-such-restart name This procedure signals a condition of type @code{condition-type:no-such-restart}. The @var{name} field of the condition is filled in from the corresponding argument to the procedure. @end deffn -@deffn {condition type+} condition-type:not-loading +@deffn {condition type} condition-type:not-loading A condition of this type is generated when the procedure @code{current-load-pathname} is called from somewhere other than inside a file being loaded. @@ -18461,13 +18937,13 @@ a file being loaded. @end group @end example -@deffn {condition type+} condition-type:warning +@deffn {condition type} condition-type:warning This is an abstract type. All warnings should inherit from this type. Warnings are a class of conditions that are usually handled by informing the user of the condition and proceeding the computation normally. @end deffn -@deffn {condition type+} condition-type:simple-warning message irritants +@deffn {condition type} condition-type:simple-warning message irritants This is the condition generated by the @code{warn} procedure. The fields @var{message} and @var{irritants} are taken directly from the arguments to @code{warn}; @var{message} contains an object (usually a @@ -18476,7 +18952,7 @@ for this type uses @code{format-error-message} to generate its output from @var{message} and @var{irritants}. @end deffn -@deffn {condition type+} condition-type:simple-condition message irritants +@deffn {condition type} condition-type:simple-condition message irritants This is an unspecialized condition that does not fall into any of the standard condition classes. The @var{message} field contains an object (usually a string) and @var{irritants} contains a list of objects. The @@ -18484,7 +18960,7 @@ reporter for this type uses @code{format-error-message} to generate its output from @var{message} and @var{irritants}. @end deffn -@deffn {condition type+} condition-type:breakpoint environment message prompt +@deffn {condition type} condition-type:breakpoint environment message prompt A condition of this type is generated by the breakpoint mechanism. The contents of its fields are beyond the scope of this document. @end deffn @@ -18530,14 +19006,14 @@ either an exact integer or an inexact real. @section Opening and Closing of Graphics Devices @cindex graphics, opening and closing devices -@deffn {procedure+} graphics-type-available? graphics-device-type +@deffn procedure graphics-type-available? graphics-device-type This predicate returns @code{#t} if the graphics system named by the symbol @var{graphics-device-type} is implemented by the Scheme system. Otherwise it returns @code{#f}, in which case it is an error to attempt to make a graphics device using @var{graphics-device-type}. @end deffn -@deffn {procedure+} enumerate-graphics-types +@deffn procedure enumerate-graphics-types This procedure returns a list of symbols which are the names of all the graphics device types that are supported by the Scheme system. The result is useful in deciding what additional arguments to supply to @@ -18545,7 +19021,7 @@ result is useful in deciding what additional arguments to supply to way of specifying the initial size, shape and other attributes. @end deffn -@deffn {procedure+} make-graphics-device graphics-device-type object @dots{} +@deffn procedure make-graphics-device graphics-device-type object @dots{} This operation creates and returns a graphics device object. @var{Graphics-device-type} is a symbol naming a graphics device type, and both the number and the meaning of the remaining arguments is @@ -18568,7 +19044,7 @@ open or it may be automatically closed. While a graphics device remains open the resources associated with it are not released. @end deffn -@deffn {procedure+} graphics-close graphics-device +@deffn procedure graphics-close graphics-device Closes @var{graphics-device}, releasing its resources. Subsequently it is an error to use @var{graphics-device}. @end deffn @@ -18607,20 +19083,20 @@ reset so that the left edge corresponds to an x-coordinate of @code{-1}, the right edge to x-coordinate @code{1}, the bottom edge to y-coordinate @code{-1}, and the top edge to y-coordinate @code{1}. -@deffn {procedure+} graphics-device-coordinate-limits graphics-device +@deffn procedure graphics-device-coordinate-limits graphics-device Returns (as multiple values) the device coordinate limits for @var{graphics-device}. The values, which are exact non-negative integers, are: @var{x-left}, @var{y-bottom}, @var{x-right}, and @var{y-top}. @end deffn -@deffn {procedure+} graphics-coordinate-limits graphics-device +@deffn procedure graphics-coordinate-limits graphics-device Returns (as multiple values) the virtual coordinate limits for @var{graphics-device}. The values, which are real numbers, are: @var{x-left}, @var{y-bottom}, @var{x-right}, and @var{y-top}. @end deffn -@deffn {procedure+} graphics-set-coordinate-limits graphics-device x-left y-bottom x-right y-top +@deffn procedure graphics-set-coordinate-limits graphics-device x-left y-bottom x-right y-top Changes the virtual coordinate limits of @var{graphics-device} to the given arguments. @var{X-left}, @var{y-bottom}, @var{x-right}, and @var{y-top} must be real numbers. Subsequent calls to @@ -18640,17 +19116,17 @@ afterwards. The procedures in this section provide the basic drawing capabilities of Scheme's graphics system. -@deffn {procedure+} graphics-clear graphics-device +@deffn procedure graphics-clear graphics-device Clears the display of @var{graphics-device}. Unaffected by the current drawing mode. @end deffn -@deffn {procedure+} graphics-draw-point graphics-device x y +@deffn procedure graphics-draw-point graphics-device x y Draws a single point on @var{graphics-device} at the virtual coordinates given by @var{x} and @var{y}, using the current drawing mode. @end deffn -@deffn {procedure+} graphics-erase-point graphics-device x y +@deffn procedure graphics-erase-point graphics-device x y Erases a single point on @var{graphics-device} at the virtual coordinates given by @var{x} and @var{y}. This procedure is unaffected by the current drawing mode. @@ -18668,14 +19144,14 @@ This is equivalent to @end group @end example -@deffn {procedure+} graphics-draw-line graphics-device x-start y-start x-end y-end +@deffn procedure graphics-draw-line graphics-device x-start y-start x-end y-end @var{X-start}, @var{y-start}, @var{x-end}, and @var{y-end} must be real numbers. Draws a line on @var{graphics-device} that connects the points (@var{x-start}, @var{y-start}) and (@var{x-end}, @var{y-end}). The line is drawn using the current drawing mode and line style. @end deffn -@deffn {procedure+} graphics-draw-text graphics-device x y string +@deffn procedure graphics-draw-text graphics-device x y string Draws the characters of @var{string} at the point (@var{x}, @var{y}) on @var{graphics-device}, using the current drawing mode. The characteristics of the characters drawn are device-dependent, but all @@ -18711,12 +19187,12 @@ graphics-set-line-style The initial state of the cursor is unspecified. -@deffn {procedure+} graphics-move-cursor graphics-device x y +@deffn procedure graphics-move-cursor graphics-device x y Moves the cursor for @var{graphics-device} to the point (@var{x}, @var{y}). The contents of the device's display are unchanged. @end deffn -@deffn {procedure+} graphics-drag-cursor graphics-device x y +@deffn procedure graphics-drag-cursor graphics-device x y Draws a line from @var{graphics-device}'s cursor to the point (@var{x}, @var{y}), simultaneously moving the cursor to that point. The line is drawn using the current drawing mode and line style. @@ -18800,8 +19276,8 @@ Style Name Pattern @end group @end example -@deffn {procedure+} graphics-bind-drawing-mode graphics-device drawing-mode thunk -@deffnx {procedure+} graphics-bind-line-style graphics-device line-style thunk +@deffn procedure graphics-bind-drawing-mode graphics-device drawing-mode thunk +@deffnx procedure graphics-bind-line-style graphics-device line-style thunk These procedures bind the drawing mode or line style, respectively, of @var{graphics-device}, invoke the procedure @var{thunk} with no arguments, then undo the binding when @var{thunk} returns. The value of @@ -18810,8 +19286,8 @@ operations performed during @var{thunk}'s dynamic extent will see the newly bound mode or style as current. @end deffn -@deffn {procedure+} graphics-set-drawing-mode graphics-device drawing-mode -@deffnx {procedure+} graphics-set-line-style graphics-device line-style +@deffn procedure graphics-set-drawing-mode graphics-device drawing-mode +@deffnx procedure graphics-set-line-style graphics-device line-style These procedures change the drawing mode or line style, respectively, of @var{graphics-device}. The mode or style will remain in effect until subsequent changes or bindings. @@ -18828,7 +19304,7 @@ this buffer after every drawing operation. The procedures in this section allow the user to control the flushing of the output buffer. -@deffn {procedure+} graphics-enable-buffering graphics-device +@deffn procedure graphics-enable-buffering graphics-device Enables buffering for @var{graphics-device}. In other words, after this procedure is called, graphics operations are permitted to buffer their drawing requests. This usually means that the drawing is delayed until @@ -18836,7 +19312,7 @@ the buffer is flushed explicitly by the user, or until it fills up and is flushed by the system. @end deffn -@deffn {procedure+} graphics-disable-buffering graphics-device +@deffn procedure graphics-disable-buffering graphics-device Disables buffering for @var{graphics-device}. By default, all graphics devices are initialized with buffering disabled. After this procedure is called, all drawing operations perform their output immediately, @@ -18846,7 +19322,7 @@ Note: @code{graphics-disable-buffering} flushes the output buffer if necessary. @end deffn -@deffn {procedure+} graphics-flush graphics-device +@deffn procedure graphics-flush graphics-device Flushes the graphics output buffer for @var{graphics-device}. This operation has no effect for devices that do not support buffering, or if buffering is disabled for the device. @@ -18870,7 +19346,7 @@ usually reset the clip rectangle for that device, as will any operation that affects the size of the device (such as a window resizing operation). However, programs should not depend on this. -@deffn {procedure+} graphics-set-clip-rectangle graphics-device x-left y-bottom x-right y-top +@deffn procedure graphics-set-clip-rectangle graphics-device x-left y-bottom x-right y-top Specifies the clip rectangle for @var{graphics-device} in virtual coordinates. @var{X-left}, @var{y-bottom}, @var{x-right}, and @var{y-top} must be real numbers. Subsequent graphics output is clipped @@ -18878,7 +19354,7 @@ to the intersection of this rectangle and the device's virtual coordinate limits. @end deffn -@deffn {procedure+} graphics-reset-clip-rectangle graphics-device +@deffn procedure graphics-reset-clip-rectangle graphics-device Eliminates the clip rectangle for @var{graphics-device}. Subsequent graphics output is clipped to the virtual coordinate limits of the device. @@ -18894,7 +19370,7 @@ In addition to the standard operations, a graphics device may support operations to control color. @code{graphics-operation} is used to invoke custom operations. -@deffn {procedure+} graphics-operation graphics-device name object @dots{} +@deffn procedure graphics-operation graphics-device name object @dots{} Invokes the graphics operation on @var{graphics-device} whose name is the symbol @var{name}, passing it the remaining arguments. This procedure can be used to invoke the standard operations, as well as @@ -18928,7 +19404,7 @@ pixmaps. The operations supported vary between devices, so look under the different device types to see what operations are available. All devices that support images support the following operations. -@defop {operation+} graphics-device create-image width height +@defop operation graphics-device create-image width height Images are created using the @code{create-image} graphics operation, specifying the @var{width} and @var{height} of the image in device coordinates (pixels). @@ -18949,11 +19425,11 @@ with different attributes (for example, different colors) is undefined. Under X, the image is display dependent. @end defop -@defop {operation+} graphics-device draw-image x y image +@defop operation graphics-device draw-image x y image The image is copied into the graphics device at the specified position. @end defop -@defop {operation+} graphics-device draw-subimage x y image im-x im-y w h +@defop operation graphics-device draw-subimage x y image im-x im-y w h Part of the image is copied into the graphics device at the specified (@var{x}, @var{y}) position. The part of the image that is copied is the rectangular region at @var{im-x} and @var{im-y} and of width @var{w} and @@ -18961,12 +19437,12 @@ height @var{h}. These four numbers are given in device coordinates (pixels). @end defop -@deffn {procedure+} image? object +@deffn procedure image? object Returns @code{#t} if @var{object} is an image, otherwise returns @code{#f}. @end deffn -@deffn {procedure+} image/destroy image +@deffn procedure image/destroy image This procedure destroys @var{image}, returning storage to the system. Programs should destroy images after they have been used because even modest images may use large amounts of memory. Images are reclaimed by @@ -18977,20 +19453,20 @@ cause a subsequent call to @code{create-image} to fail because it is unable to allocate enough memory. @end deffn -@c @deffn {procedure+} image/descriptor image +@c @deffn procedure image/descriptor image @c The procedure returns the implementation dependent image. Its use is @c discouraged as it is non-portable. @c @end deffn -@deffn {procedure+} image/height image +@deffn procedure image/height image Returns the height of the image in device coordinates. @end deffn -@deffn {procedure+} image/width image +@deffn procedure image/width image Returns the width of the image in device coordinates. @end deffn -@deffn {procedure+} image/fill-from-byte-vector image bytes +@deffn procedure image/fill-from-byte-vector image bytes The contents of @var{image} are set in a device-dependent way, using one byte per pixel from @var{bytes} (a string). Pixels are filled row by row from the top of the image to the bottom, with each row being filled @@ -19089,7 +19565,7 @@ The window is created with a @code{backing_store} attribute of @node Utilities for X Graphics, Custom Operations on X Graphics Devices, X Graphics Type, X Graphics @subsection Utilities for X Graphics -@deffn {procedure+} x-graphics/open-display display-name +@deffn procedure x-graphics/open-display display-name @cindex display, X graphics @cindex X display, graphics Opens a connection to the display whose name is @var{display-name}, @@ -19100,19 +19576,19 @@ meaning to use the value of the unix environment variable @code{DISPLAY}. @end deffn -@deffn {procedure+} x-graphics/close-display display +@deffn procedure x-graphics/close-display display Closes @var{display}; after calling this procedure, it is an error to use @var{display} for any purpose. Any windows that were previously opened on @var{display} are destroyed and their resources returned to the operating system. @end deffn -@deffn {procedure+} x-close-all-displays +@deffn procedure x-close-all-displays Closes all open connections to X displays. Equivalent to calling @code{x-close-display} on all open displays. @end deffn -@deffn {procedure+} x-geometry-string x y width height +@deffn procedure x-geometry-string x y width height @cindex geometry string, X graphics @cindex X geometry string, graphics This procedure creates and returns a standard X geometry string from the @@ -19150,10 +19626,10 @@ Custom operations are invoked using the procedure (graphics-operation device 'set-foreground-color "blue") @end example -@defop {operation+} x-graphics-device set-background-color color-name -@defopx {operation+} x-graphics-device set-foreground-color color-name -@defopx {operation+} x-graphics-device set-border-color color-name -@defopx {operation+} x-graphics-device set-mouse-color color-name +@defop operation x-graphics-device set-background-color color-name +@defopx operation x-graphics-device set-foreground-color color-name +@defopx operation x-graphics-device set-border-color color-name +@defopx operation x-graphics-device set-mouse-color color-name @findex graphics-clear These operations change the colors associated with a window. @var{Color-name} must be a string, which is the X server's name for the @@ -19168,7 +19644,7 @@ names, like @code{"red"}, and intensity names specified in the @code{"#@var{rrggbb}"} notation. @end defop -@defop {operation+} x-graphics-device draw-arc x y radius-x radius-y angle-start angle-sweep fill? +@defop operation x-graphics-device draw-arc x y radius-x radius-y angle-start angle-sweep fill? @cindex drawing arcs and circles, graphics @cindex graphics, drawing arcs and circles @cindex circles, drawing @@ -19208,8 +19684,8 @@ at virtual coordinates (3,5): @end defop -@defop {operation+} x-graphics-device draw-circle x y radius -@defopx {operation+} x-graphics-device fill-circle x y radius +@defop operation x-graphics-device draw-circle x y radius +@defopx operation x-graphics-device fill-circle x y radius @cindex drawing arcs and circles, graphics @cindex graphics, drawing arcs and circles @cindex circles, drawing @@ -19221,8 +19697,8 @@ on the graphics device at the virtual coordinates given by @var{x} and @code{draw-arc} operation. @end defop -@defop {operation+} x-graphics-device set-border-width width -@defopx {operation+} x-graphics-device set-internal-border-width width +@defop operation x-graphics-device set-border-width width +@defopx operation x-graphics-device set-internal-border-width width @findex graphics-clear These operations change the external and internal border widths of a window. @var{Width} must be an exact non-negative integer, specified in @@ -19232,26 +19708,26 @@ recommend calling @code{graphics-clear} on the window's device after doing so. @end defop -@defop {operation+} x-graphics-device set-font font-name +@defop operation x-graphics-device set-font font-name Changes the font used when drawing text in a window. @var{Font-name} must be a string that is a font name known to the X server. This operation does not affect text drawn prior to its invocation. @end defop -@defop {operation+} x-graphics-device set-mouse-shape shape-number +@defop operation x-graphics-device set-mouse-shape shape-number Changes the shape of the mouse cursor. @var{Shape-number} is an exact non-negative integer that is used as an index into the mouse-shape font; when multiplied by 2 this number corresponds to an index in the file@* @file{/usr/include/X11/cursorfont.h}. @end defop -@defop {operation+} x-graphics-device map-window -@defopx {operation+} x-graphics-device withdraw-window +@defop operation x-graphics-device map-window +@defopx operation x-graphics-device withdraw-window These operations control the mapping of windows. They correspond directly to Xlib's @code{XMapWindow} and @code{XWithdrawWindow}. @end defop -@defop {operation+} x-graphics-device resize-window width height +@defop operation x-graphics-device resize-window width height Changes the size of a window. @var{Width} and @var{height} must be exact non-negative integers. The operation corresponds directly to Xlib's @code{XResizeWindow}. @@ -19260,7 +19736,7 @@ This operation resets the virtual coordinate system and the clip rectangle. @end defop -@defop {operation+} x-graphics-device move-window x y +@defop operation x-graphics-device move-window x y Changes the position of a window on the display. @var{X} and @var{y} must be exact integers. The operation corresponds directly to Xlib's @code{XMoveWindow}. Note that the coordinates @var{x} and @var{y} do @@ -19269,7 +19745,7 @@ position the window as you might like. The only reliable way to position a window is to ask a window manager to do it for you. @end defop -@defop {operation+} x-graphics-device get-default resource property +@defop operation x-graphics-device get-default resource property This operation corresponds directly to Xlib's @code{XGetDefault}. @var{Resource} and @var{property} must be strings. The operation returns the character string corresponding to the association of @@ -19277,29 +19753,29 @@ returns the character string corresponding to the association of @code{#f} is returned. @end defop -@defop {operation+} x-graphics-device copy-area source-x-left source-y-top width height destination-x-left destination-y-top +@defop operation x-graphics-device copy-area source-x-left source-y-top width height destination-x-left destination-y-top This operation copies the contents of the rectangle specified by @var{source-x-left}, @var{source-y-top}, @var{width}, and @var{height} to the rectangle of the same dimensions at @var{destination-x-left} and @var{destination-y-top}. @end defop -@defop {operation+} x-graphics-device font-structure font-name +@defop operation x-graphics-device font-structure font-name Returns a Scheme equivalent of the X font structure for the font named @var{font-name}. If the string @var{font-name} does not name a font known to the X server, or names a 16-bit font, @code{#f} is returned. @end defop -@deffn {procedure+} x-font-structure/name font-structure -@deffnx {procedure+} x-font-structure/direction font-structure -@deffnx {procedure+} x-font-structure/all-chars-exist font-structure -@deffnx {procedure+} x-font-structure/default-char font-structure -@deffnx {procedure+} x-font-structure/min-bounds font-structure -@deffnx {procedure+} x-font-structure/max-bounds font-structure -@deffnx {procedure+} x-font-structure/start-index font-structure -@deffnx {procedure+} x-font-structure/character-bounds font-structure -@deffnx {procedure+} x-font-structure/max-ascent font-structure -@deffnx {procedure+} x-font-structure/max-descent font-structure +@deffn procedure x-font-structure/name font-structure +@deffnx procedure x-font-structure/direction font-structure +@deffnx procedure x-font-structure/all-chars-exist font-structure +@deffnx procedure x-font-structure/default-char font-structure +@deffnx procedure x-font-structure/min-bounds font-structure +@deffnx procedure x-font-structure/max-bounds font-structure +@deffnx procedure x-font-structure/start-index font-structure +@deffnx procedure x-font-structure/character-bounds font-structure +@deffnx procedure x-font-structure/max-ascent font-structure +@deffnx procedure x-font-structure/max-descent font-structure These procedures extract the components of the font description structure returned by the X graphics operation @code{font-structure}. A more complete description of these components appears in documentation @@ -19310,11 +19786,11 @@ of the first character available in the font. The @code{min-bounds} and a vector of the same type. @end deffn -@deffn {procedure+} x-character-bounds/lbearing character-bounds -@deffnx {procedure+} x-character-bounds/rbearing character-bounds -@deffnx {procedure+} x-character-bounds/width character-bounds -@deffnx {procedure+} x-character-bounds/ascent character-bounds -@deffnx {procedure+} x-character-bounds/descent character-bounds +@deffn procedure x-character-bounds/lbearing character-bounds +@deffnx procedure x-character-bounds/rbearing character-bounds +@deffnx procedure x-character-bounds/width character-bounds +@deffnx procedure x-character-bounds/ascent character-bounds +@deffnx procedure x-character-bounds/descent character-bounds These procedures extract components of objects of type @code{x-character-bounds}. A more complete description of them appears in documentation of the@* @code{XLoadQueryFont} Xlib call. @@ -19403,8 +19879,8 @@ Custom operations are invoked using the procedure (graphics-operation device 'set-foreground-color "blue") @end example -@defop {operation+} win32-graphics-device set-background-color color-name -@defopx {operation+} win32-graphics-device set-foreground-color color-name +@defop operation win32-graphics-device set-background-color color-name +@defopx operation win32-graphics-device set-foreground-color color-name @findex set-background-color @findex set-foreground-color @cindex color @@ -19443,7 +19919,7 @@ available color is used instead. @end defop -@defop {operation+} win32-graphics-device define-color name spec +@defop operation win32-graphics-device define-color name spec Define the string @var{name} to be the color specified by @var{spec}. @var{Spec} may be any acceptable color specification. Note that the color names defined this way are available to any Win32 graphics device, @@ -19455,14 +19931,14 @@ colors of the Scheme console window, or the colors of Edwin editor windows. @end defop -@defop {operation+} win32-graphics-device find-color name +@defop operation win32-graphics-device find-color name Looks up a color previously defined by @code{define-color}. This returns the color in its most efficient form for operations @code{set-foreground-color} or @code{set-background-color}. @end defop -@defop {operation+} win32-graphics-device draw-ellipse left top right bottom +@defop operation win32-graphics-device draw-ellipse left top right bottom @cindex ellipse, graphics @cindex circle, graphics @cindex graphics, ellipse @@ -19478,7 +19954,7 @@ of the line width. @end defop -@defop {operation+} win32-graphics-device fill-polygon points +@defop operation win32-graphics-device fill-polygon points @findex fill-polygon Draws a filled polygon using the current foreground color. @var{Points} is a vector of real numbers. @@ -19495,7 +19971,7 @@ draws a solid triangular region between the points (0, 0), (0, 1) and @end defop -@defop {operation+} win32-graphics-device load-bitmap pathname +@defop operation win32-graphics-device load-bitmap pathname @cindex bitmaps The graphics device contents and size are initialized from the windows bitmap file specified by @var{pathname}. If no file type is supplied @@ -19504,7 +19980,7 @@ effect when this procedure is called, it is necessary to redefine the clip rectangle afterwards. @end defop -@defop {operation+} win32-graphics-device save-bitmap pathname +@defop operation win32-graphics-device save-bitmap pathname @cindex printing graphics output The graphics device contents are saved as a bitmap to the file specified by @var{pathname}. If no file type is supplied then a @code{".BMP"} @@ -19512,36 +19988,36 @@ extension is added. The saved bitmap may be incorporated into documents or printed. @end defop -@defop {operation+} win32-graphics-device move-window x y +@defop operation win32-graphics-device move-window x y The graphics device window is moved to the screen position specified by @var{x} and @var{y}. @end defop -@defop {operation+} win32-graphics-device resize-window width height +@defop operation win32-graphics-device resize-window width height The graphics device window is resized to the specified @var{width} and @var{height} in device coordinates (pixels). If a clip rectangle is in effect when this procedure is called, it is necessary to redefine the clip rectangle afterwards. @end defop -@defop {operation+} win32-graphics-device set-line-width width +@defop operation win32-graphics-device set-line-width width This operation sets the line width for future drawing of lines, points and ellipses. It does not affect existing lines and has no effect on filled polygons. The line width is specified in device units. The default and initial value of this parameter is 1 pixel. @end defop -@defop {operation+} win32-graphics-device set-window-name name +@defop operation win32-graphics-device set-window-name name This sets the window title to the string @var{name}. The window is given the name @code{"Scheme Graphics"} at creation. @end defop -@defop {operation+} win32-graphics-device set-font handle +@defop operation win32-graphics-device set-font handle Sets the font for drawing text. Currently not well supported. If you can get a Win32 font handle it can be used here. @end defop -@defop {operation+} win32-graphics-device copy-area source-x-left source-y-top width height destination-x-left destination-y-top +@defop operation win32-graphics-device copy-area source-x-left source-y-top width height destination-x-left destination-y-top This operation copies the contents of the rectangle specified by @var{source-x-left}, @var{source-y-top}, @var{width}, and @var{height} to the rectangle of the same dimensions at @var{destination-x-left} and @@ -19599,13 +20075,13 @@ drawing area in the graphics window (i.e.@: excluding the frame). These operations control the colors used when drawing on an OS/2 graphics device. -@defop {operation+} os2-graphics-device color? +@defop operation os2-graphics-device color? @findex color? This operation returns @code{#t} if the display supports color. @end defop -@defop {operation+} os2-graphics-device set-background-color color-name -@defopx {operation+} os2-graphics-device set-foreground-color color-name +@defop operation os2-graphics-device set-background-color color-name +@defopx operation os2-graphics-device set-foreground-color color-name @findex set-background-color @findex set-foreground-color @cindex color @@ -19641,7 +20117,7 @@ If the color is not available in the graphics device then the nearest available color is used instead. @end defop -@defop {operation+} os2-graphics-device define-color name spec +@defop operation os2-graphics-device define-color name spec Define the string @var{name} to be the color specified by @var{spec}. @var{Spec} may be any acceptable color specification. Note that the color names defined this way are available to any OS/2 graphics @@ -19652,7 +20128,7 @@ colors of the Scheme console window, or the colors of Edwin editor windows. @end defop -@defop {operation+} os2-graphics-device find-color name +@defop operation os2-graphics-device find-color name Looks up a color previously defined by @code{define-color}. This returns the color in its most efficient form for operations @code{set-foreground-color} or @code{set-background-color}. @@ -19669,7 +20145,7 @@ hidden or minimized state; to activate or deactivate the window (that is, control the keyboard focus); and to control the text that appears in the window's title bar. -@defop {operation+} os2-graphics-device window-position +@defop operation os2-graphics-device window-position This operation returns the position of the graphics-device window on the desktop. The position is returned as two values (@pxref{Continuations}), which are the x and y coordinates of the @@ -19678,7 +20154,7 @@ the distance between the lower left hand corner of the desktop and the lower left hand corner of the graphics device window's frame. @end defop -@defop {operation+} os2-graphics-device set-window-position x y +@defop operation os2-graphics-device set-window-position x y The graphics-device window is moved to the screen position specified by @var{x} and @var{y}. The coordinates @var{x} and @var{y} are in units of pels (pixels), and measure the distance between the lower left hand @@ -19686,7 +20162,7 @@ corner of the desktop and the lower left hand corner of the graphics device window's frame. @end defop -@defop {operation+} os2-graphics-device window-size +@defop operation os2-graphics-device window-size This operation returns the size of the client area of the graphics-device window. The client area is the part of the window that you draw on; it does not include the window frame, title bar, etc. The @@ -19694,14 +20170,14 @@ size is returned as two values (@pxref{Continuations}), which are the width and height of the client area in units of pels (pixels). @end defop -@defop {operation+} os2-graphics-device set-window-size width height +@defop operation os2-graphics-device set-window-size width height This operation sets the size of the client area of the graphics-device window to the specified @var{width} and @var{height}, which are in units of pels (pixels). The client area is the part of the window that you draw on; it does not include the window frame, title bar, etc. @end defop -@defop {operation+} os2-graphics-device window-frame-size +@defop operation os2-graphics-device window-frame-size This operation returns the size of the graphics-device window's frame. This includes the client area, as well as the border, title bar, etc. The size is returned as two values (@pxref{Continuations}), which are @@ -19712,59 +20188,59 @@ desktop size to determine relative placement of the window or to guarantee that the entire window is visible on the desktop. @end defop -@defop {operation+} os2-graphics-device desktop-size +@defop operation os2-graphics-device desktop-size This operation returns the size of the OS/2 desktop. The size is returned as two values (@pxref{Continuations}), which are the width and height of the frame in units of pels (pixels). @end defop -@defop {operation+} os2-graphics-device raise-window +@defop operation os2-graphics-device raise-window This operation raises the graphics-device window so that it is on top of any other windows on the desktop. @end defop -@defop {operation+} os2-graphics-device lower-window +@defop operation os2-graphics-device lower-window This operation lowers the graphics-device window so that it is below all other windows on the desktop. @end defop -@defop {operation+} os2-graphics-device hide-window +@defop operation os2-graphics-device hide-window This operation hides the graphics-device window. The window disappears from the desktop, but still appears in the window list. @end defop -@defop {operation+} os2-graphics-device minimize-window +@defop operation os2-graphics-device minimize-window This operation minimizes the graphics-device window. The window disappears from the desktop, but still appears in the window list. Depending on how you have configured your desktop, the window may appear as an icon, either on the desktop or in the minimized window viewer. @end defop -@defop {operation+} os2-graphics-device maximize-window +@defop operation os2-graphics-device maximize-window This operation maximizes the graphics-device window. This causes the window to fill the entire desktop. @end defop -@defop {operation+} os2-graphics-device restore-window +@defop operation os2-graphics-device restore-window This operation restores the graphics-device window to its normal state. If the window is hidden or minimized, it is shown again, at its former position on the desktop. If the window is maximized, it is returned to its normal size. @end defop -@defop {operation+} os2-graphics-device activate-window +@defop operation os2-graphics-device activate-window This operation makes the graphics-device window be the active window. This causes the window to be put in front of all other windows on the desktop, highlights its frame, and gives it the keyboard focus. @end defop -@defop {operation+} os2-graphics-device deactivate-window +@defop operation os2-graphics-device deactivate-window This operation deactivates the graphics-device window if it was active (otherwise it has no effect). This causes some other window to be chosen to be active in its place. @end defop -@defop {operation+} os2-graphics-device set-window-title title +@defop operation os2-graphics-device set-window-title title This operation changes the text that appears in the graphics device window's title bar. The new text is given by @var{title}, which must be a string. @@ -19777,7 +20253,7 @@ These operations allow you to read some of the events that are generated by the Presentation Manager and put in the message queue of a graphics-device window. -@defop {operation+} os2-graphics-device read-button +@defop operation os2-graphics-device read-button This operation waits for the user to push a mouse button inside the client area of the graphics-device window. It then returns four values (@pxref{Continuations}) which are: the button number; the x and y @@ -19790,7 +20266,7 @@ Note that this operation only works when button events are selected (which is the default). @end defop -@defop {operation+} os2-graphics-device select-user-events mask +@defop operation os2-graphics-device select-user-events mask This operation sets the event-selection mask for the graphics device to @var{mask}. The event-selection mask is an exact non-negative integer that specifies which types of incoming events are to be saved in the @@ -19821,7 +20297,7 @@ the user-event queue. Changing the mask only affects what events will be added to the queue in the future. @end defop -@defop {operation+} os2-graphics-device read-user-event +@defop operation os2-graphics-device read-user-event This operation returns the next user event available from the user-event queue. If there are no events in the queue, the operation waits for an event to arrive before returning. @@ -19890,7 +20366,7 @@ mouse, @var{hit-test} contains the hit-test information, and @var{flags} specifies the modifier keys that were pressed at the time. @end table -@defop {operation+} os2-graphics-device discard-events +@defop operation os2-graphics-device discard-events This operation discards any events that are in the user-event queue. This is sometimes useful when you want to prompt the user for some input and don't want to consider any previous input. @@ -19903,7 +20379,7 @@ These operations allow you to: change the font used for drawing text in a graphics-device window; take a snapshot of a graphics-device window and return it as an image object; and draw multiple lines efficiently. -@defop {operation+} os2-graphics-device set-font font-name +@defop operation os2-graphics-device set-font font-name This operation sets the font used for drawing text in the graphics-device window. @var{Font-name} is a string describing the font; this string is in the form ".", for @@ -19912,7 +20388,7 @@ family, in any point size that is supported for that font family. This includes both image fonts and outline fonts. @end defop -@defop {operation+} os2-graphics-device capture-image x-left y-bottom x-right y-top +@defop operation os2-graphics-device capture-image x-left y-bottom x-right y-top This operation creates and returns an image that contains part of the client area of the graphics-device window. The portion of the client area that is selected is specified by the four coordinate arguments, @@ -19920,7 +20396,7 @@ which are given in the current virtual coordinates for the device. @xref{Images}, for more information about manipulating images. @end defop -@defop {operation+} os2-graphics-device draw-lines xv yv +@defop operation os2-graphics-device draw-lines xv yv This operation draws multiple disjoint lines; it is like multiple calls to @code{graphics-draw-line} but much faster. The arguments @var{xv} and @var{yv} are vectors of coordinates; these vectors must be the same @@ -20109,8 +20585,8 @@ changes to the original. @end table -@deffn {special form+} define-windows-type name check convert return revert -@deffnx {special form+} define-similar-windows-type name model [check [convert [return [revert]]]] +@deffn {special form} define-windows-type name check convert return revert +@deffnx {special form} define-similar-windows-type name model [check [convert [return [revert]]]] @cindex defining foreign types Both forms define a windows type. The first form defines a type in terms of its aspects as described @@ -20261,7 +20737,7 @@ Foreign procedures are declared as callable entry-points in a module, usually a dynamically linked library (DLL). -@deffn {procedure+} find-module name +@deffn procedure find-module name @cindex loading DLLs @cindex DLL, loading Returns a module suitable for use in creating procedures with @@ -20282,20 +20758,20 @@ to call a procedure in the DLL). @end deffn -@defvr {variable+} gdi32.dll +@defvr variable gdi32.dll @cindex DLL, GDI32.DLL This variable is bound to the module describing the @file{GDI32.DLL} library, which contains the Win32 API graphics calls, e.g.@: @code{LineTo}. @end defvr -@defvr {variable+} kernel32.dll +@defvr variable kernel32.dll @cindex DLL, KERNEL32.DLL This variable is bound to the module describing the @file{KERNEL32.DLL} library. @end defvr -@defvr {variable+} user32.dll +@defvr variable user32.dll @cindex DLL, USER32.DLL This variable is bound to the module describing the @file{USER32.DLL} library. This module contains many useful Win32 API procedures, like @@ -20303,7 +20779,7 @@ library. This module contains many useful Win32 API procedures, like @end defvr -@deffn {special form+} windows-procedure (name (parameter type) ...) return-type module entry-name [options] +@deffn {special form} windows-procedure (name (parameter type) ...) return-type module entry-name [options] @cindex defining foreign procedures This form creates a procedure, and could be thought of as ``foreign-named-lambda''. The form creates a Scheme procedure that @@ -20499,14 +20975,14 @@ null handle error value. The following procedures have typed parameters, using the same convention as @code{windows-procedure}. -@deffn {procedure+} open-dib (filename string) +@deffn procedure open-dib (filename string) Return type: @var{dib}. Calls the @code{OpenDIB} entry of @file{DIBUTILS.DLL}. If the return value is not @code{#f} then the file @var{filename} was found, successfully opened, and the contents were suitable for loading into memory as a device independent bitmap. @end deffn -@deffn {procedure+} write-dib (filename string) (dib dib) +@deffn procedure write-dib (filename string) (dib dib) Return type: @var{bool}. Calls the @code{WriteDIB} entry of @file{DIBUTILS.DLL}. Returns @code{#t} if the file @var{filename} could be opened and written to. After this operation the file contains the @@ -20515,14 +20991,14 @@ and various system utilities like the bitmap editor. Any problems resulting in failure are signalled by a @code{#f} return value. @end deffn -@deffn {procedure+} bitmap-from-dib (dib dib) (palette hpalette) +@deffn procedure bitmap-from-dib (dib dib) (palette hpalette) Return type: @var{hbitmap}. Calls the @code{BitmapFromDib} entry of @file{DIBUTILS.DLL}. The returned value is a device dependent bitmap. The colours from the DIB are matched against colors in @var{palette}. @end deffn -@deffn {procedure+} dib-from-bitmap (bitmap hbitmap) (style dword) (bits word) (palette hpalette) +@deffn procedure dib-from-bitmap (bitmap hbitmap) (style dword) (bits word) (palette hpalette) Return type: @var{dib}. Returns a DIB containing the same image as the device dependent bitmap @var{bitmap}. @@ -20530,7 +21006,7 @@ Returns a DIB containing the same image as the device dependent bitmap Calls the @code{DibFromBitmap} entry of @file{DIBUTILS.DLL}. @end deffn -@deffn {procedure+} dib-blt (dest hdc) (x int) (y int) (w int) (h int) (src dib) (src-x int) (src-y int) (raster-op long) +@deffn procedure dib-blt (dest hdc) (x int) (y int) (w int) (h int) (src dib) (src-x int) (src-y int) (raster-op long) Return type: @var{bool}. Calls the @code{DibBlt} entry of @file{DIBUTILS.DLL}. Similar to the Win32 API @code{BitBlt} call, but draws a DIB rather than a piece of another device context. Draws the @@ -20541,7 +21017,7 @@ rectangle of width @var{w} and height @var{h} is copied from position combined but I don't think I got this right so stick to @code{SRCCOPY}. @end deffn -@deffn {procedure+} %delete-dib (dib-handle handle) +@deffn procedure %delete-dib (dib-handle handle) Return type: @var{bool}. Calls the @code{DeleteDIB} entry of @file{DIBUTILS.DLL}. Note that the parameter is a @var{handle}, and not a @var{dib}. @@ -20551,7 +21027,7 @@ The importance of this is that if the @code{dib} record is GC-ed then a GC hook can reclaim the storage knowing only the handle. @end deffn -@deffn {procedure+} delete-dib (dib dib) +@deffn procedure delete-dib (dib dib) Return type: @var{bool}. This procedure calls @code{%delete-dib} to reclaim the storage occupied by a DIB. @@ -20560,25 +21036,25 @@ This procedure allows the programmer to reclaim external heap storage rather than risking it running out before the next garbage collection. @end deffn -@deffn {procedure+} dib-height (dib dib) +@deffn procedure dib-height (dib dib) Return type: @var{int}. Calls the @code{DibHeight} expand entry of @file{DIBUTILS.DLL}, which returns the height of the bitmap in pixels. @end deffn -@deffn {procedure+} dib-width (dib dib) +@deffn procedure dib-width (dib dib) Return type: @var{int}. Calls the @code{DibWidth} entry of @file{DIBUTILS.DLL}, which returns the width of the bitmap in pixels. @end deffn -@deffn {procedure+} copy-bitmap (bm hbitmap) +@deffn procedure copy-bitmap (bm hbitmap) Return type: @var{hbitmap}. Calls the @code{CopyBitmap} of @file{DIBUTILS.DLL}, which creates a new bitmap with the same size and contents as the original. @end deffn -@deffn {procedure+} create-dib (width int) (height int) (style int) (depth int) (palette hpalette) +@deffn procedure create-dib (width int) (height int) (style int) (depth int) (palette hpalette) Return type: @var{dib}. Calls the @code{CreateDIB} entry of @file{DIBUTILS.DLL}. Creates a DIB of @var{width} by @var{height} pixels and @var{depth} bits @@ -20588,13 +21064,13 @@ I have only ever used @code{BI_RGB}. If @var{depth}<=8 then the @var{palette} determines the DIB's colour table. @end deffn -@deffn {procedure+} crop-bitmap (bm hbitmap) (left int) (top int) (right int) (bottom int) +@deffn procedure crop-bitmap (bm hbitmap) (left int) (top int) (right int) (bottom int) Return type: @var{hbitmap}. Calls the @code{CropBitmap} entry of @file{DIBUTILS.DLL}. Returns a new bitmap containing the image from a region of the original. @end deffn -@deffn {procedure+} dib-set-pixels-unaligned dib (pixels string) +@deffn procedure dib-set-pixels-unaligned dib (pixels string) Return type: @var{bool}. Calls the @code{DIBSetPixelsUnaligned} entry of@* @file{DIBUTILS.DLL}. Stuffs bytes from @var{pixels} into the bitmap. There are no alignment -- 2.25.1