Next: Signaling and Handling Conditions, Previous: Creating Conditions, Up: Condition System Concepts
If the :report argument to define-condition is used,
a print function is defined that is called whenever
the defined condition is printed while the value of *print-escape* is false.
This function is called the condition reporter;
the text which it outputs is called a report message.
When a condition is printed and *print-escape*
is false, the condition reporter for the condition is invoked.
Conditions are printed automatically by functions such as
invoke-debugger, break, and warn.
When *print-escape* is true, the object should print in an
abbreviated fashion according to the style of the implementation
(e.g., by print-unreadable-object). It is not required that a
condition can be recreated by reading its printed representation.
No function is provided for directly accessing or invoking condition reporters.
In order to ensure a properly aesthetic result when presenting report messages to the user, certain stylistic conventions are recommended.
There are stylistic recommendations for the content of the messages output by condition reporters, but there are no formal requirements on those programs. If a program violates the recommendations for some message, the display of that message might be less aesthetic than if the guideline had been observed, but the program is still considered a conforming program.
The requirements on a program or implementation which invokes a condition reporter are somewhat stronger. A conforming program must be permitted to assume that if these style guidelines are followed, proper aesthetics will be maintained. Where appropriate, any specific requirements on such routines are explicitly mentioned below.
It is recommended that a report message be a complete sentences, in the proper case and correctly punctuated. In English, for example, this means the first letter should be uppercase, and there should be a trailing period.
(error "This is a message") ; Not recommended (error "this is a message.") ; Not recommended (error "This is a message.") ; Recommended instead
It is recommended that a report message not begin with any
introductory text, such as “Error: ” or “Warning: ”
or even just freshline or newline.
Such text is added, if appropriate to the context,
by the routine invoking the condition reporter.
It is recommended that a report message not be followed by a trailing freshline or newline. Such text is added, if appropriate to the context, by the routine invoking the condition reporter.
(error "This is a message.~%") ; Not recommended (error "~&This is a message.") ; Not recommended (error "~&This is a message.~%") ; Not recommended (error "This is a message.") ; Recommended instead
Especially if it is long, it is permissible and appropriate for a report message to contain one or more embedded newlines.
If the calling routine conventionally inserts some additional prefix
(such as “Error: ” or “;; Error: ”) on the first line of
the message, it must also assure that an appropriate prefix will be
added to each subsequent line of the output, so that the left edge of
the message output by the condition reporter will still be properly
aligned.
(defun test ()
(error "This is an error message.~%It has two lines."))
;; Implementation A
(test)
This is an error message.
It has two lines.
;; Implementation B
(test)
;; Error: This is an error message.
;; It has two lines.
;; Implementation C
(test)
>> Error: This is an error message.
It has two lines.
Because the indentation of a report message might be shifted to the right or left by an arbitrary amount, special care should be taken with the semi-standard character <Tab> (in those implementations that support such a character). Unless the implementation specifically defines its behavior in this context, its use should be avoided.
The name of the containing function should generally not be mentioned in report messages. It is assumed that the debugger will make this information accessible in situations where it is necessary and appropriate.