16.2 Error Messages

By convention, error messages (and in general, the reports generated by write-condition-report) should consist of one or more complete sentences. The usual rules for sentences should be followed: the first word of the sentence should be capitalized, and the sentence should be terminated by a period. The message should not contain extraneous whitespace such as line breaks or indentation.

The error system provides a simple formatting language that allows the programmer to have some control over the printing of error messages. This formatting language will probably be redesigned in a future release.

Error messages typically consist of a string describing the error, followed by some irritant objects. The string is printed using display, and the irritants are printed using write, typically with a space between each irritant. To allow simple formatting, we introduce a noise object, printed using display. The irritant list may contain ordinary objects interspersed with noise objects. Each noise object is printed using display, with no extra whitespace, while each normal object is printed using write, prefixed by a single space character.

Here is an example:

(define (error-within-procedure message irritant procedure)
  (error message
         irritant
         (error-irritant/noise "within procedure")    
         procedure      
         (error-irritant/noise ".")))

This would format as follows:

(error-within-procedure "Bad widget" 'widget-32 'invert-widget) error→

Bad widget widget-32 within procedure invert-widget.

Here are the operations supporting error messages:

procedure: format-error-message message irritants port

Message is typically a string (although this is not required), irritants a list of irritant objects, and port an output port. Formats message and irritants to port in the standard way. Note that, during the formatting process, the depth and breadth to which lists are printed are each limited to small numbers, to guarantee that the output from each irritant is not arbitrarily large.

procedure: error-irritant/noise value

Creates and returns a noise object whose value is value.