Output Procedures (MIT/GNU Scheme 12.1)

Next: Blocking Mode, Previous: Input Procedures, 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.

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: Blocking Mode, Previous: Input Procedures, Up: Input/Output [Contents][Index]