Output Procedures - MIT/GNU Scheme 7.7.91
Description: MIT/GNU Scheme 7.7.91

Next: Format, Previous: Input Procedures, Up: Input/Output

### 14.5 Output Procedures

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`.

All optional arguments called output-port, if not supplied, default to the current output port.

— procedure: write-char char [output-port]

> Writes char (the character itself, not a written representation of the character) to output-port, performs discretionary output flushing, and returns an unspecified value.

— procedure: write-string string [output-port]

> Writes string to 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 `write-char`, except that it is usually much faster.

— procedure: write-substring string start end [output-port]

> Writes the substring defined by string, start, and end to output-port, performs discretionary output flushing, and returns an unspecified value. This is equivalent to writing the contents of the substring, one character at a time using `write-char`, except that it is usually much faster.

— procedure: write object [output-port]

> Writes a written representation of object to output-port, and returns an unspecified value. If object has a standard external representation, then the written representation generated by `write` shall be parsable by `read` into an equivalent object. Thus strings that appear in the written representation are enclosed in doublequotes, and within those strings backslash and doublequote are escaped by backslashes. `write` performs discretionary output flushing and returns an unspecified value.

— procedure: display object [output-port]

> Writes a representation of object to output-port. Strings appear in the written representation as if written by `write-string` instead of by `write`. Character objects appear in the representation as if written by `write-char` instead of by `write`. `display` performs discretionary output flushing and returns an unspecified value.1

— procedure: newline [output-port]

> Writes an end-of-line to output-port, performs discretionary output flushing, and returns an unspecified value. Equivalent to `(write-char #\newline` output-port`)`.

— procedure: fresh-line [output-port]

> Most output ports are able to tell whether or not they are at the beginning of a line of output. If 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 output-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.

— procedure: write-line object [output-port]

> Like `write`, except that it writes an end-of-line to output-port after writing object's representation. This procedure performs discretionary output flushing and returns an unspecified value.

— procedure: flush-output [output-port]

> If 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.

— procedure: beep [output-port]

> Performs a “beep” operation on output-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.

— procedure: clear [output-port]

> “Clears the screen” of output-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.

— procedure: pp object [output-port [as-code?]]

> `pp` prints object in a visually appealing and structurally revealing manner on output-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 variables may be dynamically bound to change the behavior of the `write` and `display` procedures.

— variable: *unparser-radix*

> This variable 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`. If `*unparser-radix*` is not `10`, numbers are prefixed to indicate their radix.

— variable: *unparser-list-breadth-limit*

> This variable specifies a limit on the length of the printed representation of a list or vector; for example, if the limit is `4`, only the first four elements of any list are printed, followed by ellipses to indicate any additional elements. The value of this variable must be an exact non-negative integer, or `#f` meaning no limit; the default is `#f`.

>               (fluid-let ((*unparser-list-breadth-limit* 4))
>                 (write-to-string '(a b c d)))
>                                               => "(a b c d)"
>               (fluid-let ((*unparser-list-breadth-limit* 4))
>                 (write-to-string '(a b c d e)))
>                                               => "(a b c d ...)"

— variable: *unparser-list-depth-limit*

> This variable specifies a limit on the nesting of lists and vectors in the printed representation. If lists (or vectors) are more deeply nested than the limit, the part of the representation that exceeds the limit is replaced by ellipses. The value of this variable must be an exact non-negative integer, or `#f` meaning no limit; the default is `#f`.

>               (fluid-let ((*unparser-list-depth-limit* 4))
>                 (write-to-string '((((a))) b c d)))
>                                               => "((((a))) b c d)"
>               (fluid-let ((*unparser-list-depth-limit* 4))
>                 (write-to-string '(((((a)))) b c d)))
>                                               => "((((...))) b c d)"

— variable: *unparser-string-length-limit*

> This variable specifies a limit on the length of the printed representation of strings. If a string's length exceeds this limit, the part of the printed representation for the characters exceeding the limit is replaced by ellipses. The value of this variable must be an exact non-negative integer, or `#f` meaning no limit; the default is `#f`.

>               (fluid-let ((*unparser-string-length-limit* 4))
>                 (write-to-string "abcd"))
>                                               => "\"abcd\""
>               (fluid-let ((*unparser-string-length-limit* 4))
>                 (write-to-string "abcde"))
>                                               => "\"abcd...\""

— variable: *unparse-with-maximum-readability?*

> This variable, which takes a boolean value, tells the printer to use a special printed representation for objects that normally print in a form that cannot be recognized by `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.

#### Footnotes

[1] `write` is intended for producing machine-readable output and `display` is for producing human-readable output.