@iftex
@finalout
@end iftex
-@comment $Id: scheme.texinfo,v 1.64 1997/02/13 02:24:02 cph Exp $
+@comment $Id: scheme.texinfo,v 1.65 1999/02/26 05:49:15 cph Exp $
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename scheme
@settitle MIT Scheme Reference
@ifinfo
This file documents the MIT Scheme system.
-Copyright @copyright{} 1988-97 Massachusetts Institute of Technology
+Copyright @copyright{} 1988-1999 Massachusetts Institute of Technology
-This material was developed by the Scheme project at the Massachusetts
-Institute of Technology, Department of Electrical Engineering and Computer
-Science. Permission to copy this document, to redistribute it, and to use
-it for any purpose is granted, subject to the following restrictions and
-understandings.
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
-@enumerate
-@item
-Any copy made of this document must include this copyright notice in
-full.
-
-@item
-Users of this document agree to make their best efforts (a) to return to
-the MIT Scheme project any improvements or extensions that they make, so
-that these may be included in future releases; and (b) to inform MIT of
-noteworthy uses of this document.
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
-@item
-All materials developed as a consequence of the use of this document shall
-duly acknowledge such use, in accordance with the usual standards of
-acknowledging credit in academic research.
-
-@item
-MIT has made no warrantee or representation that the contents of this
-document will be error-free, and MIT is under no obligation to provide any
-services, by way of maintenance, update, or otherwise.
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
-@item
-In conjunction with products arising from the use of this material, there
-shall be no use of the name of the Massachusetts Institute of Technology
-nor of any adaptation thereof in any advertising, promotional, or sales
-literature without prior written consent from MIT in each case.
-@end enumerate
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Massachusetts Institute of Technology.
@end ifinfo
@titlepage
@title{MIT Scheme Reference Manual}
-@subtitle Edition 1.64
+@subtitle Edition 1.65
@subtitle for Scheme Release 7.5
-@subtitle 12 February 1997
+@subtitle 26 February 1999
@author by Chris Hanson
@author the MIT Scheme Team
@author and a cast of thousands
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988-97 Massachusetts Institute of Technology
-
-This material was developed by the Scheme project at the Massachusetts
-Institute of Technology, Department of Electrical Engineering and Computer
-Science. Permission to copy this document, to redistribute it, and to use
-it for any purpose is granted, subject to the following restrictions and
-understandings.
-
-@enumerate
-@item
-Any copy made of this document must include this copyright notice in
-full.
-
-@item
-Users of this document agree to make their best efforts (a) to return to
-the MIT Scheme project any improvements or extensions that they
-make, so that these may be included in future releases; and (b) to
-inform MIT of noteworthy uses of this document.
+Copyright @copyright{} 1988-1999 Massachusetts Institute of Technology
-@item
-All materials developed as a consequence of the use of this document shall
-duly acknowledge such use, in accordance with the usual standards of
-acknowledging credit in academic research.
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
-@item
-MIT has made no warrantee or representation that the contents of
-this document will be error-free, and MIT is under no obligation to
-provide any services, by way of maintenance, update, or otherwise.
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
-@item
-In conjunction with products arising from the use of this material,
-there shall be no use of the name of the Massachusetts Institute of
-Technology nor of any adaptation thereof in any advertising,
-promotional, or sales literature without prior written consent from
-MIT in each case.
-@end enumerate
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Massachusetts Institute of Technology.
@end titlepage
@node Top, Acknowledgements, (dir), (dir)
* Lambda Expressions::
* Lexical Binding::
-* Dynamic Binding::
+* Dynamic Binding::
* Definitions::
* Assignments::
* Quoting::
Port Primitives
+* Port Types::
* Constructors and Accessors for Ports::
-* Blocking Mode::
-* Terminal Mode::
* Input Port Operations::
* Output Port Operations::
+* Blocking Mode::
+* Terminal Mode::
File-System Interface
* Clipping of Graphics Output::
* Custom Graphics Operations::
* Images::
+* X Graphics:: Graphics on the X Window System
* Win32 Graphics:: Graphics on Microsoft Windows and Windows NT
-* OS/2 Graphics::
-* X Graphics::
-* Starbase Graphics::
+* OS/2 Graphics:: Graphics on IBM OS/2
+
+X Graphics
+
+* X Graphics Type::
+* Utilities for X Graphics::
+* Custom Operations on X Graphics Devices::
Win32 Graphics
* Event Operations for OS/2 Graphics::
* Miscellaneous Operations for OS/2 Graphics::
-X Graphics
-
-* X Graphics Type::
-* Utilities for X Graphics::
-* Custom Operations on X Graphics Devices::
-
Win32 Package Reference
* Win32 Package Overview::
Laboratory and the Laboratory for Computer Science, both of the
Massachusetts Institute of Technology. Support for this research is
provided in part by the Advanced Research Projects Agency of the
-Department of Defense under Office of Naval Research contract
-N00014-92-J-4097 and by the National Science Foundation under grant
-number MIP-9001651.
+Department of Defense and by the National Science Foundation.
@node Overview, Special Forms, Acknowledgements, Top
@chapter Overview
Throughout this manual, we will make frequent references to
@dfn{standard Scheme}, which is the language defined by the document
@cite{Revised^4 Report on the Algorithmic Language Scheme}, by William
-Clinger, Jonathan Rees, et al.@:, or by @sc{ieee} Std. 1178-1990,
+Clinger, Jonathan Rees, et al.@:, or by @sc{ieee} Std.@: 1178-1990,
@cite{IEEE Standard for the Scheme Programming Language} (in fact,
several parts of this document are copied from the @cite{Revised
Report}). MIT Scheme is an extension of standard Scheme.
* Expressions::
@end menu
-@node Notational Conventions, Scheme Concepts, , Overview
+@node Notational Conventions, Scheme Concepts, Overview, Overview
@section Notational Conventions
@cindex notational conventions
@cindex conventions, notational
* Entry Format::
@end menu
-@node Errors, Examples, , Notational Conventions
+@node Errors, Examples, Notational Conventions, Notational Conventions
@subsection Errors
@cindex errors, notational conventions
* Storage Model::
@end menu
-@node Variable Bindings, Environment Concepts, , Scheme Concepts
+@node Variable Bindings, Environment Concepts, Scheme Concepts, Scheme Concepts
@subsection Variable Bindings
@cindex variable binding
@cindex binding, of variable
conditional tests, all values count as true except for @code{#f}, which
counts as false (@pxref{Conditionals}).
-Implementation note: In MIT Scheme, @code{#f} and the empty list
-are the same object, and the printed representation of @code{#f} is
-always @samp{()}. As this contradicts the Scheme standard, MIT
-Scheme will soon be changed to make @code{#f} and the empty list
-different objects.
+Implementation note: In MIT Scheme, @code{#f} and the empty list are the
+same object, and the printed representation of @code{#f} is always
+@samp{()}. As this contradicts the Scheme standard, MIT Scheme will be
+changed to make @code{#f} and the empty list different objects.
@node External Representations, Disjointness of Types, True and False, Scheme Concepts
@subsection External Representations
* Additional Notations::
@end menu
-@node Whitespace, Delimiters, , Lexical Conventions
+@node Whitespace, Delimiters, Lexical Conventions, Lexical Conventions
@subsection Whitespace
@cindex whitespace, in programs (defn)
* Procedure Call Syntax::
@end menu
-@node Literal Expressions, Variable References, , Expressions
+@node Literal Expressions, Variable References, Expressions, Expressions
@subsection Literal Expressions
@cindex literal expression (defn)
access define-syntax macro
and delay make-environment
begin do named-lambda
-bkpt fluid-let or
-case if quasiquote
-cond in-package quote
-cons-stream lambda scode-quote
-declare let sequence
-default-object? let* set!
-define let-syntax the-environment
-define-integrable letrec unassigned?
-define-macro local-declare using-syntax
-define-structure
+case fluid-let or
+cond if quasiquote
+cons-stream in-package quote
+declare lambda scode-quote
+default-object? let sequence
+define let* set!
+define-integrable let-syntax the-environment
+define-macro letrec unassigned?
+define-structure local-declare using-syntax
@end group
@end example
@menu
* Lambda Expressions::
* Lexical Binding::
-* Dynamic Binding::
+* Dynamic Binding::
* Definitions::
* Assignments::
* Quoting::
* Structure Definitions::
@end menu
-@node Lambda Expressions, Lexical Binding, , Special Forms
+@node Lambda Expressions, Lexical Binding, Special Forms, Special Forms
@section Lambda Expressions
@deffn {special form} lambda formals expression expression @dots{}
variable is set to the new value. In addition, side effects to the
variable that occur both inside and outside of body are preserved, even
if continuations are used to jump in and out of body repeatedly.
+@end deffn
Here is a complicated example that shows the interaction between dynamic
binding and continuations:
-@page
@example
@group
(define (complicated-dynamic-binding)
the body has been preserved. Finally, we exit body normally, and write
@samp{4}, demonstrating that the side effect that occurred outside of
the body was also preserved.
-@end deffn
@node Definitions, Assignments, Dynamic Binding, Special Forms
@section Definitions
* Internal Definitions::
@end menu
-@node Top-Level Definitions, Internal Definitions, , Definitions
+@node Top-Level Definitions, Internal Definitions, Definitions, Definitions
@subsection Top-Level Definitions
@cindex top-level definition
@cindex definition, top-level
@example
@group
-`(list ,(+ 1 2) 4) @result{} (list 3 4)
+`(list ,(+ 1 2) 4) @result{} (list 3 4)
-(let ((name 'a)) `(list ,name ',name)) @result{} (list a 'a)
+(let ((name 'a)) `(list ,name ',name)) @result{} (list a 'a)
-`(a ,(+ 1 2) ,@@(map abs '(4 -5 6)) b) @result{} (a 3 4 5 6 b)
+`(a ,(+ 1 2) ,@@(map abs '(4 -5 6)) b) @result{} (a 3 4 5 6 b)
`((foo ,(- 10 3)) ,@@(cdr '(c)) . ,(car '(cons)))
- @result{} ((foo 7) . cons)
+ @result{} ((foo 7) . cons)
`#(10 5 ,(sqrt 4) ,@@(map sqrt '(16 9)) 8)
- @result{} #(10 5 2 4 3 8)
+ @result{} #(10 5 2 4 3 8)
-`,(+ 2 3) @result{} 5
+`,(+ 2 3) @result{} 5
@end group
@end example
@section Sequencing
@cindex sequencing expressions
+The @code{begin} special form is used to evaluate expressions in a
+particular order.
+
@deffn {special form} begin expression expression @dots{}
The @var{expression}s are evaluated sequentially from left to right, and
the value of the last @var{expression} is returned. This expression
@example
@group
-(define-structure (foo (constructor make-foo (#!optional a b)))
+(define-structure (foo
+ (constructor make-foo (#!optional a b)))
(a 6 read-only #t)
(b 9))
@end group
@end example
@end deffn
+@deffn {structure option} type-descriptor name
+This option cannot be used with the @code{type} or @code{named} options.
+
+By default, structures are implemented as records. The name of the
+structure is defined to hold the type descriptor of the record defined
+by the structure. The @code{type-descriptor} option specifies a
+different name to hold the type descriptor.
+
+@example
+@group
+(define-structure foo a b)
+foo @result{} #[record-type 18]
+
+(define-structure (bar (type-descriptor bar-rtd)) a b)
+bar @error{} Unbound variable: bar
+bar-rtd @result{} #[record-type 19]
+@end group
+@end example
+@end deffn
+
@deffn {structure option} conc-name [name]
By default, the prefix for naming accessors and modifiers is the name of
the structure followed by a hyphen. The @code{conc-name} option can be
@end deffn
@deffn {structure option} type representation-type
+This option cannot be used with the @code{type-descriptor} option.
+
By default, structures are implemented as records. The @code{type}
option overrides this default, allowing the programmer to specify that
the structure be implemented using another data type. The option value
@deffn {structure option} named [expression]
This is valid only in conjunction with the @code{type} option and
specifies that the structure instances be tagged to make them
-identifiable as instances of this structure type. In the usual case,
-where @var{expression} is not given, the @code{named} option causes a
-type descriptor and predicate to be defined for the structure (recall
-that the @code{type} option without @code{named} suppresses their
-definition), and also defines a default unparser method for the
-structure instances (which can be overridden by the
+identifiable as instances of this structure type. This option cannot be
+used with the @code{type-descriptor} option.
+
+In the usual case, where @var{expression} is not given, the @code{named}
+option causes a type descriptor and predicate to be defined for the
+structure (recall that the @code{type} option without @code{named}
+suppresses their definition), and also defines a default unparser method
+for the structure instances (which can be overridden by the
@code{print-procedure} option). If the default unparser method is not
wanted then the @code{print-procedure} option should be specified as
-@code{#F}. This cases the structure to be printed in its native
+@code{#F}. This causes the structure to be printed in its native
representation, as a list or vector, which includes the type descriptor.
The type descriptor is a unique object, @emph{not} a record type, that
describes the structure instances and is additionally stored in the
@example
@group
-(define-structure (foo (type vector) (initial-offset 3)) a b c)
+(define-structure (foo (type vector) (initial-offset 3))
+ a b c)
(make-foo 1 2 3) @result{} #(() () () 1 2 3)
@end group
@end example
or bit pattern to represent both.
@end deffn
+@page
@deffn procedure eq? obj1 obj2
@code{eq?} is similar to @code{eqv?} except that in some cases it is
capable of discerning distinctions finer than those detectable by
it obeys the same constraints as @code{eqv?}.
@end deffn
+@page
@deffn procedure equal? obj1 obj2
@cindex circular structure
@code{equal?} recursively compares the contents of pairs, vectors, and
* Random Numbers::
@end menu
-@node Numerical types, Exactness, , Numbers
+@node Numerical types, Exactness, Numbers, Numbers
@section Numerical types
@cindex numerical types
@var{precision})} digits to the left of the decimal point.
@item format-type
-One of the following symbols: @code{normal}, @code{scientific}, or
+One of the symbols: @code{normal}, @code{scientific}, or
@code{engineering}. This specifies the format in which the number will
-be printed. @code{scientific} specifies that the number will be printed
+be printed.@* @code{scientific} specifies that the number will be printed
using scientific notation: @code{@var{x}.@var{xxx}e@var{yyy}}. In other
words, the number is printed as a mantissa between zero inclusive and
ten exclusive, and an exponent. @code{engineering} is like
If it is bound to a value different from those described here,
@code{number->string} issues a warning and acts as though the value had
been @code{normal}.
+@end defvr
@noindent
-Some examples:
+Some examples of @code{flonum-unparser-cutoff}:
@example
-@group
(number->string (* 4 (atan 1 1)))
@result{} "3.141592653589793"
(fluid-let ((flonum-unparser-cutoff '(relative 5)))
(fluid-let ((flonum-unparser-cutoff '(absolute -5)))
(number->string (* 4e10 (atan 1 1))))
@result{} "31415900000."
-@end group
@end example
-@end defvr
@deffn procedure string->number string [radix]
Returns a number of the maximally precise representation expressed by
* Flonum Operations::
@end menu
-@node Fixnum Operations, Flonum Operations, , Fixnum and Flonum Operations
+@node Fixnum Operations, Flonum Operations, Fixnum and Flonum Operations, Fixnum and Flonum Operations
@subsection Fixnum Operations
@cindex fixnum (defn)
* Character Sets::
@end menu
-@node External Representation of Characters, Comparison of Characters, , Characters
+@node External Representation of Characters, Comparison of Characters, Characters, Characters
@section External Representation of Characters
@cindex external representation, for character
@noindent
@cindex newline character (defn)
@findex #\newline
-In addition, @code{#\newline} is either @code{#\linefeed} or
-@code{#\return}, depending on the operating system that Scheme is
-running under. All of the standard @sc{ascii} names for non-printing
-characters are supported:
+In addition, @code{#\newline} is the same as @code{#\linefeed} (but this
+may change in the future, so you should not depend on it). All of the
+standard @sc{ascii} names for non-printing characters are supported:
@example
@group
* Byte Vectors::
@end menu
-@node Construction of Strings, Selecting String Components, , Strings
+@node Construction of Strings, Selecting String Components, Strings, Strings
@section Construction of Strings
@cindex construction, of string
(string) @result{} ""
@end group
@end example
-
-@findex char->string
-For compatibility with old code, @code{char->string} is a synonym for
-this procedure.
@end deffn
@deffn procedure list->string char-list
@example
@group
-(list->string '(#\a #\b)) @result{} "ab"
-(string->list "Hello") @result{} (#\H #\e #\l #\l #\o)
+(list->string '(#\a #\b)) @result{} "ab"
+(string->list "Hello") @result{} (#\H #\e #\l #\l #\o)
@end group
@end example
@end deffn
(dynamic-wind
(lambda ()
(set! length (string-length string))
- (set-string-length! string (string-maximum-length string)))
+ (set-string-length! string
+ (string-maximum-length string)))
(lambda ()
(string-copy string))
(lambda ()
@var{if-gt} is applied. The value of the procedure is the value of the
thunk that is applied.
-@code{string-compare} distinguishes uppercase and lowercase letters;
+@code{string-compare} distinguishes uppercase and lowercase letters;@*
@code{string-compare-ci} does not.
@example
(string-find-next-char-in-set my-string char-set:alphabetic)
@result{} @r{start position of the first word in} my-string
@r{; Can be used as a predicate:}
-(if (string-find-next-char-in-set my-string (char-set #\( #\) ))
+(if (string-find-next-char-in-set my-string
+ (char-set #\( #\) ))
'contains-parentheses
'no-parentheses)
@end group
a string (it would have been easier to use @code{string-append}):
@example
@group
-(define answer (make-string 9 #\*)) @result{} @r{unspecified}
-answer @result{} "*********"
-(substring-move-left! "start" 0 5 answer 0) @result{} @r{unspecified}
-answer @result{} "start****"
-(substring-move-left! "-end" 0 4 answer 5) @result{} @r{unspecified}
-answer @result{} "start-end"
+(define answer (make-string 9 #\*)) @result{} @r{unspecified}
+answer @result{} "*********"
+(substring-move-left! "start" 0 5 answer 0) @result{} @r{unspecified}
+answer @result{} "start****"
+(substring-move-left! "-end" 0 4 answer 5) @result{} @r{unspecified}
+answer @result{} "start-end"
@end group
@end example
@end deffn
* Miscellaneous List Operations::
@end menu
-@node Pairs, Construction of Lists, , Lists
+@node Pairs, Construction of Lists, Lists, Lists
@section Pairs
This section describes the simple operations that are available for
@cindex vector, converting to list
@findex list->vector
@code{vector->list} returns a newly allocated list of the elements of
-@var{vector}. @code{subvector->list} returns a newly allocated list of the
-elements of the given subvector. The inverse of @code{vector->list} is
-@code{list->vector}.
+@var{vector}.@* @code{subvector->list} returns a newly allocated list of
+the elements of the given subvector. The inverse of @code{vector->list}
+is @code{list->vector}.
@example
(vector->list '#(dah dah didah)) @result{} (dah dah didah)
@example
@group
-(define delv (delete-member-procedure list-deletor eqv?))
-(define delete! (delete-member-procedure list-deletor! equal?))
+(define delv
+ (delete-member-procedure list-deletor eqv?))
+(define delete!
+ (delete-member-procedure list-deletor! equal?))
@end group
@end example
@end deffn
@example
@group
-(reverse '(a b c)) @result{} (c b a)
-(reverse '(a (b c) d (e (f)))) @result{} ((e (f)) d (b c) a)
+(reverse '(a b c)) @result{} (c b a)
+(reverse '(a (b c) d (e (f)))) @result{} ((e (f)) d (b c) a)
@end group
@end example
@end deffn
* Modifying Vectors::
@end menu
-@node Construction of Vectors, Selecting Vector Components, , Vectors
+@node Construction of Vectors, Selecting Vector Components, Vectors, Vectors
@section Construction of Vectors
@cindex construction, of vector
@example
@group
-(vector-map '#((a b) (d e) (g h)) cadr) @result{} #(b e h)
-(vector-map '#(1 2 3 4) (lambda (n) (expt n n))) @result{} #(1 4 27 256)
-(vector-map '#(5 7 9) +) @result{} #(5 7 9)
+(vector-map '#((a b) (d e) (g h)) cadr) @result{} #(b e h)
+(vector-map '#(1 2 3 4) (lambda (n) (expt n n)))
+ @result{} #(1 4 27 256)
+(vector-map '#(5 7 9) +) @result{} #(5 7 9)
@end group
@end example
@end deffn
@example
@group
(define (translate number)
- (vector-binary-search '#((1 . i) (2 . ii) (3 . iii) (6 . vi))
- < car number))
+ (vector-binary-search '#((1 . i)
+ (2 . ii)
+ (3 . iii)
+ (6 . vi))
+ < car number))
(translate 2) @result{} (2 . ii)
(translate 4) @result{} #F
@end group
* Integer Conversions of Bit Strings::
@end menu
-@node Construction of Bit Strings, Selecting Bit String Components, , Bit Strings
+@node Construction of Bit Strings, Selecting Bit String Components, Bit Strings, Bit Strings
@section Construction of Bit Strings
@cindex construction, of bit string
(define (scan-bitstring bs)
(let ((end (bit-string-length bs)))
(let loop ((start 0))
- (let ((next (bit-substring-find-next-set-bit bs start end)))
+ (let ((next
+ (bit-substring-find-next-set-bit bs start end)))
(if next
(begin
(write-line next)
* Weak Pairs::
@end menu
-@node Booleans, Symbols, , Miscellaneous Datatypes
+@node Booleans, Symbols, Miscellaneous Datatypes, Miscellaneous Datatypes
@section Booleans
@findex #t
unspecified. The symbol @var{field-name} must be a member of the list
of field names in the call to @code{make-record-type} that created the
type represented by @var{record-type}.
-
-@findex record-updater
-For compatibility with old code, @code{record-updater} is a synonym for
-this procedure.
@end deffn
@deffn {procedure+} record? object
@var{stream}s as its arguments.
@end deffn
-@findex the-empty-stream
-@findex head
-@findex tail
-@findex empty-stream?
-The following are supported for compatibility with old code. Please do
-not use these for new code. The variable @code{the-empty-stream} is
-bound to the end-of-stream marker; use @code{(stream)} in new code.
-@code{head} is a synonym for @code{stream-car}. @code{tail} is a
-synonym for @code{stream-cdr}. @code{empty-stream?} is a synonym for
-@code{stream-null?}.
-
@node Weak Pairs, , Streams, Miscellaneous Datatypes
@section Weak Pairs
be any type of object and that it does not prevent the keys from being
reclaimed by the garbage collector. However, two linear-time lookups
must be performed, one for each key, whereas for traditional property
-lists only one is lookup required for both keys.
+lists only one lookup is required for both keys.
@item
@dfn{Hash tables} are a powerful mechanism with constant-time access to
* Weight-Balanced Trees::
@end menu
-@node Association Lists, 1D Tables, , Associations
+@node Association Lists, 1D Tables, Associations, Associations
@section Association Lists
@comment **** begin CLTL ****
@group
(2d-put! 'foo 'bar 5)
(2d-put! 'foo 'baz 6)
-(2d-get-alist-x 'foo) @result{} ((baz . 6) (bar . 5))
+(2d-get-alist-x 'foo) @result{} ((baz . 6) (bar . 5))
@end group
@end example
@end deffn
@group
(2d-put! 'bar 'foo 5)
(2d-put! 'baz 'foo 6)
-(2d-get-alist-y 'foo) @result{} ((baz . 6) (bar . 5))
+(2d-get-alist-y 'foo) @result{} ((baz . 6) (bar . 5))
@end group
@end example
@end deffn
* Low-Level Hash Table Operations::
@end menu
-@node Construction of Hash Tables, Basic Hash Table Operations, , Hash Tables
+@node Construction of Hash Tables, Basic Hash Table Operations, Hash Tables, Hash Tables
@subsection Construction of Hash Tables
@cindex construction, of hash table
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.
-
-@findex make-symbol-hash-table
-For compatibility with old code, @code{make-symbol-hash-table} is a
-synonym for this procedure.
@end deffn
@deffn {procedure+} make-eqv-hash-table [initial-size]
weakly, except that booleans, characters, and numbers are held strongly.
These hash tables are a little slower than those made by
@code{make-eq-hash-table}.
-
-@findex make-object-hash-table
-For compatibility with old code, @code{make-object-hash-table} is a
-synonym for this procedure.
@end deffn
@deffn {procedure+} make-equal-hash-table [initial-size]
@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
-proportional to the number of associations in the table.
+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
element of the list corresponds to one of the associations in
@var{hash-table}; if the table contains multiple associations with the
same datum, so will this list. The average and worst-case times
-required by this operation are proportional to the number of
-associations in the table.
+required by this operation are linear in the number of associations in
+the table.
@end deffn
@deffn {procedure+} hash-table/for-each hash-table procedure
size during the growth phase and a small one during the static phase.
The default rehash size of a newly constructed hash table is @code{2.0}.
-@strong{Note well:} The use of an exact positive integer for a rehash
+@strong{Warning}: The use of an exact positive integer for a rehash
size is almost always undesirable; this option is provided solely for
compatibility with the Common Lisp hash-table mechanism. The reason for
this has to do with the time penalty for resizing the hash table. The
@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 to
-@code{hash-table/constructor} define the characteristics of the hash
-table as follows:
+(@pxref{Construction of Hash Tables}). The arguments define the
+characteristics of the hash table as follows:
@table @var
@item key-hash
@var{key-hash} always returns the same value for the same arguments.
The default value of this argument is @code{#f}.
@end table
+@end deffn
+@noindent
For example, here is how the constructors for ordinary hash tables could
be defined:
@group
(define (strong-hash-table/constructor key-hash key=?
#!optional rehash-after-gc?)
- (hash-table/constructor key-hash key=? cons #t car cdr set-cdr!
+ (hash-table/constructor key-hash key=?
+ cons #t car cdr set-cdr!
(if (default-object? rehash-after-gc?)
#f
rehash-after-gc?)))
rehash-after-gc?)))
@end group
@end example
-@end deffn
@deffn {procedure+} hash-table/key-hash hash-table
@deffnx {procedure+} hash-table/key=? 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 of these procedures corresponds to an argument of
-@code{hash-table/constructor}. When called, each procedure returns the
-value of the corresponding argument that was used to construct
-@var{hash-table}.
+Each procedure returns the value of the corresponding argument that was
+used to construct @var{hash-table}.
@end deffn
The following procedures return the contents of a hash table as a
number, unlike an object's address, is unchanged by garbage collection.
The object-hashing facility is useful in conjunction with hash tables,
but it may be used for other things as well. In particular, it is used
-in the generation of the written representation for some objects
+in the generation of the written representation for many objects
(@pxref{Custom Output}).
All of these procedures accept an optional argument called @var{table};
@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
+additional optional argument, @var{insert?}. If @var{insert?}@: is
supplied and is @code{#f}, @code{object-hash} will return an integer for
@var{object} only if there is already an association in the table;
otherwise, it will return @code{#f}. If @var{insert?} is not supplied,
@end example
@end deffn
+The following operations provide access to the smallest and largest
+members in a red/black tree. They are useful for implementing priority
+queues.
+
+@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
+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
+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
+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
+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
+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
+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.
+@end deffn
+
@node Weight-Balanced Trees, , Red-Black Trees, Associations
@section Weight-Balanced Trees
* Indexing Operations on Weight-Balanced Trees::
@end menu
-@node Construction of Weight-Balanced Trees, Basic Operations on Weight-Balanced Trees, , Weight-Balanced Trees
+@node Construction of Weight-Balanced Trees, Basic Operations on Weight-Balanced Trees, Weight-Balanced Trees, Weight-Balanced Trees
@subsection Construction of Weight-Balanced Trees
Binary trees require there to be a total order on the keys used to
@example
@group
(define (wt-tree/union tree1 tree2)
- (wt-tree/union-merge tree1 tree2 (lambda (key val1 val2) val2)))
+ (wt-tree/union-merge tree1 tree2
+ (lambda (key val1 val2) val2)))
@end group
@end example
@end deffn
@code{wt-tree/index} returns the @var{index}th key,
@code{wt-tree/index-datum} returns the datum associated with the
@var{index}th key and @code{wt-tree/index-pair} returns a new pair
-@code{(@var{key} . @var{datum})} which is the @code{cons} of the @var{index}th
-key and its datum. The average and worst-case times required by this
-operation are proportional to the logarithm of the number of
-associations in the tree.
+@code{(@var{key} . @var{datum})} which is the @code{cons} of the
+@var{index}th key and its datum. The average and worst-case times
+required by this operation are proportional to the logarithm of the
+number of associations in the tree.
These operations signal a condition of type
@code{condition-type:bad-range-argument} if @var{index}@code{<0} or if
@example
@group
-median: (wt-tree/index @var{wt-tree} (quotient (wt-tree/size @var{wt-tree}) 2))
-maximum: (wt-tree/index @var{wt-tree} (- (wt-tree/size @var{wt-tree}) 1))
+median: (wt-tree/index @var{wt-tree}
+ (quotient (wt-tree/size @var{wt-tree})
+ 2))
+maximum: (wt-tree/index @var{wt-tree}
+ (- (wt-tree/size @var{wt-tree})
+ 1))
@end group
@end example
@end deffn
proportional to the logarithm of the number of associations in the tree.
These operations signal an error if the tree is empty.
-They could be written
+They could have been written
@example
@group
-(define (wt-tree/min tree) (wt-tree/index tree 0))
-(define (wt-tree/min-datum tree) (wt-tree/index-datum tree 0))
-(define (wt-tree/min-pair tree) (wt-tree/index-pair tree 0))
+(define (wt-tree/min tree)
+ (wt-tree/index tree 0))
+(define (wt-tree/min-datum tree)
+ (wt-tree/index-datum tree 0))
+(define (wt-tree/min-pair tree)
+ (wt-tree/index-pair tree 0))
@end group
@end example
@end deffn
* Application Hooks::
@end menu
-@node Procedure Operations, Primitive Procedures, , Procedures
+@node Procedure Operations, Primitive Procedures, Procedures, Procedures
@section Procedure Operations
@deffn procedure apply procedure object object @dots{}
@deffn {procedure+} within-continuation continuation thunk
@cindex continuation, alternate invocation
@cindex escape procedure, alternate invocation
-@var{Continuation} must be a continuation produced by
-@code{call-with-current-continuation}.
-@var{Thunk} must be a procedure of no arguments.
-Conceptually, @code{within-continuation} invokes @var{continuation} on
-the result of invoking @var{thunk}, but @var{thunk} is executed in the
-dynamic context of @var{continuation}. In other words, the ``current''
-continuation is abandoned before @var{thunk} is invoked.
+@var{Thunk} must be a procedure of no arguments. Conceptually,@*
+@code{within-continuation} invokes @var{continuation} on the result of
+invoking @var{thunk}, but @var{thunk} is executed in the dynamic context
+of @var{continuation}. In other words, the ``current'' continuation is
+abandoned before @var{thunk} is invoked.
@end deffn
@deffn {procedure+} dynamic-wind before-thunk action-thunk after-thunk
would occur in the @var{after-thunk}.
@end deffn
-The following two procedures support multiple values. A future revision
-of the Scheme standard will support a facility similar to, but almost
-certainly different from, this one.
+The following two procedures support multiple values.
@deffn {procedure+} call-with-values thunk procedure
@cindex multiple values, from procedure
* Interpreter Environments::
@end menu
-@node Environment Operations, Environment Variables, , Environments
+@node Environment Operations, Environment Variables, Environments, Environments
@section Environment Operations
Environments are first-class objects in MIT Scheme. An environment
@code{user-initial-environment}) are already interpreter environments,
it does no harm to use such operations on them.
+@strong{Warning}: A future release of MIT Scheme will support hygenic
+macros, which are incompatible with non-top-level instances of
+@code{make-environment} and @code{the-environment}. At that time, other
+uses of these constructs will be disallowed.
+
@deffn {special form+} make-environment expression @dots{}
@cindex construction, of environment
Produces a new environment that is a child of the environment in which
* Port Primitives::
@end menu
-@node Ports, File Ports, , Input/Output
+@node Ports, File Ports, Input/Output, Input/Output
@section Ports
@cindex port (defn)
@code{output-port?}.
@end deffn
-@deffn {procedure+} guarantee-input-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 an input
-port, output port, or @sc{i/o} port, respectively. Otherwise they
+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
return @var{object}.
@findex condition-type:wrong-type-argument
@end deffn
@cindex output port, console
@code{console-i/o-port} is an @sc{i/o} port that communicates with the
``console''. Under unix, the console is the controlling terminal of the
-Scheme process. Under Windows and OS/2, the console is the window that
-is created when Scheme starts up.
+Scheme process. Under Windows and OS/2, the console is the window
+that is created when Scheme starts up.
This variable is rarely used; instead programs should use one of the
standard ports defined above. This variable should not be modified.
-
-@findex console-input-port
-@findex console-output-port
-For compatibility with old code, @code{console-input-port} and
-@code{console-output-port} are synonyms for this variable.
@end defvr
@deffn {procedure+} close-port port
-@deffnx procedure close-input-port port
-@deffnx procedure close-output-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. @code{close-input-port} and
-@code{close-output-port} are synonyms for @code{close-port} that are
-defined for compatibility with standard Scheme.
+file port, the file is closed.
+@end deffn
+
+@deffn procedure close-input-port port
+Closes @var{port} and returns an unspecified value. @var{Port} must be
+an input port or an @sc{i/o} port; if it is an @sc{i/o} port, then only
+the input side of the port is closed.
+@end deffn
+
+@deffn procedure close-output-port port
+Closes @var{port} and returns an unspecified value. @var{Port} must be
+an output port or an @sc{i/o} port; if it is an @sc{i/o} port, then only
+the output side of the port is closed.
@end deffn
@node File Ports, String Ports, Ports, Input/Output
Any file can be opened in one of two modes, @dfn{normal} or
@dfn{binary}. Normal mode is for accessing text files, and binary mode
is for accessing other files. Unix does not distinguish these modes,
-but @sc{dos}, Windows, and OS/2 do: in normal mode, their
-file ports perform @dfn{newline translation}, mapping between the
-carriage-return/linefeed sequence that terminates text lines in files,
-and the @code{#\newline} that terminates lines in Scheme. In binary
-mode, @sc{ms-dos} ports do not perform newline translation. Unless
-otherwise mentioned, the procedures in this section open files in normal
-mode.
+but Windows and OS/2 do: in normal mode, their file ports perform
+@dfn{newline translation}, mapping between the carriage-return/linefeed
+sequence that terminates text lines in files, and the @code{#\newline}
+that terminates lines in Scheme. In binary mode, such ports do not
+perform newline translation. Unless otherwise mentioned, the procedures
+in this section open files in normal mode.
@deffn procedure open-input-file filename
@cindex construction, of file input port
@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 accumulated output to the
-port as a newly allocated string.
+@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
In MIT Scheme, if @var{input-port} is an interactive input port and no
characters are immediately available, @code{read-char} will hang waiting
-for input.
+for input, even if the port is in non-blocking mode.
@end deffn
@deffn procedure peek-char [input-port]
In MIT Scheme, if @var{input-port} is an interactive input port and no
characters are immediately available, @code{peek-char} will hang waiting
-for input.
+for input, even if the port is in non-blocking mode.
@end deffn
@deffn procedure char-ready? [input-port]
encounters end of file. The port is updated to point to the terminating
character, or to end of file if no terminating character was found.
@code{read-string} returns the characters, up to but excluding the
-terminating character, as a newly allocated string. However, if end of
-file was encountered before any characters were read, @code{read-string}
-returns an end-of-file object.
+terminating character, as a newly allocated string.
+
+This procedure ignores the blocking mode of the port, blocking
+unconditionally until it sees either a delimiter or eof of file. If end
+of file is encountered before any characters are read, an end-of-file
+object is returned.
@findex read-char
On many input ports, this operation is significantly faster than the
'()
(begin
(read-char input-port)
- (cons char (loop (peek-char input-port))))))))))
+ (cons char
+ (loop (peek-char input-port))))))))))
@end group
@end example
@end deffn
+@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 string.
+
+This procedure ignores the blocking mode of the port, blocking
+unconditionally until it has read an entire line. If end of file is
+encountered before any characters are read, an end-of-file object is
+returned.
+@end deffn
+
+@deffn {procedure+} read-string! string [start [end [input-port]]]
+@code{read-string!} fills 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 port. The region is
+specified by @var{start} and @var{end}, which default to @code{0} and
+@var{string}'s length, respectively.
+
+The returned value is the number of characters written to @var{string}.
+However, there are several interesting cases to consider:
+
+@itemize @bullet
+@item
+If @code{read-string!} is called when @var{input-port} is at
+``end-of-file'', then the returned value is @code{0}. Note that
+``end-of-file'' can mean a file port that is at the file's end, a string
+port that is at the string's end, or any other port that will never
+produce more characters.
+
+@item
+If @var{input-port} is an interactive port (e.g.@: a terminal), and one
+or more characters are immediately available, the region is filled using
+the available characters. The procedure then returns immediately, even
+if the number of characters is less than the size of the region. The
+returned value is the number of characters actually written.
+
+@item
+If @var{input-port} is an interactive port and no characters are
+immediately available, the result of the operation depends on the
+blocking mode of the port. If the port is in non-blocking mode,
+@code{read-string!} immediately returns the value @code{#f}. Otherwise,
+the operation blocks until a character is available. As soon as at
+least one character is available, the region is filled with the
+available characters, and the number of characters written is
+immediately returned (even if the number available is insufficient to
+fill the region).
+@end itemize
+
+The importance of @code{read-string!} is that it is both flexible and
+extremely fast.
+@end deffn
+
@node Output Procedures, Format, Input Procedures, Input/Output
@section Output Procedures
@cindex output procedures
unless the buffer is full.
@cindex discretionary flushing, of buffered output
-@findex discretionary-output-flush
+@findex discretionary-flush-output
However, the standard output procedures described in this section
perform what is called @dfn{discretionary} flushing of the buffer.
Discretionary output flushing works as follows. After a procedure
performs its output (writing characters to the output buffer), it checks
to see if the port implements an operation called
-@code{discretionary-output-flush}. If so, then that operation is
+@code{discretionary-flush-output}. If so, then that operation is
invoked to flush the buffer. At present, only the console port defines
-@code{discretionary-output-flush}; this is used to guarantee that output
+@code{discretionary-flush-output}; this is used to guarantee that output
to the console appears immediately after it is written, without
requiring calls to @code{flush-output}.
All optional arguments called @var{output-port}, if not supplied,
default to the current 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 write-char char [output-port]
@cindex character, output to port
Writes @var{char} (the character itself, not a written representation of
@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
-writing the contents of string, one character at a time using
+writing the contents of @var{string}, one character at a time using
@code{write-char}, except that it is usually much faster.
@end deffn
@end deffn
@deffn {procedure+} fresh-line [output-port]
-Some output ports are able to tell whether or not they are at the
+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
already at the beginning of a line. If @var{output-port} is not such a
unspecified value.
@end deffn
+@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]
@cindex console, ringing the bell
@cindex ringing the console bell
@example
@group
(define (type-clash-error procedure arg spec actual)
- (format #t
- "~%Procedure ~S~%requires its %A argument ~
- to be of type ~S,~%but it was called with ~
- an argument of type ~S.~%"
- procedure arg spec actual))
+ (format
+ #t
+ "~%Procedure ~S~%requires its %A argument ~
+ to be of type ~S,~%but it was called with ~
+ an argument of type ~S.~%"
+ procedure arg spec actual))
@end group
@end example
-@code{(type-clash-error 'vector-ref "first" 'integer 'vector)} prints:
-
@example
@group
+(type-clash-error 'vector-ref
+ "first"
+ 'integer
+ 'vector)
+
+@r{prints}
+
Procedure vector-ref
requires its first argument to be of type integer,
but it was called with an argument of type vector.
defaults to the value of @code{(interaction-i/o-port)}; this is
initially the console @sc{i/o} port.
-The required argument @var{prompt} must be a string.
-
@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
If @var{prompt} is a string, it is used verbatim as the prompt string.
Otherwise, it must be a pair whose car is @code{standard} and whose cdr
-is a string; in this case the prompt string is formed by appending a
-space to the cdr string, unless it already ends in a space or is an
-empty string.
+is a string; in this case the prompt string is formed by prepending to
+the string the current @sc{rep} loop ``level number'' and a space.
+Also, a space is appended to the string, unless it already ends in a
+space or is an empty string.
-The default behavior of this procedure is to print two newlines, the
-current @sc{rep} loop ``level number'', a space, and the prompt string;
-flush the output buffer; then read an object and return it.
+The default behavior of this procedure is to print a fresh line, a
+newline, and the prompt string; flush the output buffer; then read an
+object and return it.
Under Edwin and Emacs, before the object is read, the interaction buffer
is put into a mode that allows expressions to be edited and submitted
@code{char-graphic?}. If at all possible, the character is read from
the user interface using a mode that reads the character as a single
keystroke; in other words, it should not be necessary for the user to
-follow the character with a carriage return or similar rubbish.
+follow the character with a carriage return or something similar.
@findex debug
@findex where
If @var{prompt} is a string, it is used verbatim as the prompt string.
Otherwise, it must be a pair whose car is @code{standard} and whose cdr
-is a string; in this case the prompt string is formed by appending a
-space to the cdr string, unless it already ends in a space or is an
-empty string.
+is a string; in this case the prompt string is formed by prepending to
+the string the current @sc{rep} loop ``level number'' and a space.
+Also, a space is appended to the string, unless it already ends in a
+space or is an empty string.
-The default behavior of this procedure is to print two newlines, the
-current @sc{rep} loop ``level number'', a space, and the prompt string;
-flush the output buffer; read a character in raw mode, echo that
-character, and return it.
+The default behavior of this procedure is to print a fresh line, a
+newline, and the prompt string; flush the output buffer; read a
+character in raw mode, echo that character, and return it.
Under Edwin and Emacs, instead of reading a character, the interaction
buffer is put into a mode in which graphic characters submit themselves
@var{prompt}, unless @var{prompt} already ends in a space or is the null
string.
-The default behavior of this procedure is to print two newlines and the
-prompt string; flush the output buffer; then read an object and return
-it.
+The default behavior of this procedure is to print a fresh line, a
+newline, and the prompt string; flush the output buffer; then read an
+object and return it.
Under Edwin and Emacs, the expression is read in the minibuffer.
@end deffn
to @var{prompt}, unless @var{prompt} already ends in a space or is the
null string.
-The default behavior of this procedure is to print two newlines and the
-prompt string; flush the output buffer; then read a character in raw
-mode. If the character is @code{#\y}, @code{#\Y}, or @code{#\space},
-the procedure returns @code{#t}; If the character is @code{#\n},
-@code{#\N}, or @code{#\rubout}, the procedure returns @code{#f}.
-Otherwise the prompt is repeated.
+The default behavior of this procedure is to print a fresh line, a
+newline, and the prompt string; flush the output buffer; then read a
+character in raw mode. If the character is @code{#\y}, @code{#\Y}, or
+@code{#\space}, the procedure returns @code{#t}; If the character is
+@code{#\n}, @code{#\N}, or @code{#\rubout}, the procedure returns
+@code{#f}. Otherwise the prompt is repeated.
Under Edwin or Emacs, the confirmation is read in the minibuffer.
@end deffn
often unnecessary. This interface provides the means to bypass such
features, thus improving performance.
-@findex eq?
The abstract model of an @sc{i/o} port, as implemented here, is a
combination of a set of named operations and a state. The state is an
arbitrary object, the meaning of which is determined by the operations.
The operations are defined by a mapping from names to procedures.
-Typically the names are symbols, but any object that can be
-discriminated by @code{eq?} may be used.
-The operations are divided into two classes:
+@cindex port type
+The set of named operations is represented by an object called a
+@dfn{port type}. A port type is constructed from a set of named
+operations, and is subsequently used to construct a port. The port type
+completely specifies the behavior of the port. Port types also support
+a simple form of inheritance, allowing you to create new ports that are
+similar to existing ports.
+
+The port operations are divided into two classes:
@table @asis
@item Standard operations
@end table
@menu
+* Port Types::
* Constructors and Accessors for Ports::
-* Blocking Mode::
-* Terminal Mode::
* Input Port Operations::
* Output Port Operations::
+* Blocking Mode::
+* Terminal Mode::
@end menu
-@node Constructors and Accessors for Ports, Blocking Mode, , Port Primitives
-@subsection Constructors and Accessors for Ports
+@node Port Types, Constructors and Accessors for Ports, Port Primitives, Port Primitives
+@subsection Port Types
-The procedures in this section provide means for constructing ports with
-custom operations, accessing their operations, and manipulating their
-internal state.
-
-@deffn {procedure+} make-input-port operations object
-@deffnx {procedure+} make-output-port operations object
-@deffnx {procedure+} make-i/o-port operations object
-@cindex construction, of port
-Operations must be a list; each element is a list of two elements, the
-name of the operation and the procedure that implements it. A new port
-is returned with the given operations and a state component of
-@var{object}.
+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
+@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,
+the name of the operation (a symbol) and the procedure that implements
+it. @var{Port-type} is either @code{#f} or a port type; if it is a port
+type, any operations implemented by @var{port-type} but not specified in
+@var{operations} will be implemented by the resulting port type.
@var{Operations} need not contain definitions for all of the standard
operations; the procedure will provide defaults for any standard
operations that are not defined. At a minimum, the following operations
-must be defined: for input ports, @code{read-char}, @code{peek-char},
-and @code{char-ready?}; for output ports, either @code{write-char} or
-@code{write-substring}; @sc{i/o} ports must supply the minimum
-operations for both input and output.
+must be defined: for input ports, @code{read-char} and @code{peek-char};
+for output ports, either @code{write-char} or @code{write-substring}.
+@sc{i/o} ports must supply the minimum operations for both input and
+output.
+
+If an operation in @var{operations} is defined to be @code{#f}, then the
+corresponding operation in @var{port-type} is @emph{not} inherited.
+
+If @code{read-char} is defined in @var{operations}, then any standard
+input operations defined in @var{port-type} are ignored. Likewise, if
+@code{write-char} or @code{write-substring} is defined in
+@var{operations}, then any standard output operations defined in
+@var{port-type} are ignored. This feature allows overriding the
+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
+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
+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
+Returns a newly allocated list whose elements are the names of the
+operations implemented by @var{port-type}.
@end deffn
-@deffn {procedure+} port/copy port object
-@cindex copying, of port
-Returns a new copy of @var{port}, identical to the original except that
-its state component is @var{object}. @var{Port} is not modified.
+@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
+
+@node Constructors and Accessors for Ports, Input Port Operations, Port Types, Port Primitives
+@subsection Constructors and Accessors for Ports
+
+The procedures in this section provide means for constructing ports,
+accessing the type of a port, and manipulating the state of a port.
-@code{port/copy} is normally used to speed up creation of ports. This
-is done by creating a template using one of the port constructors
-@code{make-input-port}, @code{make-output-port}, or
-@code{make-i/o-port}, as appropriate; a dummy state component is
-supplied for the template. Then @code{port/copy} is used to make a copy
-of the template, supplying the copy with the correct state. This is
-useful because the port constructors are somewhat slow, as they must
-parse the @var{operations} list, provide defaulting for missing
-operations, etc.
+@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
-@findex input-port/copy
-@findex output-port/copy
-For compatibility with old code, @code{input-port/copy} and
-@code{output-port/copy} are synonyms for this procedure.
+@deffn {procedure+} port/type port
+Returns the port type of @var{port}.
@end deffn
@deffn {procedure+} port/state port
Returns the state component of @var{port}.
-
-@findex input-port/state
-@findex output-port/state
-For compatibility with old code, @code{input-port/state} and
-@code{output-port/state} are synonyms for this procedure.
@end deffn
@deffn {procedure+} set-port/state! port object
Changes the state component of @var{port} to be @var{object}.
Returns an unspecified value.
-
-@findex set-input-port/state!
-@findex set-output-port/state!
-For compatibility with old code, @code{set-input-port/state!} and
-@code{set-output-port/@*state!} are synonyms for this procedure.
@end deffn
-@deffn {procedure+} port/operation port object
-Returns the operation named @var{object} in @var{port}. If @var{port}
-has no such operation, returns @code{#f}.
+@deffn {procedure+} port/operation port symbol
+Equivalent to
-@findex input-port/operation
-@findex output-port/operation
-@findex input-port/custom-operation
-@findex output-port/custom-operation
-For compatibility with old code, @code{input-port/operation} and
-@code{output-port/operation} are similar to @code{port/operation}. They
-differ in that they translate certain old operation names to new
-equivalents before calling @code{port/operation}.
-@code{input-port/custom-operation} and
-@code{output-port/custom-operation} are synonyms for
-@code{input-port/@*operation} and @code{output-port/operation},
-respectively.
+@example
+(port-type/operation (port/type @var{port}) @var{symbol})
+@end example
@end deffn
@deffn {procedure+} port/operation-names port
-Returns a list whose elements are the names of the operations supported
-by @code{port}. The list is not newly allocated and must not be
-modified.
+Equivalent to
-@findex input-port/operation-names
-@findex output-port/operation-names
-For compatibility with old code, @code{input-port/operation-names} and
-@code{output-port/@*operation-names} are synonyms for this procedure.
+@example
+(port-type/operation-names (port/type @var{port}))
+@end example
@end deffn
@deffn {procedure+} make-eof-object input-port
is sometimes useful when building input ports.
@end deffn
-@node Blocking Mode, Terminal Mode, Constructors and Accessors for Ports, Port Primitives
-@subsection Blocking Mode
+@node Input Port Operations, Output Port Operations, Constructors and Accessors for Ports, Port Primitives
+@subsection Input Port Operations
+@cindex input port operations
-@cindex blocking mode, of port
-An interactive port is always in one of two modes: @dfn{blocking} or
-@dfn{non-blocking}. This mode is independent of the terminal mode: each
-can be changed independent of the other. Furthermore, if it is an
-interactive @sc{i/o} port, there are separate blocking modes for input
-and for output.
+This section describes the standard operations on input ports.
+Following that, some useful custom operations are described.
-If an input port is in blocking mode, attempting to read from it when no
-input is available will cause Scheme to ``block'', i.e.@: suspend
-itself, until input is available. If an input port is in non-blocking
-mode, attempting to read from it when no input is available will cause
-the reading procedure to return immediately, indicating the lack of
-input in some way (exactly how this situation is indicated is separately
-specified for each procedure or operation).
+@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
+(e.g.@: at the end of an input file), this operation returns an
+end-of-file object. If @var{input-port} has no more characters but will
+eventually have some more (e.g.@: a terminal where nothing has been
+typed recently), and it is in non-blocking mode, @code{#f} is returned;
+otherwise the operation hangs until input is available.
+@end defop
-An output port in blocking mode will block if the output device is not
-ready to accept output. In non-blocking mode it will return immediately
-after performing as much output as the device will allow (again, each
-procedure or operation reports this situation in its own way).
+@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
-Interactive ports are initially in blocking mode; this can be changed at
-any time with the procedures defined in this section.
+@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
-These procedures represent blocking mode by the symbol @code{blocking},
-and non-blocking mode by the symbol @code{nonblocking}. An argument
-called @var{mode} must be one of these symbols. A @var{port} argument
-to any of these procedures may be any port, even if that port does not
-support blocking mode; in that case, the port is not modified in any
-way.
+@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
+returning @code{#f}, returning immediately if any characters become
+available while it is waiting.
+@end defop
-@deffn {procedure+} port/input-blocking-mode port
-Returns the input blocking mode of @var{port}.
-@end deffn
+@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
+have a marked performance improvement on buffered input ports. All
+characters up to, but excluding, the first character in @var{char-set}
+(or end of file) are read from @var{input-port}. @code{read-string}
+returns these characters as a newly allocated string, while
+@code{discard-chars} discards them and returns an unspecified value.
+These operations hang until sufficient input is available, even if
+@var{input-port} is in non-blocking mode. If end of file is encountered
+before any input characters, @code{read-string} returns an end-of-file
+object.
+@end defop
-@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
-@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
-@var{thunk}, restores the input blocking mode of @var{port} to what it
-was when @code{port/with-input-blocking-mode} was called, and returns
-the value that was yielded by @var{thunk}. This binding is performed
-by @code{dynamic-wind}, which guarantees that the input blocking mode is
-restored if @var{thunk} escapes from its continuation.
-@end deffn
-
-@deffn {procedure+} port/output-blocking-mode port
-Returns the output blocking mode of @var{port}.
-@end deffn
-
-@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
-@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
-@var{thunk}, restores the output blocking mode of @var{port} to what it
-was when @code{port/with-output-blocking-mode} was called, and returns
-the value that was yielded by @var{thunk}. This binding is performed
-by @code{dynamic-wind}, which guarantees that the output blocking mode
-is restored if @var{thunk} escapes from its continuation.
-@end deffn
-
-@node Terminal Mode, Input Port Operations, Blocking Mode, Port Primitives
-@subsection Terminal Mode
-
-@cindex terminal mode, of port
-A port that reads from or writes to a terminal has a @dfn{terminal
-mode}; this is either @dfn{cooked} or @dfn{raw}. This mode is
-independent of the blocking mode: each can be changed independent of the
-other. Furthermore, a terminal @sc{i/o} port has independent terminal
-modes both for input and for output.
-
-@cindex cooked mode, of terminal port
-A terminal port in cooked mode provides some standard processing to make
-the terminal easy to communicate with. For example, under unix, cooked
-mode on input reads from the terminal a line at a time and provides
-rubout processing within the line, while cooked mode on output might
-translate linefeeds to carriage-return/linefeed pairs. In general, the
-precise meaning of cooked mode is operating-system dependent, and
-furthermore might be customizable by means of operating system
-utilities. The basic idea is that cooked mode does whatever is
-necessary to make the terminal handle all of the usual user-interface
-conventions for the operating system, while keeping the program's
-interaction with the port as normal as possible.
-
-@cindex raw mode, of terminal port
-A terminal port in raw mode disables all of that processing. In raw
-mode, characters are directly read from and written to the device
-without any translation or interpretation by the operating system. On
-input, characters are available as soon as they are typed, and are not
-echoed on the terminal by the operating system. In general, programs
-that put ports in raw mode have to know the details of interacting with
-the terminal. In particular, raw mode is used for writing programs such
-as text editors.
-
-Terminal ports are initially in cooked mode; this can be changed at any
-time with the procedures defined in this section.
-
-These procedures represent cooked mode by the symbol @code{cooked}, and
-raw mode by the symbol @code{raw}. Additionally, the value @code{#f}
-represents ``no mode''; it is the terminal mode of a port that is not a
-terminal. An argument called @var{mode} must be one of these three
-values. A @var{port} argument to any of these procedures may be any
-port, even if that port does not support terminal mode; in that case,
-the port is not modified in any way.
-
-@deffn {procedure+} port/input-terminal-mode port
-Returns the input terminal mode of @var{port}.
-@end deffn
-
-@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
-@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
-@var{thunk}, restores the input terminal mode of @var{port} to what it
-was when @code{port/with-input-terminal-mode} was called, and returns
-the value that was yielded by @var{thunk}. This binding is performed
-by @code{dynamic-wind}, which guarantees that the input terminal mode is
-restored if @var{thunk} escapes from its continuation.
-@end deffn
-
-@deffn {procedure+} port/output-terminal-mode port
-Returns the output terminal mode of @var{port}.
-@end deffn
-
-@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
-@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
-@var{thunk}, restores the output terminal mode of @var{port} to what it
-was when @code{port/with-output-terminal-mode} was called, and returns
-the value that was yielded by @var{thunk}. This binding is performed
-by @code{dynamic-wind}, which guarantees that the output terminal mode is
-restored if @var{thunk} escapes from its continuation.
-@end deffn
-
-@node Input Port Operations, Output Port Operations, Terminal Mode, Port Primitives
-@subsection Input Port Operations
-@cindex input port operations
-
-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
-@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
-(e.g.@: at the end of an input file), this operation returns an
-end-of-file object. If @var{input-port} has no more characters but will
-eventually have some more (e.g.@: a terminal where nothing has been
-typed recently), and it is in non-blocking mode, @code{#f} is returned;
-otherwise the operation hangs until input is available.
-@end defop
-
-@defop {operation+} {input port} peek-char input-port
-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
-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
-@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
-returning @code{#f}, returning immediately if any characters become
-available while it is waiting.
-@end defop
-
-@defop {operation+} {input port} read-string input-port char-set
-@defopx {operation+} {input port} discard-chars input-port char-set
-@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
-have a marked performance improvement on buffered input ports. All
-characters up to, but excluding, the first character in @var{char-set}
-(or end of file) are read from @var{input-port}. @code{read-string}
-returns these characters as a newly allocated string, while
-@code{discard-chars} discards them and returns an unspecified value.
-These operations hang until sufficient input is available, even if
-@var{input-port} is in non-blocking mode. If end of file is encountered
-before any input characters, @code{read-string} returns an end-of-file
-object.
-@end defop
-
-@deffn {procedure+} input-port/operation/read-char input-port
-@deffnx {procedure+} input-port/operation/peek-char input-port
-@deffnx {procedure+} input-port/operation/discard-char input-port
-@deffnx {procedure+} input-port/operation/char-ready? input-port
-@deffnx {procedure+} input-port/operation/read-string input-port
-@deffnx {procedure+} input-port/operation/discard-chars input-port
-Each of these procedures returns the procedure that implements the
-respective operation for @var{input-port}. Each is equivalent to, but
-faster than, @code{input-port/operation} on the respective operation
-name:
-
-@example
-@group
-(input-port/operation/read-char @var{input-port})
-(input-port/operation @var{input-port} 'read-char)
-@end group
-@end example
-@end deffn
-
-@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
-Each of these procedures invokes the respective operation on
-@var{input-port}. For example, the following are equivalent:
-
-@example
-@group
-(input-port/read-string @var{input-port} @var{char-set})
-((input-port/operation/read-string @var{input-port}) @var{input-port} @var{char-set})
-@end group
-@end example
+@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
+number of characters written to the substring.
+
+If @var{input-port} is an interactive port, and at least one character
+is immediately available, the available characters are written to the
+substring and this operation returns immediately. If no characters are
+available, and @var{input-port} is in blocking mode, the operation
+blocks until at least one character is available. Otherwise, the
+operation returns @code{#f} immediately.
+
+This is an extremely fast way to read characters from a port.
+@end defop
+
+@deffn {procedure+} input-port/read-char input-port
+@deffnx {procedure+} input-port/peek-char input-port
+@deffnx {procedure+} input-port/discard-char input-port
+@deffnx {procedure+} input-port/char-ready? input-port k
+@deffnx {procedure+} input-port/read-string input-port char-set
+@deffnx {procedure+} input-port/discard-chars input-port char-set
+@deffnx {procedure+} input-port/read-substring input-port string start end
+Each of these procedures invokes the respective operation on
+@var{input-port}. For example, the following are equivalent:
+
+@example
+@group
+(input-port/read-char @var{input-port})
+((input-port/operation @var{input-port} 'read-char) @var{input-port})
+@end group
+@end example
@end deffn
The following custom operations are implemented for input ports to
otherwise it returns @code{#f}.
@end defop
-@defop {operation+} {input port} read-chars input-port string
-Attempts to read enough characters from @var{input-port} to fill
-@var{string}, returning the number of characters actually read.
-The string will be completely filled unless the port is unable to
-deliver the characters; this can happen when it is a file port and there
-aren't that many characters available, or when it is an interactive port
-in non-blocking mode and doesn't have that many characters immediately
-available.
-This is an extremely fast way to read characters from the port.
-@end defop
-
-@defop {operation+} {input port} read-substring input-port string start end
-Attempts to read enough characters from @var{input-port} to fill the
-substring specified by @var{string}, @var{start}, and @var{end},
-returning the number of characters actually read.
-The string will be completely filled unless the port is unable to
-deliver the characters; this can happen when it is a file port and there
-aren't that many characters available, or when it is an interactive port
-in non-blocking mode and doesn't have that many characters immediately
-available.
-This is an extremely fast way to read characters from the port.
-@end defop
-
@defop {operation+} {input port} chars-remaining input-port
-Computes an estimate of the number of characters remaining to be read
+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
an exact non-negative integer.
@end defop
-@node Output Port Operations, , Input Port Operations, Port Primitives
+@node Output Port Operations, Blocking Mode, Input Port Operations, Port Primitives
@subsection Output Port Operations
@cindex output port operations
Writes the substring specified by @var{string}, @var{start}, and
@var{end} to @var{output-port} and returns an unspecified value.
Equivalent to writing the characters of the substring, one by one, to
-@var{output-port}, but is often implemented more efficiently.
+@var{output-port}, but is implemented very efficiently.
@end defop
-@defop {operation+} {output port} write-string output-port string
-@cindex string, output to port
-Writes @var{string} to @var{output-port} and returns an unspecified
-value.
+@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
+the beginning of a line. If @var{output-port} is not such a port, and
+end-of-line is unconditionally written to the port. Returns an
+unspecified value.
@end defop
@defop {operation+} {output port} flush-output output-port
@end defop
@defop {operation+} {output port} discretionary-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.
-
-This operation, if defined, is normally identical to
-@code{flush-output}. However, it is not normally defined, and even when
-it is, it is invoked at different times (@pxref{Output Procedures}).
+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/operation/write-char output-port
-@deffnx {procedure+} output-port/operation/write-substring output-port
-@deffnx {procedure+} output-port/operation/write-string output-port
-@deffnx {procedure+} output-port/operation/flush-output output-port
-@deffnx {procedure+} output-port/operation/discretionary-flush-output output-port
-Each of these procedures returns the procedure that implements the
-respective operation for @var{output-port}. Each is equivalent to, but
-faster than, @code{output-port/operation} on the respective operation
-name:
-
-@example
-@group
-(output-port/operation/write-char @var{output-port})
-(output-port/operation @var{output-port} 'write-char)
-@end group
-@end example
-@end deffn
-
@deffn {procedure+} output-port/write-char output-port char
@deffnx {procedure+} output-port/write-substring output-port string start end
-@deffnx {procedure+} output-port/write-string output-port string
+@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
@example
@group
(output-port/write-char @var{output-port} @var{char})
-((output-port/operation/write-char @var{output-port}) @var{output-port} @var{char})
+((output-port/operation @var{output-port} 'write-char)
+ @var{output-port} @var{char})
+@end group
+@end example
+@end deffn
+
+@deffn {procedure+} output-port/write-string output-port string
+Writes @var{string} to @var{output-port}. Equivalent to
+
+@example
+@group
+(output-port/write-substring @var{output-port}
+ @var{string}
+ 0
+ (string-length @var{string}))
@end group
@end example
@end deffn
@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
as the result of this procedure. Otherwise, @code{output-port/x-size}
-returns a default value (currently @code{79}).
+returns a default value (currently @code{80}).
@code{output-port/x-size} is useful for programs that tailor their
output to the width of the display (a fairly common practice). If the
otherwise, @code{#f} is returned.
@end deffn
-@node File-System Interface, Error System, Input/Output, Top
-@chapter File-System Interface
-@cindex file-system interface
+@node Blocking Mode, Terminal Mode, Output Port Operations, Port Primitives
+@subsection Blocking Mode
-The Scheme standard provides a simple mechanism for reading and writing
-files: file ports. MIT Scheme provides additional tools for
-dealing with other aspects of the file system:
+@cindex blocking mode, of port
+An interactive port is always in one of two modes: @dfn{blocking} or
+@dfn{non-blocking}. This mode is independent of the terminal mode: each
+can be changed independent of the other. Furthermore, if it is an
+interactive @sc{i/o} port, there are separate blocking modes for input
+and for output.
-@itemize @bullet
-@item
-@dfn{Pathnames} are a reasonably operating-system independent tool for
-manipulating the component parts of file names. This can be useful for
-implementing defaulting of file name components.
-@cindex pathname
+If an input port is in blocking mode, attempting to read from it when no
+input is available will cause Scheme to ``block'', i.e.@: suspend
+itself, until input is available. If an input port is in non-blocking
+mode, attempting to read from it when no input is available will cause
+the reading procedure to return immediately, indicating the lack of
+input in some way (exactly how this situation is indicated is separately
+specified for each procedure or operation).
-@item
-Control over the @dfn{current working directory}: the place in the file
-system from which relative file names are interpreted.
-@cindex current working directory
+An output port in blocking mode will block if the output device is not
+ready to accept output. In non-blocking mode it will return immediately
+after performing as much output as the device will allow (again, each
+procedure or operation reports this situation in its own way).
-@item
-Procedures that rename, copy, delete, and test for the existence of
-files. Also, procedures that return detailed information about a
-particular file, such as its type (directory, link, etc.) or length.
+Interactive ports are initially in blocking mode; this can be changed at
+any time with the procedures defined in this section.
-@item
-A facility for reading the contents of a directory.
-@end itemize
+These procedures represent blocking mode by the symbol @code{blocking},
+and non-blocking mode by the symbol @code{nonblocking}. An argument
+called @var{mode} must be one of these symbols. A @var{port} argument
+to any of these procedures may be any port, even if that port does not
+support blocking mode; in that case, the port is not modified in any
+way.
+
+@deffn {procedure+} port/input-blocking-mode port
+Returns the input blocking mode of @var{port}.
+@end deffn
+
+@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
+@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
+@var{thunk}, restores the input blocking mode of @var{port} to what it
+was when @code{port/with-input-blocking-mode} was called, and returns
+the value that was yielded by @var{thunk}. This binding is performed
+by @code{dynamic-wind}, which guarantees that the input blocking mode is
+restored if @var{thunk} escapes from its continuation.
+@end deffn
+
+@deffn {procedure+} port/output-blocking-mode port
+Returns the output blocking mode of @var{port}.
+@end deffn
+
+@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
+@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
+@var{thunk}, restores the output blocking mode of @var{port} to what it
+was when @code{port/with-output-blocking-mode} was called, and returns
+the value that was yielded by @var{thunk}. This binding is performed
+by @code{dynamic-wind}, which guarantees that the output blocking mode
+is restored if @var{thunk} escapes from its continuation.
+@end deffn
+
+@node Terminal Mode, , Blocking Mode, Port Primitives
+@subsection Terminal Mode
+
+@cindex terminal mode, of port
+A port that reads from or writes to a terminal has a @dfn{terminal
+mode}; this is either @dfn{cooked} or @dfn{raw}. This mode is
+independent of the blocking mode: each can be changed independent of the
+other. Furthermore, a terminal @sc{i/o} port has independent terminal
+modes both for input and for output.
+
+@cindex cooked mode, of terminal port
+A terminal port in cooked mode provides some standard processing to make
+the terminal easy to communicate with. For example, under unix, cooked
+mode on input reads from the terminal a line at a time and provides
+rubout processing within the line, while cooked mode on output might
+translate linefeeds to carriage-return/linefeed pairs. In general, the
+precise meaning of cooked mode is operating-system dependent, and
+furthermore might be customizable by means of operating system
+utilities. The basic idea is that cooked mode does whatever is
+necessary to make the terminal handle all of the usual user-interface
+conventions for the operating system, while keeping the program's
+interaction with the port as normal as possible.
+
+@cindex raw mode, of terminal port
+A terminal port in raw mode disables all of that processing. In raw
+mode, characters are directly read from and written to the device
+without any translation or interpretation by the operating system. On
+input, characters are available as soon as they are typed, and are not
+echoed on the terminal by the operating system. In general, programs
+that put ports in raw mode have to know the details of interacting with
+the terminal. In particular, raw mode is used for writing programs such
+as text editors.
+
+Terminal ports are initially in cooked mode; this can be changed at any
+time with the procedures defined in this section.
+
+These procedures represent cooked mode by the symbol @code{cooked}, and
+raw mode by the symbol @code{raw}. Additionally, the value @code{#f}
+represents ``no mode''; it is the terminal mode of a port that is not a
+terminal. An argument called @var{mode} must be one of these three
+values. A @var{port} argument to any of these procedures may be any
+port, even if that port does not support terminal mode; in that case,
+the port is not modified in any way.
+
+@deffn {procedure+} port/input-terminal-mode port
+Returns the input terminal mode of @var{port}.
+@end deffn
+
+@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
+@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
+@var{thunk}, restores the input terminal mode of @var{port} to what it
+was when @code{port/with-input-terminal-mode} was called, and returns
+the value that was yielded by @var{thunk}. This binding is performed
+by @code{dynamic-wind}, which guarantees that the input terminal mode is
+restored if @var{thunk} escapes from its continuation.
+@end deffn
+
+@deffn {procedure+} port/output-terminal-mode port
+Returns the output terminal mode of @var{port}.
+@end deffn
+
+@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
+@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
+@var{thunk}, restores the output terminal mode of @var{port} to what it
+was when @code{port/with-output-terminal-mode} was called, and returns
+the value that was yielded by @var{thunk}. This binding is performed
+by @code{dynamic-wind}, which guarantees that the output terminal mode is
+restored if @var{thunk} escapes from its continuation.
+@end deffn
+
+@node File-System Interface, Error System, Input/Output, Top
+@chapter File-System Interface
+@cindex file-system interface
+
+The Scheme standard provides a simple mechanism for reading and writing
+files: file ports. MIT Scheme provides additional tools for
+dealing with other aspects of the file system:
+
+@itemize @bullet
+@item
+@dfn{Pathnames} are a reasonably operating-system independent tool for
+manipulating the component parts of file names. This can be useful for
+implementing defaulting of file name components.
+@cindex pathname
+
+@item
+Control over the @dfn{current working directory}: the place in the file
+system from which relative file names are interpreted.
+@cindex current working directory
+
+@item
+Procedures that rename, copy, delete, and test for the existence of
+files. Also, procedures that return detailed information about a
+particular file, such as its type (directory, link, etc.) or length.
+
+@item
+A facility for reading the contents of a directory.
+@end itemize
@menu
* Pathnames::
* Directory Reader::
@end menu
-@node Pathnames, Working Directory, , File-System Interface
+@node Pathnames, Working Directory, File-System Interface, File-System Interface
@section Pathnames
@comment **** begin CLTL ****
* Miscellaneous Pathnames::
@end menu
-@node Filenames and Pathnames, Components of Pathnames, , Pathnames
+@node Filenames and Pathnames, Components of Pathnames, Pathnames, Pathnames
@subsection Filenames and Pathnames
Pathname objects are usually created by parsing filenames (character
@example
@group
-(->pathname "foo") @result{} #[pathname 65 "foo"]
-(->pathname "/usr/morris") @result{} #[pathname 66 "/usr/morris"]
+(->pathname "foo") @result{} #[pathname 65 "foo"]
+(->pathname "/usr/morris") @result{} #[pathname 66 "/usr/morris"]
@end group
@end example
@end deffn
Any component of a pathname may be the symbol @code{unspecific}, meaning
that the component simply does not exist, for file systems in which such
-a value makes no sense. For example, unix, @sc{dos}, Windows, and OS/2
-file systems usually do not support version numbers, so the version
-component for such a host might be
-@code{unspecific}.@footnote{This description is adapted from
-@cite{Common Lisp, The Language}, second edition, section 23.1.1.}
+a value makes no sense. For example, unix, Windows, and OS/2 file
+systems usually do not support version numbers, so the version component
+for such a host might be @code{unspecific}.@footnote{This description is
+adapted from @cite{Common Lisp, The Language}, second edition, section
+23.1.1.}
@comment **** end CLTL ****
Each component in a pathname is typically one of the following (with
@example
@group
-(make-pathname #f #f '(absolute "usr" "morris") "foo" "scm" #f)
+(make-pathname #f
+ #f
+ '(absolute "usr" "morris")
+ "foo"
+ "scm"
+ #f)
@result{} #[pathname 67 "/usr/morris/foo.scm"]
@end group
@end example
the initialization file does not exist this procedure returns @code{#f}.
Under unix, the init file is called @file{.scheme.init}; under Windows
-and OS/2, the init file is called @file{scheme.ini}. In either case, it
-is located in the user's home directory, which is computed by
+and OS/2, the init file is called @file{scheme.ini}. In either
+case, it is located in the user's home directory, which is computed by
@code{user-homedir-pathname}.
@end deffn
@code{geteuid} system call. The resulting user name is passed to the
@code{getpwnam} system call to obtain the home directory.
-Under OS/2, the user's home directory is specified by the @code{HOME}
-environment variable. If this variable is undefined, but the
-@code{USERDIR} and @code{USER} environment variables are defined, then
-the user's home directory is @file{%USERDIR%\%USER%}. If only
-@code{USERDIR} is defined, then the user's home directory is
-@file{%USERDIR%\nouser}. If none of these variables is defined, then
-the home directory is the root directory of the current drive.
-
-Under Windows, the user's home directory is computed by examining
-several environment variables, in the following order. If
-@code{HOMEPATH} is defined, the home directory is
-@file{%HOMEDRIVE%%HOMEPATH%}. If @code{HOME} is defined, the home
-directory is @file{%HOMEDRIVE%%HOME%}. If @code{USERDIR} and
-@code{USERNAME} are defined, the home directory is
-@file{%USERDIR%\%USERNAME%}. If @code{USERDIR} and @code{USER} are
-defined, the home directory is @file{%USERDIR%\%USER%}. If
-@code{USERDIR} is defined, the home directory is
-@file{%USERDIR%\nouser}. If none of these variables is defined, then
-the home directory is the root directory of the current drive.
+Under OS/2, several heuristics are tried to find the user's home
+directory. First, if the environment variable @code{HOME} is defined,
+that is the home directory. If @code{HOME} is undefined, but the
+@code{USERDIR} and @code{USER} environment variables are defined and
+the directory @file{%USERDIR%\%USER%} exists, then it is used. Failing
+that, if the directory @file{%USER%} exists on the OS/2 system
+drive, then it is used. As a last resort, the OS/2 system drive is
+the home directory.
+
+Like OS/2, the Windows implementation uses heuristics based on
+environment variables. The user's home directory is computed by
+examining several environment variables, in the following order:
+
+@itemize @bullet
+@item
+@code{HOMEDRIVE} and @code{HOMEPATH} are both defined and
+@file{%HOMEDRIVE%%HOMEPATH%} is an existing directory. (These variables
+are automatically defined by Windows NT.)
+
+@item
+@code{HOME} is defined and @file{%HOME%} is an existing directory.
+
+@item
+@code{USERDIR} and @code{USERNAME} are defined and
+@file{%USERDIR%\%USERNAME%} is an existing directory.
+
+@item
+@code{USERDIR} and @code{USER} are defined and
+@file{%USERDIR%\%USER%} is an existing directory.
+
+@item
+@code{USERNAME} is defined and @file{%USERNAME%} is an existing
+directory on the Windows system drive.
+
+@item
+@code{USER} is defined and @file{%USER%} is an existing directory on the
+Windows system drive.
+
+@item
+Finally, if all else fails, the Windows system drive is used as the home
+directory.
+@end itemize
@end deffn
@deffn {procedure+} system-library-pathname pathname
@example
@group
(system-library-pathname "compiler.com")
- @result{} #[pathname 45 "/usr/local/lib/mit-scheme/compiler.com"]
+ @result{} #[pathname 45 "/usr/local/lib/mit-scheme/compiler.com"]
@end group
@end example
@end deffn
@deffn {procedure+} system-library-directory-pathname pathname
@cindex library, system pathname
-Locates the pathname of a MIT Scheme system library directory. An error
-of type @code{condition-type:file-operation-error} is signalled if
+Locates the pathname of an MIT Scheme system library directory. An
+error of type @code{condition-type:file-operation-error} is signalled if
@var{pathname} cannot be located on the library search path.
@example
programs and the short name for interactive use.
Additionally, @code{set-working-directory-pathname!} modifies the value
-of @code{*default-pathname-defaults*} by merging the new working
+of@* @code{*default-pathname-defaults*} by merging the new working
directory into it.
When this procedure is executed in the top-level @sc{rep} loop, it
@end deffn
@deffn {procedure+} call-with-temporary-file-pathname procedure
-@code{call-with-temporary-file-pathname} 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, it is
-deleted; then, the value yielded by @var{procedure} is returned. If
-@var{procedure} escapes from its continuation, and the file still
+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,
+it is deleted; then, the value yielded by @var{procedure} is returned.
+If @var{procedure} escapes from its continuation, and the file still
exists, it is deleted.
@end deffn
@itemize @bullet
@item
-The directory specified by the @code{TEMP} environment variable, if any.
+The directories specified by the environment variables @code{TMPDIR},
+@code{TEMP}, or @code{TMP}.
@item
-The directory specified by the @code{TMP} environment variable, if any.
+Under unix, the directories @file{/var/tmp}, @file{/usr/tmp}, or
+@file{/tmp}.
@item
-Under unix, the directories @file{/tmp} and @file{/usr/tmp}.
+Under OS/2 or Windows, the following directories on the system drive:
+@file{\temp}, @file{\tmp}, or @file{\}.
@item
-Under OS/2 or Windows, the directories: @file{\tmp} on the current
-drive; @file{c:\}; the current directory; and @file{\} on the current
-drive. (The current directory and drive are specified by
-@code{*default-pathname-defaults*}.)
+Under OS/2 or Windows, the current directory, as specified by
+@code{*default-pathname-defaults*}.
@end itemize
@end deffn
@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 one of
-the file extensions @file{.exe}, @file{.com}, @file{.cmd}, or
+identified by its mode bits. Under OS/2, an executable file has
+one of the file extensions @file{.exe}, @file{.com}, @file{.cmd}, or
@file{.bat}. Under Windows, an executable file has one of the file
extensions @file{.exe}, @file{.com}, or @file{.bat}.
@end deffn
@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.
+the two files. Under OS/2 and Windows, this is done by comparing
+the filename strings.
@end deffn
@deffn {procedure+} file-modes filename
integer arithmetic. If @var{filename} names a file that does not exist,
@code{file-access-time} returns @code{#f}.
-Some operating systems don't implement access times; in those systems
-@code{file-access-time} returns an unspecified value.
-
@findex file-access-time-direct
@findex file-access-time-indirect
In operating systems that support symbolic links, if @var{filename}
@end deffn
@deffn {procedure+} file-attributes/mode-string attributes
-The mode string of the file. This is a newly allocated string showing
-the file's mode bits. Under unix and Windows, this string is in unix
-format (simulated under Windows). Under OS/2, this string shows the
-standard OS/2 attributes in their usual format.
+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
The inode number of the file, an exact non-negative integer.
@end deffn
-The following additional accessors are defined under OS/2:
+The following additional accessor is defined under OS/2 and Windows:
@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 OS/2
-API.
+containing the file's attribute bits, exactly as specified by the
+operating system's API.
@end deffn
+The following additional accessor is defined under OS/2:
+
@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.
@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
+by@* @code{->pathname}. The directory specified by @var{directory} is
read, and the contents of the directory is returned as a newly allocated
list of absolute pathnames. The result is sorted according to the usual
sorting conventions for directories, unless @var{sort?} is specified as
the returned list contains only those pathnames whose name, type, and
version components match those of @var{directory}; @code{wild} or
@code{#f} as one of these components means ``match anything''.
+
+The OS/2 and Windows implementations support ``globbing'', in which the
+characters @code{*} and @code{?} are interpreted to mean ``match
+anything'' and ``match any character'', respectively. This ``globbing''
+is supported only in the file part of @var{directory}.
@end deffn
@node Error System, Graphics, File-System Interface, Top
* Taxonomy::
@end menu
-@node Condition Signalling, Error Messages, , Error System
+@node Condition Signalling, Error Messages, Error System, Error System
@section Condition Signalling
@cindex condition signalling (defn)
@findex ignore-error
@vindex standard-error-hook
@cindex REP loop
-This is the procedure called internally by @code{error} after it calls
-@code{signal-condition}. It normally creates creates a new @sc{repl}
-with the prompt @code{"error>"} (but see @code{standard-error-hook}).
-In order to simulate the effect of calling @code{error}, code may call
+Called internally by @code{error} after it calls
+@code{signal-condition}. Normally creates creates a new @sc{repl} with
+the prompt @code{"error>"} (but see @code{standard-error-hook}). In
+order to simulate the effect of calling @code{error}, code may call
@code{signal-condition} directly and then call
@code{standard-error-handler} if @code{signal-condition} returns.
@end deffn
* The Named Restart Abstraction::
@end menu
-@node Establishing Restart Code, Invoking Standard Restart Code, , Restarts
+@node Establishing Restart Code, Invoking Standard Restart Code, Restarts, Restarts
@subsection Establishing Restart Code
@deffn {procedure+} with-simple-restart name reporter thunk
simply aborts the computation in progress by returning an unspecified
value from the call to @code{with-simple-restart}. Otherwise
@code{with-simple-restart} returns the value computed by @var{thunk}.
+@end deffn
@example
@group
; (RESTART 1) => Return to read-eval-print level 1.
@end group
@end example
-@end deffn
@deffn {procedure+} with-restart name reporter effector interactor thunk
@findex invoke-restart
invoked it. Instead, the @var{effector} should call a continuation
created before the condition-signalling process began, and
@code{with-restart} will therefore not return in the normal manner.
+@end deffn
@example
@group
@end group
@group
-(by-george! (can-george! (lambda () -3)) @result{} -3
+(by-george! (can-george! (lambda () -3)) @result{} -3
(by-george! (can-george! (lambda () (car 'x)))) @result{} (george 1 2)
@end group
@end example
-@end deffn
@node Invoking Standard Restart Code, Finding and Invoking General Restart Code, Establishing Restart Code, Restarts
@subsection Invoking Standard Restart Code
* Simple Condition Instance Operations::
@end menu
-@node Generating Operations on Conditions, Condition State, , Condition Instances
+@node Generating Operations on Conditions, Condition State, Condition Instances, Condition Instances
@subsection Generating Operations on Conditions
@findex condition-constructor
There are several standard procedures that are conventionally used for
@var{default-handler}. If @var{condition-type} is a specialization of
@code{condition-type:error}, @var{default-handler} should be the
-procedure @code{standard-error-handler}. If @var{condition-type} is a
+procedure@* @code{standard-error-handler}. If @var{condition-type} is a
specialization of @code{condition-type:warning}, @var{default-handler}
should be the procedure @code{standard-warning-handler}. If
@var{condition-type} is a specialization of
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
contains the object that is of the wrong type.
+@end deffn
@example
@group
; (RESTART 1) => Return to read-eval-print level 1.
@end group
@end example
-@end deffn
@deffn {procedure+} error:wrong-type-datum datum type
This procedure signals a condition of type
non-negative integer, or @code{#f}), the @var{type} field contains a
string describing the type that was expected, and the @var{datum} field
contains the offending argument.
+@end deffn
@example
@group
; (RESTART 1) => Return to read-eval-print level 1.
@end group
@end example
-@end deffn
@deffn {procedure+} error:wrong-type-argument datum type operator
This procedure signals a condition of type
the @var{type} field contains the number of arguments that the procedure
accepts, and the @var{operands} field contains a list of the arguments
that were passed to the procedure.
+@end deffn
@example
@group
; (RESTART 1) => Return to read-eval-print level 1.
@end group
@end example
-@end deffn
@deffn {procedure+} error:wrong-number-of-arguments datum type operands
This procedure signals a condition of type
often, this type indicates that an index to some data structure is
outside of the range of indices for that structure. The @var{datum}
field contains the offending object.
+@end deffn
@example
@group
; (RESTART 1) => Return to read-eval-print level 1.
@end group
@end example
-@end deffn
@deffn {procedure+} error:datum-out-of-range datum
This procedure signals a condition of type
indicates the argument position that was involved (this field contains
either a symbol, a non-negative integer, or @code{#f}), and the
@var{datum} field is the offending argument.
+@end deffn
@example
@group
; (RESTART 1) => Return to read-eval-print level 1.
@end group
@end example
-@end deffn
@deffn {procedure+} error:bad-range-argument datum operator
This procedure signals a condition of type
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
saved as a list in the @var{operands} field.
+@end deffn
@example
@group
; (RESTART 1) => Return to read-eval-print level 1.
@end group
@end example
-@end deffn
@deffn {condition type+} condition-type:file-error filename
This is an abstract type. It indicates that an error associated with a
variable that is not bound. The @var{location} field contains the name
of the variable, and the @var{environment} field contains the
environment in which the reference occurred.
+@end deffn
@example
@group
; (RESTART 1) => Return to read-eval-print level 1.
@end group
@end example
-@end deffn
@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
which the reference occurred.
+@end deffn
@example
@group
; (RESTART 1) => Return to read-eval-print level 1.
@end group
@end example
-@end deffn
@deffn {condition type+} condition-type:arithmetic-error operator operands
This is an abstract type. It indicates that a numerical operation was
operation (or a symbol naming the procedure), and the @var{operands}
field contains a list of the arguments that were passed to the
procedure.
+@end deffn
@example
@group
; (RESTART 1) => Return to read-eval-print level 1.
@end group
@end example
-@end deffn
@deffn {procedure+} error:divide-by-zero operator operands
This procedure signals a condition of type
procedures that look for particular named restarts, for example
@code{muffle-warning}. The @var{name} field contains the name that was
being searched for.
+@end deffn
@example
@group
; (RESTART 1) => Return to read-eval-print level 1.
@end group
@end example
-@end deffn
@deffn {procedure+} error:no-such-restart name
This procedure signals a condition of type
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 deffn
@example
@group
; (RESTART 1) => Return to read-eval-print level 1.
@end group
@end example
-@end deffn
@deffn {condition type+} condition-type:warning
This is an abstract type. All warnings should inherit from this type.
that is suitable for many graphics applications. In particular it is
often used for plotting data points from experiments. The interface is
generic in that it can support different types of graphics devices in a
-uniform manner. At the present time only two types of graphics device
-are implemented.
+uniform manner. At the present time only one type of graphics device
+is implemented on each operating system.
Procedures are available for drawing points, lines, and text; defining
the coordinate system; clipping graphics output; controlling some of the
* Clipping of Graphics Output::
* Custom Graphics Operations::
* Images::
+* X Graphics:: Graphics on the X Window System
* Win32 Graphics:: Graphics on Microsoft Windows and Windows NT
-* OS/2 Graphics::
-* X Graphics::
-* Starbase Graphics::
+* OS/2 Graphics:: Graphics on IBM OS/2
@end menu
-@node Opening and Closing of Graphics Devices, Coordinates for Graphics, , Graphics
+@node Opening and Closing of Graphics Devices, Coordinates for Graphics, Graphics, Graphics
@section Opening and Closing of Graphics Devices
@cindex graphics, opening and closing devices
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 deffn
+@noindent
This is equivalent to
@example
(graphics-draw-point device x y))))
@end group
@end example
-@end deffn
@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
The source and destination are combined by the device on a
pixel-by-pixel basis as follows:
-@page
@example
@group
Mode Meaning
the documentation for its type.
@end deffn
-@node Images, Win32 Graphics, Custom Graphics Operations, Graphics
+@node Images, X Graphics, Custom Graphics Operations, Graphics
@section Images
@cindex graphics, images
@cindex images, graphics
@var{image}) (image/width @var{image}))} bytes in @var{bytes}.
@end deffn
-@node Win32 Graphics, OS/2 Graphics, Images, Graphics
-@section Win32 Graphics
-@cindex Win32 graphics
-
-MIT Scheme supports graphics on Microsoft Windows 3.1, Windows 95, and
-Windows NT. In addition to the usual operations, there are operations
-to control the size, position and colors of a graphics window. Win32
-devices support images, which are implemented as device independent
-bitmaps (@sc{dib}s).
-
-The Win32 graphics device type is implemented as a top level window.
-@code{graphics-enable-buffering} is implemented and gives a 2x to 4x
-speedup on many graphics operations. As a convenience, when buffering
-is enabled clicking on the graphics window's title bar effects a
-@code{graphics-flush} operation. The user has the benefit of the
-increased performance and the ability to view the progress in drawing at
-the click of a mouse button.
+@node X Graphics, Win32 Graphics, Images, Graphics
+@section X Graphics
+@cindex X graphics
+@cindex X window system
+MIT Scheme supports graphics in the X window system (version 11).
+Arbitrary numbers of displays may be opened, and arbitrary numbers of
+graphics windows may be created for each display. A variety of
+operations is available to manipulate various aspects of the windows, to
+control their size, position, colors, and mapping. The X graphics
+device type supports images, which are implemented as Xlib @code{XImage}
+objects. X display, window, and image objects are automatically closed
+if they are reclaimed by the garbage collector.
@menu
-* Win32 Graphics Type::
-* Custom Operations for Win32 Graphics:: Custom Operations for Win32 Graphics Devices
+* X Graphics Type::
+* Utilities for X Graphics::
+* Custom Operations on X Graphics Devices::
@end menu
-@node Win32 Graphics Type, Custom Operations for Win32 Graphics, , Win32 Graphics
-@subsection Win32 Graphics Type
+@node X Graphics Type, Utilities for X Graphics, X Graphics, X Graphics
+@subsection X Graphics Type
-Win32 graphics devices are created by specifying the symbol @code{win32}
-as the @var{graphics-device-type} argument to
-@code{make-graphics-device}. The Win32 graphics device type is
-implemented as a top-level window and supports color drawing in addition
-to the standard Scheme graphics operations.
-Graphics devices are opened as follows:
+A graphics device for X windows is created by passing the symbol
+@code{x} as the graphics device type name to
+@code{make-graphics-device}:
@example
-(make-graphics-device 'win32 #!optional @var{width} @var{height} @var{palette})
+(make-graphics-device 'x #!optional @var{display} @var{geometry} @var{suppress-map?})
@end example
@noindent
-where @var{width} and @var{height} specify the size, in pixels, of the
-drawing area in the graphics window (i.e.@: excluding the frame).
-@var{Palette} determines the colors available for drawing in the window.
+where @var{display} is either a display object, @code{#f}, or a string;
+@var{geometry} is either @code{#f} or a string; and @var{suppress-map?}
+is a boolean or a vector (see below). A new window is created on the
+appropriate display, and a graphics device representing that window is
+returned.
-When a color is specified for drawing, the nearest color available in
-the palette is used. Permitted values for @var{palette} are
+@findex x-open-display
+@var{Display} specifies which X display the window is to be opened on;
+if it is @code{#f} or a string, it is passed as an argument to
+@code{x-open-display}, and the value returned by that procedure is used
+in place of the original argument. @var{Geometry} is an X geometry
+string, or @code{#f} which means to use the default geometry (which is
+specified as a resource).
-@table @asis
-@item @code{'grayscale}
-The window allocates colors from a grayscale palette
-of approximately 236 shades of gray.
+@var{Suppress-map?}, if given, may take two forms. First, it may be a
+boolean: if @code{#f} (the default), the window is automatically mapped
+after it is created; otherwise, @code{#t} means to suppress this
+automatic mapping. The second form is a vector of three elements. The
+first element is a boolean with the same meaning as the boolean form of
+@var{suppress-map?}. The second element is a string, which specifies an
+alternative resource name to be used for looking up the window's
+resources. The third element is also a string, which specifies a class
+name for looking up the window's resources. The default value for
+@var{suppress-map?} is @code{#f}.
-@item @code{'grayscale-128}
-The window allocates colors from a grayscale palette of 128 shades of
-gray.
+The default resource and class names are @code{"schemeGraphics"} and
+@code{"SchemeGraphics"} respectively.
-@item @code{'standard}
-The standard palette has good selection of colors and grays.
+@cindex resources, X graphics
+@cindex X resources, graphics
+The window is initialized using the resource and class names specified
+by @var{suppress-map?}, and is sensitive to the following resource
+properties:
-@item @code{#f} or @code{'system}
-The colors available are those in the system palette. There are usually
-16 to 20 colors in the system palette and these are usually sufficent
-for simple applications like line drawings and x-vs-y graphs of
-mathematical functions. Drawing with the system palette can be more
-efficient.
+@example
+@group
+Property Class Default
+-------- ----- -------
+geometry Geometry 512x384+0+0
+font Font fixed
+borderWidth BorderWidth 2
+internalBorder BorderWidth @r{[border width]}
+background Background white
+foreground Foreground black
+borderColor BorderColor @r{[foreground color]}
+cursorColor Foreground @r{[foreground color]}
+pointerColor Foreground @r{[foreground color]}
+@end group
+@end example
-@end table
-@noindent
-If @var{palette} is not specified then the @code{standard} palette is
-used.
+The window is created with a @code{backing_store} attribute of
+@code{Always}. The window's name and icon name are initialized to
+@code{"scheme-graphics"}.
+@node Utilities for X Graphics, Custom Operations on X Graphics Devices, X Graphics Type, X Graphics
+@subsection Utilities for X Graphics
-@node Custom Operations for Win32 Graphics, , Win32 Graphics Type, Win32 Graphics
-@subsection Custom Operations for Win32 Graphics
+@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},
+returning a display object. If unable to open a connection, @code{#f}
+is returned. @var{Display-name} is normally a string, which is an X
+display name in the usual form; however, @code{#f} is also allowed,
+meaning to use the value of the unix environment variable
+@code{DISPLAY}.
+@end deffn
+
+@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
+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
+@cindex geometry string, X graphics
+@cindex X geometry string, graphics
+This procedure creates and returns a standard X geometry string from the
+given arguments. @var{X} and @var{y} must be either exact integers or
+@code{#f}, while @var{width} and @var{height} must be either exact
+non-negative integers or @code{#f}. Usually either @var{x} and @var{y}
+are both specified or both @code{#f}; similarly for @var{width} and
+@var{height}. If only one of the elements of such a pair is specified,
+it is ignored.
+
+Examples:
+
+@example
+@group
+(x-geometry-string #f #f 100 200) @result{} "100x200"
+(x-geometry-string 2 -3 100 200) @result{} "100x200+2-3"
+(x-geometry-string 2 -3 #f #f) @result{} "+2-3"
+@end group
+@end example
+
+Note that the @var{x} and @var{y} arguments cannot distinguish between
+@code{+0} and @code{-0}, even though these have different meanings in X.
+If either of those arguments is @code{0}, it means @code{+0} in X
+terminology. If you need to distinguish these two cases you must create
+your own geometry string using Scheme's string and number primitives.
+@end deffn
+
+@node Custom Operations on X Graphics Devices, , Utilities for X Graphics, X Graphics
+@subsection Custom Operations on X Graphics Devices
Custom operations are invoked using the procedure
@code{graphics-operation}. For example,
(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
-@findex set-background-color
-@findex set-foreground-color
-@cindex color
+@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 of one of the valid color specification forms
-listed below. @code{set-background-color} and
-@code{set-foreground-color} change the colors to be used when drawing,
-but have no effect on anything drawn prior to their invocation. Because
-changing the background color affects the entire window, we recommend
-calling @code{graphics-clear} on the window's device afterwards.
+@var{Color-name} must be a string, which is the X server's name for the
+desired color. @code{set-border-color} and @code{set-mouse-color}
+immediately change the border and mouse-cursor colors.
+@code{set-background-color} and @code{set-foreground-color} change the
+colors to be used when drawing, but have no effect on anything drawn
+prior to their invocation. Because changing the background color
+affects the entire window, we recommend calling @code{graphics-clear} on
+the window's device afterwards. Color names include both mnemonic
+names, like @code{"red"}, and intensity names specified in the
+@code{"#@var{rrggbb}"} notation.
+@end defop
-The foreground color affects the drawing of text, points, lines,
-ellipses and filled polygons.
+@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
+@findex draw-arc
-Colors are specified in one of three ways:
+Operation @code{draw-arc} draws or fills an arc. An arc is a segment of
+a circle, which may have been stretched along the x- or y- axis to form
+an ellipse.
-@table @asis
-@item An integer
-This is the Win32 internal RGB value.
+The parameters @var{x}, @var{y}, @var{radius-x} and @var{radius-y}
+describe the circle and @var{angle-start} and @var{angle-sweep} choose
+which part of the circle is drawn. The arc is drawn on the graphics
+device with the center of the circle at the virtual coordinates given by
+@var{x} and @var{y}. @var{radius-x} and @var{radius-y} determine the
+size of the circle in virtual coordinate units.
-@item By name
-A limited number of names are understood by the system.
-Names are strings, e.g.@: @code{"red"}, @code{"blue"}, @code{"black"}.
-More names can be registered with the @code{define-color} operation.
+The parameter @var{angle-start} determines where the arc starts. It is
+measured in degrees in an anti-clockwise direction, starting at 3
+o'clock. @var{angle-sweep} determines how much of the circle is drawn.
+It too is measured anti-clockwise in degrees. A negative value means
+the measurement is in a clockwise direction.
-@item RGB (Red-Green-Blue) triples
-A triple is either a vector or list of three integers in the range
-0--255 inclusive which specify the intensity of the red, green and blue
-components of the color. Thus @code{#(0 0 0)} is black, @code{(0 0
-128)} is dark blue and @code{#(255 255 255)} is white.
-@end table
+Note that the angles are determined on a unit circle before it is
+stretched into an ellipse, so the actual angles that you will see on the
+computer screen depends on all of: @var{radius-x} and @var{radius-y},
+the window size, and the virtual coordinates.
-@noindent
-If the color is not available in the graphics device then the nearest
-available color is used instead.
-@end defop
+If @var{fill?} is @code{#f} then just the segment of the circle is
+drawn, otherwise the arc is filled in a pie-slice fashion.
+This draws a quarter circle pie slice, standing on its point, with point
+at virtual coordinates (3,5):
-@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,
-and the names do @emph{not} have to be defined for each device.
+@example
+(graphics-opereration g 'draw-arc 3 5 .5 .5 45 90 #t)
+@end example
+@end defop
-Color names defined by this interface may also be used when setting the
-colors of the Scheme console window, or the colors of Edwin editor
-windows.
+@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
+@findex draw-circle
+@findex fill-circle
+These operations draw a circle (outline) or a filled circle (solid) at
+on the graphics device at the virtual coordinates given by @var{x} and
+@var{y}. These operations could be implemented trivially interms of the
+@code{draw-arc} operation.
@end defop
-@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}.
+@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
+pixels. The change takes place immediately. Note that changing the
+internal border width can cause displayed graphics to be garbled; we
+recommend calling @code{graphics-clear} on the window's device after
+doing so.
@end defop
+@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+} win32-graphics-device draw-ellipse left top right bottom
-@cindex ellipse, graphics
-@cindex circle, graphics
-@cindex graphics, ellipse
-@cindex graphics, circle
-Draw an ellipse. @var{Left}, @var{top}, @var{right} and @var{bottom}
-indicate the coordinates of the bounding rectangle of the ellipse.
-Circles are merely ellipses with equal width and height. Note that the
-bounding rectangle has horizontal and vertical sides. Ellipses with
-rotated axes cannot be drawn. The rectangle applies to the center of the
-line used to draw the ellipse; if the line width has been set to greater
-than 1 then the ellipse will spill outside the bounding rectange by half
-of the line width.
+@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
+These operations control the mapping of windows. They correspond
+directly to Xlib's @code{XMapWindow} and @code{XWithdrawWindow}.
+@end defop
-@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.
-The numbers are in the order x1 y1 x2 y2 ... xn yn.
+@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}.
+
+This operation resets the virtual coordinate system and the clip
+rectangle.
+@end defop
+
+@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
+not take the external border into account, and therefore will not
+position the window as you might like. The only reliable way to
+position a window is to ask a window manager to do it for you.
+@end defop
+
+@defop {operation+} x-graphics-device get-default resource property
+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
+@var{resource} and @var{property}; if no such association exists,
+@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
+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
+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
+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
+of the @code{XLoadQueryFont} Xlib call. @code{start-index} is the index
+of the first character available in the font. The @code{min-bounds} and
+@code{max-bounds} components are structures of type
+@code{x-character-bounds}, and the @code{character-bounds} component is
+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
+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.
+@end deffn
+
+@node Win32 Graphics, OS/2 Graphics, X Graphics, Graphics
+@section Win32 Graphics
+@cindex Win32 graphics
+
+MIT Scheme supports graphics on Microsoft Windows 95, Windows 98, and
+Windows NT. In addition to the usual operations, there are operations
+to control the size, position and colors of a graphics window. Win32
+devices support images, which are implemented as device independent
+bitmaps (@sc{dib}s).
+
+The Win32 graphics device type is implemented as a top level window.
+@code{graphics-enable-buffering} is implemented and gives a 2x to 4x
+speedup on many graphics operations. As a convenience, when buffering
+is enabled clicking on the graphics window's title bar effects a
+@code{graphics-flush} operation. The user has the benefit of the
+increased performance and the ability to view the progress in drawing at
+the click of a mouse button.
+
+
+@menu
+* Win32 Graphics Type::
+* Custom Operations for Win32 Graphics:: Custom Operations for Win32 Graphics Devices
+@end menu
+
+@node Win32 Graphics Type, Custom Operations for Win32 Graphics, Win32 Graphics, Win32 Graphics
+@subsection Win32 Graphics Type
+
+Win32 graphics devices are created by specifying the symbol @code{win32}
+as the @var{graphics-device-type} argument to
+@code{make-graphics-device}. The Win32 graphics device type is
+implemented as a top-level window and supports color drawing in addition
+to the standard Scheme graphics operations.
+
+Graphics devices are opened as follows:
+
+@example
+(make-graphics-device 'win32 #!optional @var{width} @var{height} @var{palette})
+@end example
+
+@noindent
+where @var{width} and @var{height} specify the size, in pixels, of the
+drawing area in the graphics window (i.e.@: excluding the frame).
+@var{Palette} determines the colors available for drawing in the window.
+
+When a color is specified for drawing, the nearest color available in
+the palette is used. Permitted values for @var{palette} are
+
+@table @asis
+@item @code{'grayscale}
+The window allocates colors from a grayscale palette
+of approximately 236 shades of gray.
+
+@item @code{'grayscale-128}
+The window allocates colors from a grayscale palette of 128 shades of
+gray.
+
+@item @code{'standard}
+The standard palette has good selection of colors and grays.
+
+@item @code{#f} or @code{'system}
+The colors available are those in the system palette. There are usually
+16 to 20 colors in the system palette and these are usually sufficent
+for simple applications like line drawings and x-vs-y graphs of
+mathematical functions. Drawing with the system palette can be more
+efficient.
+
+@end table
+@noindent
+If @var{palette} is not specified then the @code{standard} palette is
+used.
+
+
+
+@node Custom Operations for Win32 Graphics, , Win32 Graphics Type, Win32 Graphics
+@subsection Custom Operations for Win32 Graphics
+
+Custom operations are invoked using the procedure
+@code{graphics-operation}. For example,
+
+@example
+(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
+@findex set-background-color
+@findex set-foreground-color
+@cindex color
+These operations change the colors associated with a window.
+@var{Color-name} must be of one of the valid color specification forms
+listed below. @code{set-background-color} and
+@code{set-foreground-color} change the colors to be used when drawing,
+but have no effect on anything drawn prior to their invocation. Because
+changing the background color affects the entire window, we recommend
+calling @code{graphics-clear} on the window's device afterwards.
+
+The foreground color affects the drawing of text, points, lines,
+ellipses and filled polygons.
+
+Colors are specified in one of three ways:
+
+@table @asis
+@item An integer
+This is the Win32 internal RGB value.
+
+@item By name
+A limited number of names are understood by the system.
+Names are strings, e.g.@: @code{"red"}, @code{"blue"}, @code{"black"}.
+More names can be registered with the @code{define-color} operation.
+
+@item RGB (Red-Green-Blue) triples
+A triple is either a vector or list of three integers in the range
+0--255 inclusive which specify the intensity of the red, green and blue
+components of the color. Thus @code{#(0 0 0)} is black, @code{(0 0
+128)} is dark blue and @code{#(255 255 255)} is white.
+@end table
+
+@noindent
+If the color is not available in the graphics device then the nearest
+available color is used instead.
+@end defop
+
+
+@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,
+and the names do @emph{not} have to be defined for each device.
+
+
+Color names defined by this interface may also be used when setting the
+colors of the Scheme console window, or the colors of Edwin editor
+windows.
+@end defop
+
+@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
+@cindex ellipse, graphics
+@cindex circle, graphics
+@cindex graphics, ellipse
+@cindex graphics, circle
+Draw an ellipse. @var{Left}, @var{top}, @var{right} and @var{bottom}
+indicate the coordinates of the bounding rectangle of the ellipse.
+Circles are merely ellipses with equal width and height. Note that the
+bounding rectangle has horizontal and vertical sides. Ellipses with
+rotated axes cannot be drawn. The rectangle applies to the center of the
+line used to draw the ellipse; if the line width has been set to greater
+than 1 then the ellipse will spill outside the bounding rectange by half
+of the line width.
+@end defop
+
+
+@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.
+The numbers are in the order x1 y1 x2 y2 ... xn yn.
For example,
@example
@var{destination-y-top}.
@end defop
-@node OS/2 Graphics, X Graphics, Win32 Graphics, Graphics
+@node OS/2 Graphics, , Win32 Graphics, Graphics
@section OS/2 Graphics
@cindex OS/2 graphics
-MIT Scheme supports graphics under the OS/2 Presentation Manager in OS/2
-version 2.1 and later. The OS/2 graphics device type is implemented as
-a top level window. In addition to the usual operations, there are
-operations to control the size, position, and colors of a graphics
-window. OS/2 graphics devices support images, which are implemented as
-memory presentation spaces.
+MIT Scheme supports graphics under the OS/2 Presentation Manager in
+OS/2 version 2.1 and later. The OS/2 graphics device type is
+implemented as a top level window. In addition to the usual operations,
+there are operations to control the size, position, and colors of a
+graphics window. OS/2 graphics devices support images, which are
+implemented as memory presentation spaces.
The custom graphics operations defined in this section are invoked using
the procedure @code{graphics-operation}. For example,
* Miscellaneous Operations for OS/2 Graphics::
@end menu
-@node OS/2 Graphics Type, Color Operations for OS/2 Graphics, , OS/2 Graphics
+@node OS/2 Graphics Type, Color Operations for OS/2 Graphics, OS/2 Graphics, OS/2 Graphics
@subsection OS/2 Graphics Type
-OS/2 graphics devices are created by specifying the symbol @code{os/2}
-as the @var{graphics-device-type} argument to
+OS/2 graphics devices are created by specifying the symbol
+@code{os/2} as the @var{graphics-device-type} argument to
@code{make-graphics-device}. The OS/2 graphics device type is
implemented as a top-level window and supports color drawing in addition
to the standard Scheme graphics operations.
@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 device,
-and the names do @emph{not} have to be defined for each device.
+color names defined this way are available to any OS/2 graphics
+device, and the names do @emph{not} have to be defined for each device.
Color names defined by this interface may also be used when setting the
colors of the Scheme console window, or the colors of Edwin editor
guarantee that the entire window is visible on the desktop.
@end defop
-@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
-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
-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
-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
-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
-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
-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
-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
-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
-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.
-@end defop
-
-@node Event Operations for OS/2 Graphics, Miscellaneous Operations for OS/2 Graphics, Window Operations for OS/2 Graphics, OS/2 Graphics
-@subsection Event Operations for OS/2 Graphics
-
-These operations allow you to read some of the events that are generated
-by the Presentation Manager and put in the message queue of a
-graphics-device window.
-
-@defop {operation+} os2-graphics-device read-button
-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
-coordinates of the mouse pointer at the time the button was pressed, in
-pels (pixels) relative to the lower left hand corner of the client area;
-and the graphics device that the mouse pointer was over at the time the
-button was pressed.
-
-Note that this operation only works when button events are selected
-(which is the default).
-@end defop
-
-@defop {operation+} os2-graphics-device select-user-events mask
-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
-user-event queue for later retrieval by the @code{read-user-event}
-operation. The mask is specified by setting the bits corresponding to
-the event types that you are interested in, as follows:
-
-@example
-@group
-Number Mask Description
------- ----- -----------
-0 #x001 Button press/release
-1 #x002 Close (close the window) [WM_CLOSE]
-2 #x004 Focus change [WM_SETFOCUS]
-3 #x008 Key press/release [WM_CHAR]
-4 #x010 Paint [WM_PAINT]
-5 #x020 Size change [WM_SIZE]
-6 #x040 Visibility change [WM_SHOW]
-7 #x080 Command [WM_COMMAND]
-8 #x100 Help [WM_HELP]
-9 #x200 Mouse-move [WM_MOUSEMOVE]
-@end group
-@end example
-
-@noindent
-Note that this operation does not affect any events that are already in
-the user-event queue. Changing the mask only affects what events will
-be added to the queue in the future.
-@end defop
-
-@defop {operation+} os2-graphics-device read-user-event
-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.
-@end defop
-
-An event is a vector whose first element is the event-type number, whose
-second element is the graphics device that the event refers to, and
-whose remaining elements provide information about the event. Here is a
-table of the possible event types and their vector layout:
-
-@table @code
-@item #(0 @var{device} @var{number} @var{type} @var{x} @var{y} @var{flags})
-A button event. @var{Number} is the button number, for example button
-number @code{0} is usually the left mouse button, @code{1} is usually
-the right button, etc. @var{Type} specifies what occurred: @code{0}
-means the button was pressed, @code{1} means the button was released,
-@code{2} means the button was clicked, and @code{3} means the button was
-double clicked. @var{X} and @var{y} are the position of the mouse
-pointer at the time of the event, in units of pels (pixels) measured
-from the lower left corner of the client area of the associated window.
-Finally, @var{flags} specifies what shift keys were pressed at the time
-of the button event; it is a mask word created by combining zero or more
-of the following flags: @code{#x08} means the shift key was pressed,
-@code{#x10} means the control key was pressed, and @code{#x20} means the
-alt key was pressed.
-
-@item #(1 @var{device})
-A close event. The user has selected the close button from the system
-menu, or typed @key{Alt-f4}.
-
-@item #(2 @var{device} @var{gained?})
-A focus event. If @var{gained?} is @code{#t}, the keyboard focus is
-being gained, and if @var{gained?} is @code{#f}, it is being lost.
-
-@item #(3 @var{device} @var{code} @var{flags} @var{repeat})
-A keyboard event. This is much too complicated to describe here. See
-the OS/2 toolkit documentation for details.
-
-@item #(4 @var{device} @var{xl} @var{xh} @var{yl} @var{yh})
-A paint event. Part of the graphics-device window that was obscured has
-been revealed and the Presentation Manager is informing the window that
-it must repaint that area. Scheme will take care of the painting for
-you, so this event isn't very useful.
-
-@item #(5 @var{device} @var{width} @var{height})
-A size-change event. The size of the graphics-device window has
-changed, and @var{width} and @var{height} specify the new size in pels
-(pixels).
-
-@item #(6 @var{device} @var{shown?})
-A visibility event. Indicates that the graphics-device window has been
-hidden or revealed. If @var{shown?} is @code{#f}, the window is hidden,
-and if it is @code{#t}, the window is shown.
-
-@item #(7 @var{device} @var{source} @var{mouse?})
-@itemx #(8 @var{device} @var{source} @var{mouse?})
-A menu command. @var{Source} specifies which menu item was selected to
-cause this event, and @var{mouse?} is a boolean indicating whether the
-item was selected with the mouse or the keyboard. The event-type number
-@code{7} indicates a command from a @samp{WM_COMMAND} message, while
-@code{8} is a command from a @samp{WM_HELP} message.
-
-@item #(9 @var{device} @var{x} @var{y} @var{hit-test} @var{flags})
-The mouse was moved. @var{X} and @var{y} specify the position of the
-mouse, @var{hit-test} contains the hit-test information, and @var{flags}
-specifies the modifier keys that were pressed at the time.
-@end table
-
-@defop {operation+} os2-graphics-device discard-events
-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.
-@end defop
-
-@node Miscellaneous Operations for OS/2 Graphics, , Event Operations for OS/2 Graphics, OS/2 Graphics
-@subsection Miscellaneous Operations for OS/2 Graphics
-
-These operations allow you to: change the font used for drawing text in
-a graphics-device window; take a snapshot of a graphics-device window
-and return it as an image object; and draw multiple lines efficiently.
-
-@defop {operation+} os2-graphics-device set-font font-name
-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
-example, @code{"10.Courier"}. You may specify any fixed-pitch font
-family, in any point size that is supported for that font family. This
-includes both image fonts and outline fonts.
-@end defop
-
-@defop {operation+} os2-graphics-device capture-image x-left y-bottom x-right y-top
-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,
-which are given in the current virtual coordinates for the device.
-@xref{Images}, for more information about manipulating images.
-@end defop
-
-@defop {operation+} os2-graphics-device draw-lines xv yv
-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
-length, and the length must be a multiple of two. The contents of the
-vectors are alternating start/end pairs. For example, the following are
-equivalent:
-
-@example
-@group
-(graphics-draw-line device xs ys xe ye)
-(graphics-operation device 'draw-lines
- (vector xs xe)
- (vector ys ye))
-@end group
-@end example
-@end defop
-
-@node X Graphics, Starbase Graphics, OS/2 Graphics, Graphics
-@section X Graphics
-@cindex X graphics
-
-@cindex X window system
-MIT Scheme supports graphics in the X window system (version 11).
-Arbitrary numbers of displays may be opened, and arbitrary numbers of
-graphics windows may be created for each display. A variety of
-operations is available to manipulate various aspects of the windows, to
-control their size, position, colors, and mapping. The X graphics
-device type supports images, which are implemented as Xlib @code{XImage}
-objects. X display, window, and image objects are automatically closed
-if they are reclaimed by the garbage collector.
-
-@menu
-* X Graphics Type::
-* Utilities for X Graphics::
-* Custom Operations on X Graphics Devices::
-@end menu
-
-@node X Graphics Type, Utilities for X Graphics, , X Graphics
-@subsection X Graphics Type
-
-
-A graphics device for X windows is created by passing the symbol
-@code{x} as the graphics device type name to
-@code{make-graphics-device}:
-
-@example
-(make-graphics-device 'x #!optional @var{display} @var{geometry} @var{suppress-map?})
-@end example
-
-@noindent
-where @var{display} is either a display object, @code{#f}, or a string;
-@var{geometry} is either @code{#f} or a string; and @var{suppress-map?}
-is a boolean or a vector (see below). A new window is created on the
-appropriate display, and a graphics device representing that window is
-returned.
-
-@findex x-open-display
-@var{Display} specifies which X display the window is to be opened on;
-if it is @code{#f} or a string, it is passed as an argument to
-@code{x-open-display}, and the value returned by that procedure is used
-in place of the original argument. @var{Geometry} is an X geometry
-string, or @code{#f} which means to use the default geometry (which is
-specified as a resource).
-
-@var{Suppress-map?}, if given, may take two forms. First, it may be a
-boolean: if @code{#f} (the default), the window is automatically mapped
-after it is created; otherwise, @code{#t} means to suppress this
-automatic mapping. The second form is a vector of three elements. The
-first element is a boolean with the same meaning as the boolean form of
-@var{suppress-map?}. The second element is a string, which specifies an
-alternative resource name to be used for looking up the window's
-resources. The third element is also a string, which specifies a class
-name for looking up the window's resources. The default value for
-@var{suppress-map?} is @code{#f}.
-
-The default resource and class names are @code{"schemeGraphics"} and
-@code{"SchemeGraphics"} respectively.
-
-@cindex resources, X graphics
-@cindex X resources, graphics
-The window is initialized using the resource and class names specified
-by @var{suppress-map?}, and is sensitive to the following resource
-properties:
-
-@example
-@group
-Property Class Default
--------- ----- -------
-geometry Geometry 512x384+0+0
-font Font fixed
-borderWidth BorderWidth 2
-internalBorder BorderWidth @r{[border width]}
-background Background white
-foreground Foreground black
-borderColor BorderColor @r{[foreground color]}
-cursorColor Foreground @r{[foreground color]}
-pointerColor Foreground @r{[foreground color]}
-@end group
-@end example
-
-The window is created with a @code{backing_store} attribute of
-@code{Always}. The window's name and icon name are initialized to
-@code{"scheme-graphics"}.
-
-
-@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
-@cindex display, X graphics
-@cindex X display, graphics
-Opens a connection to the display whose name is @var{display-name},
-returning a display object. If unable to open a connection, @code{#f}
-is returned. @var{Display-name} is normally a string, which is an X
-display name in the usual form; however, @code{#f} is also allowed,
-meaning to use the value of the unix environment variable
-@code{DISPLAY}.
-@end deffn
-
-@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
-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
-@cindex geometry string, X graphics
-@cindex X geometry string, graphics
-This procedure creates and returns a standard X geometry string from the
-given arguments. @var{X} and @var{y} must be either exact integers or
-@code{#f}, while @var{width} and @var{height} must be either exact
-non-negative integers or @code{#f}. Usually either @var{x} and @var{y}
-are both specified or both @code{#f}; similarly for @var{width} and
-@var{height}. If only one of the elements of such a pair is specified,
-it is ignored.
-
-Examples:
-
-@example
-@group
-(x-geometry-string #f #f 100 200) @result{} "100x200"
-(x-geometry-string 2 -3 100 200) @result{} "100x200+2-3"
-(x-geometry-string 2 -3 #f #f) @result{} "+2-3"
-@end group
-@end example
-
-Note that the @var{x} and @var{y} arguments cannot distinguish between
-@code{+0} and @code{-0}, even though these have different meanings in X.
-If either of those arguments is @code{0}, it means @code{+0} in X
-terminology. If you need to distinguish these two cases you must create
-your own geometry string using Scheme's string and number primitives.
-@end deffn
-
-@node Custom Operations on X Graphics Devices, , Utilities for X Graphics, X Graphics
-@subsection Custom Operations on X Graphics Devices
-
-Custom operations are invoked using the procedure
-@code{graphics-operation}. For example,
-
-@example
-(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
-@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
-desired color. @code{set-border-color} and @code{set-mouse-color}
-immediately change the border and mouse-cursor colors.
-@code{set-background-color} and @code{set-foreground-color} change the
-colors to be used when drawing, but have no effect on anything drawn
-prior to their invocation. Because changing the background color
-affects the entire window, we recommend calling @code{graphics-clear} on
-the window's device afterwards. Color names include both mnemonic
-names, like @code{"red"}, and intensity names specified in the
-@code{"#@var{rrggbb}"} notation.
-@end defop
-
-@defop {operation+} x-graphics-device draw-arc x y radius-x radius-y angle-start angle-sweep fill?
-@cindex drawing arcs and circles, graphics
-@cindex graphics, drawing arcs and circles
-@cindex circles, drawing
-@findex draw-arc
-
-Operation @code{draw-arc} draws or fills an arc. An arc is a segment of
-a circle, which may have been stretched along the x- or y- axis to form
-an ellipse.
-
-The parameters @var{X}, @var{Y}, @var{RADIUS-X} and @var{RADIUS-Y}
-describe the circle and @var{ANGLE-START} and @var{ANGLE-SWEEP} choose
-which part of the circle is drawn. The arc is drawn on the graphics
-device with the center of the circle at the virtual coordinates given by
-@var{X} and @var{Y}. @var{RADIUS-X} and @var{RADIUS-Y} determine the
-size of the circle in virtual coordinate units.
-
-The parameter @var{ANGLE-START} determines where the arc starts. It is
-measured in degrees in an anti-clockwise direction, starting at 3
-o'clock. @var{ANGLE-SWEEP} determines how much of the circle is drawn.
-It too is measured anti-clockwise in degrees. A negative value means
-the measurement is in a clockwise direction.
-
-Note that the angles are determined on a unit circle before it is
-stretched into an ellipse, so the actual angles that you will see on the
-computer screen depends on all of: @var{RADIUS-X} and @var{RADIUS-Y},
-the window size, and the virtual coordinates.
-
-If @var{fill?} is @code{#F} then just the segment of the circle is
-drawn, otherwise the arc is filled in a pie-slice fashion.
-
-This draws a quarter circle pie slice, standing on its point, with point
-at virtual coordinates (3,5):
-
-@example
-(graphics-opereration g 'draw-arc 3 5 .5 .5 45 90 #T)
-@end example
-
-@end defop
-
-@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
-@findex draw-circle
-@findex fill-circle
-These operations draw a circle (outline) or a filled circle (solid) at
-on the graphics device at the virtual coordinates given by @var{X} and
-@var{Y}. These operations could be implemented trivially interms of the
-@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
-@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
-pixels. The change takes place immediately. Note that changing the
-internal border width can cause displayed graphics to be garbled; we
-recommend calling @code{graphics-clear} on the window's device after
-doing so.
+@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+} 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.
+@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+} 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}.
+@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+} x-graphics-device map-window
-@defopx {operation+} x-graphics-device withdraw-window
-These operations control the mapping of windows. They correspond
-directly to the Xlib procedures @code{XMapWindow} and
-@code{XWithdrawWindow}.
+@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+} 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 the
-Xlib procedure @code{XResizeWindow}.
+@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
-This operation resets the virtual coordinate system and the clip
-rectangle.
+@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+} 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 the Xlib
-procedure @code{XMoveWindow}. Note that the coordinates @var{x} and
-@var{y} do not take the external border into account, and therefore will
-not position the window as you might like. The only reliable way to
-position a window is to ask a window manager to do it for you.
+@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+} x-graphics-device get-default resource property
-This operation corresponds directly to the Xlib procedure
-@code{XGetDefault}. @var{Resource} and @var{property} must be strings.
-The operation returns the character string corresponding to the
-association of @var{resource} and @var{property}; if no such association
-exists, @code{#f} is returned.
+@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+} 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}.
+@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+} 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.
+@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.
@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
-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
-of the @code{XLoadQueryFont} Xlib call. @code{start-index} is the index
-of the first character available in the font. The @code{min-bounds} and
-@code{max-bounds} components are structures of type
-@code{x-character-bounds}, and the @code{character-bounds} component is
-a vector of the same type.
-@end deffn
+@node Event Operations for OS/2 Graphics, Miscellaneous Operations for OS/2 Graphics, Window Operations for OS/2 Graphics, OS/2 Graphics
+@subsection Event Operations for OS/2 Graphics
-@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.
-@end deffn
+These operations allow you to read some of the events that are generated
+by the Presentation Manager and put in the message queue of a
+graphics-device window.
-@node Starbase Graphics, , X Graphics, Graphics
-@section Starbase Graphics
-@cindex starbase graphics
+@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
+coordinates of the mouse pointer at the time the button was pressed, in
+pels (pixels) relative to the lower left hand corner of the client area;
+and the graphics device that the mouse pointer was over at the time the
+button was pressed.
-On Hewlett-Packard computers under the HP-UX operating system, Scheme
-supports graphics through the Starbase graphics library. Note that the
-default distribution of Scheme for HP computers does not include support
-for Starbase --- you must rebuild the microcode to get this support.
+Note that this operation only works when button events are selected
+(which is the default).
+@end defop
-@defvr {variable+} starbase-graphics-device-type
-This is the device type for Starbase graphics devices. A Starbase
-device is opened as follows:
+@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
+user-event queue for later retrieval by the @code{read-user-event}
+operation. The mask is specified by setting the bits corresponding to
+the event types that you are interested in, as follows:
@example
-(make-graphics-device 'starbase @var{device-name} @var{driver-name})
+@group
+Number Mask Description
+------ ----- -----------
+0 #x001 Button press/release
+1 #x002 Close (close the window) [WM_CLOSE]
+2 #x004 Focus change [WM_SETFOCUS]
+3 #x008 Key press/release [WM_CHAR]
+4 #x010 Paint [WM_PAINT]
+5 #x020 Size change [WM_SIZE]
+6 #x040 Visibility change [WM_SHOW]
+7 #x080 Command [WM_COMMAND]
+8 #x100 Help [WM_HELP]
+9 #x200 Mouse-move [WM_MOUSEMOVE]
+@end group
@end example
-where @var{device-name} and @var{driver-name} are strings that are used
-as the device and driver arguments to the Starbase @code{gopen} call.
-The device is opened with kind @code{OUTDEV} and mode @code{0}. The
-device is initialized to have a mapping mode of @code{DISTORT}, and a
-line color index of @code{1}.
-@end defvr
-
-@defop {operation+} starbase-graphics-device write-image-file filename invert?
-This operation writes an image of the Starbase device's display in the
-file specified by @var{filename}. The image is formatted to print on an
-HP Laserjet printer. Normally pixels with a color index of 0 are not
-drawn by the printer, and all other pixels are; this results in the
-background being white and the foreground being black in the printed
-image. If @var{invert?} is not @code{#f}, this is reversed: the
-background is printed as black and the foreground is not printed.
+@noindent
+Note that this operation does not affect any events that are already in
+the user-event queue. Changing the mask only affects what events will
+be added to the queue in the future.
@end defop
-@defop {operation+} starbase-graphics-device color-map-size
-Returns, as an exact non-negative integer, the number of entries in the
-color map for the device.
+@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.
@end defop
-@defop {operation+} starbase-graphics-device define-color color-index red green blue
-Defines the color associated with the color-map index @var{color-index}.
-@var{Color-index} must be an exact non-negative integer strictly less
-than the number of entries in the color map. @var{Red}, @var{green},
-and @var{blue} must be real numbers in the range 0 to 1 inclusive, which
-define the color to be put in the map.
-@end defop
+An event is a vector whose first element is the event-type number, whose
+second element is the graphics device that the event refers to, and
+whose remaining elements provide information about the event. Here is a
+table of the possible event types and their vector layout:
-@defop {operation+} starbase-graphics-device set-line-color color-index
-Changes the foreground color used in graphics operations for this
-device. @var{Color-index} must be an exact non-negative integer
-strictly less than the number of entries in the color map. Graphics
-drawn after this operation is invoked will appear in this new color.
-@end defop
+@table @code
+@item #(0 @var{device} @var{number} @var{type} @var{x} @var{y} @var{flags})
+A button event. @var{Number} is the button number, for example button
+number @code{0} is usually the left mouse button, @code{1} is usually
+the right button, etc. @var{Type} specifies what occurred: @code{0}
+means the button was pressed, @code{1} means the button was released,
+@code{2} means the button was clicked, and @code{3} means the button was
+double clicked. @var{X} and @var{y} are the position of the mouse
+pointer at the time of the event, in units of pels (pixels) measured
+from the lower left corner of the client area of the associated window.
+Finally, @var{flags} specifies what shift keys were pressed at the time
+of the button event; it is a mask word created by combining zero or more
+of the following flags: @code{#x08} means the shift key was pressed,
+@code{#x10} means the control key was pressed, and @code{#x20} means the
+alt key was pressed.
-The text drawn by a Starbase device is controlled by the following
-characteristics:
+@item #(1 @var{device})
+A close event. The user has selected the close button from the system
+menu, or typed @key{Alt-f4}.
-@table @asis
-@item Aspect
-The @dfn{aspect} of a character is its height-to-width ratio, a real
-number. By default, this has the value @code{1}.
-@cindex aspect, of graphics character (defn)
-
-@item Height
-The @dfn{height} of a character in virtual device coordinates, a real
-number. This is measured along the ``up vector'', which is defined by
-the slant of the character. By default, the height is @code{.1}.
-@cindex height, of graphics character (defn)
-
-@item Rotation
-The @dfn{rotation} of a character defines the direction in which the
-characters are drawn. It is specified as a real number in degrees, but
-only 4 values have any meaning: @code{0}, @code{90}, @code{180}, and
-@code{270}. @code{0} draws left-to-right with upright characters;
-@code{90} draws top-to-bottom with characters on their right side;
-@code{180} draws right-to-left with upside-down characters; @code{270}
-draws bottom-to-top with characters on their left side. The default
-rotation is @code{0}.
-@cindex rotation, of graphics character (defn)
-
-@item Slant
-The @dfn{slant} of a character defines the ``up vector''; it is a real
-number which is the tangent of the angle between the character's
-``vertical'' (defined by the rotation), and the ``up vector'', measured
-clockwise. The default slant is @code{0}.
-@cindex slant, of graphics character (defn)
+@item #(2 @var{device} @var{gained?})
+A focus event. If @var{gained?} is @code{#t}, the keyboard focus is
+being gained, and if @var{gained?} is @code{#f}, it is being lost.
+
+@item #(3 @var{device} @var{code} @var{flags} @var{repeat})
+A keyboard event. This is much too complicated to describe here. See
+the OS/2 toolkit documentation for details.
+
+@item #(4 @var{device} @var{xl} @var{xh} @var{yl} @var{yh})
+A paint event. Part of the graphics-device window that was obscured has
+been revealed and the Presentation Manager is informing the window that
+it must repaint that area. Scheme will take care of the painting for
+you, so this event isn't very useful.
+
+@item #(5 @var{device} @var{width} @var{height})
+A size-change event. The size of the graphics-device window has
+changed, and @var{width} and @var{height} specify the new size in pels
+(pixels).
+
+@item #(6 @var{device} @var{shown?})
+A visibility event. Indicates that the graphics-device window has been
+hidden or revealed. If @var{shown?} is @code{#f}, the window is hidden,
+and if it is @code{#t}, the window is shown.
+
+@item #(7 @var{device} @var{source} @var{mouse?})
+@itemx #(8 @var{device} @var{source} @var{mouse?})
+A menu command. @var{Source} specifies which menu item was selected to
+cause this event, and @var{mouse?} is a boolean indicating whether the
+item was selected with the mouse or the keyboard. The event-type number
+@code{7} indicates a command from a @samp{WM_COMMAND} message, while
+@code{8} is a command from a @samp{WM_HELP} message.
+
+@item #(9 @var{device} @var{x} @var{y} @var{hit-test} @var{flags})
+The mouse was moved. @var{X} and @var{y} specify the position of the
+mouse, @var{hit-test} contains the hit-test information, and @var{flags}
+specifies the modifier keys that were pressed at the time.
@end table
-@defop {operation+} starbase-graphics-device text-aspect
-@defopx {operation+} starbase-graphics-device text-height
-@defopx {operation+} starbase-graphics-device text-rotation
-@defopx {operation+} starbase-graphics-device text-slant
-These operations return the current values of the text
-characteristics.
+@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.
+@end defop
+
+@node Miscellaneous Operations for OS/2 Graphics, , Event Operations for OS/2 Graphics, OS/2 Graphics
+@subsection Miscellaneous Operations for OS/2 Graphics
+
+These operations allow you to: change the font used for drawing text in
+a graphics-device window; take a snapshot of a graphics-device window
+and return it as an image object; and draw multiple lines efficiently.
+
+@defop {operation+} os2-graphics-device set-font font-name
+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
+example, @code{"10.Courier"}. You may specify any fixed-pitch font
+family, in any point size that is supported for that font family. This
+includes both image fonts and outline fonts.
@end defop
-@defop {operation+} starbase-graphics-device set-text-aspect aspect
-@defopx {operation+} starbase-graphics-device set-text-height height
-@defopx {operation+} starbase-graphics-device set-text-rotation rotation
-@defopx {operation+} starbase-graphics-device set-text-slant slant
-These operations alter the current values of the text characteristics.
-They have no effect on text drawn prior to their invocation.
+@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,
+which are given in the current virtual coordinates for the device.
+@xref{Images}, for more information about manipulating images.
+@end defop
+
+@defop {operation+} os2-graphics-device draw-lines xv yv
+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
+length, and the length must be a multiple of two. The contents of the
+vectors are alternating start/end pairs. For example, the following are
+equivalent:
+
+@example
+@group
+(graphics-draw-line device xs ys xe ye)
+(graphics-operation device 'draw-lines
+ (vector xs xe)
+ (vector ys ye))
+@end group
+@end example
@end defop
-@c WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW
@node Win32 Package Reference, Index, Graphics, Top
@chapter Win32 Package Reference
@end menu
-@node Win32 Package Overview, Foreign function interface, , Win32 Package Reference
+@node Win32 Package Overview, Foreign function interface, Win32 Package Reference, Win32 Package Reference
@section Overview
mechanism.
@cindex limitations
-@strong{Warning:} The FFI as it stands has several flaws which make it
+@strong{Warning}: The FFI as it stands has several flaws which make it
difficult to use reliably. It is expected that both the interface to
and the mechanisms used by the FFI will be changed in the future. We
provide it, and this documentation, only to give people an early start
C data structure).
@cindex warning
-@strong{Warning:} It is extremely dangerous to try to pass Scheme
+@strong{Warning}: It is extremely dangerous to try to pass Scheme
callback procedures to C procedures. It is only possible by passing
integer `handles' rather than the actual procedures, and even so, if a
garbage collection occurs during the execution of the callback procedure
* Win32 API names and procedures::
@end menu
-@node Windows Types, Windows Foreign Procedures, , Foreign function interface
+@node Windows Types, Windows Foreign Procedures, Foreign function interface, Foreign function interface
@subsection Windows Types
@cindex Windows types
@example
@group
(define my-type unchecked) @error{} Unbound variable
-(define-similar-windows-type my-type unchecked) @r{;; the correct way}
+(define-similar-windows-type my-type unchecked)
+ @r{;; the correct way}
@end group
@end example
@example
@group
(define set-window-title
- (windows-procedure (set-window-text (window hwnd) (text string))
- bool user32.dll "SetWindowText"))
+ (windows-procedure
+ (set-window-text (window hwnd) (text string))
+ bool user32.dll "SetWindowText"))
-(set-window-title my-win "Hi") @result{} #t
- @r{;; Changes window's title/text}
+(set-window-title my-win "Hi")
+ @result{} #t
+ @r{;; Changes window's title/text}
-set-window-title @result{} #[compiled-procedure ...]
-set-window-text @error{} Unbound variable
+set-window-title @result{} #[compiled-procedure ...]
+set-window-text @error{} Unbound variable
@end group
@end example
* Other parts of the DIB Utilities implementation::
@end menu
-@node DIB procedures, Other parts of the DIB Utilities implementation, , Device Independent Bitmap Utilities
+@node DIB procedures, Other parts of the DIB Utilities implementation, Device Independent Bitmap Utilities, Device Independent Bitmap Utilities
@subsection DIB procedures
The following procedures have typed parameters, using the same
@deffn {procedure+} dib-set-pixels-unaligned dib (pixels string)
Return type: @var{bool}.
-Calls the @code{DIBSetPixelsUnaligned} entry of @file{DIBUTILS.DLL}. Stuffs
+Calls the @code{DIBSetPixelsUnaligned} entry of@* @file{DIBUTILS.DLL}. Stuffs
bytes from @var{pixels} into the bitmap. There are no alignment
constraints on @var{pixels} (the usual way of doing this is to use the
@code{SetDIBits} function which requires that every scan line of the
@c @section Writing windows procedures
@c
@c @cindex warning
-@c @strong{Warning:} Do not try to do this. It is very hard to get it even
+@c @strong{Warning}: Do not try to do this. It is very hard to get it even
@c partly right and probably impossible to make the program 100% reliable.
@c
@c It is possible to write Scheme procedures that determine the behavior
projects / mit-scheme.git / commitdiff