11.3.91 generate_message/3   hook

Synopsis

:- multifile 'SU_messages':generate_message/3.

'SU_messages':generate_message(+MessageTerm, -S0, -S)

For a given MessageTerm, generates a list composed of Control-Arg pairs and the atom nl. This can be translated into a nested list of Control-Arg pairs, which can be used as input to print_message_lines/3.

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

Clauses for 'SU_messages':generate_message/3 underly all messages from Prolog. They may be examined and altered. They are found in library('SU_messages').

The purpose of this predicate is to allow you to redefine the displayal of Prolog’s messages. For example, to translate all the messages from English into some other language.

This predicate should not be modified if all you want to do is modify or add a few messages: user:generate_message_hook/3 is provided for that purpose.

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, then 'SU_messages':generate_message(Message,L,[]) is called instead. If that succeeds, then 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.

'SU_messages':generate_message/3 is not included by default in runtime systems, since end-users of application programs should probably not be seeing any messages from the Prolog system.

If there is a call to print_message/2 when when 'SU_messages':generate_message/3 does not succeed for some reason, then the message term itself is printed, for example:

| ?- print_message(error,unexpected_error(37)).
! unexpected_error(37)

'SU_messages':generate_message/3 failed because the message term was not recognized. In the following example print_message/2 is being called by the default exception handler:

| ?- write(A,B).
! Instantiation error in argument 1 of write/2
! goal:  write(_2107,_2108)

Examples

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

Note that the terminating nl is required.

Exceptions

print_message/2 checks that the generated list is a valid parse.

See Also

ref-msg.