11.3.89 generate_message_hook/3 [hook]

Synopsis

:- multifile user:generate_message_hook/3.

user:generate_message_hook(+MessageTerm, -S0, -S)

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

Arguments

MessageTerm
term

May be any term.

S0
list of pair

The resulting list of Control-Args pairs.

S
list of pair

The remaining list.

Description

For a given MessageTerm, generates the list of Control-Args pairs required for print_message_lines/3 to format the message for display.

This is the same as 'SU_messages':generate_message/3 except that it is a hook. It is intended to be used when you want to override particular messages from the Prolog system, or when you want to add some messages. If you are using your own exception classes (see raise_exception/1) it may be useful to provide generate_message_hook clauses for those exceptions so that the print_message/2 (and thus the default exception handler that calls print_message/2) can print them out nicely.

The Prolog system uses the built-in predicate print_message/2 to print all its messages. When print_message/2 is called, it calls user:generate_message_hook(Message,L,[]) to generate the message. If that fails, 'SU_messages':generate_message(Message,L,[]) is called instead. If that succeeds, L is assumed to have been bound to a list whose elements are either Control-Args pairs or the atom nl. Each Control-Arg pair should be such that the call

     format(user_error, Control, Args)

is valid. The atom nl is used for breaking the message into lines. Using the format specification ‘~n’ (new-line) is discouraged, since the routine that actually prints the message (see user:message_hook/3 and print_message_lines/3) may need to have control over newlines.

Examples

     :- multifile user:generate_message_hook/3.
     user:generate_message_hook(hello_world) -->
             ['hello world'-[],nl].

Note that the terminating nl is required.

See Also

ref-msg.


Send feedback on this subject.