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

## 30.8. Class `EXT:FILL-STREAM`

As an example of the use of “GRAY” `STREAM`s, 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))
          (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.45 | Last modified: 2008-05-14

Enter your search termsSubmit search form
Webclisp.cons.orgclisp.podval.orgwww.lisp.org

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