8.13.2 Message Handling Predicates

print_message(+Severity, +Message) hookable

Prints a Message of a given Severity. The behavior can be customized using the hooks user:portray_message/2, user:generate_message_hook/3 and user:message_hook/3.

All messages from the system are printed by calling this predicate.

First print_message/2 calls user:portray_message/2 with the same arguments. If this does not succeed, the message is processed in the following phases:

• Message generation phase: the abstract message term Message is formatted, i.e. converted to a format-command list. First the hook predicate user:generate_message_hook/3 is tried, then if it does not succeed, 'SU_messages':generate_message/3 is called. If that also fails or gives an exception, then the built-in default conversion is used, which gives the following result:

                 ['~q'-[Message],nl]
            

• Line splitting transformation: the format-command list is converted to format-command lines—the list is broken up into a list of lists, each list containing format-commands for one line.
• Message printing phase: The text of the message (format-command lines generated in the previous stage) is printed. First the hook predicate user:message_hook/3 is tried, then, if it does not succeed, the built-in predicate print_message_lines/3 is called for the user_error stream.

portray_message(+Severity, +Message) hook

user:portray_message(+Severity, +Message)

Called by print_message/2 before processing the message. If this succeeds, it is assumed that the message has been processed and nothing further is done.

generate_message_hook(+Message, -L0, -L) hook

user:generate_message_hook(+Message, -L0, -L)

A way for the user to override the call to 'SU_messages':generate_message/3 in the message generation phase in print_message/2.

'SU_messages':generate_message(+Message, -L0, -L) extendible

Defines how to transform a message term Message to a format-command list. For a given Message, generates a format-command list in the form of the difference list L0-L; this means, that L0 is the generated list with L appended to it. This list will be translated into format-command lines, which will be passed to the message printing phase.

message_hook(+Severity, +Message, +Lines) hook

user:message_hook(+Severity, +Message, +Lines)

Overrides the call to print_message_lines/3 in the message printing phase of print_message/2. A way for the user to intercept the abstract message term Message of type Severity, whose translation into format-command lines is Lines, before it is actually printed.

print_message_lines(+Stream, +Severity, +Lines)

Print the Lines to Stream, preceding each line with a prefix defined by Severity. Lines must be a valid format-command lines, Severity can be an arbitrary atom. If it is one of the predefined severities, the corresponding prefix is used in printing the message lines. Otherwise the Severity itself is interpreted as the prefix (this is for Quintus Prolog compatibility, where print_message_lines/3 takes the prefix as its second argument). In case of the query severity no newline is written after the last line.

goal_source_info(+AGoal, ?Goal, ?SourceInfo)

Decompose the AGoal annotated goal into a Goal proper and the SourceInfo descriptor term, indicating the source position of the goal.

Annotated goals occur in most of error message terms, and carry information on the Goal causing the error and its source position. The SourceInfo term, retrieved by goal_source_info/3 will be one of the following:

[]

The goal has no source information associated with it.

fileref(File,Line)

The goal occurs in file File, line Line.

clauseref(File,MFunc,ClauseNo,CallNo,Line)

The goal occurs in file File, within predicate MFunc, clause number ClauseNo, call number CallNo and virtual line number Line. Here, MFunc is of form Module:Name/Arity, calls are numbered textually and the virtual line number shows the position of the goal within the listing of the predicate MFunc, as produced by listing/1. Such a term is returned for goals occurring in interpreted predicates, which do not have “real” line number information, e.g. because they were entered from the terminal, or created dynamically.