Next: , 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.