nl

Emit a newline

Fmt - Args

Emit the result of format(Fmt, Args)

Fmt

Emit the result of format(Fmt)

ansi(Class, Fmt, Args)

Use ansi_format/3 for color output.

url(Location)

Emit a source location as a hyperlink. Location is File:Line:Column, File:Line, File or a URL.

url(Location, Label)

As above, but print Label rather than Location. Label is plain text, Fmt-Args or ansi(Class, Fmt, Args), the latter combining a hyperlink with a style class.

flush

Used only as last element of the list. Simply flush the output instead of producing a final newline.

at_same_line

Start the messages at the same line (instead of using ~N)

eol

End the decorated part of the last line. See print_message_lines/3.

The elements begin(Class, Ctx) and end(Ctx) that decorate the message as a whole are added by print_message_lines/3.

Use predicate_reference//1,2 to refer to a predicate rather than formatting the predicate indicator by hand.

deprecated

- Use code for message translation should call translate_message//1.

See also

- swi_location//1 uses the same term to insert context before the core of the message.

Note that eol ends the last line of the answer. The empty line that separates the answer from the next query is not part of the answer and keeps the default background.

Resolving the call site uses library(prolog_stack), which has to run the decompiler and read the source file. This is affordable for an interactive tracer, but we only do it if the location can actually be used, i.e., if hyperlinks are rendered. See goal_links/0.

• A callable term (a head), optionally module qualified
• A predicate indicator, optionally module qualified

The module is kept here. Whether or not it is printed is left to predicate_reference//2, which uses user_predicate_indicator/2.

See also

- pi_head/2 of library(prolog_code) for the general version. This one is in the boot files and thus cannot use it.

module(+Which)

One of auto (default), hide or show. Using auto, the module qualification is removed if hidden_module/1 holds for it.

link(+Bool)

If false, do not try to create a hyperlink. Default true.

style(+Class)

Style class for the reference. Default code.

tag(+Bool)

If true, add a tag that indicates the kind of predicate. See predicate_kind/2. Default false. Only sensible if the reference is the only thing on the line.

If Spec cannot be interpreted as a predicate it is printed using the code class and ~p, i.e., we never fail on a malformed message.

• iso
• built_in
• foreign
• library(Name)
• module(Module)
• user
• undefined

• time
• time(Format)
• thread

In addition, the hook message_prefix_hook/2 is called that allows for additional context information.

If PrefixOrKind is kind(Kind), the message as a whole may be decorated. To this end the lines are wrapped in begin(Class, Ctx) and end(Ctx), where Class is derived from Kind using msg_color_class/2. Ctx is a variable that is bound by whoever implements prolog:message_line_element/2 for begin/2 (normally library(ansi_term)) and remains unbound if the decoration is not available, e.g., because Stream is not a terminal.

The elements that need Ctx are rewritten by prefix_nl/4 to carry it. See there for the details.

• nl, flush and eol become nl(Ctx), flush(Ctx) and eol(Ctx). Their handler writes the sequence that paints the remainder of the line before ending it if the message has a background colour.
• ansi(Attrs, Fmt, Args) becomes ansi(Attrs, Fmt, Args, Ctx). Its handler re-installs the decoration of the message as a whole after writing the element, as the element ends with a full reset. The same applies to an ansi/3 element used as the label of an url/2 element.

The last line of a message is ended implicitly: if Lines does not end in nl or flush an nl is added. This one does not paint: what follows the message is not part of it. A message that wants its last line painted ends it using eol.