30.8. Class EXT:FILL-STREAM

30.8. Class `EXT:FILL-STREAM`
Prev	Chapter 30. Gray streams	Next

30.8. Class `EXT:FILL-STREAM`

List of Examples

30.1. Example of EXT:FILL-STREAM usage

As an example of the use of “GRAY” STREAMs, CLISP offers an additional class, EXT:FILL-STREAM. An instance of this class is a “formatting” STREAM, which makes the final output to the underlying stream look neat: indented and filled. An instance of EXT:FILL-STREAM is created like this:

(MAKE-INSTANCE 'EXT:FILL-STREAM :stream stream
               [:text-indent symbol-or-number]
               [:sexp-indent symbol-or-number-or-function])

where

stream

is the target STREAM where the output actually goes.

symbol-or-number

is the variable whose value is the INTEGER text indentation or the indentation itself (defaults to 0).

symbol-or-number-or-function

When FORMAT writes an S-expression to a EXT:FILL-STREAM using ~S, and the expression's printed representation does not fit on the current line, it is printed on separate lines, ignoring the prescribed text indentation and preserving spacing. When this argument is non-NIL, the S-expression is indented by:

T: the text indentation above;
SYMBOL: SYMBOL-VALUE is the indentation;
INTEGER: the indentation itself;
FUNCTION: called with one argument, the text indentation, and the value is used as S-expression indentation; thus IDENTITY is equivalent to T above.

Defaults to CUSTOM:*FILL-INDENT-SEXP*, whose initial value is 1+.

Warning

Note that, due to buffering, one must call FORCE-OUTPUT when done with the EXT:FILL-STREAM (and before changing the indent variable). The former is done automatically by the macro (with-fill-stream (fill target-stream ...) ...).

Example 30.1. Example of EXT:FILL-STREAM usage

(defvar *my-indent-level*)
(with-output-to-string (out)
  (let ((*print-right-margin* 20)
        (*print-pretty* t)
        (*my-indent-level* 2))
    (with-fill-stream (fill out :text-indent '*my-indent-level*)
      (format fill "~%this is some long sentence which will      be broken at spaces")
      (force-output fill)
      (let ((*my-indent-level* 5))
        (format fill "~%and    properly indented to the level specified by the ~S argument which can be a ~S or an ~S - cool!"
                :TEXT-INDENT 'symbol 'integer)
        (force-output fill))
      (format fill "~%Don't forget  to call ~S on it, and/or use ~S   Pretty formatting of the  S-expressions    printed with ~~S is  preserved: ~S"
              'force-output 'with-fill-stream '(defun foo (x y z) (if x (+ y z) (* y z)))))))
⇒ "
  this is some long
  sentence which
  will be broken at
  spaces
     and properly
     indented to
     the level
     specified by
     the
     :TEXT-INDENT
     argument which
     can be a
     SYMBOL or an
     INTEGER -
     cool!
  Don't forget to
  call FORCE-OUTPUT
  on it, and/or use
  WITH-FILL-STREAM
  Pretty formatting
  of the
  S-expressions
  printed with ~S
  is preserved:
   (DEFUN FOO
    (X Y Z)
    (IF X (+ Y Z)
     (* Y Z)))
"

Prev	Up	Next
30.7. Generic functions for binary output	Home	Part III. Extensions Specific to CLISP