23.4 Typed Output

An application can specify that all output done within a certain dynamic extent should be associated with a given Lisp object and be declared to be of a specified presentation type. The resulting output is saved in the window's output history as a presentation. Specifically, the presentation remembers the output that was performed (by saving the associated output record), the Lisp object associated with the output, and the presentation type specified at output time. The object can be any Lisp object. [annotate]

with-output-as-presentation  (stream object type &key modifier single-box allow-sensitive-inferiors parent record-type &allow-other-keys ) &body body [Macro]

The output of body to the extended output recording stream is used to generate a presentation whose underlying object is object and whose presentation type is type. Each invocation of this macro results in the creation of a presentation object in the stream's output history unless output recording has been disabled or :allow-sensitive-inferiors nil was specified at a higher level, in which case the presentation object is not inserted into the history. with-output-as-presentation returns the presentation corresponding to the output. [annotate]

The stream argument is not evaluated, and must be a symbol that is bound to an extended output stream or output recording stream. If stream is t, *standard-output* is used. body may have zero or more declarations as its first forms. [annotate]

type may be a presentation type abbreviation. [annotate]

modifier, which defaults to nil, is some sort of object that describes how the presentation object might be modified. For example, it might be a function of one argument (the new value) that can be called in order to store a new value for object after a user somehow "edits" the presentation. modifier must have indefinite extent. [annotate]

single-box is used to specify the presentation-single-box component of the resulting presentation. It can take on the values described under presentation-single-box. [annotate]

When the boolean allow-sensitive-inferiors is false, nested calls to present or with-output-as-presentation inside this one will not generate presentations. The default is true. [annotate]

parent specifies what output record should serve as the parent for the newly created presentation. If unspecified, stream-current-output-record of stream will be used as the parent. [annotate]

record-type specifies the class of the presentation output record to be created. It defaults to standard-presentation. This argument should only be supplied by a programmer if there is a new class of output record that supports the updating output record protocol. [annotate]

All arguments of this macro are evaluated. [annotate]

For example, [annotate]

(with-output-as-presentation (stream #p"foo" 'pathname)
  (princ "FOO" stream))


present  object &optional type &key stream view modifier acceptably for-context-type single-box allow-sensitive-inferiors sensitive record-type [Function]

The object of presentation type type is presented to the extended output stream stream (which defaults to *standard-output*), using the type's present method for the supplied view view. type is a presentation type specifier, and can be an abbreviation. It defaults to (presentation-type-of object). The other arguments and overall behavior of present are as for stream-present. [annotate]

The returned value of present is the presentation object that contains the output corresponding to the object. [annotate]

present must be implemented by first expanding any presentation type abbreviations (type and for-context-type), and then calling stream-present on stream, object, type, and the remaining keyword arguments, which are described below. [annotate]


stream-present  stream object type &key view modifier acceptably for-context-type single-box allow-sensitive-inferiors sensitive record-type [Generic Function]

stream-present is the per-stream implementation of present, analogous to the relationship between write-char and stream-write-char. All extended output streams and output recording streams must implement a method for stream-present. The default method (on standard-extended-output-stream) implements the following behavior. [annotate]

The object object of type type is presented to the stream stream by calling the type's present method for the supplied view view. The returned value is the presentation containing the output corresponding to the object. [annotate]

type is a presentation type specifier. view is a view object that defaults to stream-default-view of stream. [annotate]

for-context-type is a presentation type specifier that is passed to the present method for type, which can use it to tailor how the object will be presented. for-context-type defaults to type. [annotate]

modifier, single-box, allow-sensitive-inferiors, and record-type are the same as for with-output-as-presentation. [annotate]

acceptably defaults to nil, which requests the present method to produce text designed to be read by human beings. If acceptably is t, it requests the present method to produce text that is recognized by the accept method for for-context-type. This makes no difference to most presentation types. [annotate]

Note: What happens when `acceptably' is T, but it's not possible to create "acceptable" output? We need some way to detect this, so the input-editor can choose between putting literal-object "accept gestures" or just a sequence of characters into the input buffer when a presentation is clicked on. [edit]-- Troels Henriksen 2006-10-29 20:05Z

The boolean sensitive defaults to true. If it is false, no presentation is produced. [annotate]


present-to-string  object &optional type &key view acceptably for-context-type string index [Function]

Same as present inside with-output-to-string. If string is supplied, it must be a string with a fill pointer. When index is supplied, it is used as an index into string. view, acceptably, and for-context-type are as for present. [annotate]

The first returned value is the string. When string is supplied, a second value is returned, the updated index. [annotate]