message_hook/3 hook

Synopsis

:- multifile message_hook/3.

message_hook(+MessageTerm, +Severity, +Lines)

Overrides the call to print_message_lines/3 in print_message/2. A way for the user to intercept the Message of type Severity, whose translations is Lines, before it is actually printed.

Arguments

MessageTerm term

any term

Severity one of [informational,warning,error,help,silent]

Lines list of pair

is of the form [Line1, Line2, ...], where each Linei is of the form [Control_1-Args_1,Control_2-Args_2, ...].

Description

After a message is parsed, but before the message is written, print_message/2 calls

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

If the call to user:message_hook/3 succeeds, print_message succeeds without further processing. Otherwise the built-in message display is used. It is often useful to have a message hook that performs some action and then fails, allowing other message hooks to run, and eventually allowing the message to be printed as usual. See ref-msg-umf-ipm for an example.

Exceptions

An exception raised by this predicate causes an error message to be printed and then the original message is printed using the default message text and formatting. Since the user defines message_hook/3, they can write code that might raise exceptions.

Examples

The following is the default, built-in message portrayal predicate:

     message_hook(MessageTerm,Severity,Lines):-
       ( Severity == silent ->
         true
         /* Don't translate or print silent messages */
       ; severity_prefix(Severity,Prefix,Stream) ->
         print_message_lines(Stream,Prefix,Lines)
       ; raise_exception(domain_error(
             print_message(Severity,MessageTerm),1,
             one_of([help,error,warning,
                     informational,silent]),
             Severity)).
     
     severity_prefix(silent,         '', user_error).
     severity_prefix(help,           '', user_error).
     severity_prefix(error,       '! ',  user_error).
     severity_prefix(warning,     '* ',  user_error).
     severity_prefix(informational,'% ', user_error).
     

The reasoning behind the assignment of streams is that all unsolicited output should go to user_error.

Tips

See Also

print_message/2, generate_message/3, print_message_lines/3 ref-msg