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


These notes document CLISP version 2.49+Last modified: 2016-09-05