@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
* Prompting::
* Port Primitives::
* Parser Buffers::
+* Parser Language::
Port Primitives
* Blocking Mode::
* Terminal Mode::
+Parser Language
+
+* *Matcher::
+* *Parser::
+* Parser-language Macros::
+
Operating-System Interface
* Pathnames::
@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
@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
@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
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
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.
@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
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:
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}
@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
@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
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.
@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
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.
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:
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}.
@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:
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
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
@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.
@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.
@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.
@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.
@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.
@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
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
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.
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
@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
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
@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},
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
@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
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.
@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),
@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
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
@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.
@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,
@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
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).
@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}.
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}.
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}.
@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
``@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
@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?}.
@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;
@end deffn
@deffn procedure string<? string1 string2
-@deffnx {procedure+} substring<? string1 start1 end1 string2 start2 end2
+@deffnx procedure substring<? string1 start1 end1 string2 start2 end2
@deffnx procedure string>? string1 string2
@deffnx procedure string<=? string1 string2
@deffnx procedure string>=? string1 string2
@deffnx {procedure} string-ci<? string1 string2
-@deffnx {procedure+} substring-ci<? string1 start1 end1 string2 start2 end2
+@deffnx procedure substring-ci<? string1 start1 end1 string2 start2 end2
@deffnx {procedure} string-ci>? string1 string2
@deffnx {procedure} string-ci<=? string1 string2
@deffnx {procedure} string-ci>=? string1 string2
@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
@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 =
@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
@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
@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"}
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
@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
@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:
@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:
@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
@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
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,
@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;
@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
@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
@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
@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}.
@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
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.
@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
@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.
@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}
@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}
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
@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.
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.
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.
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
@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:
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
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
@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
@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.
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.
@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
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.
@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
@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!}
@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:
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
@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}.
@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.
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.
@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}.
@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
@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
@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
@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
@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
(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
@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
@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}.
@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
@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:
@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}
@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.
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?
@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?
@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
@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
@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
@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:
@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:
@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
@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
@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:
@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
@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:
@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
@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
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
@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
@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
@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
@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
@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:
@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
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
@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 key<? unwrap-key key
+@deffn procedure vector-binary-search vector key<? unwrap-key key
@cindex searching, of vector
Searches @var{vector} for an element with a key matching @var{key},
returning the element if one is found or @code{#f} if none. The
@section Cutting Vectors
@cindex cutting, of vector
-@deffn {procedure+} subvector vector start end
+@deffn procedure subvector vector start end
Returns a newly allocated vector that contains the elements of
@var{vector} between index @var{start} (inclusive) and @var{end}
(exclusive).
@end deffn
-@deffn {procedure+} vector-head vector end
+@deffn procedure vector-head vector end
Equivalent to
@example
@end example
@end deffn
-@deffn {procedure+} vector-tail vector start
+@deffn procedure vector-tail vector start
Equivalent to
@example
@cindex moving, of vector elements
@deffn {procedure} vector-fill! vector object
-@deffnx {procedure+} subvector-fill! vector start end object
+@deffnx procedure subvector-fill! vector start end object
Stores @var{object} in every element of the vector (subvector) and
returns an unspecified value.
@end deffn
-@deffn {procedure+} subvector-move-left! vector1 start1 end1 vector2 start2
-@deffnx {procedure+} subvector-move-right! vector1 start1 end1 vector2 start2
+@deffn procedure subvector-move-left! vector1 start1 end1 vector2 start2
+@deffnx procedure subvector-move-right! vector1 start1 end1 vector2 start2
Destructively copies the elements of @var{vector1}, starting with index
@var{start1} (inclusive) and ending with @var{end1} (exclusive), into
@var{vector2} starting at index @var{start2} (inclusive).
@end table
@end deffn
-@deffn {procedure+} sort! vector procedure
-@deffnx {procedure+} merge-sort! vector procedure
-@deffnx {procedure+} quick-sort! vector procedure
+@deffn procedure sort! vector procedure
+@deffnx procedure merge-sort! vector procedure
+@deffnx procedure quick-sort! vector procedure
@var{Procedure} must be a procedure of two arguments that defines a
@dfn{total ordering} on the elements of @var{vector}. The elements of
@var{vector} are rearranged so that they are sorted in the order defined
@section Construction of Bit Strings
@cindex construction, of bit string
-@deffn {procedure+} make-bit-string k initialization
+@deffn procedure make-bit-string k initialization
Returns a newly allocated bit string of length @var{k}. If
@var{initialization} is @code{#f}, the bit string is filled with 0 bits;
otherwise, the bit string is filled with 1 bits.
@end example
@end deffn
-@deffn {procedure+} bit-string-allocate k
+@deffn procedure bit-string-allocate k
Returns a newly allocated bit string of length @var{k}, but does not
initialize it.
@end deffn
-@deffn {procedure+} bit-string-copy bit-string
+@deffn procedure bit-string-copy bit-string
@cindex copying, of bit string
Returns a newly allocated copy of @var{bit-string}.
@end deffn
@node Selecting Bit String Components, Cutting and Pasting Bit Strings, Construction of Bit Strings, Bit Strings
@section Selecting Bit String Components
-@deffn {procedure+} bit-string? object
+@deffn procedure bit-string? object
@cindex type predicate, for bit string
Returns @code{#t} if @var{object} is a bit string; otherwise returns
@code{#f}.
@end deffn
-@deffn {procedure+} bit-string-length bit-string
+@deffn procedure bit-string-length bit-string
@cindex length, of bit string
Returns the length of @var{bit-string}.
@end deffn
-@deffn {procedure+} bit-string-ref bit-string k
+@deffn procedure bit-string-ref bit-string k
@cindex selection, of bit string component
@cindex component selection, of bit string
Returns @code{#t} if the @var{k}th bit is 1; otherwise returns
@code{#f}. @var{K} must be a valid index of @var{bit-string}.
@end deffn
-@deffn {procedure+} bit-string-set! bit-string k
+@deffn procedure bit-string-set! bit-string k
Sets the @var{k}th bit in @var{bit-string} to 1 and returns an
unspecified value. @var{K} must be a valid index of @var{bit-string}.
@end deffn
-@deffn {procedure+} bit-string-clear! bit-string k
+@deffn procedure bit-string-clear! bit-string k
Sets the @var{k}th bit in @var{bit-string} to 0 and returns an
unspecified value. @var{K} must be a valid index of @var{bit-string}.
@end deffn
-@deffn {procedure+} bit-substring-find-next-set-bit bit-string start end
+@deffn procedure bit-substring-find-next-set-bit bit-string start end
@cindex searching, of bit string
Returns the index of the first occurrence of a set bit in the substring
of @var{bit-string} from @var{start} (inclusive) to @var{end}
@cindex cutting, of bit string
@cindex pasting, of bit strings
-@deffn {procedure+} bit-string-append bit-string-1 bit-string-2
+@deffn procedure bit-string-append bit-string-1 bit-string-2
@cindex appending, of bit strings
Appends the two bit string arguments, returning a newly allocated bit
string as its result. In the result, the bits copied from
copied from @var{bit-string-2}.
@end deffn
-@deffn {procedure+} bit-substring bit-string start end
+@deffn procedure bit-substring bit-string start end
@cindex substring, of bit string
Returns a newly allocated bit string whose bits are copied from
@var{bit-string}, starting at index @var{start} (inclusive) and ending
@node Bitwise Operations on Bit Strings, Modification of Bit Strings, Cutting and Pasting Bit Strings, Bit Strings
@section Bitwise Operations on Bit Strings
-@deffn {procedure+} bit-string-zero? bit-string
+@deffn procedure bit-string-zero? bit-string
Returns @code{#t} if @var{bit-string} contains only 0 bits; otherwise
returns @code{#f}.
@end deffn
-@deffn {procedure+} bit-string=? bit-string-1 bit-string-2
+@deffn procedure bit-string=? bit-string-1 bit-string-2
@cindex equivalence predicate, for bit strings
@cindex comparison, of bit strings
Compares the two bit string arguments and returns @code{#t} if they are the
same length and contain the same bits; otherwise returns @code{#f}.
@end deffn
-@deffn {procedure+} bit-string-not bit-string
+@deffn procedure bit-string-not bit-string
@cindex inverse, of bit string
Returns a newly allocated bit string that is the bitwise-logical
negation of @var{bit-string}.
@end deffn
-@deffn {procedure+} bit-string-movec! target-bit-string bit-string
+@deffn procedure bit-string-movec! target-bit-string bit-string
The destructive version of @code{bit-string-not}. The arguments
@var{target-bit-string} and @var{bit-string} must be bit strings of the
same length. The bitwise-logical negation of @var{bit-string} is
this procedure is unspecified.
@end deffn
-@deffn {procedure+} bit-string-and bit-string-1 bit-string-2
+@deffn procedure bit-string-and bit-string-1 bit-string-2
Returns a newly allocated bit string that is the bitwise-logical ``and''
of the arguments. The arguments must be bit strings of identical
length.
@end deffn
-@deffn {procedure+} bit-string-andc bit-string-1 bit-string-2
+@deffn procedure bit-string-andc bit-string-1 bit-string-2
Returns a newly allocated bit string that is the bitwise-logical ``and''
of @var{bit-string-1} with the bitwise-logical negation of
@var{bit-string-2}. The arguments must be bit strings of identical
length.
@end deffn
-@deffn {procedure+} bit-string-or bit-string-1 bit-string-2
+@deffn procedure bit-string-or bit-string-1 bit-string-2
Returns a newly allocated bit string that is the bitwise-logical
``inclusive or'' of the arguments. The arguments must be bit strings of
identical length.
@end deffn
-@deffn {procedure+} bit-string-xor bit-string-1 bit-string-2
+@deffn procedure bit-string-xor bit-string-1 bit-string-2
Returns a newly allocated bit string that is the bitwise-logical
``exclusive or'' of the arguments. The arguments must be bit strings of
identical length.
@end deffn
-@deffn {procedure+} bit-string-and! target-bit-string bit-string
-@deffnx {procedure+} bit-string-or! target-bit-string bit-string
-@deffnx {procedure+} bit-string-xor! target-bit-string bit-string
-@deffnx {procedure+} bit-string-andc! target-bit-string bit-string
+@deffn procedure bit-string-and! target-bit-string bit-string
+@deffnx procedure bit-string-or! target-bit-string bit-string
+@deffnx procedure bit-string-xor! target-bit-string bit-string
+@deffnx procedure bit-string-andc! target-bit-string bit-string
These are destructive versions of the above operations. The arguments
@var{target-bit-string} and @var{bit-string} must be bit strings of the
same length. Each of these procedures performs the corresponding
@cindex filling, of bit string
@cindex moving, of bit string elements
-@deffn {procedure+} bit-string-fill! bit-string initialization
+@deffn procedure bit-string-fill! bit-string initialization
Fills @var{bit-string} with zeroes if @var{initialization} is @code{#f};
otherwise fills @var{bit-string} with ones. Returns an unspecified
value.
@end deffn
-@deffn {procedure+} bit-string-move! target-bit-string bit-string
+@deffn procedure bit-string-move! target-bit-string bit-string
Moves the contents of @var{bit-string} into @var{target-bit-string}. Both
arguments must be bit strings of the same length. The results of the
operation are undefined if the arguments are the same bit string.
@end deffn
-@deffn {procedure+} bit-substring-move-right! bit-string-1 start1 end1 bit-string-2 start2
+@deffn procedure bit-substring-move-right! bit-string-1 start1 end1 bit-string-2 start2
Destructively copies the bits of @var{bit-string-1}, starting at index
@var{start1} (inclusive) and ending at @var{end1} (exclusive), into
@var{bit-string-2} starting at index @var{start2} (inclusive).
@section Integer Conversions of Bit Strings
@cindex integer, converting to bit string
-@deffn {procedure+} unsigned-integer->bit-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}
@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
@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
@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
@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
@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
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
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
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}.
@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}.
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
@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
@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
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
much faster.
@end deffn
-@deffn {procedure+} symbol<? symbol1 symbol2
+@deffn procedure symbol<? symbol1 symbol2
This procedure computes a total order on symbols. It is equivalent to
@example
@dfn{Cells} are data structures similar to pairs except that they have
only one element. They are useful for managing state.
-@deffn {procedure+} cell? object
+@deffn procedure cell? object
@cindex type predicate, for cell
Returns @code{#t} if @var{object} is a cell; otherwise returns
@code{#f}.
@end deffn
-@deffn {procedure+} make-cell object
+@deffn procedure make-cell object
@cindex construction, of cell
Returns a newly allocated cell whose contents is @var{object}.
@end deffn
-@deffn {procedure+} cell-contents cell
+@deffn procedure cell-contents cell
@cindex selection, of cell component
@cindex component selection, of cell
Returns the current contents of @var{cell}.
@end deffn
-@deffn {procedure+} set-cell-contents! cell object
+@deffn procedure set-cell-contents! cell object
Alters the contents of @var{cell} to be @var{object}. Returns an
unspecified value.
@end deffn
-@deffn {procedure+} bind-cell-contents! cell object thunk
+@deffn procedure bind-cell-contents! cell object thunk
Alters the contents of @var{cell} to be @var{object}, calls @var{thunk}
with no arguments, then restores the original contents of @var{cell} and
returns the value returned by @var{thunk}. This is completely
Definitions}).
@findex define-structure
-@deffn {procedure+} make-record-type type-name field-names
+@deffn procedure make-record-type type-name field-names
@cindex record-type descriptor (defn)
Returns a @dfn{record-type descriptor}, a value representing a new data
type, disjoint from all others. The @var{type-name} argument must be a
unspecified how record-type descriptors are represented.
@end deffn
-@deffn {procedure+} record-constructor record-type [field-names]
+@deffn procedure record-constructor record-type [field-names]
Returns a procedure for constructing new members of the type represented
by @var{record-type}. The returned procedure accepts exactly as many
arguments as there are symbols in the given list, @var{field-names};
list.
@end deffn
-@deffn {procedure+} record-predicate record-type
+@deffn procedure record-predicate record-type
Returns a procedure for testing membership in the type represented by
@var{record-type}. The returned procedure accepts exactly one argument
and returns @code{#t} if the argument is a member of the indicated
record type; it returns @code{#f} otherwise.
@end deffn
-@deffn {procedure+} record-accessor record-type field-name
+@deffn procedure record-accessor record-type field-name
Returns a procedure for reading the value of a particular field of a
member of the type represented by @var{record-type}. The returned
procedure accepts exactly one argument which must be a record of the
@var{record-type}.
@end deffn
-@deffn {procedure+} record-modifier record-type field-name
+@deffn procedure record-modifier record-type field-name
Returns a procedure for writing the value of a particular field of a
member of the type represented by @var{record-type}. The returned
procedure accepts exactly two arguments: first, a record of the
type represented by @var{record-type}.
@end deffn
-@deffn {procedure+} record? object
+@deffn procedure record? object
@cindex type predicate, for record
Returns @code{#t} if @var{object} is a record of any type and @code{#f}
otherwise. Note that @code{record?} may be true of any Scheme value; of
appropriate descriptor.
@end deffn
-@deffn {procedure+} record-type-descriptor record
+@deffn procedure record-type-descriptor record
Returns the record-type descriptor representing the type of
@var{record}. That is, for example, if the returned descriptor were
passed to @code{record-predicate}, the resulting predicate would return
procedure that created @var{record}.
@end deffn
-@deffn {procedure+} record-type? object
+@deffn procedure record-type? object
@cindex type predicate, for record type
Returns @code{#t} if @var{object} is a record-type descriptor; otherwise
returns @code{#f}.
@end deffn
-@deffn {procedure+} record-type-name record-type
+@deffn procedure record-type-name record-type
Returns the type name associated with the type represented by
@var{record-type}. The returned value is @code{eqv?} to the
@var{type-name} argument given in the call to @code{make-record-type}
that created the type represented by @var{record-type}.
@end deffn
-@deffn {procedure+} record-type-field-names record-type
+@deffn procedure record-type-field-names record-type
Returns a list of the symbols naming the fields in members of the type
represented by @var{record-type}. The returned value is @code{equal?}
to the @var{field-names} argument given in the call to
@end example
@end deffn
-@deffn {procedure+} promise? object
+@deffn procedure promise? object
@cindex type predicate, for promise
Returns @code{#t} if @var{object} is a promise; otherwise returns
@code{#f}.
@end deffn
-@deffn {procedure+} promise-forced? promise
+@deffn procedure promise-forced? promise
Returns @code{#t} if @var{promise} has been forced and its value cached;
otherwise returns @code{#f}.
@end deffn
-@deffn {procedure+} promise-value promise
+@deffn procedure promise-value promise
If @var{promise} has been forced and its value cached, this procedure
returns the cached value. Otherwise, an error is signalled.
@end deffn
tail of a stream is not computed until it is referred to.
This allows streams to be used to represent infinitely long lists.
-@deffn {procedure+} stream object @dots{}
+@deffn procedure stream object @dots{}
@cindex construction, of stream
Returns a newly allocated stream whose elements are the arguments. Note
that the expression @code{(stream)} returns the empty stream, or
end-of-stream marker.
@end deffn
-@deffn {procedure+} list->stream 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
@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
@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
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
@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,
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
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
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
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
@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)
@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?
@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?
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
@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
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
@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
@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
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
@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
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
@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
@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
@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
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
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
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}
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
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.
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}
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
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
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
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
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:
@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
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
@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
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
@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
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
@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}.
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.
@noindent
once before calling any of the procedures defined here.
-@deffn {procedure+} make-rb-tree key=? key<?
+@deffn procedure make-rb-tree key=? key<?
This procedure creates and returns a newly allocated red-black tree.
The tree contains no associations. @var{Key=?} and @var{key<?} are
predicates that compare two keys and determine whether they are equal to
of these predicates is true.
@end deffn
-@deffn {procedure+} rb-tree? object
+@deffn procedure rb-tree? object
Returns @code{#t} if @var{object} is a red-black tree, otherwise
returns @code{#f}.
@end deffn
-@deffn {procedure+} rb-tree/insert! rb-tree key datum
+@deffn procedure rb-tree/insert! rb-tree key datum
Associates @var{datum} with @var{key} in @var{rb-tree} and returns an
unspecified value. If @var{rb-tree} already has an association for
@var{key}, that association is replaced. The average and worst-case
the number of assocations in @var{rb-tree}.
@end deffn
-@deffn {procedure+} rb-tree/lookup rb-tree key default
+@deffn procedure rb-tree/lookup rb-tree key default
Returns the datum associated with @var{key} in @var{rb-tree}. If
@var{rb-tree} doesn't contain an association for @var{key},
@var{default} is returned. The average and worst-case times required by
assocations in @var{rb-tree}.
@end deffn
-@deffn {procedure+} rb-tree/delete! rb-tree key
+@deffn procedure rb-tree/delete! rb-tree key
If @var{rb-tree} contains an association for @var{key}, removes it.
Returns an unspecified value. The average and worst-case times required
by this operation are proportional to the logarithm of the number of
assocations in @var{rb-tree}.
@end deffn
-@deffn {procedure+} rb-tree->alist 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
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{key<?} argument used to construct
@var{rb-tree}. The time required by this
operation is proportional to the number of associations in the tree.
@end deffn
-@deffn {procedure+} rb-tree/datum-list rb-tree
+@deffn procedure rb-tree/datum-list rb-tree
Returns a newly allocated list of the datums in @var{rb-tree}. Each
element of the list corresponds to one of the associations in
@var{rb-tree}, so if the tree contains multiple associations with the
@end example
@end deffn
-@deffn {procedure+} rb-tree/equal? rb-tree-1 rb-tree-2 datum=?
+@deffn procedure rb-tree/equal? rb-tree-1 rb-tree-2 datum=?
Compares @var{rb-tree-1} and @var{rb-tree-2} for equality, returning
@code{#t} iff they are equal and @code{#f} otherwise. The trees must
have been constructed with the same equality and order predicates (same
number of associations in the tree.
@end deffn
-@deffn {procedure+} rb-tree/empty? rb-tree
+@deffn procedure rb-tree/empty? rb-tree
Returns @code{#t} iff @var{rb-tree} contains no associations. Otherwise
returns @code{#f}.
@end deffn
-@deffn {procedure+} rb-tree/size rb-tree
+@deffn procedure rb-tree/size rb-tree
Returns the number of associations in @var{rb-tree}, an exact
non-negative integer. The average and worst-case times required by this
operation are proportional to the number of associations in the tree.
@end deffn
-@deffn {procedure+} rb-tree/height rb-tree
+@deffn procedure rb-tree/height rb-tree
Returns the height of @var{rb-tree}, an exact non-negative integer.
This is the length of the longest path from a leaf of the tree to the
root. The average and worst-case times required by this operation are
@end example
@end deffn
-@deffn {procedure+} rb-tree/copy rb-tree
+@deffn procedure rb-tree/copy rb-tree
Returns a newly allocated copy of @var{rb-tree}. The copy is identical
to @var{rb-tree} in all respects, except that changes to @var{rb-tree}
do not affect the copy, and vice versa. The time required by this
operation is proportional to the number of associations in the tree.
@end deffn
-@deffn {procedure+} alist->rb-tree alist key=? key<?
+@deffn procedure alist->rb-tree alist key=? key<?
Returns a newly allocated red-black tree that contains the same
associations as @var{alist}. This procedure is equivalent to:
members in a red/black tree. They are useful for implementing priority
queues.
-@deffn {procedure+} rb-tree/min rb-tree default
+@deffn procedure rb-tree/min rb-tree default
Returns the smallest key in @var{rb-tree}, or @var{default} if the tree
is empty.
@end deffn
-@deffn {procedure+} rb-tree/min-datum rb-tree default
+@deffn procedure rb-tree/min-datum rb-tree default
Returns the datum associated with the smallest key in @var{rb-tree}, or
@var{default} if the tree is empty.
@end deffn
-@deffn {procedure+} rb-tree/min-pair rb-tree
+@deffn procedure rb-tree/min-pair rb-tree
Finds the smallest key in @var{rb-tree} and returns a pair containing
that key and its associated datum. If the tree is empty, returns
@code{#f}.
@end deffn
-@deffn {procedure+} rb-tree/max rb-tree default
+@deffn procedure rb-tree/max rb-tree default
Returns the largest key in @var{rb-tree}, or @var{default} if the tree
is empty.
@end deffn
-@deffn {procedure+} rb-tree/max-datum rb-tree default
+@deffn procedure rb-tree/max-datum rb-tree default
Returns the datum associated with the largest key in @var{rb-tree}, or
@var{default} if the tree is empty.
@end deffn
-@deffn {procedure+} rb-tree/max-pair rb-tree
+@deffn procedure rb-tree/max-pair rb-tree
Finds the largest key in @var{rb-tree} and returns a pair containing
that key and its associated datum. If the tree is empty, returns
@code{#f}.
@end deffn
-@deffn {procedure+} rb-tree/delete-min! rb-tree default
-@deffnx {procedure+} rb-tree/delete-min-datum! rb-tree default
-@deffnx {procedure+} rb-tree/delete-min-pair! rb-tree
-@deffnx {procedure+} rb-tree/delete-max! rb-tree default
-@deffnx {procedure+} rb-tree/delete-max-datum! rb-tree default
-@deffnx {procedure+} rb-tree/delete-max-pair! rb-tree
+@deffn procedure rb-tree/delete-min! rb-tree default
+@deffnx procedure rb-tree/delete-min-datum! rb-tree default
+@deffnx procedure rb-tree/delete-min-pair! rb-tree
+@deffnx procedure rb-tree/delete-max! rb-tree default
+@deffnx procedure rb-tree/delete-max-datum! rb-tree default
+@deffnx procedure rb-tree/delete-max-pair! rb-tree
These operations are exactly like the accessors above, in that they
return information associated with the smallest or largest key, except
that they simultaneously delete that key.
types are created at the beginning of a program and used many times
throughout the program's execution.
-@deffn {procedure+} make-wt-tree-type key<?
+@deffn procedure make-wt-tree-type key<?
This procedure creates and returns a new tree type based on the ordering
predicate @var{key<?}.
@var{Key<?} must be a total ordering, having the property that for all
same call to @code{make-wt-tree-type}.
@end deffn
-@defvr {variable+} number-wt-type
+@defvr variable number-wt-type
A standard tree type for trees with numeric keys. @code{Number-wt-type}
could have been defined by
@end example
@end defvr
-@defvr {variable+} string-wt-type
+@defvr variable string-wt-type
A standard tree type for trees with string keys. @code{String-wt-type}
could have been defined by
@end example
@end defvr
-@deffn {procedure+} make-wt-tree wt-tree-type
+@deffn procedure make-wt-tree wt-tree-type
This procedure creates and returns a newly allocated weight-balanced
tree. The tree is empty, i.e. it contains no associations.
@var{Wt-tree-type} is a weight-balanced tree type obtained by calling
@code{make-wt-tree-type}; the returned tree has this type.
@end deffn
-@deffn {procedure+} singleton-wt-tree wt-tree-type key datum
+@deffn procedure singleton-wt-tree wt-tree-type key datum
This procedure creates and returns a newly allocated weight-balanced
tree. The tree contains a single association, that of @var{datum} with
@var{key}. @var{Wt-tree-type} is a weight-balanced tree type obtained
by calling @code{make-wt-tree-type}; the returned tree has this type.
@end deffn
-@deffn {procedure+} alist->wt-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:
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.
@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
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
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
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
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
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
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}
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
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
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
@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}.
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,
@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.
@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
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,
@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
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
@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
@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
@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
@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}.
(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
@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.
@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
@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
@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
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,@*
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
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}
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
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
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})}
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
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.
@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
@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
@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}.
* Prompting::
* Port Primitives::
* Parser Buffers::
+* Parser Language::
@end menu
@node Ports, File Ports, Input/Output, Input/Output
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}.
@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
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
@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,
@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
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.
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
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.
@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.
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.
``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}.
@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
@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
@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
@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
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
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
@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
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
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
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.
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
@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
@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
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
this does nothing.
@end deffn
-@deffn {procedure+} clear [output-port]
+@deffn procedure clear [output-port]
@cindex console, clearing
@cindex display, clearing
@cindex screen, clearing
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,
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
@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
@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
@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
@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)
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
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
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
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
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
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.
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
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
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.
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,
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
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
@end example
@end deffn
-@deffn {procedure+} port/operation-names port
+@deffn procedure port/operation-names port
Equivalent to
@example
@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?
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
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
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
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
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:
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.
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.
@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
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:
@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
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
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;
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
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
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
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
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
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
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
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
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}.
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
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
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
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
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
@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.
@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}.
@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
@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
@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
@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
@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}.
@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}.
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
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
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
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
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:
@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
@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.
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.
@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
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
@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
@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
@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
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
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
@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
@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
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}.
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
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
@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,
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
@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:
@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
@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
@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
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
@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
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}
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
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.
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.
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
@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
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},
@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
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
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.
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
@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
@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
@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.
``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.
@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.
@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.
@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
@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.
@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}.
@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
@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.
@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.
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.
@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
@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.
@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
@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
@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
@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
@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.
@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.
@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
@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
@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
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.
@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
@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
@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.
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
@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.
@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.
@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.
@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:
@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.
@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
@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
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.
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
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.
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.
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.
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,
@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
@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
@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.
@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
@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
@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
@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
@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)}.
@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
@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
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
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.
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
@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
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}.
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:
(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
@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.
@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:
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:
@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}:
@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
@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}.
@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
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
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
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
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
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
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
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}.
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}
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}
@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
@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
@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
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
@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
@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
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
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
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
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
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},
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
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,
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
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.
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
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
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.
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
@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
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
@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
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
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}.
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
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
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}
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
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
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
@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
@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
@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
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
@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
@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
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
@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
@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
@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
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
@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
@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
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
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
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
@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
@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
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}
@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
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
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
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
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
@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.
@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
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
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
@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
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
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
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
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.
@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
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.
@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
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.
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
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,
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.
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
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.
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
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).
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
(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
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
@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},
@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
(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
@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
@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
@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
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}.
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
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
@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
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.
(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
@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,
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
@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.
@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
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"}
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
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
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
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}.
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
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
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
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
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.
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
(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
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.
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.
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 "<point-size>.<family-name>", for
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,
@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
@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
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
@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
@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
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
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}.
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
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}.
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.
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
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
projects / mit-scheme.git / commitdiff