Next: Blocking Mode, Previous: Input Procedures, Up: Input/Output [Contents][Index]
Output ports may or may not support buffering of output, in which output characters are collected together in a buffer and then sent to the output device all at once. (Most of the output ports implemented by the runtime system support buffering.) Sending all of the characters in the buffer to the output device is called flushing the buffer. In general, output procedures do not flush the buffer of an output port unless the buffer is full.
However, the standard output procedures described in this section
perform what is called 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
discretionary-flush-output. If so, then that operation is
invoked to flush the buffer. At present, only the console port defines
discretionary-flush-output; this is used to guarantee that output
to the console appears immediately after it is written, without
requiring calls to flush-output-port.
In this section, all optional arguments called port default to the current output port.
Note: MIT/GNU Scheme doesn’t support datum labels, so any
behavior in write, write-shared, or write-simple
that depends on datum labels is not implemented. At present all three
of these procedures are equivalent. This will be remedied in a future
release.
Writes a representation of object to the given textual output
port. Strings that appear in the written representation are
enclosed in quotation marks, and within those strings backslash and
quotation mark characters are escaped by backslashes. Symbols that
contain non-ASCII characters are escaped with vertical lines.
Character objects are written using the #\ notation.
If object contains cycles which would cause an infinite loop using the normal written representation, then at least the objects that form part of the cycle must be represented using datum labels. Datum labels must not be used if there are no cycles.
Implementations may support extended syntax to represent record types or other types that do not have datum representations.
The write procedure returns an unspecified value.
On MIT/GNU Scheme write performs discretionary output flushing.
The write-shared procedure is the same as write, except
that shared structure must be represented using datum labels for all
pairs and vectors that appear more than once in the output.
The write-simple procedure is the same as write, except
that shared structure is never represented using datum labels. This
can cause write-simple not to terminate if object
contains circular structure.
Writes a representation of object to the given textual output port.
Strings that appear in the written representation are output as if by
write-string instead of by write. Symbols are not escaped. Character
objects appear in the representation as if written by write-char
instead of by write. The display representation of other objects is
unspecified. However, display must not loop forever on
self-referencing pairs, vectors, or records. Thus if the normal write
representation is used, datum labels are needed to represent cycles as
in write.
Implementations may support extended syntax to represent record types or other types that do not have datum representations.
The display procedure returns an unspecified value.
Rationale: The write procedure is intended for producing
machine-readable output and display for producing
human-readable output.
Writes an end of line to textual output port. Exactly how this is done differs from one operating system to another. Returns an unspecified value.
Writes the character char (not an external representation of the character) to the given textual output port and returns an unspecified value.
Writes the characters of string from start to end in left-to-right order to the textual output port.
This procedure is deprecated; use write-string instead.
Writes the byte to the given binary output port and returns an unspecified value.
In MIT/GNU Scheme, if port is an interactive output port in
non-blocking mode and writing a byte would block, write-u8
immediately returns #f without writing anything. Otherwise
byte is written and 1 is returned.
Writes the bytes of bytevector from start to end in left-to-right order to the binary output port.
In MIT/GNU Scheme, if port is an interactive output port in
non-blocking mode write-bytevector will write as many bytes as
it can without blocking, then returns the number of bytes written; if
no bytes can be written without blocking, returns #f without
writing anything. Otherwise write-bytevector returns the
number of bytes actually written, which may be less than the number
requested if unable to write all the bytes. (For example, if writing
to a file and the file system is full.)
Flushes any buffered output from the buffer of port to the underlying file or device and returns an unspecified value.
This procedure is deprecated; use flush-output-port
instead.
Most output ports are able to tell whether or not they are at the
beginning of a line of output. If 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 port is not such a
port, this procedure is identical to newline. In either case,
fresh-line performs discretionary output flushing and returns an
unspecified value.
Like write, except that it writes an end-of-line to
port after writing object’s representation. This
procedure performs discretionary output flushing and returns an
unspecified value.
Performs a “beep” operation on port, performs discretionary output flushing, and returns an unspecified value. On the console port, this usually causes the console bell to beep, but more sophisticated interactive ports may take other actions, such as flashing the screen. On most output ports, e.g. file and string output ports, this does nothing.
“Clears the screen” of port, performs discretionary output flushing, and returns an unspecified value. On a terminal or window, this has a well-defined effect. On other output ports, e.g. file and string output ports, this does nothing.
pp prints object in a visually appealing and structurally
revealing manner on port. If object is a procedure,
pp attempts to print the source text. If the optional argument
as-code? is true, pp prints lists as Scheme code, providing
appropriate indentation; by default this argument is false. pp
performs discretionary output flushing and returns an unspecified value.
The following parameters may be used with parameterize to
change the behavior of the write and display procedures.
This parameter specifies the default radix used to print numbers. Its
value must be one of the exact integers 2, 8, 10,
or 16; the default is 10. For values other than
10, numbers are prefixed to indicate their radix.
This parameter specifies a limit on the length of the printed
representation of a list or vector; for example, if the limit is
4, only the first four elements of any list are printed, followed
by ellipses to indicate any additional elements. The value of this
parameter must be an exact non-negative integer, or #f meaning no
limit; the default is #f.
(parameterize ((param:printer-list-breadth-limit 4))
(lambda ()
(write-to-string '(a b c d))))
⇒ "(a b c d)"
(parameterize ((param:printer-list-breadth-limit 4))
(lambda ()
(write-to-string '(a b c d e))))
⇒ "(a b c d ...)"
This parameter specifies a limit on the nesting of lists and vectors in
the printed representation. If lists (or vectors) are more deeply
nested than the limit, the part of the representation that exceeds the
limit is replaced by ellipses. The value of this parameter must be an
exact non-negative integer, or #f meaning no limit; the default
is #f.
(parameterize ((param:printer-list-depth-limit 4))
(lambda ()
(write-to-string '((((a))) b c d))))
⇒ "((((a))) b c d)"
(parameterize ((param:printer-list-depth-limit 4))
(lambda ()
(write-to-string '(((((a)))) b c d))))
⇒ "((((...))) b c d)"
This parameter specifies a limit on the length of the printed
representation of strings. If a string’s length exceeds this limit, the
part of the printed representation for the characters exceeding the
limit is replaced by ellipses. The value of this parameter must be an
exact non-negative integer, or #f meaning no limit; the default
is #f.
(parameterize ((param:printer-string-length-limit 4))
(lambda ()
(write-to-string "abcd")))
⇒ "\"abcd\""
(parameterize ((param:printer-string-length-limit 4))
(lambda ()
(write-to-string "abcde")))
⇒ "\"abcd...\""
This parameter, which takes a boolean value, tells the printer to use a
special printed representation for objects that normally print in a form
that cannot be recognized by read. These objects are printed
using the representation #@n, where n is the result
of calling hash on the object to be printed. The reader
recognizes this syntax, calling unhash on n to get back the
original object. Note that this printed representation can only be
recognized by the Scheme program in which it was generated, because
these hash numbers are different for each invocation of Scheme.
These variables are deprecated; instead use the corresponding parameter objects.
Next: Blocking Mode, Previous: Input Procedures, Up: Input/Output [Contents][Index]