.. index:: single: logtalk
.. _logtalk/0:

.. rst-class:: right

**object**

``logtalk``
===========

Built-in object providing message printing, debugging, library, source file, and hacking methods.

| **Availability:** 
|    ``built_in``

| **Author:** Paulo Moura
| **Version:** 3:1:1
| **Date:** 2025-04-07

| **Compilation flags:**
|    ``static, built_in, context_switching_calls, threaded``


| **Dependencies:**
|   (none)


| **Remarks:**

   - Default message kinds: ``silent``, ``silent(Key)``, ``banner``, ``help``, ``comment``, ``comment(Key)``, ``information``, ``information(Key)``, ``warning``, ``warning(Key)``, ``error``, ``error(Key)``, ``debug``, ``debug(Key)``, ``question``, and ``question(Key)``.
   - Printing of silent messages: By default, silent messages are not printed. These messages are only useful when intercepted.
   - Printing of banner and comment messages: By default, banner and comment messages are only printed when the ``report`` flag is turned on.
   - Printing of help, information, and question messages: These messages are always printed by default as they provide requested output.
   - Printing of warning messages: By default, warning messages are not printed when the ``report`` flag is turned off.
   - Printing of error messages: These messages are always printed by default.
   - Printing of debug messages: By default, debug messages are only printed when the ``debug`` flag is turned on. The compiler suppresses debug message printing goals when compiling in optimized mode.
   - Meta messages: A *meta message* is a message that have another message as argument and is typically used for debugging messages. Meta messages avoid the need of defining tokenizer rules for every message but can be intercepted as any other message.
   - Meta message ``@Message``: By default, the message is printed as passed to the ``write/1`` predicate followed by a newline.
   - Meta message ``Key-Value``: By default, the message is printed as "Key: Value" followed by a newline. The key is printed as passed to the ``write/1`` predicate while the value is printed as passed to the ``writeq/1`` predicate.
   - Meta message ``Format+Arguments``: By default, the message is printed as passed to the ``format/2`` predicate.
   - Meta message ``List``: By default, the list items are printed indented one per line. The items are preceded by a dash and can be ``@Message``, ``Key-Value``, or ``Format+Arguments`` messages. If that is not the case, the item is printed as passed to the ``writeq/1`` predicate.
   - Meta message ``Title::List``: By default, the title is printed followed by a newline and the indented list items, one per line. The items are printed as in the ``List`` meta message.
   - Meta message ``[Stream,Prefix]>>Goal``: By default, call user-defined ``Goal`` in the context of ``user``. The use of a lambda expression allows passing the message stream and prefix. Printing the prefix is delegated to the goal.
   - Meta message ``[Stream]>>Goal``: By default, call user-defined ``Goal`` in the context of ``user``. The use of a lambda expression allows passing the message stream.
   - Message tokens: ``at_same_line``, ``tab(Expression)``, ``nl``, ``flush``, ``Format-Arguments``, ``term(Term,Options)``, ``ansi(Attributes,Format,Arguments)``, ``begin(Kind,Variable)``, and ``end(Variable)``.

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: print_message/3
.. _logtalk/0::print_message/3:

``print_message/3``
^^^^^^^^^^^^^^^^^^^

Prints a message of the given kind for the specified component.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``print_message(Kind,Component,Message)``
| **Mode and number of proofs:**
|    ``print_message(+nonvar,+nonvar,+nonvar)`` - ``one``


------------

.. index:: print_message_tokens/3
.. _logtalk/0::print_message_tokens/3:

``print_message_tokens/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Print the messages tokens to the given stream, prefixing each line with the specified atom.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``print_message_tokens(Stream,Prefix,Tokens)``
| **Mode and number of proofs:**
|    ``print_message_tokens(@stream_or_alias,+atom,@list(nonvar))`` - ``one``


------------

.. index:: print_message_token/4
.. _logtalk/0::print_message_token/4:

``print_message_token/4``
^^^^^^^^^^^^^^^^^^^^^^^^^

User-defined hook predicate for printing a message token (see this object remarks).

| **Compilation flags:**
|    ``dynamic, multifile``

| **Template:**
|    ``print_message_token(Stream,Prefix,Token,Tokens)``
| **Mode and number of proofs:**
|    ``print_message_token(@stream_or_alias,@atom,@nonvar,@list(nonvar))`` - ``zero_or_one``


------------

.. index:: message_tokens//2
.. _logtalk/0::message_tokens//2:

``message_tokens//2``
^^^^^^^^^^^^^^^^^^^^^

User-defined hook grammar rule for converting a message into a list of tokens (see this object remarks).

| **Compilation flags:**
|    ``dynamic, multifile``

| **Template:**
|    ``message_tokens(Message,Component)``
| **Mode and number of proofs:**
|    ``message_tokens(+nonvar,+nonvar)`` - ``zero_or_one``


------------

.. index:: message_prefix_stream/4
.. _logtalk/0::message_prefix_stream/4:

``message_prefix_stream/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Message line prefix and output stream to be used when printing a message given its kind and component.

| **Compilation flags:**
|    ``dynamic, multifile``

| **Template:**
|    ``message_prefix_stream(Kind,Component,Prefix,Stream)``
| **Mode and number of proofs:**
|    ``message_prefix_stream(?nonvar,?nonvar,?atom,?stream_or_alias)`` - ``zero_or_more``


------------

.. index:: message_prefix_file/6
.. _logtalk/0::message_prefix_file/6:

``message_prefix_file/6``
^^^^^^^^^^^^^^^^^^^^^^^^^

Message line prefix and output file to be used when printing a message given its kind and component.

| **Compilation flags:**
|    ``dynamic, multifile``

| **Template:**
|    ``message_prefix_file(Kind,Component,Prefix,File,Mode,Options)``
| **Mode and number of proofs:**
|    ``message_prefix_file(?nonvar,?nonvar,?atom,?atom,?atom,?list(compound))`` - ``zero_or_more``


------------

.. index:: message_hook/4
.. _logtalk/0::message_hook/4:

``message_hook/4``
^^^^^^^^^^^^^^^^^^

User-defined hook predicate for intercepting message printing calls.

| **Compilation flags:**
|    ``dynamic, multifile``

| **Template:**
|    ``message_hook(Message,Kind,Component,Tokens)``
| **Mode and number of proofs:**
|    ``message_hook(+nonvar,+nonvar,+nonvar,+list(nonvar))`` - ``zero_or_one``


------------

.. index:: ask_question/5
.. _logtalk/0::ask_question/5:

``ask_question/5``
^^^^^^^^^^^^^^^^^^

Asks a question and reads the answer until the check predicate is true.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``ask_question(Kind,Component,Question,Check,Answer)``
| **Meta-predicate template:**
|    ``ask_question(*,*,*,1,*)``
| **Mode and number of proofs:**
|    ``ask_question(+nonvar,+nonvar,+nonvar,+callable,-term)`` - ``one``


------------

.. index:: question_hook/6
.. _logtalk/0::question_hook/6:

``question_hook/6``
^^^^^^^^^^^^^^^^^^^

User-defined hook predicate for intercepting question asking calls.

| **Compilation flags:**
|    ``dynamic, multifile``

| **Template:**
|    ``question_hook(Question,Kind,Component,Tokens,Check,Answer)``
| **Meta-predicate template:**
|    ``question_hook(*,*,*,*,1,*)``
| **Mode and number of proofs:**
|    ``question_hook(+nonvar,+nonvar,+nonvar,+list(nonvar),+callable,-term)`` - ``zero_or_one``


------------

.. index:: question_prompt_stream/4
.. _logtalk/0::question_prompt_stream/4:

``question_prompt_stream/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Prompt and input stream to be used when asking a question given its kind and component.

| **Compilation flags:**
|    ``dynamic, multifile``

| **Template:**
|    ``question_prompt_stream(Kind,Component,Prompt,Stream)``
| **Mode and number of proofs:**
|    ``question_prompt_stream(?nonvar,?nonvar,?atom,?stream_or_alias)`` - ``zero_or_more``


------------

.. index:: trace_event/2
.. _logtalk/0::trace_event/2:

``trace_event/2``
^^^^^^^^^^^^^^^^^

Trace event handler. The runtime calls all trace event handlers using a failure-driven loop before calling the debug event handler.

| **Compilation flags:**
|    ``dynamic, multifile``

| **Template:**
|    ``trace_event(Event,ExecutionContext)``
| **Mode and number of proofs:**
|    ``trace_event(@callable,@execution_context)`` - ``zero``

| **Remarks:**

    - Unification events: Generated after a successful unification with a fact - ``fact(Entity,Fact,Clause,File,Line)`` - or a rule head - ``rule(Entity,Head,Clause,File,Line)``.
    - Goal events: Generated when calling a goal: ``top_goal(Goal,CompiledGoal)`` or ``goal(Goal,CompiledGoal)``.


------------

.. index:: debug_handler/1
.. _logtalk/0::debug_handler/1:

``debug_handler/1``
^^^^^^^^^^^^^^^^^^^

Enumerates, by backtracking, all declared debug handler providers. Define a clause for this predicate to declare a new debug handler provider.

| **Compilation flags:**
|    ``static, multifile``

| **Template:**
|    ``debug_handler(Provider)``
| **Mode and number of proofs:**
|    ``debug_handler(?object_identifier)`` - ``zero_or_more``
|    ``debug_handler(?category_identifier)`` - ``zero_or_more``


------------

.. index:: active_debug_handler/1
.. _logtalk/0::active_debug_handler/1:

``active_debug_handler/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Current active debug handler provider if any. There is at most one active debug handler provider at any given moment.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``active_debug_handler(Provider)``
| **Mode and number of proofs:**
|    ``active_debug_handler(?category_identifier)`` - ``zero_or_one``
|    ``active_debug_handler(?category_identifier)`` - ``zero_or_one``


------------

.. index:: activate_debug_handler/1
.. _logtalk/0::activate_debug_handler/1:

``activate_debug_handler/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Activates the given debug handler provider. There is at most one active debug handler provider at any given moment. Fails if the object or category is not declared as a debug handler provider.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``activate_debug_handler(Provider)``
| **Mode and number of proofs:**
|    ``activate_debug_handler(@object_identifier)`` - ``zero_or_one``
|    ``activate_debug_handler(@category_identifier)`` - ``zero_or_one``


------------

.. index:: deactivate_debug_handler/0
.. _logtalk/0::deactivate_debug_handler/0:

``deactivate_debug_handler/0``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Deactivates the current debug handler provider if any.

| **Compilation flags:**
|    ``static``

| **Mode and number of proofs:**
|    ``deactivate_debug_handler`` - ``one``


------------

.. index:: debug_handler/3
.. _logtalk/0::debug_handler/3:

``debug_handler/3``
^^^^^^^^^^^^^^^^^^^

Debug event handler. Called by the runtime when the given provider is active.

| **Compilation flags:**
|    ``static, multifile``

| **Template:**
|    ``debug_handler(Provider,Event,ExecutionContext)``
| **Mode and number of proofs:**
|    ``debug_handler(+object_identifier,+callable,+execution_context)`` - ``zero_or_more``
|    ``debug_handler(+category_identifier,+callable,+execution_context)`` - ``zero_or_more``

| **Remarks:**

    - Unification events: Generated after a successful unification with a fact - ``fact(Entity,Fact,Clause,File,Line)`` - or a rule head - ``rule(Entity,Head,Clause,File,Line)``.
    - Goal events: Generated when calling a goal: ``top_goal(Goal,CompiledGoal)`` or ``goal(Goal,CompiledGoal)``.


------------

.. index:: expand_library_path/2
.. _logtalk/0::expand_library_path/2:

``expand_library_path/2``
^^^^^^^^^^^^^^^^^^^^^^^^^

Expands a library alias (an atom) or a compound term (using library notation) into its absolute path. Uses a depth bound to prevent loops.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``expand_library_path(LibraryAlias,AbsolutePath)``
| **Mode and number of proofs:**
|    ``expand_library_path(+atom,?atom)`` - ``zero_or_one``
|    ``expand_library_path(+callable,?atom)`` - ``zero_or_one``


------------

.. index:: loaded_file/1
.. _logtalk/0::loaded_file/1:

``loaded_file/1``
^^^^^^^^^^^^^^^^^

Enumerates, by backtracking, all loaded files, returning their full paths.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``loaded_file(Path)``
| **Mode and number of proofs:**
|    ``loaded_file(?atom)`` - ``zero_or_more``


------------

.. index:: loaded_file_property/2
.. _logtalk/0::loaded_file_property/2:

``loaded_file_property/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Enumerates, by backtracking, loaded file properties.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``loaded_file_property(Path,Property)``
| **Mode and number of proofs:**
|    ``loaded_file_property(?atom,?compound)`` - ``zero_or_more``

| **Remarks:**

    - Property ``basename/1``: Basename of the file (includes the file extension, if any).
    - Property ``directory/1``: Directory of the file (ending with a slash).
    - Property ``mode/1``: Compilation mode of the file (possible values are ``optimal``, ``normal``, and ``debug``).
    - Property ``flags/1``: Explicit flags used for compiling the file.
    - Property ``text_properties/1``: List of the file text properties (``encoding/1`` and ``bom/1``). Empty if no ``encoding/1`` directive is present and the stream used for reading the file does not have a ``bom/1`` (or equivalent) property.
    - Property ``target/1``: Full path of the generated intermediate Prolog file.
    - Property ``modified/1``: File modification time stamp (should be regarded as an opaque but otherwise comparable term).
    - Property ``parent/1``: Full path of the parent file that loaded the file.
    - Property ``includes/2``: Full path of a file included by the file and the line of the ``include/1`` directive.
    - Property ``includes/1``: Full path of a file included by the file.
    - Property ``library/1``: Library alias for the library that includes the file.
    - Property ``object/3``: Identifier for an object defined in the file and the start and end lines of its definition.
    - Property ``object/1``: Identifier for an object defined in the file.
    - Property ``protocol/3``: Identifier for a protocol defined in the file and the start and end lines of its definition.
    - Property ``protocol/1``: Identifier for a protocol defined in the file.
    - Property ``category/3``: Identifier for a category defined in the file and the start and end lines of its definition.
    - Property ``category/1``: Identifier for a category defined in the file.


------------

.. index:: file_type_extension/2
.. _logtalk/0::file_type_extension/2:

``file_type_extension/2``
^^^^^^^^^^^^^^^^^^^^^^^^^

Enumerates, by backtracking, all defined file type extensions. The defined types are: ``source``, ``object``, ``logtalk``, ``prolog``, and ``tmp``. The source type returns both ``logtalk`` and ``prolog`` type extensions.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``file_type_extension(Type,Extension)``
| **Mode and number of proofs:**
|    ``file_type_extension(?atom,?atom)`` - ``zero_or_more``


------------

.. index:: compile_aux_clauses/1
.. _logtalk/0::compile_aux_clauses/1:

``compile_aux_clauses/1``
^^^^^^^^^^^^^^^^^^^^^^^^^

Compiles a list of auxiliary clauses. Can only be called during source file compilation, usually from ``term_expansion/2`` or ``goal_expansion/2`` hook predicate definitions.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``compile_aux_clauses(Clauses)``
| **Mode and number of proofs:**
|    ``compile_aux_clauses(@list(clause))`` - ``one``


------------

.. index:: entity_prefix/2
.. _logtalk/0::entity_prefix/2:

``entity_prefix/2``
^^^^^^^^^^^^^^^^^^^

Converts between an entity identifier and the entity prefix that is used for its compiled code. When none of the arguments is instantiated, it returns the identifier and the prefix of the entity under compilation, if any.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``entity_prefix(Entity,Prefix)``
| **Mode and number of proofs:**
|    ``entity_prefix(?entity_identifier,?atom)`` - ``zero_or_one``


------------

.. index:: compile_predicate_heads/4
.. _logtalk/0::compile_predicate_heads/4:

``compile_predicate_heads/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Compiles clause heads. The heads are compiled in the context of the entity under compilation when the entity argument is not instantiated.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``compile_predicate_heads(Heads,Entity,CompiledHeads,ExecutionContext)``
| **Mode and number of proofs:**
|    ``compile_predicate_heads(@list(callable),?entity_identifier,-list(callable),@execution_context)`` - ``zero_or_one``
|    ``compile_predicate_heads(@conjunction(callable),?entity_identifier,-conjunction(callable),@execution_context)`` - ``zero_or_one``
|    ``compile_predicate_heads(@callable,?entity_identifier,-callable,@execution_context)`` - ``zero_or_one``


------------

.. index:: compile_predicate_indicators/3
.. _logtalk/0::compile_predicate_indicators/3:

``compile_predicate_indicators/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Compiles predicate indicators. The predicate are compiled in the context of the entity under compilation when the entity argument is not instantiated.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``compile_predicate_indicators(PredicateIndicators,Entity,CompiledPredicateIndicators)``
| **Mode and number of proofs:**
|    ``compile_predicate_indicators(@list(predicate_indicator),?entity_identifier,-list(predicate_indicator))`` - ``zero_or_one``
|    ``compile_predicate_indicators(@conjunction(predicate_indicator),?entity_identifier,-conjunction(predicate_indicator))`` - ``zero_or_one``
|    ``compile_predicate_indicators(@predicate_indicator,?entity_identifier,-predicate_indicator)`` - ``zero_or_one``


------------

.. index:: decompile_predicate_heads/4
.. _logtalk/0::decompile_predicate_heads/4:

``decompile_predicate_heads/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Decompiles clause heads. All compiled clause heads must belong to the same entity, which must be loaded.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``decompile_predicate_heads(CompiledHeads,Entity,Type,Heads)``
| **Mode and number of proofs:**
|    ``decompile_predicate_heads(@list(callable),-entity_identifier,-atom,-list(callable))`` - ``zero_or_one``
|    ``decompile_predicate_heads(@conjunction(callable),-entity_identifier,-atom,-conjunction(callable))`` - ``zero_or_one``
|    ``decompile_predicate_heads(@callable,-entity_identifier,-atom,-callable)`` - ``zero_or_one``


------------

.. index:: decompile_predicate_indicators/4
.. _logtalk/0::decompile_predicate_indicators/4:

``decompile_predicate_indicators/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Decompiles predicate indicators. All compiled predicate indicators must belong to the same entity, which must be loaded.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``decompile_predicate_indicators(CompiledPredicateIndicators,Entity,Type,PredicateIndicators)``
| **Mode and number of proofs:**
|    ``decompile_predicate_indicators(@list(predicate_indicator),-entity_identifier,-atom,-list(predicate_indicator))`` - ``zero_or_one``
|    ``decompile_predicate_indicators(@conjunction(predicate_indicator),-entity_identifier,-atom,-conjunction(predicate_indicator))`` - ``zero_or_one``
|    ``decompile_predicate_indicators(@predicate_indicator,-entity_identifier,-atom,-predicate_indicator)`` - ``zero_or_one``


------------

.. index:: execution_context/7
.. _logtalk/0::execution_context/7:

``execution_context/7``
^^^^^^^^^^^^^^^^^^^^^^^

Execution context term data. Execution context terms should be considered opaque terms subject to change without notice.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``execution_context(ExecutionContext,Entity,Sender,This,Self,MetaCallContext,CoinductionStack)``
| **Mode and number of proofs:**
|    ``execution_context(?nonvar,?entity_identifier,?object_identifier,?object_identifier,?object_identifier,@list(callable),@list(callable))`` - ``zero_or_one``


------------

Protected predicates
--------------------

(none)

Private predicates
------------------

.. index:: active_debug_handler_/1
.. _logtalk/0::active_debug_handler_/1:

``active_debug_handler_/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Current active debug handler provider. There is at most one active debug handler provider at any given moment.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``active_debug_handler_(Provider)``
| **Mode and number of proofs:**
|    ``active_debug_handler_(?entity_identifier)`` - ``zero_or_one``


------------

Operators
---------

(none)

