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

**object**

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

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

| **Author:** Paulo Moura
| **Version:** 1.15
| **Date:** 2019/4/1

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


(no dependencies on other entities)


Public interface
----------------

.. raw:: html

   <div id="print_message/3"> </div>

.. 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``


.. raw:: html

   <div id="print_message_tokens/3"> </div>

.. 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``


.. raw:: html

   <div id="print_message_token/4"> </div>

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

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

User-defined hook predicate for printing a message token (at_same_line, nl, flush, Format-Arguments, term(Term,Options), ansi(Attributes,Format,Arguments), begin(Kind,Variable), and end(Variable)).

| **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``


.. raw:: html

   <div id="message_tokens//2"> </div>

.. 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 (at_same_line, nl, flush, Format-Arguments, term(Term,Options), ansi(Attributes,Format,Arguments), begin(Kind,Variable), and end(Variable)).

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

| **Template:**
|    ``message_tokens(Message,Component)``

.. raw:: html

   <div id="message_prefix_stream/4"> </div>

.. 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``


.. raw:: html

   <div id="message_hook/4"> </div>

.. 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``


.. raw:: html

   <div id="ask_question/5"> </div>

.. 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``


.. raw:: html

   <div id="question_hook/6"> </div>

.. 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``


.. raw:: html

   <div id="question_prompt_stream/4"> </div>

.. 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``


.. raw:: html

   <div id="trace_event/2"> </div>

.. 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``


.. raw:: html

   <div id="debug_handler_provider/1"> </div>

.. index:: debug_handler_provider/1
.. _logtalk/0::debug_handler_provider/1:

``debug_handler_provider/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Declares an object as the debug handler provider. There should be at most one debug handler provider loaded at any given moment.

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

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


.. raw:: html

   <div id="debug_handler/2"> </div>

.. index:: debug_handler/2
.. _logtalk/0::debug_handler/2:

``debug_handler/2``
^^^^^^^^^^^^^^^^^^^

Debug event handler. The defined events are unification events - fact(Entity,Fact,Clause,File,Line) and rule(Entity,Head,Clause,File,Line) - and goal events - top_goal(Goal,CompiledGoal) and goal(Goal,CompiledGoal).

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

| **Template:**
|    ``debug_handler(Event,ExecutionContext)``
| **Mode and number of proofs:**
|    ``debug_handler(?entity_identifier,?atom)`` - ``zero_or_more``


.. raw:: html

   <div id="expand_library_path/2"> </div>

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

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

Expands a library alias or a library path into its absolute path. Uses a depth bound to prevent loops.

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

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


.. raw:: html

   <div id="loaded_file/1"> </div>

.. 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``


.. raw:: html

   <div id="loaded_file_property/2"> </div>

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

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

Enumerates, by backtracking, all loaded file properties. Valid properties are: basename/1, directory/1, mode/1, flags/1, text_properties/1 (encoding/1 and bom/1), target/1, modified/1, parent/1, includes/1, library/1, object/1, protocol/1, and category/1.

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

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


.. raw:: html

   <div id="file_type_extension/2"> </div>

.. 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``


.. raw:: html

   <div id="compile_aux_clauses/1"> </div>

.. 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``


.. raw:: html

   <div id="entity_prefix/2"> </div>

.. 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``


.. raw:: html

   <div id="compile_predicate_heads/4"> </div>

.. 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``


.. raw:: html

   <div id="compile_predicate_indicators/3"> </div>

.. 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``


.. raw:: html

   <div id="decompile_predicate_heads/4"> </div>

.. 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``


.. raw:: html

   <div id="decompile_predicate_indicators/4"> </div>

.. 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``


.. raw:: html

   <div id="execution_context/7"> </div>

.. 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 interface
-------------------

(none)

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

(none)

Operators
---------

(none)

Remarks
-------

* **Message kinds**: The default set is {silent, silent(Category), banner, help, comment, comment(Category), information, information(Category), warning, warning(Category), error, error(Category), debug, debug(Category), question, question(Category)}.

* **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.

* **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.

* **@Message meta message**: By default, the message is printed as passed to the write/1 predicate followed by a newline.

* **Key-Value meta message**: By default, the message is printed as "Key: Value" followed by a newline. The value is printed as passed to the writeq/1 predicate.

* **List meta message**: By default, the list items are printed indented one per line. The items are preceded by a dash and printed as passed to the writeq/1 predicate.

* **Title::List meta message**: By default, the title is printed followed by a newline and the indented list items, one per line. The items are preceded by a dash and printed as passed to the writeq/1 predicate.

