Next: , Previous: , Up: Input/Output   [Contents][Index]


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

standard procedure: write object [port]

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.

standard procedure: write-shared object [port]

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.

standard procedure: write-simple object [port]

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.

standard procedure: display object [port]

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.

standard procedure: newline [port]

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.

standard procedure: write-char char [port]

Writes the character char (not an external representation of the character) to the given textual output port and returns an unspecified value.

standard procedure: write-string string [port [start [end]]]

Writes the characters of string from start to end in left-to-right order to the textual output port.

obsolete procedure: write-substring string start end [port]

This procedure is deprecated; use write-string instead.

standard procedure: write-u8 byte [port]

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.

standard procedure: write-bytevector bytevector [port [start [end]]]

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

standard procedure: flush-output-port [port]

Flushes any buffered output from the buffer of port to the underlying file or device and returns an unspecified value.

obsolete procedure: flush-output [port]

This procedure is deprecated; use flush-output-port instead.

procedure: fresh-line [port]

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.

procedure: write-line object [port]

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.

procedure: beep [port]

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.

procedure: clear [port]

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

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

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.

parameter: param:printer-radix

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.

parameter: param:printer-list-breadth-limit

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))
  (write-to-string '(a b c d)))
                                ⇒ "(a b c d)"
(parameterize ((param:printer-list-breadth-limit 4))
  (write-to-string '(a b c d e)))
                                ⇒ "(a b c d ...)"
parameter: param:printer-list-depth-limit

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))
  (write-to-string '((((a))) b c d)))
                                ⇒ "((((a))) b c d)"
(parameterize ((param:printer-list-depth-limit 4))
  (write-to-string '(((((a)))) b c d)))
                                ⇒ "((((...))) b c d)"
parameter: param:printer-string-length-limit

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))
  (write-to-string "abcd"))
                                ⇒ "\"abcd\""
(parameterize ((param:printer-string-length-limit 4))
  (write-to-string "abcde"))
                                ⇒ "\"abcd...\""
parameter: param:print-with-maximum-readability?

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.

obsolete variable: *unparser-radix*
obsolete variable: *unparser-list-breadth-limit*
obsolete variable: *unparser-list-depth-limit*
obsolete variable: *unparser-string-length-limit*
obsolete variable: *unparse-with-maximum-readability?*

These variables are deprecated; instead use the corresponding parameter objects.


Next: , Previous: , Up: Input/Output   [Contents][Index]