CLOS provides these top-level facilities for presenting output. with-output-as-presentation is the most general operator, and present and present-to-string support common idioms.
with-output-as-presentation[Macro]
Arguments: (stream object type &key modifier single-box allow-sensitive-inferiors record-type) &body body
Summary: The output of body to the extended output recording stream 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.
The stream argument 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.
type is a presentation type specifier and may be an abbreviation.
modifier , which defaults to nil , is a function 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.
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 .
When the boolean allow-sensitive-inferiors is nil , nested calls to present or with-output-as-presentation inside this one will not generate presentations. The default is t .
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.
All arguments of this macro are evaluated:
(with-output-as-presentation (stream #p"foo" 'pathname)
(princ "FOO" stream))
present[Function]
Arguments: object &optional type &key stream view modifier acceptably for-context-type single-box allow-sensitive-inferiors sensitive record-type
Summary: 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 .
The returned value of present is the presentation object that contains the output corresponding to the object.
present expands any presentation type abbreviations ( type and for-context-type ), and then calls stream-present on stream , object , type , and the remaining keyword arguments.
stream-present [Generic Function]
Arguments: stream object type &key view modifier acceptably for-context-type single-box allow-sensitive-inferiors sensitive record-type
Summary: 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 implement a method for stream-present . The default method (on standard-extended-output-stream ) is as follows.
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.
type is a presentation type specifier.
view is a view object that defaults to stream-default-view of stream .
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 .
modifier , single-box , allow-sensitive-inferiors , and record-type are the same as for with-output-as-presentation .
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.
The boolean sensitive defaults to t . If it is nil , no presentation is produced.
present-to-string [Function]
Arguments: object &optional type &key view acceptably for-context-type string index
Summary: 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 .
The first returned value is the string. When string is supplied, a second value is returned, the updated index .