object

logtalk

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

Availability:
built_in
Author: Paulo Moura
Version: 2:0:0
Date: 2024-05-18
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)

Public predicates

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

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

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

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

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

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

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

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

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

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

deactivate_debug_handler/0

Deactivates the current debug handler provider if any.

Compilation flags:
static
Mode and number of proofs:
deactivate_debug_handler - one

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

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

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

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/1: Full path of a file included by the file.

  • Property library/1: Library alias for the library that includes the file.

  • Property object/1: Identifier for an object defined in the file.

  • Property protocol/1: Identifier for a protocol defined in the file.

  • Property category/1: Identifier for a category defined in the file.

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

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

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

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

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

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

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

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

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)