6.3.1 CLOS Operators

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.


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

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 .

CommonLisp Interface Manager 2.0 User's Guide - 30 Jul 2004