This is TheLogtalkHandbook-3.96.0.info, produced by makeinfo version 7.2
from TheLogtalkHandbook-3.96.0.texi.

     The Logtalk Handbook v3.96.0, Nov 18, 2025

     Paulo Moura

     Copyright © 1998-2025, Paulo Moura

INFO-DIR-SECTION Programming Languages
START-INFO-DIR-ENTRY
* The Logtalk Handbook: (TheLogtalkHandbook-3.96.0.info). Declarative object-oriented logic programming
                        language.
END-INFO-DIR-ENTRY


   Generated by Sphinx 7.4.7.


File: TheLogtalkHandbook-3.96.0.info,  Node: Top,  Next: User Manual,  Up: (dir)

The Logtalk Handbook
********************

     The Logtalk Handbook v3.96.0, Nov 18, 2025

     Paulo Moura

     Copyright © 1998-2025, Paulo Moura

* Menu:

* User Manual::
* Reference Manual::
* Tutorial::
* FAQ::
* Developer Tools::
* Libraries::
* Ports::
* Contributions::
* Glossary::
* Index: Index<2>.
* Index::

 -- The Detailed Node Listing --

User Manual

* Declarative object-oriented programming::
* Main features::
* Nomenclature::
* Messages::
* Objects::
* Protocols::
* Categories::
* Predicates::
* Inheritance::
* Event-driven programming::
* Multi-threading programming::
* Error handling::
* Reflection::
* Writing and running applications::
* Printing messages and asking questions::
* Term and goal expansion::
* Documenting::
* Debugging::
* Performance: Performance<2>.
* Installing Logtalk::
* Prolog integration and migration::

Main features

* Integration of logic and object-oriented programming::
* Integration of event-driven and object-oriented programming::
* Support for component-based programming::
* Support for both prototype and class-based systems::
* Support for multiple object hierarchies::
* Separation between interface and implementation::
* Private, protected and public inheritance: Private protected and public inheritance.
* Private, protected and public object predicates: Private protected and public object predicates.
* Parametric objects::
* High level multi-threading programming support::
* Smooth learning curve::
* Compatibility with most Prolog systems and the ISO standard::
* Performance::
* Logtalk scope::

Nomenclature

* Prolog nomenclature::
* Smalltalk nomenclature::
* C++ nomenclature::
* Java nomenclature::
* Python nomenclature::

Messages

* Operators used in message-sending::
* Sending a message to an object::
* Delegating a message to an object::
* Sending a message to self::
* Broadcasting::
* Calling imported and inherited predicates::
* Message sending and event generation::
* Sending a message from a module::
* Message sending performance::

Objects

* Objects, prototypes, classes, and instances: Objects prototypes classes and instances.
* Defining a new object::
* Parametric objects: Parametric objects<2>.
* Finding defined objects::
* Creating a new object at runtime::
* Abolishing an existing object::
* Object directives::
* Object relationships::
* Object properties::
* Built-in objects::
* Multi-threading applications::

Objects, prototypes, classes, and instances

* Prototypes::
* Classes::

Parametric objects

* Accessing object parameters::
* Parametric object proxies::

Object directives

* Object initialization::
* Dynamic objects::
* Object documentation::
* Loading files into an object::
* Declaring object aliases::

Built-in objects

* The built-in pseudo-object user::
* The built-in object logtalk::

Protocols

* Defining a new protocol::
* Finding defined protocols::
* Creating a new protocol at runtime::
* Abolishing an existing protocol::
* Protocol directives::
* Protocol relationships::
* Protocol properties::
* Implementing protocols::
* Built-in protocols::
* Multi-threading applications: Multi-threading applications<2>.

Protocol directives

* Dynamic protocols::
* Protocol documentation::
* Loading files into a protocol::

Built-in protocols

* The built-in protocol expanding::
* The built-in protocol monitoring::
* The built-in protocol forwarding::

Categories

* Defining a new category::
* Hot patching::
* Finding defined categories::
* Creating a new category at runtime::
* Abolishing an existing category::
* Category directives::
* Category relationships::
* Category properties::
* Importing categories::
* Calling category predicates::
* Parametric categories::
* Built-in categories::
* Multi-threading applications: Multi-threading applications<3>.

Category directives

* Dynamic categories::
* Category documentation::
* Loading files into a category::
* Declaring object aliases: Declaring object aliases<2>.

Built-in categories

* The built-in category core_messages::

Predicates

* Reserved predicate names::
* Declaring predicates::
* Defining predicates::
* Definite clause grammar rules::
* Built-in methods::
* Predicate properties::
* Finding declared predicates::
* Calling Prolog predicates::
* Defining Prolog multifile predicates::
* Asserting and retracting Prolog predicates::

Declaring predicates

* Scope directives::
* Mode directive::
* Meta-predicate directive::
* Discontiguous directive::
* Dynamic directive::
* Operator directive::
* Uses directive::
* Alias directive::
* Documenting directive::
* Multifile directive::
* Coinductive directive::
* Synchronized directive::

Defining predicates

* Object predicates::
* Category predicates::
* Meta-predicates::
* Lambda expressions::
* Redefining built-in predicates::

Built-in methods

* Logic and control methods::
* Execution context methods::
* Error handling and throwing methods::
* Database methods::
* Meta-call methods::
* All solutions methods::
* Reflection methods::
* Definite clause grammar parsing methods and non-terminals::

Calling Prolog predicates

* Calling Prolog built-in predicates::
* Calling Prolog non-standard built-in meta-predicates::
* Calling Prolog foreign predicates::
* Calling Prolog user-defined plain predicates::
* Calling Prolog module predicates::
* Calling Prolog module meta-predicates::

Inheritance

* Protocol inheritance::
* Implementation inheritance::
* Public, protected, and private inheritance: Public protected and private inheritance.
* Multiple inheritance::
* Composition versus multiple inheritance::

Protocol inheritance

* Lookup order for prototype hierarchies::
* Lookup order for class hierarchies::

Implementation inheritance

* Lookup order for prototype hierarchies: Lookup order for prototype hierarchies<2>.
* Lookup order for class hierarchies: Lookup order for class hierarchies<2>.
* Redefining inherited predicate definitions::
* Specializing inherited predicate definitions::
* Union of inherited and local predicate definitions::
* Selective inheritance of predicate definitions::

Event-driven programming

* Definitions::
* Event generation::
* Communicating events to monitors::
* Performance concerns::
* Monitor semantics::
* Activation order of monitors::
* Event handling::

Definitions

* Event::
* Monitor::

Event handling

* Defining new events::
* Abolishing defined events::
* Finding defined events::
* Defining event handlers::

Multi-threading programming

* Enabling multi-threading support::
* Enabling objects to make multi-threading calls::
* Multi-threading built-in predicates::
* One-way asynchronous calls::
* Asynchronous calls and synchronized predicates::
* Synchronizing threads through notifications::
* Threaded engines::
* Multi-threading performance::

Multi-threading built-in predicates

* Proving goals concurrently using threads::
* Proving goals asynchronously using threads::

Error handling

* Raising Exceptions::
* Type-checking::
* Expected terms::
* Compiler warnings and errors::
* Runtime errors::

Compiler warnings and errors

* Unknown entities::
* Singleton variables::
* Redefinition of Prolog built-in predicates::
* Redefinition of Logtalk built-in predicates::
* Redefinition of Logtalk built-in methods::
* Misspell calls of local predicates::
* Portability warnings::
* Deprecated elements::
* Missing directives::
* Duplicated directives::
* Duplicated clauses::
* Goals that are always true or false::
* Trivial fails::
* Suspicious calls::
* Lambda variables::
* Redefinition of predicates declared in uses/2 or use_module/2 directives::
* Other warnings and errors::

Runtime errors

* Logtalk built-in predicates::
* Logtalk built-in methods::
* Message sending::

Reflection

* Structural reflection::
* Behavioral reflection::

Structural reflection

* Transparent-box view::
* Black-box view::

Writing and running applications

* Starting Logtalk::
* Running parallel Logtalk processes::
* Source files::
* Multi-pass compiler::
* Compiling and loading your applications::
* Compiler errors, warnings, and comments: Compiler errors warnings and comments.
* Loader files::
* Libraries of source files::
* Settings files::
* Compiler linter::
* Compiler flags::
* Reloading source files::
* Batch processing::
* Optimizing performance::
* Portable applications::
* Conditional compilation::
* Avoiding common errors::
* Coding style guidelines::

Source files

* Naming conventions::
* Source file text encoding::

Compiler flags

* Read-only flags::
* Version flags::
* Lint flags::
* Optional features compilation flags::
* Backend Prolog compiler and loader flags::
* Other flags::
* User-defined flags::

Printing messages and asking questions

* Printing messages::
* Message tokenization::
* Meta-messages::
* Defining message prefixes and output streams::
* Defining message prefixes and output files::
* Intercepting messages::
* Asking questions::
* Intercepting questions::
* Multi-threading applications: Multi-threading applications<4>.

Term and goal expansion

* Defining expansions::
* Expanding grammar rules::
* Bypassing expansions::
* Hook objects::
* Virtual source file terms and loading context::
* Default compiler expansion workflow::
* User defined expansion workflows::
* Using Prolog defined expansions::
* Debugging expansions::

Documenting

* Entity documenting directives::
* Predicate documenting directives::
* Describing predicates::
* Documenting predicate exceptions::
* Processing and viewing documenting files::
* Inline formatting in comments text::
* Diagrams::

Debugging

* Compiling source files in debug mode::
* Procedure box model::
* Activating the debugger::
* Defining breakpoints::
* Defining log points::
* Tracing program execution::
* Debugging using breakpoints::
* Debugging commands::
* Customizing term writing::
* Context-switching calls::
* Debugging messages::
* Using the term-expansion mechanism for debugging::
* Ports profiling::
* Debug and trace events::
* Source-level debugger::

Defining breakpoints

* Defining predicate and clause breakpoints::
* Defining conditional breakpoints::
* Defining hit count breakpoints::
* Defining triggered breakpoints::
* Defining context breakpoints::
* Removing all breakpoints::

Customizing term writing

* Term write depth::
* Custom term writing::

Debugging messages

* Meta-messages: Meta-messages<2>.
* Selective printing of debug messages::

Performance

* Source code compilation modes::
* Source code compilation order::
* Local predicate calls::
* Calls to imported or inherited predicates::
* Calls to module predicates::
* Messages: Messages<2>.
* Automatic expansion of built-in meta-predicates::
* Inlining::
* Generated code simplification and optimizations::
* Size of the generated code::
* Circular references::
* Debug mode overhead::
* Other considerations::

Installing Logtalk

* Hardware and software requirements::
* Logtalk installers::
* Source distribution::
* Distribution overview::

Hardware and software requirements

* Computer and operating system::
* Prolog compiler::

Distribution overview

* Adapter files::
* Compiler and runtime::
* Library::
* Examples::
* Logtalk source files::

Prolog integration and migration

* Source files with both Prolog code and Logtalk code::
* Encapsulating plain Prolog code in objects::
* Converting Prolog modules into objects::
* Compiling Prolog modules as objects::
* Dealing with proprietary Prolog directives and predicates::
* Calling Prolog module predicates: Calling Prolog module predicates<2>.
* Loading converted Prolog applications::

Encapsulating plain Prolog code in objects

* Prolog multifile predicates::

Compiling Prolog modules as objects

* Supported module directives::
* Unsupported module directives::
* Modules using a term-expansion mechanism::
* File search paths::

Reference Manual

* Grammar::
* Control constructs::
* Directives: Directives<2>.
* Built-in predicates::
* Built-in methods: Built-in methods<2>.

Grammar

* Entities::
* Object definition::
* Category definition::
* Protocol definition::
* Entity relations::
* Entity identifiers::
* Source files: Source files<2>.
* Source file names::
* Terms::
* Directives::
* Clauses and goals::
* Lambda expressions: Lambda expressions<2>.
* Entity properties::
* Predicate properties: Predicate properties<2>.
* Compiler flags: Compiler flags<2>.

Entity relations

* Implemented protocols::
* Extended protocols::
* Imported categories::
* Extended objects::
* Extended categories::
* Instantiated objects::
* Specialized objects::
* Complemented objects::
* Entity and predicate scope::

Entity identifiers

* Object identifiers::
* Category identifiers::
* Protocol identifiers::
* Module identifiers::

Terms

* Object terms::
* Category terms::

Directives

* Source file directives::
* Conditional compilation directives::
* Object directives: Object directives<2>.
* Category directives: Category directives<2>.
* Protocol directives: Protocol directives<2>.
* Predicate directives::

Control constructs

* Message sending: Message sending<2>.
* Message delegation::
* Calling imported and inherited predicates: Calling imported and inherited predicates<2>.
* Calling predicates in this::
* Calling external predicates::
* Context switching calls::

Message sending

* (;;)/2: /2.
* (;;)/1: /1.

(::)/2

* Description::
* Modes and number of proofs::
* Errors::
* Examples: Examples<2>.

(::)/1

* Description: Description<2>.
* Modes and number of proofs: Modes and number of proofs<2>.
* Errors: Errors<2>.
* Examples: Examples<3>.

Message delegation

* []/1::

[]/1

* Description: Description<3>.
* Modes and number of proofs: Modes and number of proofs<3>.
* Errors: Errors<3>.
* Examples: Examples<4>.

Calling imported and inherited predicates

* (^^)/1: ^^ /1.

(^^)/1

* Description: Description<4>.
* Modes and number of proofs: Modes and number of proofs<4>.
* Errors: Errors<4>.
* Examples: Examples<5>.

Calling predicates in this

* (@)/1: @ /1.

(@)/1

* Description: Description<5>.
* Modes and number of proofs: Modes and number of proofs<5>.
* Errors: Errors<5>.
* Examples: Examples<6>.

Calling external predicates

* {}/1::

{}/1

* Description: Description<6>.
* Modes and number of proofs: Modes and number of proofs<6>.
* Errors: Errors<6>.
* Examples: Examples<7>.

Context switching calls

* (<<)/2: << /2.

(<<)/2

* Description: Description<7>.
* Modes and number of proofs: Modes and number of proofs<7>.
* Errors: Errors<7>.
* Examples: Examples<8>.

Directives

* Source file directives: Source file directives<2>.
* Conditional compilation directives: Conditional compilation directives<2>.
* Entity directives::
* Predicate directives: Predicate directives<2>.

Source file directives

* encoding/1::
* include/1::
* initialization/1::
* op/3::
* set_logtalk_flag/2::

encoding/1

* Description: Description<8>.
* Template and modes::
* Examples: Examples<9>.

include/1

* Description: Description<9>.
* Template and modes: Template and modes<2>.
* Examples: Examples<10>.

initialization/1

* Description: Description<10>.
* Template and modes: Template and modes<3>.
* Examples: Examples<11>.

op/3

* Description: Description<11>.
* Template and modes: Template and modes<4>.
* Examples: Examples<12>.

set_logtalk_flag/2

* Description: Description<12>.
* Template and modes: Template and modes<5>.
* Errors: Errors<8>.
* Examples: Examples<13>.

Conditional compilation directives

* if/1::
* elif/1::
* else/0::
* endif/0::

if/1

* Description: Description<13>.
* Template and modes: Template and modes<6>.
* Examples: Examples<14>.

elif/1

* Description: Description<14>.
* Template and modes: Template and modes<7>.
* Examples: Examples<15>.

else/0

* Description: Description<15>.
* Template and modes: Template and modes<8>.
* Examples: Examples<16>.

endif/0

* Description: Description<16>.
* Template and modes: Template and modes<9>.
* Examples: Examples<17>.

Entity directives

* built_in/0::
* category/1-4::
* dynamic/0::
* end_category/0::
* end_object/0::
* end_protocol/0::
* info/1::
* object/1-5::
* protocol/1-2::
* threaded/0::
* uses/1::
* use_module/1::

built_in/0

* Description: Description<17>.
* Template and modes: Template and modes<10>.
* Examples: Examples<18>.

category/1-4

* Description: Description<18>.
* Template and modes: Template and modes<11>.
* Examples: Examples<19>.

dynamic/0

* Description: Description<19>.
* Template and modes: Template and modes<12>.
* Examples: Examples<20>.

end_category/0

* Description: Description<20>.
* Template and modes: Template and modes<13>.
* Examples: Examples<21>.

end_object/0

* Description: Description<21>.
* Template and modes: Template and modes<14>.
* Examples: Examples<22>.

end_protocol/0

* Description: Description<22>.
* Template and modes: Template and modes<15>.
* Examples: Examples<23>.

info/1

* Description: Description<23>.
* Template and modes: Template and modes<16>.
* Examples: Examples<24>.

object/1-5

* Description: Description<24>.
* Template and modes: Template and modes<17>.
* Examples: Examples<25>.

protocol/1-2

* Description: Description<25>.
* Template and modes: Template and modes<18>.
* Examples: Examples<26>.

threaded/0

* Description: Description<26>.
* Template and modes: Template and modes<19>.
* Examples: Examples<27>.

uses/1

* Description: Description<27>.
* Template and modes: Template and modes<20>.
* Examples: Examples<28>.

use_module/1

* Description: Description<28>.
* Template and modes: Template and modes<21>.
* Examples: Examples<29>.

Predicate directives

* alias/2::
* coinductive/1::
* discontiguous/1::
* dynamic/1::
* info/2::
* meta_predicate/1::
* meta_non_terminal/1::
* mode/2::
* mode_non_terminal/2::
* multifile/1::
* private/1::
* protected/1::
* public/1::
* synchronized/1::
* uses/2::
* use_module/2::

alias/2

* Description: Description<29>.
* Template and modes: Template and modes<22>.
* Examples: Examples<30>.

coinductive/1

* Description: Description<30>.
* Template and modes: Template and modes<23>.
* Examples: Examples<31>.

discontiguous/1

* Description: Description<31>.
* Template and modes: Template and modes<24>.
* Examples: Examples<32>.

dynamic/1

* Description: Description<32>.
* Template and modes: Template and modes<25>.
* Examples: Examples<33>.

info/2

* Description: Description<33>.
* Template and modes: Template and modes<26>.
* Examples: Examples<34>.

meta_predicate/1

* Description: Description<34>.
* Template and modes: Template and modes<27>.
* Examples: Examples<35>.

meta_non_terminal/1

* Description: Description<35>.
* Template and modes: Template and modes<28>.
* Examples: Examples<36>.

mode/2

* Description: Description<36>.
* Template and modes: Template and modes<29>.
* Examples: Examples<37>.

mode_non_terminal/2

* Description: Description<37>.
* Template and modes: Template and modes<30>.
* Examples: Examples<38>.

multifile/1

* Description: Description<38>.
* Template and modes: Template and modes<31>.
* Examples: Examples<39>.

private/1

* Description: Description<39>.
* Template and modes: Template and modes<32>.
* Examples: Examples<40>.

protected/1

* Description: Description<40>.
* Template and modes: Template and modes<33>.
* Examples: Examples<41>.

public/1

* Description: Description<41>.
* Template and modes: Template and modes<34>.
* Examples: Examples<42>.

synchronized/1

* Description: Description<42>.
* Template and modes: Template and modes<35>.
* Examples: Examples<43>.

uses/2

* Description: Description<43>.
* Template and modes: Template and modes<36>.
* Examples: Examples<44>.

use_module/2

* Description: Description<44>.
* Template and modes: Template and modes<37>.
* Examples: Examples<45>.

Built-in predicates

* Enumerating objects, categories and protocols: Enumerating objects categories and protocols.
* Enumerating objects, categories and protocols properties: Enumerating objects categories and protocols properties.
* Creating new objects, categories and protocols: Creating new objects categories and protocols.
* Abolishing objects, categories and protocols: Abolishing objects categories and protocols.
* Objects, categories, and protocols relations: Objects categories and protocols relations.
* Event handling: Event handling<2>.
* Multi-threading::
* Multi-threading engines::
* Compiling and loading source files::
* Flags::
* Linter::

Enumerating objects, categories and protocols

* current_category/1::
* current_object/1::
* current_protocol/1::

current_category/1

* Description: Description<45>.
* Modes and number of proofs: Modes and number of proofs<8>.
* Errors: Errors<9>.
* Examples: Examples<46>.

current_object/1

* Description: Description<46>.
* Modes and number of proofs: Modes and number of proofs<9>.
* Errors: Errors<10>.
* Examples: Examples<47>.

current_protocol/1

* Description: Description<47>.
* Modes and number of proofs: Modes and number of proofs<10>.
* Errors: Errors<11>.
* Examples: Examples<48>.

Enumerating objects, categories and protocols properties

* category_property/2::
* object_property/2::
* protocol_property/2::

category_property/2

* Description: Description<48>.
* Modes and number of proofs: Modes and number of proofs<11>.
* Errors: Errors<12>.
* Examples: Examples<49>.

object_property/2

* Description: Description<49>.
* Modes and number of proofs: Modes and number of proofs<12>.
* Errors: Errors<13>.
* Examples: Examples<50>.

protocol_property/2

* Description: Description<50>.
* Modes and number of proofs: Modes and number of proofs<13>.
* Errors: Errors<14>.
* Examples: Examples<51>.

Creating new objects, categories and protocols

* create_category/4::
* create_object/4::
* create_protocol/3::

create_category/4

* Description: Description<51>.
* Modes and number of proofs: Modes and number of proofs<14>.
* Errors: Errors<15>.
* Examples: Examples<52>.

create_object/4

* Description: Description<52>.
* Modes and number of proofs: Modes and number of proofs<15>.
* Errors: Errors<16>.
* Examples: Examples<53>.

create_protocol/3

* Description: Description<53>.
* Modes and number of proofs: Modes and number of proofs<16>.
* Errors: Errors<17>.
* Examples: Examples<54>.

Abolishing objects, categories and protocols

* abolish_category/1::
* abolish_object/1::
* abolish_protocol/1::

abolish_category/1

* Description: Description<54>.
* Modes and number of proofs: Modes and number of proofs<17>.
* Errors: Errors<18>.
* Examples: Examples<55>.

abolish_object/1

* Description: Description<55>.
* Modes and number of proofs: Modes and number of proofs<18>.
* Errors: Errors<19>.
* Examples: Examples<56>.

abolish_protocol/1

* Description: Description<56>.
* Modes and number of proofs: Modes and number of proofs<19>.
* Errors: Errors<20>.
* Examples: Examples<57>.

Objects, categories, and protocols relations

* extends_object/2-3::
* extends_protocol/2-3::
* extends_category/2-3::
* implements_protocol/2-3::
* conforms_to_protocol/2-3::
* complements_object/2::
* imports_category/2-3::
* instantiates_class/2-3::
* specializes_class/2-3::

extends_object/2-3

* Description: Description<57>.
* Modes and number of proofs: Modes and number of proofs<20>.
* Errors: Errors<21>.
* Examples: Examples<58>.

extends_protocol/2-3

* Description: Description<58>.
* Modes and number of proofs: Modes and number of proofs<21>.
* Errors: Errors<22>.
* Examples: Examples<59>.

extends_category/2-3

* Description: Description<59>.
* Modes and number of proofs: Modes and number of proofs<22>.
* Errors: Errors<23>.
* Examples: Examples<60>.

implements_protocol/2-3

* Description: Description<60>.
* Modes and number of proofs: Modes and number of proofs<23>.
* Errors: Errors<24>.
* Examples: Examples<61>.

conforms_to_protocol/2-3

* Description: Description<61>.
* Modes and number of proofs: Modes and number of proofs<24>.
* Errors: Errors<25>.
* Examples: Examples<62>.

complements_object/2

* Description: Description<62>.
* Modes and number of proofs: Modes and number of proofs<25>.
* Errors: Errors<26>.
* Examples: Examples<63>.

imports_category/2-3

* Description: Description<63>.
* Modes and number of proofs: Modes and number of proofs<26>.
* Errors: Errors<27>.
* Examples: Examples<64>.

instantiates_class/2-3

* Description: Description<64>.
* Modes and number of proofs: Modes and number of proofs<27>.
* Errors: Errors<28>.
* Examples: Examples<65>.

specializes_class/2-3

* Description: Description<65>.
* Modes and number of proofs: Modes and number of proofs<28>.
* Errors: Errors<29>.
* Examples: Examples<66>.

Event handling

* abolish_events/5::
* current_event/5::
* define_events/5::

abolish_events/5

* Description: Description<66>.
* Modes and number of proofs: Modes and number of proofs<29>.
* Errors: Errors<30>.
* Examples: Examples<67>.

current_event/5

* Description: Description<67>.
* Modes and number of proofs: Modes and number of proofs<30>.
* Errors: Errors<31>.
* Examples: Examples<68>.

define_events/5

* Description: Description<68>.
* Modes and number of proofs: Modes and number of proofs<31>.
* Errors: Errors<32>.
* Examples: Examples<69>.

Multi-threading

* threaded/1::
* threaded_call/1-2::
* threaded_once/1-2::
* threaded_ignore/1::
* threaded_exit/1-2::
* threaded_peek/1-2::
* threaded_cancel/1::
* threaded_wait/1::
* threaded_notify/1::

threaded/1

* Description: Description<69>.
* Meta-predicate template::
* Modes and number of proofs: Modes and number of proofs<32>.
* Errors: Errors<33>.
* Examples: Examples<70>.

threaded_call/1-2

* Description: Description<70>.
* Meta-predicate template: Meta-predicate template<2>.
* Modes and number of proofs: Modes and number of proofs<33>.
* Errors: Errors<34>.
* Examples: Examples<71>.

threaded_once/1-2

* Description: Description<71>.
* Meta-predicate template: Meta-predicate template<3>.
* Modes and number of proofs: Modes and number of proofs<34>.
* Errors: Errors<35>.
* Examples: Examples<72>.

threaded_ignore/1

* Description: Description<72>.
* Meta-predicate template: Meta-predicate template<4>.
* Modes and number of proofs: Modes and number of proofs<35>.
* Errors: Errors<36>.
* Examples: Examples<73>.

threaded_exit/1-2

* Description: Description<73>.
* Modes and number of proofs: Modes and number of proofs<36>.
* Errors: Errors<37>.
* Examples: Examples<74>.

threaded_peek/1-2

* Description: Description<74>.
* Modes and number of proofs: Modes and number of proofs<37>.
* Errors: Errors<38>.
* Examples: Examples<75>.

threaded_cancel/1

* Description: Description<75>.
* Modes and number of proofs: Modes and number of proofs<38>.
* Errors: Errors<39>.
* Examples: Examples<76>.

threaded_wait/1

* Description: Description<76>.
* Modes and number of proofs: Modes and number of proofs<39>.
* Errors: Errors<40>.
* Examples: Examples<77>.

threaded_notify/1

* Description: Description<77>.
* Modes and number of proofs: Modes and number of proofs<40>.
* Errors: Errors<41>.
* Examples: Examples<78>.

Multi-threading engines

* threaded_engine_create/3::
* threaded_engine_destroy/1::
* threaded_engine/1::
* threaded_engine_self/1::
* threaded_engine_next/2::
* threaded_engine_next_reified/2::
* threaded_engine_yield/1::
* threaded_engine_post/2::
* threaded_engine_fetch/1::

threaded_engine_create/3

* Description: Description<78>.
* Meta-predicate template: Meta-predicate template<5>.
* Modes and number of proofs: Modes and number of proofs<41>.
* Errors: Errors<42>.
* Examples: Examples<79>.

threaded_engine_destroy/1

* Description: Description<79>.
* Modes and number of proofs: Modes and number of proofs<42>.
* Errors: Errors<43>.
* Examples: Examples<80>.

threaded_engine/1

* Description: Description<80>.
* Modes and number of proofs: Modes and number of proofs<43>.
* Errors: Errors<44>.
* Examples: Examples<81>.

threaded_engine_self/1

* Description: Description<81>.
* Modes and number of proofs: Modes and number of proofs<44>.
* Errors: Errors<45>.
* Examples: Examples<82>.

threaded_engine_next/2

* Description: Description<82>.
* Modes and number of proofs: Modes and number of proofs<45>.
* Errors: Errors<46>.
* Examples: Examples<83>.

threaded_engine_next_reified/2

* Description: Description<83>.
* Modes and number of proofs: Modes and number of proofs<46>.
* Errors: Errors<47>.
* Examples: Examples<84>.

threaded_engine_yield/1

* Description: Description<84>.
* Modes and number of proofs: Modes and number of proofs<47>.
* Errors: Errors<48>.
* Examples: Examples<85>.

threaded_engine_post/2

* Description: Description<85>.
* Modes and number of proofs: Modes and number of proofs<48>.
* Errors: Errors<49>.
* Examples: Examples<86>.

threaded_engine_fetch/1

* Description: Description<86>.
* Modes and number of proofs: Modes and number of proofs<49>.
* Errors: Errors<50>.
* Examples: Examples<87>.

Compiling and loading source files

* logtalk_compile/1::
* logtalk_compile/2::
* logtalk_load/1::
* logtalk_load/2::
* logtalk_make/0::
* logtalk_make/1::
* logtalk_make_target_action/1::
* logtalk_library_path/2::
* logtalk_load_context/2::

logtalk_compile/1

* Description: Description<87>.
* Modes and number of proofs: Modes and number of proofs<50>.
* Errors: Errors<51>.
* Examples: Examples<88>.

logtalk_compile/2

* Description: Description<88>.
* Modes and number of proofs: Modes and number of proofs<51>.
* Errors: Errors<52>.
* Examples: Examples<89>.

logtalk_load/1

* Description: Description<89>.
* Modes and number of proofs: Modes and number of proofs<52>.
* Errors: Errors<53>.
* Examples: Examples<90>.

logtalk_load/2

* Description: Description<90>.
* Modes and number of proofs: Modes and number of proofs<53>.
* Errors: Errors<54>.
* Examples: Examples<91>.

logtalk_make/0

* Description: Description<91>.
* Modes and number of proofs: Modes and number of proofs<54>.
* Errors: Errors<55>.
* Examples: Examples<92>.

logtalk_make/1

* Description: Description<92>.
* Modes and number of proofs: Modes and number of proofs<55>.
* Errors: Errors<56>.
* Examples: Examples<93>.

logtalk_make_target_action/1

* Description: Description<93>.
* Modes and number of proofs: Modes and number of proofs<56>.
* Errors: Errors<57>.
* Examples: Examples<94>.

logtalk_library_path/2

* Description: Description<94>.
* Modes and number of proofs: Modes and number of proofs<57>.
* Errors: Errors<58>.
* Examples: Examples<95>.

logtalk_load_context/2

* Description: Description<95>.
* Modes and number of proofs: Modes and number of proofs<58>.
* Errors: Errors<59>.
* Examples: Examples<96>.

Flags

* current_logtalk_flag/2::
* set_logtalk_flag/2: set_logtalk_flag/2<2>.
* create_logtalk_flag/3::

current_logtalk_flag/2

* Description: Description<96>.
* Modes and number of proofs: Modes and number of proofs<59>.
* Errors: Errors<60>.
* Examples: Examples<97>.

set_logtalk_flag/2

* Description: Description<97>.
* Modes and number of proofs: Modes and number of proofs<60>.
* Errors: Errors<61>.
* Examples: Examples<98>.

create_logtalk_flag/3

* Description: Description<98>.
* Modes and number of proofs: Modes and number of proofs<61>.
* Errors: Errors<62>.
* Examples: Examples<99>.

Linter

* logtalk_linter_hook/7::

logtalk_linter_hook/7

* Description: Description<99>.
* Modes and number of proofs: Modes and number of proofs<62>.
* Errors: Errors<63>.
* Examples: Examples<100>.

Built-in methods

* Logic and control::
* Execution context::
* Reflection: Reflection<2>.
* Database::
* Meta-calls::
* Error handling: Error handling<2>.
* All solutions::
* Event handling: Event handling<3>.
* Message forwarding::
* Definite clause grammar rules: Definite clause grammar rules<2>.
* Term and goal expansion: Term and goal expansion<2>.
* Coinduction hooks::
* Message printing::
* Question asking::

Logic and control

* !/0::
* true/0::
* fail/0::
* false/0::
* repeat/0::

!/0

* Description: Description<100>.
* Modes and number of proofs: Modes and number of proofs<63>.
* Errors: Errors<64>.
* Examples: Examples<101>.

true/0

* Description: Description<101>.
* Modes and number of proofs: Modes and number of proofs<64>.
* Errors: Errors<65>.
* Examples: Examples<102>.

fail/0

* Description: Description<102>.
* Modes and number of proofs: Modes and number of proofs<65>.
* Errors: Errors<66>.
* Examples: Examples<103>.

false/0

* Description: Description<103>.
* Modes and number of proofs: Modes and number of proofs<66>.
* Errors: Errors<67>.
* Examples: Examples<104>.

repeat/0

* Description: Description<104>.
* Modes and number of proofs: Modes and number of proofs<67>.
* Errors: Errors<68>.
* Examples: Examples<105>.

Execution context

* context/1::
* parameter/2::
* self/1::
* sender/1::
* this/1::

context/1

* Description: Description<105>.
* Modes and number of proofs: Modes and number of proofs<68>.
* Errors: Errors<69>.
* Examples: Examples<106>.

parameter/2

* Description: Description<106>.
* Modes and number of proofs: Modes and number of proofs<69>.
* Errors: Errors<70>.
* Examples: Examples<107>.

self/1

* Description: Description<107>.
* Modes and number of proofs: Modes and number of proofs<70>.
* Errors: Errors<71>.
* Examples: Examples<108>.

sender/1

* Description: Description<108>.
* Modes and number of proofs: Modes and number of proofs<71>.
* Errors: Errors<72>.
* Examples: Examples<109>.

this/1

* Description: Description<109>.
* Modes and number of proofs: Modes and number of proofs<72>.
* Errors: Errors<73>.
* Examples: Examples<110>.

Reflection

* current_op/3::
* current_predicate/1::
* predicate_property/2::

current_op/3

* Description: Description<110>.
* Modes and number of proofs: Modes and number of proofs<73>.
* Errors: Errors<74>.
* Examples: Examples<111>.

current_predicate/1

* Description: Description<111>.
* Modes and number of proofs: Modes and number of proofs<74>.
* Errors: Errors<75>.
* Examples: Examples<112>.

predicate_property/2

* Description: Description<112>.
* Modes and number of proofs: Modes and number of proofs<75>.
* Errors: Errors<76>.
* Examples: Examples<113>.

Database

* abolish/1::
* asserta/1::
* assertz/1::
* clause/2::
* retract/1::
* retractall/1::

abolish/1

* Description: Description<113>.
* Modes and number of proofs: Modes and number of proofs<76>.
* Errors: Errors<77>.
* Examples: Examples<114>.

asserta/1

* Description: Description<114>.
* Modes and number of proofs: Modes and number of proofs<77>.
* Errors: Errors<78>.
* Examples: Examples<115>.

assertz/1

* Description: Description<115>.
* Modes and number of proofs: Modes and number of proofs<78>.
* Errors: Errors<79>.
* Examples: Examples<116>.

clause/2

* Description: Description<116>.
* Modes and number of proofs: Modes and number of proofs<79>.
* Errors: Errors<80>.
* Examples: Examples<117>.

retract/1

* Description: Description<117>.
* Modes and number of proofs: Modes and number of proofs<80>.
* Errors: Errors<81>.
* Examples: Examples<118>.

retractall/1

* Description: Description<118>.
* Modes and number of proofs: Modes and number of proofs<81>.
* Errors: Errors<82>.
* Examples: Examples<119>.

Meta-calls

* call/1-N::
* ignore/1::
* once/1::
* (\+)/1: \+ /1.

call/1-N

* Description: Description<119>.
* Meta-predicate template: Meta-predicate template<6>.
* Modes and number of proofs: Modes and number of proofs<82>.
* Errors: Errors<83>.
* Examples: Examples<120>.

ignore/1

* Description: Description<120>.
* Meta-predicate template: Meta-predicate template<7>.
* Modes and number of proofs: Modes and number of proofs<83>.
* Errors: Errors<84>.
* Examples: Examples<121>.

once/1

* Description: Description<121>.
* Meta-predicate template: Meta-predicate template<8>.
* Modes and number of proofs: Modes and number of proofs<84>.
* Errors: Errors<85>.
* Examples: Examples<122>.

(\+)/1

* Description: Description<122>.
* Meta-predicate template: Meta-predicate template<9>.
* Modes and number of proofs: Modes and number of proofs<85>.
* Errors: Errors<86>.
* Examples: Examples<123>.

Error handling

* catch/3::
* throw/1::
* instantiation_error/0::
* uninstantiation_error/1::
* type_error/2::
* domain_error/2::
* consistency_error/3::
* existence_error/2::
* permission_error/3::
* representation_error/1::
* evaluation_error/1::
* resource_error/1::
* syntax_error/1::
* system_error/0::

catch/3

* Description: Description<123>.
* Modes and number of proofs: Modes and number of proofs<86>.
* Errors: Errors<87>.
* Examples: Examples<124>.

throw/1

* Description: Description<124>.
* Modes and number of proofs: Modes and number of proofs<87>.
* Errors: Errors<88>.
* Examples: Examples<125>.

instantiation_error/0

* Description: Description<125>.
* Modes and number of proofs: Modes and number of proofs<88>.
* Errors: Errors<89>.
* Examples: Examples<126>.

uninstantiation_error/1

* Description: Description<126>.
* Modes and number of proofs: Modes and number of proofs<89>.
* Errors: Errors<90>.
* Examples: Examples<127>.

type_error/2

* Description: Description<127>.
* Modes and number of proofs: Modes and number of proofs<90>.
* Errors: Errors<91>.
* Examples: Examples<128>.

domain_error/2

* Description: Description<128>.
* Modes and number of proofs: Modes and number of proofs<91>.
* Errors: Errors<92>.
* Examples: Examples<129>.

consistency_error/3

* Description: Description<129>.
* Modes and number of proofs: Modes and number of proofs<92>.
* Errors: Errors<93>.
* Examples: Examples<130>.

existence_error/2

* Description: Description<130>.
* Modes and number of proofs: Modes and number of proofs<93>.
* Errors: Errors<94>.
* Examples: Examples<131>.

permission_error/3

* Description: Description<131>.
* Modes and number of proofs: Modes and number of proofs<94>.
* Errors: Errors<95>.
* Examples: Examples<132>.

representation_error/1

* Description: Description<132>.
* Modes and number of proofs: Modes and number of proofs<95>.
* Errors: Errors<96>.
* Examples: Examples<133>.

evaluation_error/1

* Description: Description<133>.
* Modes and number of proofs: Modes and number of proofs<96>.
* Errors: Errors<97>.
* Examples: Examples<134>.

resource_error/1

* Description: Description<134>.
* Modes and number of proofs: Modes and number of proofs<97>.
* Errors: Errors<98>.
* Examples: Examples<135>.

syntax_error/1

* Description: Description<135>.
* Modes and number of proofs: Modes and number of proofs<98>.
* Errors: Errors<99>.
* Examples: Examples<136>.

system_error/0

* Description: Description<136>.
* Modes and number of proofs: Modes and number of proofs<99>.
* Errors: Errors<100>.
* Examples: Examples<137>.

All solutions

* bagof/3::
* findall/3::
* findall/4::
* forall/2::
* setof/3::

bagof/3

* Description: Description<137>.
* Meta-predicate template: Meta-predicate template<10>.
* Modes and number of proofs: Modes and number of proofs<100>.
* Errors: Errors<101>.
* Examples: Examples<138>.

findall/3

* Description: Description<138>.
* Meta-predicate template: Meta-predicate template<11>.
* Modes and number of proofs: Modes and number of proofs<101>.
* Errors: Errors<102>.
* Examples: Examples<139>.

findall/4

* Description: Description<139>.
* Meta-predicate template: Meta-predicate template<12>.
* Modes and number of proofs: Modes and number of proofs<102>.
* Errors: Errors<103>.
* Examples: Examples<140>.

forall/2

* Description: Description<140>.
* Meta-predicate template: Meta-predicate template<13>.
* Modes and number of proofs: Modes and number of proofs<103>.
* Errors: Errors<104>.
* Examples: Examples<141>.

setof/3

* Description: Description<141>.
* Meta-predicate template: Meta-predicate template<14>.
* Modes and number of proofs: Modes and number of proofs<104>.
* Errors: Errors<105>.
* Examples: Examples<142>.

Event handling

* before/3::
* after/3::

before/3

* Description: Description<142>.
* Modes and number of proofs: Modes and number of proofs<105>.
* Errors: Errors<106>.
* Examples: Examples<143>.

after/3

* Description: Description<143>.
* Modes and number of proofs: Modes and number of proofs<106>.
* Errors: Errors<107>.
* Examples: Examples<144>.

Message forwarding

* forward/1::

forward/1

* Description: Description<144>.
* Modes and number of proofs: Modes and number of proofs<107>.
* Errors: Errors<108>.
* Examples: Examples<145>.

Definite clause grammar rules

* call//1-N::
* eos//0::
* phrase//1::
* phrase/2::
* phrase/3::

call//1-N

* Description: Description<145>.
* Meta-non-terminal template::
* Modes and number of proofs: Modes and number of proofs<108>.
* Errors: Errors<109>.
* Examples: Examples<146>.

eos//0

* Description: Description<146>.
* Modes and number of proofs: Modes and number of proofs<109>.
* Errors: Errors<110>.
* Examples: Examples<147>.

phrase//1

* Description: Description<147>.
* Meta-non-terminal template: Meta-non-terminal template<2>.
* Modes and number of proofs: Modes and number of proofs<110>.
* Errors: Errors<111>.
* Examples: Examples<148>.

phrase/2

* Description: Description<148>.
* Meta-predicate template: Meta-predicate template<15>.
* Modes and number of proofs: Modes and number of proofs<111>.
* Errors: Errors<112>.
* Examples: Examples<149>.

phrase/3

* Description: Description<149>.
* Meta-predicate template: Meta-predicate template<16>.
* Modes and number of proofs: Modes and number of proofs<112>.
* Errors: Errors<113>.
* Examples: Examples<150>.

Term and goal expansion

* expand_term/2::
* term_expansion/2::
* expand_goal/2::
* goal_expansion/2::

expand_term/2

* Description: Description<150>.
* Modes and number of proofs: Modes and number of proofs<113>.
* Errors: Errors<114>.
* Examples: Examples<151>.

term_expansion/2

* Description: Description<151>.
* Modes and number of proofs: Modes and number of proofs<114>.
* Errors: Errors<115>.
* Examples: Examples<152>.

expand_goal/2

* Description: Description<152>.
* Modes and number of proofs: Modes and number of proofs<115>.
* Errors: Errors<116>.
* Examples: Examples<153>.

goal_expansion/2

* Description: Description<153>.
* Modes and number of proofs: Modes and number of proofs<116>.
* Errors: Errors<117>.
* Examples: Examples<154>.

Coinduction hooks

* coinductive_success_hook/1-2::

coinductive_success_hook/1-2

* Description: Description<154>.
* Modes and number of proofs: Modes and number of proofs<117>.
* Errors: Errors<118>.
* Examples: Examples<155>.

Message printing

* print_message/3::
* message_tokens//2::
* message_hook/4::
* message_prefix_stream/4::
* message_prefix_file/6::
* print_message_tokens/3::
* print_message_token/4::

print_message/3

* Description: Description<155>.
* Modes and number of proofs: Modes and number of proofs<118>.
* Errors: Errors<119>.
* Examples: Examples<156>.

message_tokens//2

* Description: Description<156>.
* Modes and number of proofs: Modes and number of proofs<119>.
* Errors: Errors<120>.
* Examples: Examples<157>.

message_hook/4

* Description: Description<157>.
* Modes and number of proofs: Modes and number of proofs<120>.
* Errors: Errors<121>.
* Examples: Examples<158>.

message_prefix_stream/4

* Description: Description<158>.
* Modes and number of proofs: Modes and number of proofs<121>.
* Errors: Errors<122>.
* Examples: Examples<159>.

message_prefix_file/6

* Description: Description<159>.
* Modes and number of proofs: Modes and number of proofs<122>.
* Errors: Errors<123>.
* Examples: Examples<160>.

print_message_tokens/3

* Description: Description<160>.
* Modes and number of proofs: Modes and number of proofs<123>.
* Errors: Errors<124>.
* Examples: Examples<161>.

print_message_token/4

* Description: Description<161>.
* Modes and number of proofs: Modes and number of proofs<124>.
* Errors: Errors<125>.
* Examples: Examples<162>.

Question asking

* ask_question/5::
* question_hook/6::
* question_prompt_stream/4::

ask_question/5

* Description: Description<162>.
* Modes and number of proofs: Modes and number of proofs<125>.
* Meta-predicate template: Meta-predicate template<17>.
* Errors: Errors<126>.
* Examples: Examples<163>.

question_hook/6

* Description: Description<163>.
* Modes and number of proofs: Modes and number of proofs<126>.
* Meta-predicate template: Meta-predicate template<18>.
* Errors: Errors<127>.
* Examples: Examples<164>.

question_prompt_stream/4

* Description: Description<164>.
* Modes and number of proofs: Modes and number of proofs<127>.
* Errors: Errors<128>.
* Examples: Examples<165>.

Tutorial

* List predicates::
* Dynamic object attributes::
* A reflective class-based system::
* Profiling programs::

List predicates

* Defining a list object::
* Defining a list protocol::
* Summary::

Dynamic object attributes

* Defining a category::
* Importing the category::
* Summary: Summary<2>.

A reflective class-based system

* Defining the base classes::
* Summary: Summary<3>.

Profiling programs

* Messages as events::
* Profilers as monitors::
* Summary: Summary<4>.

FAQ

* General::
* Compatibility::
* Installation::
* Portability::
* Programming::
* Troubleshooting::
* Usability::
* Deployment::
* Performance: Performance<3>.
* Licensing::
* Support::

General

* Why are all versions of Logtalk numbered 2.x or 3.x?: Why are all versions of Logtalk numbered 2 x or 3 x?.
* Why do I need a Prolog compiler to use Logtalk?::
* Is the Logtalk implementation based on Prolog modules?::
* Does the Logtalk implementation use term-expansion?::

Compatibility

* What are the backend Prolog compiler requirements to run Logtalk?::
* Can I use constraint-based packages with Logtalk?::
* Can I use Logtalk objects and Prolog modules at the same time?::

Installation

* The integration scripts/shortcuts are not working!::
* I get errors when starting up Logtalk after upgrading to the latest version!::

Portability

* Are my Logtalk applications portable across Prolog compilers?::
* Are my Logtalk applications portable across operating systems?::

Programming

* Should I use prototypes or classes in my application?::
* Can I use both classes and prototypes in the same application?::
* Can I mix classes and prototypes in the same hierarchy?::
* Can I use a protocol or a category with both prototypes and classes?::
* What support is provided in Logtalk for defining and using components?::
* What support is provided in Logtalk for reflective programming?::

Troubleshooting

* Using compiler options on calls to the Logtalk compiling and loading predicates does not work!::
* Gecko-based browsers (e.g., Firefox) show non-rendered HTML entities when browsing XML documenting files!: Gecko-based browsers e g Firefox show non-rendered HTML entities when browsing XML documenting files!.
* Compiling a source file results in errors or warnings but the Logtalk compiler reports a successful compilation with zero errors and zero warnings!::

Usability

* Is there a shortcut for compiling and loading source files?::
* Is there an equivalent directive to the ensure_loaded/1 Prolog directive?::
* Are there shortcuts for the make functionality?::

Deployment

* Can I create standalone applications with Logtalk?::

Performance

* Is Logtalk implemented as a meta-interpreter?::
* What kind of code Logtalk generates when compiling objects? Dynamic code? Static code?::
* How about message-sending performance? Does Logtalk use static binding or dynamic binding?::
* Which Prolog-dependent factors are most crucial for good Logtalk performance?::
* How does Logtalk performance compare with plain Prolog and with Prolog modules?::

Licensing

* What’s the Logtalk distribution license?::
* Can Logtalk be used in commercial applications?::
* What’s the final license for a combination of Logtalk with a Prolog compiler?::

Support

* Are there professional consulting, training and supporting services?: Are there professional consulting training and supporting services?.

Developer Tools

* Overview::
* asdf::
* assertions::
* code_metrics::
* dead_code_scanner::
* debug_messages::
* debugger::
* diagrams::
* doclet::
* help::
* issue_creator::
* lgtdoc::
* lgtunit::
* linter::
* make::
* packs::
* ports_profiler::
* profiler::
* tutor::
* wrapper::

Overview

* Loading the developer tools::
* Tools documentation::
* Tools common flags::
* Tools requirements::

Tools requirements

* Tool dependencies for full functionality::
* Python dependencies (all operating-systems): Python dependencies all operating-systems.
* macOS - MacPorts::
* macOS - Homebrew::
* Ubuntu::
* RedHat::
* Windows - Chocolatey::
* Installers::
* Windows - PowerShell add-ons::

assertions

* API documentation::
* Loading::
* Testing::
* Adding assertions to your source code::
* Automatically adding file and line context information to assertions::
* Suppressing assertion calls from source code::
* Redirecting assertion failure messages::
* Converting assertion failures into errors::

code_metrics

* API documentation: API documentation<2>.
* Loading: Loading<2>.
* Testing: Testing<2>.
* Available metrics::
* Coupling metrics::
* Halstead metric::
* UPN metric::
* Cyclomatic complexity metric::
* Usage::
* Excluding code from analysis::
* Defining new metrics::
* Third-party tools::
* Applying metrics to Prolog modules::
* Applying metrics to plain Prolog code::

dead_code_scanner

* API documentation: API documentation<3>.
* Loading: Loading<3>.
* Testing: Testing<3>.
* Usage: Usage<2>.
* Excluding code from analysis: Excluding code from analysis<2>.
* Integration with the make tool::
* Caveats::
* Scanning Prolog modules::
* Scanning plain Prolog files::

debug_messages

* API documentation: API documentation<4>.
* Loading: Loading<4>.
* Testing: Testing<4>.
* Usage: Usage<3>.

debugger

* API documentation: API documentation<5>.
* Loading: Loading<5>.
* Testing: Testing<5>.
* Usage: Usage<4>.
* Alternative debugger tools::
* Known issues::

diagrams

* Requirements::
* API documentation: API documentation<6>.
* Loading: Loading<6>.
* Testing: Testing<6>.
* Supported diagrams::
* Graph elements::
* Supported graph languages::
* Customization::
* Linking diagrams::
* Creating diagrams for Prolog module applications::
* Creating diagrams for plain Prolog files::
* Other notes::

Requirements

* macOS - MacPorts: macOS - MacPorts<2>.
* macOS - Homebrew: macOS - Homebrew<2>.
* Windows - Chocolatey: Windows - Chocolatey<2>.
* Installers: Installers<2>.

doclet

* API documentation: API documentation<7>.
* Loading: Loading<7>.
* Automating running doclets::
* Integration with the make tool: Integration with the make tool<2>.

help

* Requirements: Requirements<2>.
* API documentation: API documentation<8>.
* Loading: Loading<8>.
* Testing: Testing<7>.
* Supported operating-systems::
* Usage: Usage<5>.
* Experimental features::
* Known issues: Known issues<2>.

issue_creator

* Requirements: Requirements<3>.
* Loading: Loading<9>.
* Usage: Usage<6>.
* Known issues: Known issues<3>.

lgtdoc

* Requirements: Requirements<4>.
* API documentation: API documentation<9>.
* Loading: Loading<10>.
* Testing: Testing<8>.
* Documenting source code::
* Generating documentation::
* Documentation linter checks::

lgtunit

* Main files::
* API documentation: API documentation<10>.
* Loading: Loading<11>.
* Testing: Testing<9>.
* Writing and running tests::
* Automating running tests::
* Parametric test objects::
* Test dialects::
* User-defined test dialects::
* QuickCheck::
* Skipping tests::
* Selecting tests::
* Checking test goal results::
* Testing local predicates::
* Testing non-deterministic predicates::
* Testing generators::
* Testing input/output predicates::
* Suppressing tested predicates output::
* Tests with timeout limits::
* Setup and cleanup goals::
* Test annotations::
* Test execution times and memory usage::
* Working with test data files::
* Flaky tests::
* Mocking::
* Debugging messages in tests::
* Debugging failed tests::
* Code coverage::
* Utility predicates::
* Exporting test results in xUnit XML format::
* Exporting test results in the TAP output format::
* Generating Allure reports::
* Exporting code coverage results in XML format::
* Automatically creating bug reports at issue trackers::
* Minimizing test results output::
* Help with warnings::
* Known issues: Known issues<4>.

linter

* Main linter checks::
* Help on linter warnings::
* Extending the linter::
* Linting Prolog modules::
* Linting plain Prolog files::

make

* API documentation: API documentation<11>.
* Help with warnings: Help with warnings<2>.
* Known issues: Known issues<5>.

packs

* Requirements: Requirements<5>.
* API documentation: API documentation<12>.
* Loading: Loading<12>.
* Testing: Testing<10>.
* Usage: Usage<7>.
* Registries and packs storage::
* Virtual environments::
* Registry specification::
* Registry handling::
* Registry development::
* Pack specification::
* Encrypted packs::
* Signed packs::
* Pack URLs and Single Sign-On::
* Multiple pack versions::
* Pack dependencies::
* Pack portability::
* Pack development::
* Pack handling::
* Pack documentation::
* Pinning registries and packs::
* Testing packs::
* Security considerations::
* Best practices::
* Installing Prolog packs::
* Help with warnings: Help with warnings<3>.
* Known issues: Known issues<6>.

ports_profiler

* API documentation: API documentation<13>.
* Loading: Loading<13>.
* Testing: Testing<11>.
* Compiling source files for port profiling::
* Generating profiling data::
* Printing profiling data reports::
* Interpreting profiling data::
* Profiling Prolog modules::
* Profiling plain Prolog code::
* Known issues: Known issues<7>.

profiler

* Loading: Loading<14>.
* Testing: Testing<12>.
* Supported backend Prolog compilers::
* Compiling source code for profiling::

tutor

* API documentation: API documentation<14>.
* Loading: Loading<15>.
* Usage: Usage<8>.

wrapper

* API documentation: API documentation<15>.
* Loading: Loading<16>.
* Workflows::
* Customization: Customization<2>.
* Current limitations::

Libraries

* Overview: Overview<2>.
* arbitrary::
* assignvars::
* base64::
* basic_types::
* cbor::
* core::
* coroutining::
* csv::
* dates::
* dependents::
* dictionaries::
* dif::
* edcg::
* events::
* expand_library_alias_paths::
* expecteds::
* format::
* genint::
* gensym::
* git::
* grammars::
* heaps::
* hierarchies::
* hook_flows::
* hook_objects::
* html::
* ids::
* intervals::
* java::
* json::
* json_lines::
* listing::
* logging::
* loops::
* meta::
* meta_compiler::
* mutations::
* nested_dictionaries::
* optionals::
* options::
* os::
* queues::
* random::
* reader::
* recorded_database::
* redis::
* sets::
* statistics::
* term_io::
* timeout::
* tsv::
* types::
* ulid::
* unicode_data::
* union_find::
* uuid::
* zippers::

Overview

* Library documentation::
* Loading libraries::
* Testing libraries::
* Credits::
* Other notes: Other notes<2>.

arbitrary

* API documentation: API documentation<16>.
* Loading: Loading<17>.
* Testing: Testing<13>.
* Pre-defined types::
* Usage: Usage<9>.
* Defining new generators and shrinkers::
* Scoped generators and shrinkers::
* Reproducing sequences of arbitrary terms::
* Default size of generated terms::
* Known issues: Known issues<8>.

assignvars

* API documentation: API documentation<17>.
* Loading: Loading<18>.
* Testing: Testing<14>.

base64

* API documentation: API documentation<18>.
* Loading: Loading<19>.
* Testing: Testing<15>.
* Encoding::
* Decoding::

basic_types

* API documentation: API documentation<19>.
* Loading: Loading<20>.
* Testing: Testing<16>.

cbor

* Representation::
* Encoding: Encoding<2>.
* Decoding: Decoding<2>.
* API documentation: API documentation<20>.
* Loading: Loading<21>.
* Testing: Testing<17>.

core

* API documentation: API documentation<21>.
* Loading: Loading<22>.
* Testing: Testing<18>.

coroutining

* API documentation: API documentation<22>.
* Loading: Loading<23>.
* Testing: Testing<19>.
* Usage: Usage<10>.

csv

* API documentation: API documentation<23>.
* Loading: Loading<24>.
* Testing: Testing<20>.
* Usage: Usage<11>.

dates

* API documentation: API documentation<24>.
* Loading: Loading<25>.

dependents

* API documentation: API documentation<25>.
* Loading: Loading<26>.

dictionaries

* API documentation: API documentation<26>.
* Loading: Loading<27>.
* Testing: Testing<21>.
* Usage: Usage<12>.
* Credits: Credits<2>.

dif

* API documentation: API documentation<27>.
* Loading: Loading<28>.
* Testing: Testing<22>.
* Usage: Usage<13>.

edcg

* API documentation: API documentation<28>.
* Loading: Loading<29>.
* Testing: Testing<23>.
* Usage: Usage<14>.
* Introduction::
* Syntax::
* Declaration of Predicates::
* Declaration of Accumulators::
* Declaration of Passed Arguments::
* Additional documentation::

events

* API documentation: API documentation<29>.
* Loading: Loading<30>.

expand_library_alias_paths

* API documentation: API documentation<30>.
* Loading: Loading<31>.
* Usage: Usage<15>.

expecteds

* API documentation: API documentation<31>.
* Loading: Loading<32>.
* Testing: Testing<24>.
* Usage: Usage<16>.
* See also::

format

* API documentation: API documentation<32>.
* Loading: Loading<33>.
* Testing: Testing<25>.
* Usage: Usage<17>.
* Portability: Portability<2>.

genint

* API documentation: API documentation<33>.
* Loading: Loading<34>.
* Testing: Testing<26>.
* Usage: Usage<18>.

gensym

* API documentation: API documentation<34>.
* Loading: Loading<35>.
* Testing: Testing<27>.
* Usage: Usage<19>.

git

* API documentation: API documentation<35>.
* Loading: Loading<36>.
* Testing: Testing<28>.
* Usage: Usage<20>.

grammars

* API documentation: API documentation<36>.
* Loading: Loading<37>.
* Testing: Testing<29>.
* Usage: Usage<21>.

heaps

* API documentation: API documentation<37>.
* Loading: Loading<38>.
* Testing: Testing<30>.
* Credits: Credits<3>.

hierarchies

* API documentation: API documentation<38>.
* Loading: Loading<39>.
* Testing: Testing<31>.

hook_flows

* API documentation: API documentation<39>.
* Loading: Loading<40>.
* Testing: Testing<32>.
* Usage: Usage<22>.

hook_objects

* API documentation: API documentation<40>.
* Loading: Loading<41>.
* Testing: Testing<33>.
* Usage: Usage<23>.

Usage

* Using the Prolog backend adapter file expansion rules::
* Restoring the default compiler expansion workflow::
* Preventing applying any (other) user-defined expansion rules: Preventing applying any other user-defined expansion rules.
* Expanding grammar rules into clauses independently of the compiler::
* Using the expansion rules defined in a Prolog module::
* Wrap the contents of a plain Prolog file as an object::
* Outputting term-expansion results to a stream or a file::
* Printing entity predicate goals before or after calling them::
* Suppressing goals::

html

* API documentation: API documentation<41>.
* Loading: Loading<42>.
* Testing: Testing<34>.
* Generating a HTML document::
* Generating a HTML fragment::
* Working with callbacks to generate content::
* Working with custom elements::

ids

* API documentation: API documentation<42>.
* Loading: Loading<43>.
* Testing: Testing<35>.
* Usage: Usage<24>.

intervals

* API documentation: API documentation<43>.
* Loading: Loading<44>.
* Testing: Testing<36>.

java

* API documentation: API documentation<44>.
* Loading: Loading<45>.
* Testing: Testing<37>.
* Usage: Usage<25>.
* Known issues: Known issues<9>.

json

* API documentation: API documentation<45>.
* Loading: Loading<46>.
* Testing: Testing<38>.
* Representation: Representation<2>.
* Encoding: Encoding<3>.
* Decoding: Decoding<3>.
* Known issues: Known issues<10>.

json_lines

* API documentation: API documentation<46>.
* Loading: Loading<47>.
* Testing: Testing<39>.
* Representation: Representation<3>.
* Encoding: Encoding<4>.
* Decoding: Decoding<4>.
* Known issues: Known issues<11>.

listing

* API documentation: API documentation<47>.
* Loading: Loading<48>.
* Testing: Testing<40>.
* Usage: Usage<26>.

logging

* API documentation: API documentation<48>.
* Loading: Loading<49>.

loops

* API documentation: API documentation<49>.
* Loading: Loading<50>.
* Testing: Testing<41>.
* Usage: Usage<27>.

meta

* API documentation: API documentation<50>.
* Loading: Loading<51>.
* Testing: Testing<42>.
* Usage: Usage<28>.

meta_compiler

* API documentation: API documentation<51>.
* Loading: Loading<52>.
* Testing: Testing<43>.
* Usage: Usage<29>.
* Known issues: Known issues<12>.

mutations

* API documentation: API documentation<52>.
* Loading: Loading<53>.
* Testing: Testing<44>.
* Usage: Usage<30>.

nested_dictionaries

* API documentation: API documentation<53>.
* Loading: Loading<54>.
* Testing: Testing<45>.
* Usage: Usage<31>.
* Curly term representation::

optionals

* API documentation: API documentation<54>.
* Loading: Loading<55>.
* Testing: Testing<46>.
* Usage: Usage<32>.
* See also: See also<2>.

options

* API documentation: API documentation<55>.
* Loading: Loading<56>.
* Testing: Testing<47>.
* Usage: Usage<33>.

os

* API documentation: API documentation<56>.
* Loading: Loading<57>.
* Testing: Testing<48>.
* Known issues: Known issues<13>.

queues

* API documentation: API documentation<57>.
* Loading: Loading<58>.
* Testing: Testing<49>.
* Usage: Usage<34>.

random

* API documentation: API documentation<58>.
* Loading: Loading<59>.
* Testing: Testing<50>.
* Usage: Usage<35>.

reader

* API documentation: API documentation<59>.
* Loading: Loading<60>.
* Testing: Testing<51>.

recorded_database

* API documentation: API documentation<60>.
* Loading: Loading<61>.
* Testing: Testing<52>.
* Usage: Usage<36>.
* Known issues: Known issues<14>.

redis

* API documentation: API documentation<61>.
* Loading: Loading<62>.
* Testing: Testing<53>.
* Credits: Credits<4>.
* Known issues: Known issues<15>.

sets

* API documentation: API documentation<62>.
* Loading: Loading<63>.
* Testing: Testing<54>.
* Usage: Usage<37>.
* Credits: Credits<5>.

statistics

* API documentation: API documentation<63>.
* Loading: Loading<64>.
* Testing: Testing<55>.

term_io

* API documentation: API documentation<64>.
* Loading: Loading<65>.
* Testing: Testing<56>.

timeout

* API documentation: API documentation<65>.
* Loading: Loading<66>.
* Testing: Testing<57>.
* Known issues: Known issues<16>.

tsv

* API documentation: API documentation<66>.
* Loading: Loading<67>.
* Testing: Testing<58>.
* Usage: Usage<38>.

types

* API documentation: API documentation<67>.
* Loading: Loading<68>.
* Testing: Testing<59>.
* Type-checking: Type-checking<2>.
* Defining new types::
* Examples: Examples<166>.

ulid

* API documentation: API documentation<68>.
* Loading: Loading<69>.
* Testing: Testing<60>.
* Generating ULIDs::
* Type-checking ULIDs::

unicode_data

* Authors::
* License::
* Website::
* Description: Description<165>.
* Requirements: Requirements<6>.
* Usage: Usage<39>.
* Known issues: Known issues<17>.
* Acknowledgements::
* Files and API Summary::

Files and API Summary

* unicode_arabic_shaping.pl: unicode_arabic_shaping pl.
* unicode_bidi_mirroring.pl: unicode_bidi_mirroring pl.
* unicode_blocks.pl: unicode_blocks pl.
* unicode_case_folding.pl: unicode_case_folding pl.
* unicode_categories.pl: unicode_categories pl.
* unicode_cjk_radicals.pl: unicode_cjk_radicals pl.
* unicode_composition_exclusions.pl: unicode_composition_exclusions pl.
* unicode_core_properties.pl: unicode_core_properties pl.
* unicode_decomposition_type.pl: unicode_decomposition_type pl.
* unicode_derived_age.pl: unicode_derived_age pl.
* unicode_derived_bidi_class.pl: unicode_derived_bidi_class pl.
* unicode_derived_combining_class.pl: unicode_derived_combining_class pl.
* unicode_derived_core_properties.pl: unicode_derived_core_properties pl.
* unicode_derived_decomposition_type.pl: unicode_derived_decomposition_type pl.
* unicode_derived_east_asian_width.pl: unicode_derived_east_asian_width pl.
* unicode_derived_joining_group.pl: unicode_derived_joining_group pl.
* unicode_derived_joining_type.pl: unicode_derived_joining_type pl.
* unicode_derived_line_break.pl: unicode_derived_line_break pl.
* unicode_derived_normalization_props.pl: unicode_derived_normalization_props pl.
* unicode_derived_numeric_type.pl: unicode_derived_numeric_type pl.
* unicode_derived_numeric_values.pl: unicode_derived_numeric_values pl.
* unicode_hangul_syllable_type.pl: unicode_hangul_syllable_type pl.
* unicode_indic_matra_category.pl: unicode_indic_matra_category pl.
* unicode_indic_syllabic_category.pl: unicode_indic_syllabic_category pl.
* unicode_jamo.pl: unicode_jamo pl.
* unicode_name_aliases.pl: unicode_name_aliases pl.
* unicode_names.pl: unicode_names pl.
* unicode_prop_list.pl: unicode_prop_list pl.
* unicode_range_scripts.pl: unicode_range_scripts pl.
* unicode_script_extensions.pl: unicode_script_extensions pl.
* unicode_scripts.pl: unicode_scripts pl.
* unicode_special_casing.pl: unicode_special_casing pl.
* unicode_unihan_variants.pl: unicode_unihan_variants pl.
* unicode_version.pl: unicode_version pl.

union_find

* API documentation: API documentation<69>.
* Loading: Loading<70>.
* Testing: Testing<61>.
* Usage: Usage<40>.

uuid

* API documentation: API documentation<70>.
* Loading: Loading<71>.
* Testing: Testing<62>.
* Generating version 1 UUIDs::
* Generating version 4 UUIDs::
* Generating the null UUID::

zippers

* API documentation: API documentation<71>.
* Loading: Loading<72>.
* Testing: Testing<63>.

Ports

* fcube::
* metagol::
* toychr::

fcube

* API documentation: API documentation<72>.
* Loading: Loading<73>.
* Testing: Testing<64>.

metagol

* API documentation: API documentation<73>.
* Loading: Loading<74>.
* Testing: Testing<65>.

toychr

* API documentation: API documentation<74>.
* Loading: Loading<75>.
* Testing: Testing<66>.

Contributions

* flags::
* iso8601::
* pddl_parser::
* verdi_neruda::
* xml_parser::

flags

* API documentation: API documentation<75>.
* Loading: Loading<76>.
* Testing: Testing<67>.

iso8601

* API documentation: API documentation<76>.
* Loading: Loading<77>.
* Testing: Testing<68>.

pddl_parser

* API documentation: API documentation<77>.
* Loading: Loading<78>.
* Testing: Testing<69>.

xml_parser

* API documentation: API documentation<78>.
* Loading: Loading<79>.
* Testing: Testing<70>.
* Known issues: Known issues<18>.


File: TheLogtalkHandbook-3.96.0.info,  Node: User Manual,  Next: Reference Manual,  Prev: Top,  Up: Top

1 User Manual
*************

* Menu:

* Declarative object-oriented programming::
* Main features::
* Nomenclature::
* Messages::
* Objects::
* Protocols::
* Categories::
* Predicates::
* Inheritance::
* Event-driven programming::
* Multi-threading programming::
* Error handling::
* Reflection::
* Writing and running applications::
* Printing messages and asking questions::
* Term and goal expansion::
* Documenting::
* Debugging::
* Performance: Performance<2>.
* Installing Logtalk::
* Prolog integration and migration::


File: TheLogtalkHandbook-3.96.0.info,  Node: Declarative object-oriented programming,  Next: Main features,  Up: User Manual

1.1 Declarative object-oriented programming
===========================================

Logtalk is a 'declarative object-oriented logic programming language'.
This means that Logtalk shares key concepts with other object-oriented
programming languages but abstracts and reinterprets these concepts in
the context of declarative logic programming.

The key concepts in 'declarative' object-oriented programming are
'encapsulation' and 'reuse patterns'.  Notably, the concept of 'mutable
state', which is an 'imperative' concept, is not a significant concept
in 'declarative' object-oriented programming.  Declarative
object-oriented programming concepts can be materialized in both logic
and functional languages.  In this section, we focus only on declarative
object-oriented logic programming.

The first key generalization of object-oriented programming concepts is
the concept of 'object' itself.  What an object encapsulates depends on
the 'base programming paradigm' where we apply object-oriented
programming concepts.  When these concepts are applied to an imperative
language, where mutable state and destructive assignment are central,
objects naturally encapsulate and abstract mutable state, providing
disciplined access and modification.  When these concepts are applied to
a declarative logic language such as Prolog, objects naturally
encapsulate predicates.  Therefore, an object can be seen as a 'theory',
expressed by a set of related predicates.  Theories are usually static,
and thus Logtalk objects are static by default.  This contrasts with
imperative object-oriented languages where usually classes are static
and objects are dynamic.  This view of an object as a set of predicates
also forgoes a distinction between 'data' and 'procedures' that is
central to imperative object-oriented languages but moot in declarative,
*note homoiconic: 7. logic languages.

The second key generalization concerns the relation between objects and
other entities such as protocols (interfaces) and ancestor objects.  The
idea is that entity relations define 'reuse patterns' and the 'roles'
played by the participating entities.  A common reuse pattern is
'inheritance'.  In this case, an entity inherits, and thus reuses,
resources from an ancestor entity.  In a reuse pattern, each
participating entity plays a specific 'role'.  The same entity, however,
can play multiple roles depending on its relations with other entities.
For example, an object can play the role of a class for its instances,
the role of a subclass for its superclasses, and the role of an instance
for its metaclass.  Another common reuse pattern is 'protocol
implementation'.  In this case, an object implementing a protocol reuses
its predicate declarations by providing an implementation for those
predicates and exposing those predicates to its clients.  An essential
consequence of this generalization is that protocols, objects, and
categories are first-class entities, while e.g.  'prototype', 'parent',
'class', 'instance', 'metaclass', 'subclass', 'superclass', or
'ancestor' are just 'roles' that an object can play.  When sending a
message to an object, the corresponding predicate 'declaration' and
predicate 'definition' lookup procedures (reuse patterns) depend on the
role or roles that the object plays (see the *note Inheritance: 8.
section for details).  Another consequence of this generalization is
that a language can provide multiple reuse patterns instead of selecting
a set of patterns and supporting this set as a design choice that
excludes other reuse patterns.  For example, most imperative
object-oriented languages are either class-based or prototype-based.  In
contrast, Logtalk supports both classes and prototypes by providing the
corresponding reuse patterns using objects as first-class entities
capable of playing multiple roles.


File: TheLogtalkHandbook-3.96.0.info,  Node: Main features,  Next: Nomenclature,  Prev: Declarative object-oriented programming,  Up: User Manual

1.2 Main features
=================

Several years ago, I decided that the best way to learn object-oriented
programming was to build my own object-oriented language.  Prolog being
always my favorite language, I chose to extend it with object-oriented
capabilities.  Strong motivation also comes from my frustration with
Prolog shortcomings for writing large applications.  Eventually this
work led to the Logtalk programming language as we know it today.  The
first system to use the name Logtalk appeared in February 1995.  At that
time, Logtalk was mainly an experiment in computational reflection with
a rudimentary runtime and no compiler.  Based on feedback by users and
on the author’s subsequent work, the name was retained and Logtalk was
created as a full programming language focusing on using object-oriented
concepts for code encapsulation and reuse.  Development started in
January 1998 with the first public alpha version released in July 1998.
The first stable release (2.0) was published in February 1999.
Development of the third generation of Logtalk started in 2012 with the
first public alpha version in August 2012 and the first stable release
(3.0.0) in January 2015.

Logtalk provides the following features:

* Menu:

* Integration of logic and object-oriented programming::
* Integration of event-driven and object-oriented programming::
* Support for component-based programming::
* Support for both prototype and class-based systems::
* Support for multiple object hierarchies::
* Separation between interface and implementation::
* Private, protected and public inheritance: Private protected and public inheritance.
* Private, protected and public object predicates: Private protected and public object predicates.
* Parametric objects::
* High level multi-threading programming support::
* Smooth learning curve::
* Compatibility with most Prolog systems and the ISO standard::
* Performance::
* Logtalk scope::


File: TheLogtalkHandbook-3.96.0.info,  Node: Integration of logic and object-oriented programming,  Next: Integration of event-driven and object-oriented programming,  Up: Main features

1.2.1 Integration of logic and object-oriented programming
----------------------------------------------------------

     Logtalk tries to bring together the main advantages of these two
     programming paradigms.  On one hand, the object orientation allows
     us to work with the same set of entities in the successive phases
     of application development, giving us a way of organizing and
     encapsulating the knowledge of each entity within a given domain.
     On the other hand, logic programming allows us to represent, in a
     declarative way, the knowledge we have of each entity.  Together,
     these two advantages allow us to minimize the distance between an
     application and its problem domain, making the writing and
     maintenance of programming easier and more productive.

     From a pragmatic perspective, Logtalk objects provide Prolog with
     the possibility of defining several namespaces, instead of the
     traditional Prolog single database, addressing some of the needs of
     large software projects.


File: TheLogtalkHandbook-3.96.0.info,  Node: Integration of event-driven and object-oriented programming,  Next: Support for component-based programming,  Prev: Integration of logic and object-oriented programming,  Up: Main features

1.2.2 Integration of event-driven and object-oriented programming
-----------------------------------------------------------------

     Event-driven programming enables the building of reactive systems,
     where computing which takes place at each moment is a result of the
     observation of occurring events.  This integration complements
     object-oriented programming, in which each computing is initiated
     by the explicit sending of a message to an object.  The user
     dynamically defines what events are to be observed and establishes
     monitors for these events.  This is especially useful when
     representing relationships between objects that imply constraints
     in the state of participating objects *note [Rumbaugh87]: 10, *note
     [Rumbaugh88]: 11, *note [Fornarino_et_al_89]: 12, *note [Razek92]:
     13.  Other common uses are reflective applications like code
     debugging or profiling *note [Maes87]: 14.  Predicates can be
     implicitly called when a spied event occurs, allowing programming
     solutions which minimize object coupling.  In addition, events
     provide support for behavioral reflection and can be used to
     implement the concepts of 'pointcut' and 'advice' found in
     Aspect-Oriented Programming.


File: TheLogtalkHandbook-3.96.0.info,  Node: Support for component-based programming,  Next: Support for both prototype and class-based systems,  Prev: Integration of event-driven and object-oriented programming,  Up: Main features

1.2.3 Support for component-based programming
---------------------------------------------

     Predicates can be encapsulated inside 'categories' which can be
     imported by any object, without any code duplication and
     irrespective of object hierarchies.  A category is a first-class
     encapsulation entity, at the same level as objects and protocols,
     which can be used as a component when building new objects.  Thus,
     objects may be defined through composition of categories, which act
     as fine-grained units of code reuse.  Categories may also extend
     existing objects.  Categories can be used to implement 'mixins' and
     'aspects'.  Categories allow for code reuse between unrelated
     objects, independent of hierarchy relations, in the same vein as
     protocols allow for interface reuse.


File: TheLogtalkHandbook-3.96.0.info,  Node: Support for both prototype and class-based systems,  Next: Support for multiple object hierarchies,  Prev: Support for component-based programming,  Up: Main features

1.2.4 Support for both prototype and class-based systems
--------------------------------------------------------

     Almost any (if not all) object-oriented languages available today
     are either class-based or prototype-based *note [Lieberman86]: 19,
     with a strong predominance of class-based languages.  Logtalk
     provides support for both hierarchy types.  That is, we can have
     both prototype and class hierarchies in the same application.
     Prototypes solve a problem of class-based systems where we
     sometimes have to define a class that will have only one instance
     in order to reuse a piece of code.  Classes solve a dual problem in
     prototype based systems where it is not possible to encapsulate
     some code to be reused by other objects but not by the
     encapsulating object.  Stand-alone objects, that is, objects that
     do not belong to any hierarchy, are a convenient solution to
     encapsulate code that will be reused by several unrelated objects.


File: TheLogtalkHandbook-3.96.0.info,  Node: Support for multiple object hierarchies,  Next: Separation between interface and implementation,  Prev: Support for both prototype and class-based systems,  Up: Main features

1.2.5 Support for multiple object hierarchies
---------------------------------------------

     Languages like Smalltalk-80 *note [Goldberg83]: 1c, Objective-C
     *note [Cox86]: 1d. and Java *note [Joy_et_al_00]: 1e. define a
     single hierarchy rooted in a class usually named ‘Object’.  This
     makes it easy to ensure that all objects share a common behavior
     but also tends to result in lengthy hierarchies where it is
     difficult to express objects which represent exceptions to default
     behavior.  In Logtalk we can have multiple, independent, object
     hierarchies.  Some of them can be prototype-based while others can
     be class-based.  Furthermore, stand-alone objects provide a simple
     way to encapsulate utility predicates that do not need or fit in an
     object hierarchy.


File: TheLogtalkHandbook-3.96.0.info,  Node: Separation between interface and implementation,  Next: Private protected and public inheritance,  Prev: Support for multiple object hierarchies,  Up: Main features

1.2.6 Separation between interface and implementation
-----------------------------------------------------

     This is an expected (should we say standard ?)  feature of almost
     any modern programming language.  Logtalk provides support for
     separating interface from implementation in a flexible way:
     predicate directives can be contained in an object, a category or a
     protocol (first-order entities in Logtalk) or can be spread in both
     objects, categories and protocols.


File: TheLogtalkHandbook-3.96.0.info,  Node: Private protected and public inheritance,  Next: Private protected and public object predicates,  Prev: Separation between interface and implementation,  Up: Main features

1.2.7 Private, protected and public inheritance
-----------------------------------------------

     Logtalk supports private, protected and public inheritance in a
     similar way to C++ *note [Stroustrup86]: 23, enabling us to
     restrict the scope of inherited, imported or implemented predicates
     (by default inheritance is public).


File: TheLogtalkHandbook-3.96.0.info,  Node: Private protected and public object predicates,  Next: Parametric objects,  Prev: Private protected and public inheritance,  Up: Main features

1.2.8 Private, protected and public object predicates
-----------------------------------------------------

     Logtalk supports data hiding by implementing private, protected and
     public object predicates in a way similar to C++ *note
     [Stroustrup86]: 23.  Private predicates can only be called from the
     container object.  Protected predicates can be called by the
     container object or by the container descendants.  Public
     predicates can be called from any object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Parametric objects,  Next: High level multi-threading programming support,  Prev: Private protected and public object predicates,  Up: Main features

1.2.9 Parametric objects
------------------------

     Object names can be compound terms (instead of atoms), providing a
     way to parameterize object predicates.  Parametric objects are
     implemented in a similar way to ‘L&O’ *note [McCabe92]: 28, ‘OL(P)’
     *note [Fromherz93]: 29. or ‘SICStus Objects’ *note [SICStus95]: 2a.
     (however, access to parameter values is done via a built-in method
     instead of making the parameters scope global over the whole
     object).  Parametric objects allows us to treat any predicate
     clause as defining an 'instantiation' of a parametric object.
     Thus, a parametric object allows us to encapsulate and associate
     any number of predicates with a compound term.


File: TheLogtalkHandbook-3.96.0.info,  Node: High level multi-threading programming support,  Next: Smooth learning curve,  Prev: Parametric objects,  Up: Main features

1.2.10 High level multi-threading programming support
-----------------------------------------------------

     High level multi-threading programming is available when running
     Logtalk with selected backend Prolog compilers, allowing objects to
     support both synchronous and asynchronous messages.  Logtalk allows
     programmers to take advantage of modern multi-processor and
     multi-core computers without bothering with the details of creating
     and destroying threads, implement thread communication, or
     synchronizing threads.


File: TheLogtalkHandbook-3.96.0.info,  Node: Smooth learning curve,  Next: Compatibility with most Prolog systems and the ISO standard,  Prev: High level multi-threading programming support,  Up: Main features

1.2.11 Smooth learning curve
----------------------------

     Logtalk has a smooth learning curve, by adopting standard Prolog
     syntax and by enabling an incremental learning and use of most of
     its features.


File: TheLogtalkHandbook-3.96.0.info,  Node: Compatibility with most Prolog systems and the ISO standard,  Next: Performance,  Prev: Smooth learning curve,  Up: Main features

1.2.12 Compatibility with most Prolog systems and the ISO standard
------------------------------------------------------------------

     The Logtalk system has been designed to be compatible with most
     Prolog compilers and, in particular, with the ISO Prolog standard
     *note [ISO95]: 31.  It runs in almost any computer system with a
     modern Prolog compiler.


File: TheLogtalkHandbook-3.96.0.info,  Node: Performance,  Next: Logtalk scope,  Prev: Compatibility with most Prolog systems and the ISO standard,  Up: Main features

1.2.13 Performance
------------------

     The current Logtalk implementation works as a trans-compiler:
     Logtalk source files are first compiled to Prolog source files,
     which are then compiled by the chosen Prolog compiler.  Therefore,
     Logtalk performance necessarily depends on the *note backend Prolog
     compiler: 34.  The Logtalk compiler preserves the programmers
     choices when writing efficient code that takes advantage of tail
     recursion and first-argument indexing.

     As an object-oriented language, Logtalk can use both *note static
     binding: 35. and *note dynamic binding: 36. for matching messages
     and methods.  Furthermore, Logtalk entities (objects, protocols,
     and categories) are independently compiled, allowing for a very
     flexible programming development.  Entities can be edited,
     compiled, and loaded at runtime, without necessarily implying
     recompilation of all related entities.

     When dynamic binding is used, the Logtalk runtime engine implements
     caching of *note message lookups: 37. (including messages to 'self'
     and 'super' calls), ensuring a performance level close to what
     could be achieved when using static binding.

     For more detailed information on performance, see its dedicated
     *note section: 38.


File: TheLogtalkHandbook-3.96.0.info,  Node: Logtalk scope,  Prev: Performance,  Up: Main features

1.2.14 Logtalk scope
--------------------

Logtalk, being a superset of Prolog, shares with it the same preferred
areas of application but also extends them with those areas where
object-oriented features provide an advantage compared to plain Prolog.
Among these areas we have:

'Logic and object-oriented programming teaching and researching'

     Logtalk smooth learning curve, combined with support for both
     prototype and class-based programming, protocols, components or
     aspects via category-based composition, and other advanced
     object-oriented features allow a smooth introduction to
     object-oriented programming to people with a background in Prolog
     programming.  The distribution of Logtalk source code using an
     open-source license provides a framework for people to learn and
     then modify to try out new ideas on object-oriented programming
     research.  In addition, the Logtalk distribution includes plenty of
     programming examples that can be used in the classroom for teaching
     logic and object-oriented programming concepts.

'Structured knowledge representations and knowledge-based systems'

     Logtalk objects, coupled with event-driven programming features,
     enable easy implementation of frame-like systems and similar
     structured knowledge representations.

'Blackboard systems, agent-based systems, and systems with complex object relationships'

     Logtalk support for event-driven programming can provide a basis
     for the dynamic and reactive nature of blackboard type
     applications.

'Highly portable applications'

     Logtalk is compatible with most modern Prolog systems that support
     official and de facto standards.  Used as a way to provide Prolog
     with namespaces, it avoids the porting problems of most Prolog
     module systems.  Platform, operating system, or compiler specific
     code can be isolated from the rest of the code by encapsulating it
     in objects with well-defined interfaces.

'Alternative to a Prolog module system'

     Logtalk can be used as an alternative to a Prolog compiler module
     system.  Most Prolog applications that use modules can be converted
     into Logtalk applications, improving portability across Prolog
     systems and taking advantage of the stronger encapsulation and
     reuse framework provided by Logtalk object-oriented features.

'Integration with other programming languages'

     Logtalk support for most key object-oriented features helps users
     integrating Prolog with object-oriented languages like C++, Java,
     or Smalltalk by facilitating a high-level mapping between the two
     languages.


File: TheLogtalkHandbook-3.96.0.info,  Node: Nomenclature,  Next: Messages,  Prev: Main features,  Up: User Manual

1.3 Nomenclature
================

Depending on your logic programming and object-oriented programming
background (or lack of it), you may find Logtalk nomenclature either
familiar or at odds with the terms used in other languages.  In
addition, being a superset of Prolog, terms such as 'predicate' and
'method' are often used interchangeably.  Logtalk inherits most of its
nomenclature from Prolog and Smalltalk.

Note that the same terms can have different meanings in different
languages.  A good example is 'class'.  The support for meta-classes in
e.g.  Smalltalk translates to a concept of class that is different in
key aspects from the concept of class in e.g.  Java or C++.  Other terms
that can have different meanings are 'delegation' and 'forwarding'.
There are also cases where the same concept is found under different
names in some languages (e.g., 'self' and 'this') but that can also mean
different concepts in Logtalk and other languages.  Always be aware of
these differences and be cautious with assumptions carried from other
programming languages.

In this section, we map nomenclatures from Prolog and popular OOP
languages such as Smalltalk, C++, Java, and Python to the Logtalk
nomenclature.  The Logtalk distribution includes several examples of how
to implement common concepts found in other languages, complementing the
information in this section.  This Handbook also features a *note Prolog
interoperability section: 3e. and an extensive *note glossary: 3f.
providing the exact meaning of the names commonly used in Logtalk
programming.

* Menu:

* Prolog nomenclature::
* Smalltalk nomenclature::
* C++ nomenclature::
* Java nomenclature::
* Python nomenclature::


File: TheLogtalkHandbook-3.96.0.info,  Node: Prolog nomenclature,  Next: Smalltalk nomenclature,  Up: Nomenclature

1.3.1 Prolog nomenclature
-------------------------

Being a superset of Prolog, Logtalk inherits its nomenclature.  But
Logtalk also aims to fix several Prolog shortcomings, thus introducing
new concepts and refining existing Prolog concepts.  Logtalk
object-oriented nature also introduces names and concepts that are not
common when discussing logic programming semantics.  We mention here the
most relevant ones, notably those where semantics or common practice
differ.  Further details can be found elsewhere in this Handbook.

'arbitrary goals as directives'

     Although not ISO Prolog Core standard compliant, several Prolog
     systems accept using arbitrary goal as directives.  This is not
     supported in Logtalk source files.  Always use an *note
     initialization/1: 42. directive to wrap those goals.  This ensures
     that any initialization goals, which often have side-effects, are
     only called if the source file is successfully compiled and loaded.

'calling a predicate'

     Sending a *note message: 43. to an object is similar to 'calling a
     goal' with the difference that the actual predicate that is called
     is determined not just by the message 'term' but also by the object
     receiving the message and possibly its ancestors.  This is also
     different from calling a Prolog module predicate: a message may
     result e.g.  in calling a predicate *note inherited: 44. by the
     object but calling a module predicate requires the predicate to
     exist in (or be reexported by) the module.

'closed-world assumption semantics'

     Logtalk provides clear closed-world assumption semantics: messages
     or calls for declared but undefined predicates fail.  Messages or
     calls for unknown (i.e., not declared) predicates throw an error.
     Crucially, this semantics applies to both 'static' and 'dynamic'
     predicates.  But in Prolog workarounds are required to have a
     static predicate being known by the runtime without it being also
     defined (so that calling it would fail instead of throwing a
     predicate existence error).

'compiling and loading source files'

     Logtalk provides its own built-in predicates for *note compiling
     and loading: 45. source files.  It also provides convenient
     top-level interpreter *note shorthands: 46. for these and other
     frequent operations.  In general, the traditional Prolog built-in
     predicates and top-level interpreter shorthands cannot be used to
     load Logtalk source files.

'debugging'

     In most (if not all) Prolog systems, debugging support is a
     built-in feature made available using a set of built-in predicates
     like ‘trace/0’ and ‘spy/1’.  But in Logtalk the *note default
     debugger: 47. is a regular application, implemented using a public
     *note reflection API: 48.  This means that the debugger must be
     explicitly loaded (either automatically from a *note settings file:
     49. at startup or from the top-level).  It also means that the
     debugger can be easily extended or replaced by an alternative
     application.

'directive operators'

     Some Prolog systems declare directive names as operators (e.g.,
     ‘dynamic’, ‘multifile’, …).  This is not required by the ISO Prolog
     Core standard.  It’s a practice that should be avoided as it makes
     code non-portable.

'encapsulation'

     Logtalk enforces encapsulation of object predicates, generating a
     permission error when a predicate is not within the scope of the
     caller.  In contrast, most Prolog module systems allow any module
     predicate to be called by using explicit qualification, even if not
     exported.  Worse, some Prolog systems also allow defining clauses
     for a module predicate outside the module, without declaring the
     predicate as multifile, by simply writing clauses with explicit
     module-qualified heads.

'entity loading'

     When using Prolog modules, ‘use_module/1-2’ (or equivalent)
     directives both load the module files and declare that the
     (implicitly or explicitly) imported predicates can be used with
     implicit module qualification.  But Logtalk separates entity
     (object, protocol, category, or module) predicate 'usage'
     declarations (via *note uses/1: 4a. and *note uses/2: 4b. or its
     own *note use_module/1: 4c. and *note use_module/2: 4d. directives)
     from 'loading' goals (using the *note logtalk_load/1: 46. and *note
     logtalk_load/2: 4e. predicates), called using an explicit and
     disciplined approach from *note loader files: 4f.

'flags scope'

     The *note set_logtalk_flag/2: 50. 'directive' is always local to
     the entity or source file that contains it.  Only calls to the
     *note set_logtalk_flag/2: 51. 'predicate' set the global default
     value for a flag.  This distinction is lacking in Prolog (where
     directives usually have a global scope) and Prolog modules (where
     some flags are local to modules in some systems and global in other
     systems).

'meta-predicate call semantics'

     Logtalk provides consistent *note meta-predicate: 52. call
     semantics: meta-arguments are always called in the meta-predicate
     calling context.  This contrasts with Prolog module meta-predicates
     where the semantics of implicitly qualified calls are different
     from explicitly qualified calls.

'operators scope'

     Operators declared inside an entity (object, protocol, or category)
     are local to the entity.  But operators defined in a source file
     but outside an entity are global for compatibility with existing
     Prolog code.

'predicates scope'

     In plain Prolog, all predicates are visible.  In a Prolog module, a
     predicate can be exported or local.  In Logtalk, a predicate can be
     *note public: 53, *note protected: 54, *note private: 55, or *note
     local: 56.

'predicate declaration'

     Logtalk provides a clear distinction between *note declaring: 57. a
     predicate and *note defining: 58. a predicate.  This is a
     fundamental requirement for the concept of *note protocol: 59. (aka
     interface) in Logtalk: we must be able to 'declare' a predicate
     without necessarily 'defining' it.  This clear distinction is
     missing in Prolog and Prolog modules.  Notably, it’s a compiler
     error for a module to try to export a predicate that it does not
     define.

'predicate loading conflicts'

     Logtalk does not use predicate import/export semantics.  Thus,
     there are never conflicts when loading entities (objects,
     protocols, or categories) that declare the same public predicates.
     But attempting to load two Prolog modules that export the same
     predicate results in a conflict, usually a compilation error (this
     is especially problematic when the ‘use_module/1’ directive is
     used; e.g.  adding a new exported predicate can break applications
     that use the module but not the new predicate).


File: TheLogtalkHandbook-3.96.0.info,  Node: Smalltalk nomenclature,  Next: C++ nomenclature,  Prev: Prolog nomenclature,  Up: Nomenclature

1.3.2 Smalltalk nomenclature
----------------------------

The Logtalk name originates from a combination of the Prolog and
Smalltalk names.  Smalltalk had a significant influence on the design of
Logtalk and thus inherits some of its ideas and nomenclature.  The
following list relates the most commonly used Smalltalk terms with their
Logtalk counterparts.

'abstract class'

     Similar to Smalltalk, an abstract class is just a class not meant
     to be instantiated by not understanding a message to create
     instances.

'assignment statement'

     Logtalk, as a superset of Prolog, uses 'logic variables' and
     'unification' and thus provides no equivalent to the Smalltalk
     assignment statement.

'block'

     Logtalk supports lambda expressions and meta-predicates, which can
     be used to provide similar functionality to Smalltalk blocks.

'class'

     In Logtalk, 'class' is a just a 'role' that an object can play.
     This is similar to Smalltalk, where classes are also objects.

'class method'

     Class methods in Logtalk are simply instance methods declared and
     defined in the class metaclass.

'class variable'

     Logtalk objects, which can play the roles of class and instance,
     encapsulate predicates, not state.  Class variables, which in
     Smalltalk are really shared instance variables, can be emulated in
     a class by defining a predicate locally instead of defining it in
     the class instances.

'inheritance'

     While Smalltalk only supports single inheritance, Logtalk supports
     single inheritance, multiple inheritance, and multiple
     instantiation.

'instance'

     While in Smalltalk every object is an 'instance' of some class,
     objects in Logtalk can play different roles, including the role of
     a prototype where the concepts of instance and class don’t apply.
     Moreover, instances can be either created dynamically or defined
     statically.

'instance method'

     Instance methods in Logtalk are simply predicates declared and
     defined in a class and thus inherited by the class instances.

'instance variable'

     Logtalk being a 'declarative' language, objects encapsulate a set
     of predicates instead of encapsulating 'state'.  But different
     objects may provide different definitions of the same predicates.
     Mutable internal state as in Smalltalk can be emulated by using
     dynamic predicates.

'message'

     Similar to Smalltalk, a 'message' is a request for an operation,
     which is interpreted in Logtalk as a logic query, asking for the
     construction of a proof that something is true.

'message selector'

     Logtalk uses the predicate template (i.e., the predicate callable
     term with all its arguments unbound) as a message selector.  The
     actual type of the message arguments is not considered.  Like
     Smalltalk, Logtalk uses 'single dispatch' on the message receiver.

'metaclass'

     Metaclasses are optional in Logtalk (except for a root class) and
     can be shared by several classes.  When metaclasses are used,
     infinite regression is simply avoided by making a class an instance
     of itself.

'method'

     Same as in Smalltalk, a 'method' is the actual code (i.e.,
     predicate definition) that is run to answer a message.  Logtalk
     uses the words 'method' and 'predicate' interchangeably.

'method categories'

     There is no support in Logtalk for partitioning the methods of an
     object into different categories.  The Logtalk concept of
     'category' (a first-class entity) was, however, partially inspired
     by Smalltalk method categories.

'object'

     Unlike Smalltalk, where 'everything' is an object, Logtalk language
     constructs include both 'terms' (as in Prolog representing e.g.
     numbers and structures) and three first-class entities: objects,
     protocols, and categories.

'pool variables*'

     Logtalk, as a superset of Prolog, uses 'predicates' with no
     distinction between 'variables' and 'methods'.  Categories can be
     used to share a set of predicate definitions between any number of
     objects.

'protocol'

     In Smalltalk, an object 'protocol' is the set of messages it
     understands.  The same concept applies in Logtalk.  But Logtalk
     also supports protocols as first-class entities where a protocol
     can be implemented by multiple objects and an object can implement
     multiple protocols.

'self'

     Logtalk uses the same definition of 'self' found in Smalltalk: the
     object that received the message being processed.  Note, however,
     that 'self' is not a keyword in Logtalk but is implicit in the
     *note (;;)/1: 5c. message to 'self' control construct.

'subclass'

     Same definition in Logtalk.

'super'

     As in Smalltalk, the idea of 'super' is to allow calling an
     inherited predicate (that is usually being redefined).  Note,
     however, that 'super' is not a keyword in Logtalk, which provides
     instead a *note (^^)/1: 5d. 'super' call control construct.

'superclass'

     Same definition in Logtalk.  But while in Smalltalk a class can
     only have a single superclass, Logtalk support for multiple
     inheritance allows a class to have multiple superclasses.


File: TheLogtalkHandbook-3.96.0.info,  Node: C++ nomenclature,  Next: Java nomenclature,  Prev: Smalltalk nomenclature,  Up: Nomenclature

1.3.3 C++ nomenclature
----------------------

There are several C++ glossaries available on the Internet.  The list
that follows relates the most commonly used C++ terms with their Logtalk
equivalents.

'abstract class'

     Logtalk uses an 'operational' definition of abstract class: any
     class that does not inherit a method for creating new instances can
     be considered an abstract class.  Moreover, Logtalk supports *note
     interfaces/protocols: 59, which are often a better way to provide
     the functionality of C++ abstract classes.

'base class'

     Logtalk uses the term *note superclass: 60. with the same meaning.

'data member'

     Logtalk uses *note predicates: 61. for representing both behavior
     and data.

'constructor function'

     There are no special methods for creating new objects in Logtalk.
     Instead, Logtalk provides a built-in predicate, *note
     create_object/4: 62, which can be used as a building block to
     define more sophisticated object creation predicates.

'derived class'

     Logtalk uses the term *note subclass: 63. with the same meaning.

'destructor function'

     There are no special methods for deleting new objects in Logtalk.
     Instead, Logtalk provides a built-in predicate, *note
     abolish_object/1: 64, which is often used to define more
     sophisticated object deletion predicates.

'friend function'

     Not supported in Logtalk.  Nevertheless, see the User Manual
     section on *note meta-predicates: 65.

'instance'

     In Logtalk, an instance can be either created dynamically at
     runtime or defined statically in a source file in the same way as
     classes.

'member'

     Logtalk uses the term *note predicate: 61.

'member function'

     Logtalk uses *note predicates: 61. for representing both behavior
     and data.

'namespace'

     Logtalk does not support multiple identifier namespaces.  All
     Logtalk entity identifiers share the same namespace (Logtalk
     entities are objects, categories, and protocols).

'nested class'

     Logtalk does not support nested classes.

'static member'

     Logtalk does not support a ‘static’ keyword.  But the equivalent of
     static members can be declared in a class metaclass.

'template'

     Logtalk supports *note parametric objects: 66, which allows you to
     get the similar functionality of templates at runtime.

'this'

     Logtalk uses the built-in context method *note self/1: 67. for
     retrieving the instance that received the message being processed.
     Logtalk also provides a *note this/1: 68. method but for returning
     the class containing the method being executed.  Why the name
     clashes?  Well, the notion of *note self: 69. was inherited from
     Smalltalk, which predates C++.

'virtual member function'

     There is no ‘virtual’ keyword in Logtalk.  Any inherited or
     imported predicate can be redefined (either overridden or
     specialized).  Logtalk can use *note static binding: 35. or *note
     dynamic binding: 36. for locating both method declarations and
     method definitions.  Moreover, methods that are declared but not
     defined simply fail when called (as per the *note closed-world
     assumption: 6a.).


File: TheLogtalkHandbook-3.96.0.info,  Node: Java nomenclature,  Next: Python nomenclature,  Prev: C++ nomenclature,  Up: Nomenclature

1.3.4 Java nomenclature
-----------------------

There are several Java glossaries available on the Internet.  The list
that follows relates the most commonly used Java terms with their
Logtalk equivalents.

'abstract class'

     Logtalk uses an 'operational' definition of abstract class: any
     class that does not inherit a method for creating new instances is
     an abstract class.  I.e.  there is no ‘abstract’ keyword in
     Logtalk.

'abstract method'

     In Logtalk, you may simply declare a method (*note predicate: 61.)
     in a class without defining it, leaving its definition to some
     descendant subclass.

'assertion'

     There is no ‘assertion’ keyword in Logtalk.  Assertions are
     supported using Logtalk compilation hooks and developer tools.

'class'

     Logtalk objects can play the role of classes, instances, or
     protocols (depending on their relations with other objects).

'extends'

     There is no ‘extends’ keyword in Logtalk.  Class inheritance is
     indicated using 'specialization relations'.  Moreover, the 'extends
     relation' is used in Logtalk to indicate protocol, category, or
     prototype extension.

'interface'

     Logtalk uses the term *note protocol: 59. with a similar meaning.
     But note that Logtalk objects and categories declared as
     implementing a protocol are not required to provide definitions for
     the declared predicates (*note closed-world assumption: 6a.).

'callback method'

     Logtalk supports *note event-driven programming: 6d, the most
     common usage context of callback methods.  Callback methods can
     also be implemented using *note meta-predicates: 52.

'constructor'

     There are no special methods for creating new objects in Logtalk.
     Instead, Logtalk provides a built-in predicate, *note
     create_object/4: 62, which is often used to define more
     sophisticated object creation predicates.

'final'

     There is no ‘final’ keyword in Logtalk.  Predicates can always be
     redeclared and redefined in subclasses (and instances!).

'inner class'

     Inner classes are not supported in Logtalk.

'instance'

     In Logtalk, an instance can be either created dynamically at
     runtime or defined statically in a source file in the same way as
     classes.

'method'

     Logtalk uses the term *note predicate: 61. interchangeably with the
     term 'method'.

'method call'

     Logtalk usually uses the expression 'message-sending' for method
     calls, true to its Smalltalk heritage.

'method signature'

     Logtalk selects the method/predicate to execute in order to answer
     a method call based only on the method name and number of
     arguments.  Logtalk (and Prolog) are not typed languages in the
     same sense as Java.

'package'

     There is no concept of packages in Logtalk.  All Logtalk entities
     (objects, protocols, categories) share a single namespace.  But
     Logtalk does support a concept of *note library: 6e. that allows
     grouping of entities whose source files share a common path prefix.

'reflection'

     Logtalk features a 'white box' API supporting 'structural'
     reflection about *note entity contents: 6f, a 'black box' API
     supporting 'behavioral' reflection about *note object protocols:
     70, and an *note events: 71. API for reasoning about messages
     exchanged at runtime.

'static'

     There is no ‘static’ keyword in Logtalk.  See the entries below on
     'static method' and 'static variable'.

'static method'

     Static methods may be implemented in Logtalk by using a *note
     metaclass: 72. for the class and defining the static methods in the
     metaclass.  I.e.  static methods are simply instance methods of the
     class metaclass.

'static variable'

     Static variables are 'shared instance variables' and can simply be
     both declared and defined in a class.  The built-in database
     methods can be used to implement destructive updates if necessary
     by accessing and updating a single clause of a dynamic predicate
     stored in the class.

'super'

     Instead of a ‘super’ keyword, Logtalk provides a super operator and
     control construct, *note (^^)/1: 5d, for calling overridden
     methods.

'synchronized'

     Logtalk supports *note multi-threading programming: 73. in selected
     Prolog compilers, including a *note synchronized/1: 74. predicate
     directive.  Logtalk allows you to synchronize a predicate or a set
     of predicates using per-predicate or per-predicate-set 'mutexes'.

'this'

     Logtalk uses the built-in context method *note self/1: 67. for
     retrieving the instance that received the message being processed.
     Logtalk also provides a *note this/1: 68. method but for returning
     the class containing the method being executed.  Why the name
     clashes?  Well, the notion of *note self: 69. was inherited from
     Smalltalk, which predates C++.


File: TheLogtalkHandbook-3.96.0.info,  Node: Python nomenclature,  Prev: Java nomenclature,  Up: Nomenclature

1.3.5 Python nomenclature
-------------------------

The list that follows relates the commonly used Python concepts with
their Logtalk equivalents.

'abstract class'

     Logtalk uses a different definition of abstract class: a class that
     does not inherit a method for creating new instances.  Notably, the
     presence of 'abstract methods' (i.e., predicates that are declared
     but not defined) does not make a class abstract.

'abstract method'

     Logtalk uses the term 'predicate' interchangeably with 'method'.
     Predicates can be declared without also being defined in an object
     (or category).

'class'

     Logtalk objects can play the role of classes, instances, or
     protocols (depending on their relations with other objects).

'dictionary'

     There is no native, built-in associative data type.  But the
     library provides several implementations of a dictionary protocol.

'function'

     The closest equivalent is a predicate defined in ‘user’, a
     pseudo-object for predicates not defined in regular objects, and
     thus callable from anywhere without requiring a scope directive.

'function object'

     Predicate calls (goals) can be passed or returned from other
     predicates and unified with other terms (e.g., variables).

'import path'

     Logtalk uses the term 'library' to refer to a directory of source
     files and supports defining aliases (symbolic names) to library
     paths to abstract the actual locations.

'lambda'

     Logtalk natively supports lambda expressions.

'list'

     Lists are compound terms with native syntax support.

'list comprehensions'

     There is no native, built-in support for list comprehensions.  But
     the standard ‘findall/3’ predicate can be used to construct a list
     by calling a goal that generates the list elements.

'loader'

     Logtalk uses the term 'loader' to refer to source files whose main
     or sole purpose is to load other source files.

'loop'

     There are no native loop control constructs based on a counter.
     But the library provides implementations of several loop
     predicates.

'metaclass'

     Logtalk objects play the role of metaclasses when instantiated by
     objects that play the role of classes.

'method'

     Logtalk uses the terms 'method' and 'predicate' interchangeably.
     Predicates can be defined in objects (and categories).  The value
     of 'self' is implicit, unlike in Python where it is the first
     parameter of any method.

'method resolution order'

     Logtalk uses a depth-first algorithm to lookup method (predicate)
     declarations and definitions.  It’s possible to use predicate
     'aliases' to access predicate declarations and definitions other
     than the first ones found by the lookup algorithm.

'object'

     Objects are first-class entities that can play multiple roles,
     including prototype, class, instance, and metaclass.

'package'

     Logtalk uses the term 'library' to refer to a directory of source
     files defining objects, categories, and protocols.

'set'

     There is no native, built-in set type.  But the library provides
     set implementations.

'string'

     The interpretation of text between double-quotes depends on the
     ‘double_quotes’ flag.  Depending on this flag, double-quoted text
     can be interpreted as a list of characters, a list of character
     codes, or an atom.  Some backend Prolog compilers allow
     double-quoted text to be interpreted as a string in the Python
     sense.

'tuple'

     Compound terms can be used to represent tuples of any complexity.

'variable'

     Logtalk works with 'logical variables', which are close to the
     mathematical concept of variables and distinct from variables in
     imperative or imperative-based OOP languages where they are
     symbolic names for memory locations.  Logical variables can be
     'unified' with any term, including other variables.

'while loop'

     The built-in ‘forall/2’ predicate implements a 'generate-and-test'
     loop.


File: TheLogtalkHandbook-3.96.0.info,  Node: Messages,  Next: Objects,  Prev: Nomenclature,  Up: User Manual

1.4 Messages
============

Messages allow us to ask an object to prove a goal and must always match
a declared predicate within the scope of the 'sender' object.  Note that
sending a message is fundamentally different from calling a predicate.
When calling a predicate, the caller decides implicitly which predicate
definition will be executed.  When sending a message, it is the
receiving object, not the sender, that decides which predicate
definition (if any) will be called to answer the message.  The predicate
definition that is used to answer a message depends on the relations
between the object and its imported categories and ancestor objects (if
any).  See the *note Inheritance: 8. section for details on the
predicate declaration and predicate definition lookup procedures.

When a message corresponds to a *note meta-predicate: 52, the
meta-arguments are always called in the context of the object (or
category) sending the message.

Logtalk uses nomenclature similar to other object-oriented programming
languages such as Smalltalk.  Therefore, the terms 'query' and 'message'
are used interchangeably when referring to a declared predicate that is
part of an object interface.  Likewise, the terms 'predicate' and
'method' are used interchangeably when referring to the predicate
definition (inside an object or category) that is called to answer a
message.

* Menu:

* Operators used in message-sending::
* Sending a message to an object::
* Delegating a message to an object::
* Sending a message to self::
* Broadcasting::
* Calling imported and inherited predicates::
* Message sending and event generation::
* Sending a message from a module::
* Message sending performance::


File: TheLogtalkHandbook-3.96.0.info,  Node: Operators used in message-sending,  Next: Sending a message to an object,  Up: Messages

1.4.1 Operators used in message-sending
---------------------------------------

Logtalk declares the following operators for the message-sending control
constructs:

     :- op(600, xfy, ::).
     :- op(600,  fy, ::).
     :- op(600,  fy, ^^).

It is assumed that these operators remain active (once the Logtalk
compiler and runtime files are loaded) until the end of the Prolog
session (this is the usual behavior of most Prolog compilers).  Note
that these operator definitions are compatible with the predefined
operators in the Prolog ISO standard.


File: TheLogtalkHandbook-3.96.0.info,  Node: Sending a message to an object,  Next: Delegating a message to an object,  Prev: Operators used in message-sending,  Up: Messages

1.4.2 Sending a message to an object
------------------------------------

Sending a message to an object is accomplished by using the *note
(;;)/2: 7e. control construct:

     ..., Object::Message, ...

The message must match a public predicate declared for the receiving
object.  The message may also correspond to a protected or private
predicate if the 'sender' matches the predicate scope container.  If the
predicate is declared but not defined, the message simply fails (as per
the *note closed-world assumption: 6a.).


File: TheLogtalkHandbook-3.96.0.info,  Node: Delegating a message to an object,  Next: Sending a message to self,  Prev: Sending a message to an object,  Up: Messages

1.4.3 Delegating a message to an object
---------------------------------------

It is also possible to send a message to an object while preserving the
original 'sender' and 'meta-call context' by using the *note []/1: 81.
delegation control construct:

     ..., [Object::Message], ....

This control construct can only be used within objects and categories
(at the top-level interpreter, the 'sender' is always the pseudo-object
‘user’ so using this control construct would be equivalent to using the
‘(::)/2’ message-sending control construct).


File: TheLogtalkHandbook-3.96.0.info,  Node: Sending a message to self,  Next: Broadcasting,  Prev: Delegating a message to an object,  Up: Messages

1.4.4 Sending a message to 'self'
---------------------------------

While defining a predicate, we sometimes need to send a message to
'self', i.e., to the same object that has received the original message.
This is done in Logtalk through the *note (;;)/1: 5c. control construct:

     ..., ::Message, ....

The message must match either a public or protected predicate declared
for the receiving object or a private predicate within the scope of the
'sender' otherwise an error will be thrown.  If the message is sent from
inside a category or if we are using private inheritance, then the
message may also match a private predicate.  Again, if the predicate is
declared but not defined, the message simply fails (as per the *note
closed-world assumption: 6a.).


File: TheLogtalkHandbook-3.96.0.info,  Node: Broadcasting,  Next: Calling imported and inherited predicates,  Prev: Sending a message to self,  Up: Messages

1.4.5 Broadcasting
------------------

In the Logtalk context, 'broadcasting' is interpreted as the sending of
several messages to the same object.  This can be achieved by using the
message-sending control construct described above.  However, for
convenience, Logtalk implements an extended syntax for message-sending
that may improve program readability in some cases.  This extended
syntax uses the ‘(,)/2’, ‘(;)/2’, and ‘(->)/2’ control constructs (plus
the ‘(*->)/2’ soft-cut control construct when provided by the backend
Prolog compiler).  For example, if we wish to send several messages to
the same object, we can write:

     | ?- Object::(Message1, Message2, ...).

This is semantically equivalent to:

     | ?- Object::Message1, Object::Message2, ... .

This extended syntax may also be used with the ‘(::)/1’ message-sending
control construct.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling imported and inherited predicates,  Next: Message sending and event generation,  Prev: Broadcasting,  Up: Messages

1.4.6 Calling imported and inherited predicates
-----------------------------------------------

When redefining a predicate, sometimes we need to call the inherited
definition in the new code.  This functionality, introduced by the
Smalltalk language through the ‘super’ primitive, is available in
Logtalk using the *note (^^)/1: 5d. control construct:

     ..., ^^Predicate, ....

Most of the time we will use this control construct by instantiating the
pattern:

     Predicate :-
         ...,            % do something
         ^^Predicate,    % call inherited definition
         ... .           % do something more

This control construct is generalized in Logtalk where it may be used to
call any imported or inherited predicate definition.  This control
construct may be used within objects and categories.  When combined with
*note static binding: 35, this control construct allows imported and
inherited predicates to be called with the same performance as local
predicates.  As with the message-sending control constructs, the
‘(^^)/1’ call simply fails when the predicate is declared but not
defined (as per the *note closed-world assumption: 6a.).


File: TheLogtalkHandbook-3.96.0.info,  Node: Message sending and event generation,  Next: Sending a message from a module,  Prev: Calling imported and inherited predicates,  Up: Messages

1.4.7 Message sending and event generation
------------------------------------------

Assuming the *note events: 89. flag is set to ‘allow’ for the object (or
category) sending a message using the *note (;;)/2: 7e. control
construct, two events are generated, one before and one after the
message execution.  Messages that are sent using the *note (;;)/1: 5c.
(message to 'self') control construct or the *note (^^)/1: 5d. super
mechanism described above do not generate any events.  The rationale
behind this distinction is that messages to 'self' and 'super' calls are
only used internally in the definition of methods or to execute
additional messages with the same target object (represented by 'self').
In other words, events are only generated when using an object’s public
interface; they cannot be used to break object encapsulation.

If we need to generate events for a public message sent to 'self', then
we just need to write something like:

     Predicate :-
         ...,
         % get self reference
         self(Self),
         % send a message to self using (::)/2
         Self::Message,
         ... .

If we also need the sender of the message to be other than the object
containing the predicate definition, we can write:

     Predicate :-
         ...,
         % send a message to self using (::)/2
         % sender will be the pseudo-object user
         self(Self),
         {Self::Message},
         ... .

When events are not used, it is possible to turn off event generation
globally or on a per-entity basis by using the ‘events’ compiler flag to
optimize message-sending performance (see the *note Event-driven
programming: 6d. section for more details).


File: TheLogtalkHandbook-3.96.0.info,  Node: Sending a message from a module,  Next: Message sending performance,  Prev: Message sending and event generation,  Up: Messages

1.4.8 Sending a message from a module
-------------------------------------

Messages can be sent to objects from within Prolog modules.  Depending
on the backend support for goal-expansion and on the *note optimize: 8c.
flag being turned on, the messages will use static binding when
possible.  This optimization requires the object to be compiled and
loaded before the module.  Note that the module can be ‘user’.  This is
usually the case when sending the message from the top-level
interpreter.  Thus, the same conditions apply in this case.  Note that
loading Prolog modules using Prolog directives or built-in predicates
necessarily limits the range of possible optimizations for messages sent
from the modules.

     Warning: If you want to benchmark the performance of a
     message-sending goal at the top-level interpreter, be careful to
     check first if the goal is pre-compiled to use static binding;
     otherwise you will also be benchmarking the Logtalk compiler
     itself.


File: TheLogtalkHandbook-3.96.0.info,  Node: Message sending performance,  Prev: Sending a message from a module,  Up: Messages

1.4.9 Message sending performance
---------------------------------

For a detailed discussion on message-sending performance, see the *note
Performance: 38. section.


File: TheLogtalkHandbook-3.96.0.info,  Node: Objects,  Next: Protocols,  Prev: Messages,  Up: User Manual

1.5 Objects
===========

The main goal of Logtalk objects is the encapsulation and reuse of
predicates.  Instead of a single database containing all your code,
Logtalk objects provide separated namespaces or databases, allowing the
partitioning of code into more manageable parts.  Logtalk is a
'declarative programming language' and does not aim to bring some sort
of new dynamic state change concept to Logic Programming or Prolog.

Logtalk, defines two built-in objects, user(1) and logtalk(2), which are
described at the end of this section.

* Menu:

* Objects, prototypes, classes, and instances: Objects prototypes classes and instances.
* Defining a new object::
* Parametric objects: Parametric objects<2>.
* Finding defined objects::
* Creating a new object at runtime::
* Abolishing an existing object::
* Object directives::
* Object relationships::
* Object properties::
* Built-in objects::
* Multi-threading applications::

   ---------- Footnotes ----------

   (1) ../../apis/user_0.html#user-0

   (2) ../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Objects prototypes classes and instances,  Next: Defining a new object,  Up: Objects

1.5.1 Objects, prototypes, classes, and instances
-------------------------------------------------

There are only three kinds of encapsulation entities in Logtalk:
'objects', 'protocols', and 'categories'.  Logtalk uses the term
'object' in a broad sense.  The terms 'prototype', 'parent', 'class',
'subclass', 'superclass', 'metaclass', and 'instance' always designate
an object.  Different names are used to emphasize the 'role' played by
an object in a particular context.  I.e.  we use a term other than
object when we want to make the relationship with other objects
explicit.  For example, an object with an 'instantiation' relation with
another object plays the role of an 'instance', while the instantiated
object plays the role of a 'class'; an object with a 'specialization'
relation with another object plays the role of a 'subclass', while the
specialized object plays the role of a 'superclass'; an object with an
'extension' relation with another object plays the role of a
'prototype', the same for the extended object.  A 'stand-alone' object,
i.e.  an object with no relations with other objects, is always
interpreted as a prototype.  In Logtalk, entity relations essentially
define 'patterns' of code reuse.  An entity is compiled according to the
roles it plays.

Logtalk allows you to work from standalone objects to any kind of
hierarchy, either class-based or prototype-based.  You may use single or
multiple inheritance, use or forgo metaclasses, implement reflective
designs, use parametric objects, and take advantage of protocols and
categories (think components).

* Menu:

* Prototypes::
* Classes::


File: TheLogtalkHandbook-3.96.0.info,  Node: Prototypes,  Next: Classes,  Up: Objects prototypes classes and instances

1.5.1.1 Prototypes
..................

Prototypes are either self-defined objects or objects defined as
extensions to other prototypes with whom they share common properties.
Prototypes are ideal for representing one-of-a-kind objects.  Prototypes
usually represent concrete objects in the application domain.  When
linking prototypes using 'extension' relations, Logtalk uses the term
'prototype hierarchies' although most authors prefer to use the term
'hierarchy' only with class generalization/specialization relations.  In
the context of logic programming, prototypes are often the ideal
replacement for modules.


File: TheLogtalkHandbook-3.96.0.info,  Node: Classes,  Prev: Prototypes,  Up: Objects prototypes classes and instances

1.5.1.2 Classes
...............

Classes are used to represent abstractions of common properties of sets
of objects.  Classes often provide an ideal structuring solution when
you want to express hierarchies of abstractions or work with many
similar objects.  Classes are used indirectly through 'instantiation'.
Contrary to most object-oriented programming languages, instances can be
created both dynamically at runtime or defined in a source file like
other objects.  Using classes requires defining at least one *note
metaclass: 72, as explained below.


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining a new object,  Next: Parametric objects<2>,  Prev: Objects prototypes classes and instances,  Up: Objects

1.5.2 Defining a new object
---------------------------

We can define a new object in the same way we write Prolog code: by
using a text editor.  Logtalk source files may contain one or more
objects, categories, or protocols.  If you prefer to define each entity
in its own source file, it is recommended that the file be named after
the object.  By default, all Logtalk source files use the extension
‘.lgt’ but this is optional and can be set in the adapter files.
Intermediate Prolog source files (generated by the Logtalk compiler)
have, by default, a ‘_lgt’ suffix and a ‘.pl’ extension.  Again, this
can be set to match the needs of a particular Prolog compiler in the
corresponding adapter file.  For instance, we may define an object named
‘vehicle’ and save it in a ‘vehicle.lgt’ source file, which will be
compiled to a ‘vehicle_lgt.pl’ Prolog file (depending on the *note
backend compiler: 34, the names of the intermediate Prolog files may
include a directory hash and a process identifier to prevent file name
clashes when embedding Logtalk applications or running parallel Logtalk
processes).

Object names can be atoms or compound terms (when defining parametric
objects, see below).  Objects, categories, and protocols share the same
name space: we cannot have an object with the same name as a protocol or
a category.

Object code (directives and predicates) is textually encapsulated by
using two Logtalk directives: *note object/1-5: 9a. and *note
end_object/0: 9b.  The simplest object will be one that is
self-contained, not depending on any other Logtalk entity:

     :- object(Object).
         ...
     :- end_object.

If an object implements one or more protocols then the opening directive
will be:

     :- object(Object,
         implements([Protocol1, Protocol2, ...])).
         ...
     :- end_object.

An object can import one or more categories:

     :- object(Object,
         imports([Category1, Category2, ...])).
         ...
     :- end_object.

If an object both implements protocols and imports categories, then we
will write:

     :- object(Object,
         implements([Protocol1, Protocol2, ...]),
         imports([Category1, Category2, ...])).
         ...
     :- end_object.

In object-oriented programming, objects are usually organized in
hierarchies that enable interface and code sharing by inheritance.  In
Logtalk, we can construct prototype-based hierarchies by writing:

     :- object(Prototype,
         extends(Parent)).
         ...
     :- end_object.

We can also have class-based hierarchies by defining instantiation and
specialization relations between objects.  To define an object as a
class instance we will write:

     :- object(Object,
         instantiates(Class)).
         ...
     :- end_object.

A class may specialize another class, its superclass:

     :- object(Class,
         specializes(Superclass)).
         ...
     :- end_object.

If we are defining a reflexive system where every class is also an
instance, we will probably be using the following pattern:

     :- object(Class,
         instantiates(Metaclass),
         specializes(Superclass)).
         ...
     :- end_object.

In short, an object can be a 'stand-alone' object or be part of an
object hierarchy.  The hierarchy can be prototype-based (defined by
extending other objects) or class-based (with instantiation and
specialization relations).  An object may also implement one or more
protocols or import one or more categories.

A 'stand-alone' object (i.e., an object with no extension,
instantiation, or specialization relations with other objects) always
plays the role of a prototype, that is, a self-describing object.  If we
want to use classes and instances, then we will need to specify at least
one instantiation or specialization relation.  The best way to do this
is to define a set of objects that provide the basis of a reflective
system *note [Cointe87]: 9c, *note [Moura94]: 9d.  For example:

     % avoid the inevitable unknown entity warnings as in a
     % reflective system there will always be references to
     % an entity that will be defined after the reference

     :- set_logtalk_flag(unknown_entities, silent).


     % default root of the inheritance graph
     % providing predicates common to all objects

     :- object(object,
         instantiates(class)).
         ...
     :- end_object.


     % default metaclass for all classes providing
     % predicates common to all instantiable classes

     :- object(class,
         instantiates(class),
         specializes(abstract_class)).
         ...
     :- end_object.


     % default metaclass for all abstract classes
     % providing predicates common to all classes

     :- object(abstract_class,
         instantiates(class),
         specializes(object)).
         ...
     :- end_object.

Note that with these instantiation and specialization relations,
‘object’, ‘class’, and ‘abstract_class’ are, at the same time, classes
and instances of some class.  In addition, each object inherits its own
predicates and the predicates of the other two objects without any
inheritance loop.

When a full-blown reflective system solution is not needed, the above
scheme can be simplified by making an object an instance of itself, i.e.
by making a class its own metaclass.  For example:

     :- object(class,
         instantiates(class)).
         ...
     :- end_object.

We can use, in the same application, both prototype and class-based
hierarchies (and freely exchange messages between all objects).  We
cannot, however, mix the two types of hierarchies by, e.g., specializing
an object that extends another object in this current Logtalk version.

Logtalk also supports public, protected, and private inheritance.  See
the *note inheritance: 9e. section for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Parametric objects<2>,  Next: Finding defined objects,  Prev: Defining a new object,  Up: Objects

1.5.3 Parametric objects
------------------------

Parametric objects have a compound term as identifier where all the
arguments of the compound term are variables.  These variables can be
bound when sending a message or become bound when a message to the
object succeeds, thus acting as 'object parameters'.  The object
predicates can be coded to depend on those parameters, which are logical
variables shared by all object predicates.  When an object state is set
at object creation and never changed, parameters provide a better
solution than using the object’s database via asserts.  Parametric
objects can also be used to associate a set of predicates to terms that
share a common functor and arity.

* Menu:

* Accessing object parameters::
* Parametric object proxies::


File: TheLogtalkHandbook-3.96.0.info,  Node: Accessing object parameters,  Next: Parametric object proxies,  Up: Parametric objects<2>

1.5.3.1 Accessing object parameters
...................................

Object parameters can be accessed using *note parameter variables: a1.
or built-in execution context methods.  Parameter variables is the
recommended solution to access object parameters.  Although they
introduce a concept of entity global variables, their unique syntax
(‘_ParameterName_’) avoids conflicts, makes them easily recognizable,
and distinguishes them from other named anonymous variables.  For
example:

     :- object(foo(_Bar_, _Baz_, ...)).

         ...
         bar(_Bar_).

         baz :-
             baz(_Baz_),
             ... .

Note that using parameter variables doesn’t change the fact that entity
parameters are logical variables.  Parameter variables simplify code
maintenance by allowing parameters to be added, reordered, or removed
without having to specify or update parameter indexes.

Logtalk provides also a *note parameter/2: a2. built-in local method to
access individual parameters:

     :- object(foo(_Bar, _Baz, ...)).

         ...
         bar(Bar) :-
             parameter(1, Bar).

         baz :-
             parameter(2, Baz),
             baz(Baz),
             ... .

An alternative solution is to use the built-in local method *note
this/1: 68, which allows access to all parameters with a single call.
For example:

     :- object(foo(_Bar, _Baz, ...)).

         ...
         baz :-
             this(foo(_, Baz, ...)),
             baz(Baz),
             ... .

Both solutions are equally efficient as calls to the methods ‘this/1’
and ‘parameter/2’ are usually compiled inline into a clause head
unification.  The drawback of this second solution is that we must check
all calls of ‘this/1’ if we change the object name.  Note that we can’t
use these method with the message-sending operators (*note (;;)/2: 7e,
*note (;;)/1: 5c, or *note (^^)/1: 5d.).

When storing a parametric object in its own source file, the convention
is to name the file after the object, with the object arity appended.
For instance, when defining an object named ‘sort(Type)’, we may save it
in a ‘sort_1.lgt’ text file.  This way it is easy to avoid file name
clashes when saving Logtalk entities that have the same functor but
different arity.


File: TheLogtalkHandbook-3.96.0.info,  Node: Parametric object proxies,  Prev: Accessing object parameters,  Up: Parametric objects<2>

1.5.3.2 Parametric object proxies
.................................

Compound terms with the same functor and with the same number of
arguments as a parametric object identifier may act as 'proxies' to a
parametric object.  Proxies may be stored on the database as Prolog
facts and be used to represent different instantiations of a parametric
object identifier.  For example:

     :- object(circle(_Id_, _Radius_, _Color_)).

         :- public(area/1).
         ...

     :- end_object.

     % parametric object proxies:
     circle('#1', 1.23, blue).
     circle('#2', 3.71, yellow).
     circle('#3', 0.39, green).
     circle('#4', 5.74, black).
     circle('#5', 8.32, cyan).

Logtalk provides a convenient notation for accessing proxies represented
as Prolog facts when sending a message:

     ..., {Proxy}::Message, ...

For example, using the ‘circle/3’ parametric object above, we can
compute a list with the areas of all circles using the following goal:

     | ?- findall(Area, {circle(_, _, _)}::area(Area), Areas).

     Areas = [4.75291, 43.2412, 0.477836, 103.508, 217.468].

In this context, the proxy argument is proved as a plain Prolog goal.
If successful, the message is sent to the corresponding parametric
object.  Typically, the proof allows retrieval of parameter
instantiations.  This construct can either be used with a proxy argument
that is sufficiently instantiated in order to unify with a single Prolog
fact or with a proxy argument that unifies with several facts on
backtracking.


File: TheLogtalkHandbook-3.96.0.info,  Node: Finding defined objects,  Next: Creating a new object at runtime,  Prev: Parametric objects<2>,  Up: Objects

1.5.4 Finding defined objects
-----------------------------

We can find, by backtracking, all defined objects by calling the *note
current_object/1: a6. built-in predicate with an unbound argument:

     | ?- current_object(Object).
     Object = logtalk ;
     Object = user ;
     ...

This predicate can also be used to test if an object is defined by
calling it with a valid object identifier (an atom or a compound term).


File: TheLogtalkHandbook-3.96.0.info,  Node: Creating a new object at runtime,  Next: Abolishing an existing object,  Prev: Finding defined objects,  Up: Objects

1.5.5 Creating a new object at runtime
--------------------------------------

An object can be dynamically created at runtime by using the *note
create_object/4: 62. built-in predicate:

     | ?- create_object(Object, Relations, Directives, Clauses).

The first argument should be either a variable or the name of the new
object (a Prolog atom or compound term, which must not match any
existing entity name).  The remaining three arguments correspond to the
relations described in the opening object directive and to the object
code contents (directives and clauses).

For example, the call:

     | ?- create_object(
              foo,
              [extends(bar)],
              [public(foo/1)],
              [foo(1), foo(2)]
          ).

is equivalent to compiling and loading the object:

     :- object(foo,
         extends(bar)).

         :- dynamic.

         :- public(foo/1).
         foo(1).
         foo(2).

     :- end_object.

If we need to create a lot of (dynamic) objects at runtime, then it is
best to define a metaclass or a prototype with a predicate that will
call this built-in predicate to make new objects.  This predicate may
provide automatic object name generation, name checking, and accept
object initialization options.


File: TheLogtalkHandbook-3.96.0.info,  Node: Abolishing an existing object,  Next: Object directives,  Prev: Creating a new object at runtime,  Up: Objects

1.5.6 Abolishing an existing object
-----------------------------------

Dynamic objects can be abolished using the *note abolish_object/1: 64.
built-in predicate:

     | ?- abolish_object(Object).

The argument must be an identifier of a defined dynamic object;
otherwise an error will be thrown.


File: TheLogtalkHandbook-3.96.0.info,  Node: Object directives,  Next: Object relationships,  Prev: Abolishing an existing object,  Up: Objects

1.5.7 Object directives
-----------------------

Object directives are used to set initialization goals, define object
properties, document an object dependencies on other Logtalk entities,
and load the contents of files into an object.

* Menu:

* Object initialization::
* Dynamic objects::
* Object documentation::
* Loading files into an object::
* Declaring object aliases::


File: TheLogtalkHandbook-3.96.0.info,  Node: Object initialization,  Next: Dynamic objects,  Up: Object directives

1.5.7.1 Object initialization
.............................

We can define a goal to be executed as soon as an object is (compiled
and) loaded to memory with the *note initialization/1: 42. directive:

     :- initialization(Goal).

The argument can be any valid Logtalk goal.  For example, a call to a
local predicate:

     :- object(foo).

         :- initialization(init).
         :- private(init/0).

         init :-
             ... .

         ...

     :- end_object.

Or a message to another object:

     :- object(assembler).

         :- initialization(control::start).
         ...

     :- end_object.

Another common initialization goal is a message to 'self' in order to
call an inherited or imported predicate.  For example, assuming that we
have a ‘monitor’ category defining a ‘reset/0’ predicate, we could
write:

     :- object(profiler,
         imports(monitor)).

         :- initialization(::reset).
         ...

     :- end_object.

Note, however, that descendant objects do not inherit initialization
directives.  In this context, 'self' denotes the object that contains
the directive.  Also note that object initialization does not
necessarily mean setting an object dynamic state.


File: TheLogtalkHandbook-3.96.0.info,  Node: Dynamic objects,  Next: Object documentation,  Prev: Object initialization,  Up: Object directives

1.5.7.2 Dynamic objects
.......................

Similar to Prolog predicates, an object can be either static or dynamic.
An object created during the execution of a program is always dynamic.
An object defined in a file can be either dynamic or static.  Dynamic
objects are declared by using the *note dynamic/0: b1. directive in the
object source code:

     :- dynamic.

The directive must precede any predicate directives or clauses.  Please
be aware that using dynamic code results in a performance hit when
compared to static code.  We should only use dynamic objects when these
need to be abolished during program execution.  In addition, note that
we can declare and define dynamic predicates within a static object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Object documentation,  Next: Loading files into an object,  Prev: Dynamic objects,  Up: Object directives

1.5.7.3 Object documentation
............................

An object can be documented with arbitrary user-defined information by
using the *note info/1: b4. entity directive.  See the *note
Documenting: b5. section for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading files into an object,  Next: Declaring object aliases,  Prev: Object documentation,  Up: Object directives

1.5.7.4 Loading files into an object
....................................

The *note include/1: b8. directive can be used to load the contents of a
file into an object.  A typical usage scenario is to load a plain Prolog
file into an object, thus providing a simple way to encapsulate its
contents.  For example, assume a ‘cities.pl’ file defining facts for a
‘city/4’ predicate.  We could define a wrapper for this database by
writing:

     :- object(cities).

         :- public(city/4).

         :- include(dbs('cities.pl')).

     :- end_object.

The ‘include/1’ directive can also be used when creating an object
dynamically.  For example:

     | ?- create_object(cities, [], [public(city/4), include(dbs('cities.pl'))], []).


File: TheLogtalkHandbook-3.96.0.info,  Node: Declaring object aliases,  Prev: Loading files into an object,  Up: Object directives

1.5.7.5 Declaring object aliases
................................

The *note uses/1: 4a. directive can be used to declare object aliases.
The typical uses of this directive include shortening long object names,
working consistently with specific parameterizations of parametric
objects, and simplifying experimenting with different object
implementations of the same protocol when using explicit
message-sending.


File: TheLogtalkHandbook-3.96.0.info,  Node: Object relationships,  Next: Object properties,  Prev: Object directives,  Up: Objects

1.5.8 Object relationships
--------------------------

Logtalk provides six sets of built-in predicates that enable us to query
the system about the relationships that an object has with other
entities.

The *note instantiates_class/2-3: bd. built-in predicates can be used to
query all instantiation relations:

     | ?- instantiates_class(Instance, Class).

or, if we also want to know the instantiation scope:

     | ?- instantiates_class(Instance, Class, Scope).

Specialization relations can be found by using the *note
specializes_class/2-3: be. built-in predicates:

     | ?- specializes_class(Class, Superclass).

or, if we also want to know the specialization scope:

     | ?- specializes_class(Class, Superclass, Scope).

For prototypes, we can query extension relations using the *note
extends_object/2-3: bf. built-in predicates:

     | ?- extends_object(Object, Parent).

or, if we also want to know the extension scope:

     | ?- extends_object(Object, Parent, Scope).

In order to find which objects import which categories, we can use the
*note imports_category/2-3: c0. built-in predicates:

     | ?- imports_category(Object, Category).

or, if we also want to know the importation scope:

     | ?- imports_category(Object, Category, Scope).

To find which objects implements which protocols, we can use the *note
implements_protocol/2-3: c1. and *note conforms_to_protocol/2-3: c2.
built-in predicates:

     | ?- implements_protocol(Object, Protocol, Scope).

or, if we also want to consider inherited protocols:

     | ?- conforms_to_protocol(Object, Protocol, Scope).

Note that, if we use an unbound first argument, we will need to use the
*note current_object/1: a6. built-in predicate to ensure that the entity
returned is an object and not a category.

To find which objects are explicitly complemented by categories, we can
use the *note complements_object/2: c3. built-in predicate:

     | ?- complements_object(Category, Object).

Note that more than one category may explicitly complement a single
object, and a single category can complement several objects.


File: TheLogtalkHandbook-3.96.0.info,  Node: Object properties,  Next: Built-in objects,  Prev: Object relationships,  Up: Objects

1.5.9 Object properties
-----------------------

We can find the properties of defined objects by calling the built-in
predicate *note object_property/2: c6.:

     | ?- object_property(Object, Property).

The following object properties are supported:

‘static’

     The object is static

‘dynamic’

     The object is dynamic (and thus can be abolished in runtime by
     calling the *note abolish_object/1: 64. built-in predicate)

‘built_in’

     The object is a built-in object (and thus always available)

‘threaded’

     The object supports/makes multi-threading calls

‘file(Path)’

     Absolute path of the source file defining the object (if
     applicable)

‘file(Basename, Directory)’

     Basename and directory of the source file defining the object (if
     applicable); ‘Directory’ always ends with a ‘/’

‘lines(BeginLine, EndLine)’

     Source file begin and end lines of the object definition (if
     applicable)

‘directive(BeginLine, EndLine)’

     Source file begin and end lines of the object opening directive (if
     applicable)

‘context_switching_calls’

     The object supports context-switching calls (i.e., can be used with
     the *note (<<)/2: c7. debugging control construct)

‘dynamic_declarations’

     The object supports dynamic declarations of predicates

‘events’

     Messages sent from the object generate events

‘source_data’

     Source data available for the object

‘complements(Permission)’

     The object supports complementing categories with the specified
     permission (‘allow’ or ‘restrict’)

‘complements’

     The object supports complementing categories

‘public(Resources)’

     List of public predicates and operators declared by the object

‘protected(Resources)’

     List of protected predicates and operators declared by the object

‘private(Resources)’

     List of private predicates and operators declared by the object

‘declares(Predicate, Properties)’

     List of *note properties: c8. for a predicate declared by the
     object

‘defines(Predicate, Properties)’

     List of *note properties: c8. for a predicate defined by the object

‘includes(Predicate, Entity, Properties)’

     List of *note properties: c8. for an object multifile predicate
     that are defined in the specified entity (the properties include
     ‘number_of_clauses(Number)’, ‘number_of_rules(Number)’,
     ‘include(File)’, ‘lines(Start,End)’, and ‘line_count(Start)’ with
     ‘Start-End’ being the line range of the first multifile predicate
     clause)

‘provides(Predicate, Entity, Properties)’

     List of *note properties: c8. for other entity multifile predicates
     that are defined in the object (the properties include
     ‘number_of_clauses(Number)’, ‘number_of_rules(Number)’,
     ‘include(File)’, ‘lines(Start,End)’, and ‘line_count(Start)’ with
     ‘Start-End’ being the line range of the first multifile predicate
     clause)

‘references(Reference, Properties)’

     List of *note properties: c8. for other references to entities in
     calls to the execution-context built-in methods and in directives
     for multifile predicates and multifile non-terminals that are found
     in the object (the properties include ‘in(Context)’,
     ‘non_terminal(NonTerminal)’, ‘include(File)’, ‘lines(Start,End)’,
     and ‘line_count(Start)’ with ‘Start-End’ being the line range of
     the first reference, a directive, a predicate clause, or a
     non-terminal grammar rule; the possible values for ‘Context’ are
     ‘multifile’, ‘dynamic’, ‘discontiguous’, ‘meta_predicate’,
     ‘meta_non_terminal’, and ‘clause’); ‘Reference’ can be either
     ‘Entity’ or ‘Entity::Functor/Arity’

‘alias(Entity, Properties)’

     List of *note properties: c8. for an *note entity alias: c9.
     declared by the object (the properties include ‘object’ in case of
     an object alias, ‘module’ in case of a module alias,
     ‘for(Original)’, ‘lines(Start,End)’, and ‘line_count(Start)’ with
     ‘Start-End’ being the line range of the ‘uses/1’ or ‘use_module/1’
     directive)

‘alias(Predicate, Properties)’

     List of *note properties: c8. for a *note predicate alias: ca.
     declared by the object (the properties include ‘predicate’,
     ‘for(Original)’, ‘from(Entity)’, ‘non_terminal(NonTerminal)’,
     ‘lines(Start,End)’, and ‘line_count(Start)’ with ‘Start-End’ being
     the line range of the alias directive)

‘calls(Call, Properties)’

     List of *note properties: c8. for predicate calls made by the
     object (‘Call’ is either a predicate indicator or a control
     construct such as ‘(::)/1-2’ or ‘(^^)/1’ with a predicate indicator
     as argument; note that ‘Call’ may not be ground in case of a call
     to a control construct where its argument is only known at runtime;
     the properties include ‘caller(Caller)’, ‘alias(Alias)’,
     ‘non_terminal(NonTerminal)’, ‘lines(Start,End)’,
     ‘line_count(Start)’ with ‘Caller’, ‘Alias’, and ‘NonTerminal’ being
     predicate indicators and ‘Start-End’ being the line range of the
     predicate clause or directive making the call)

‘updates(Predicate, Properties)’

     List of *note properties: c8. for dynamic predicate updates (and
     also access using the ‘clause/2’ predicate) made by the object
     (‘Predicate’ is either a predicate indicator or a control construct
     such as ‘(::)/1-2’ or ‘(:)/2’ with a predicate indicator as
     argument; note that ‘Predicate’ may not be ground in case of a
     control construct argument only known at runtime; the properties
     include ‘updater(Updater)’, ‘alias(Alias)’,
     ‘non_terminal(NonTerminal)’, ‘lines(Start,End)’, and
     ‘line_count(Start)’ with ‘Updater’ being a (possibly multifile)
     predicate indicator, ‘Alias’ and ‘NonTerminal’ being predicate
     indicators, and ‘Start-End’ being the line range of the predicate
     clause or directive updating the predicate)

‘number_of_clauses(Number)’

     Total number of predicate clauses defined in the object at
     compilation time (includes both user-defined clauses and auxiliary
     clauses generated by the compiler or by the *note expansion hooks:
     cb. but does not include clauses for multifile predicates defined
     for other entities or clauses for the object own multifile
     predicates contributed by other entities)

‘number_of_rules(Number)’

     Total number of predicate rules defined in the object at
     compilation time (includes both user-defined rules and auxiliary
     rules generated by the compiler or by the *note expansion hooks:
     cb. but does not include rules for multifile predicates defined for
     other entities or rules for the object own multifile predicates
     contributed by other entities)

‘number_of_user_clauses(Number)’

     Total number of user-defined predicate clauses defined in the
     object at compilation time (does not include clauses for multifile
     predicates defined for other entities or clauses for the object own
     multifile predicates contributed by other entities)

‘number_of_user_rules(Number)’

     Total number of user-defined predicate rules defined in the object
     at compilation time (does not include rules for multifile
     predicates defined for other entities or rules for the object own
     multifile predicates contributed by other entities)

‘debugging’

     The object is compiled in debug mode

‘module’

     The object resulted from the compilation of a Prolog module

When a predicate is called from an ‘initialization/1’ directive, the
argument of the ‘caller/1’ property is ‘(:-)/1’.

Some properties such as line numbers are only available when the object
is defined in a source file compiled with the *note source_data: cc.
flag turned on.  Moreover, line numbers are only supported in *note
backend Prolog compilers: 34. that provide access to the start line of a
read term.  When such support is not available, the value ‘-1’ is
returned for the start and end lines.

The properties that return the number of clauses (rules) report the
clauses (rules) 'textually defined in the object' for both multifile and
non-multifile predicates.  Thus, these numbers exclude clauses (rules)
for multifile predicates 'contributed' by other entities.


File: TheLogtalkHandbook-3.96.0.info,  Node: Built-in objects,  Next: Multi-threading applications,  Prev: Object properties,  Up: Objects

1.5.10 Built-in objects
-----------------------

Logtalk defines some built-in objects that are always available for any
application.

* Menu:

* The built-in pseudo-object user::
* The built-in object logtalk::


File: TheLogtalkHandbook-3.96.0.info,  Node: The built-in pseudo-object user,  Next: The built-in object logtalk,  Up: Built-in objects

1.5.10.1 The built-in pseudo-object ‘user’
..........................................

The built-in user(1) pseudo-object virtually contains all user predicate
definitions not encapsulated in a Logtalk entity (or a Prolog module for
backends supporting a module system).  These predicates are assumed to
be implicitly declared public.  Messages sent from this pseudo-object,
which includes messages sent from the top-level interpreter, generate
events when the default value of the *note events: 89. flag is set to
‘allow’.  Defining complementing categories for this pseudo-object is
not supported.

With some of the *note backend Prolog compilers: 34. that support a
module system, it is possible to load (the) Logtalk (compiler/runtime)
into a module other than the pseudo-module ‘user’.  In this case, the
Logtalk pseudo-object ‘user’ virtually contains all user predicate
definitions defined in the module where Logtalk was loaded.

   ---------- Footnotes ----------

   (1) ../../apis/user_0.html#user-0


File: TheLogtalkHandbook-3.96.0.info,  Node: The built-in object logtalk,  Prev: The built-in pseudo-object user,  Up: Built-in objects

1.5.10.2 The built-in object ‘logtalk’
......................................

The built-in logtalk(1) object provides *note message printing: d3.
predicates, *note question asking: d4. predicates, *note debug and trace
event: d5. predicates, predicates for accessing the internal database of
loaded files and their properties, and also a set of low-level utility
predicates normally used when defining hook objects.  Consult its API
documentation for details.

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Multi-threading applications,  Prev: Built-in objects,  Up: Objects

1.5.11 Multi-threading applications
-----------------------------------

When writing multi-threading applications, user-defined predicates
calling built-in predicates such as ‘create_object/4’ and
‘abolish_object/1’ may need to be declared synchronized in order to
avoid race conditions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Protocols,  Next: Categories,  Prev: Objects,  Up: User Manual

1.6 Protocols
=============

Protocols enable the separation between interface and implementation:
several objects can implement the same protocol, and an object can
implement several protocols.  Protocols may contain only predicate
declarations.  In some languages the term 'interface' is used with a
similar meaning.  Logtalk allows predicate declarations of any scope
within protocols, contrary to some languages that only allow public
declarations.

Logtalk defines three built-in protocols, monitoring(1), expanding(2),
and forwarding(3), which are described at the end of this section.

* Menu:

* Defining a new protocol::
* Finding defined protocols::
* Creating a new protocol at runtime::
* Abolishing an existing protocol::
* Protocol directives::
* Protocol relationships::
* Protocol properties::
* Implementing protocols::
* Built-in protocols::
* Multi-threading applications: Multi-threading applications<2>.

   ---------- Footnotes ----------

   (1) ../../apis/monitoring_0.html#monitoring-0

   (2) ../../apis/expanding_0.html#expanding-0

   (3) ../../apis/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining a new protocol,  Next: Finding defined protocols,  Up: Protocols

1.6.1 Defining a new protocol
-----------------------------

We can define a new protocol in the same way we write Prolog code: by
using a text editor.  Logtalk source files may contain one or more
objects, categories, or protocols.  If you prefer to define each entity
in its own source file, it is recommended that the file be named after
the protocol.  By default, all Logtalk source files use the extension
‘.lgt’ but this is optional and can be set in the adapter files.
Intermediate Prolog source files (generated by the Logtalk compiler)
have, by default, a ‘_lgt’ suffix and a ‘.pl’ extension.  Again, this
can be set to match the needs of a particular Prolog compiler in the
corresponding adapter file.  For example, we may define a protocol named
‘listp’ and save it in a ‘listp.lgt’ source file that will be compiled
to a ‘listp_lgt.pl’ Prolog file (depending on the backend compiler, the
names of the intermediate Prolog files may include a directory hash and
a process identifier to prevent file name clashes when embedding Logtalk
applications or running parallel Logtalk processes).

Protocol names must be atoms.  Objects, categories, and protocols share
the same namespace: we cannot have a protocol with the same name as an
object or a category.

Protocol directives are textually encapsulated by using two Logtalk
directives: *note protocol/1-2: dc. and *note end_protocol/0: dd.  The
most simple protocol will be one that is self-contained, not depending
on any other Logtalk entity:

     :- protocol(Protocol).
         ...
     :- end_protocol.

If a protocol extends one or more protocols, then the opening directive
will be:

     :- protocol(Protocol,
         extends([Protocol1, Protocol2, ...])).
         ...
     :- end_protocol.

In order to maximize protocol reuse, all predicates specified in a
protocol should relate to the same functionality.  Therefore, the only
recommended use of protocol extension is when you need both a minimal
protocol and an extended version of the same protocol with additional,
convenient predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Finding defined protocols,  Next: Creating a new protocol at runtime,  Prev: Defining a new protocol,  Up: Protocols

1.6.2 Finding defined protocols
-------------------------------

We can find, by backtracking, all defined protocols by using the *note
current_protocol/1: e0. built-in predicate with a unbound argument:

     | ?- current_protocol(Protocol).

This predicate can also be used to test if a protocol is defined by
calling it with a valid protocol identifier (an atom).


File: TheLogtalkHandbook-3.96.0.info,  Node: Creating a new protocol at runtime,  Next: Abolishing an existing protocol,  Prev: Finding defined protocols,  Up: Protocols

1.6.3 Creating a new protocol at runtime
----------------------------------------

We can create a new (dynamic) protocol at runtime by calling the Logtalk
built-in predicate *note create_protocol/3: e3.:

     | ?- create_protocol(Protocol, Relations, Directives).

The first argument should be either a variable or the name of the new
protocol (a Prolog atom, which must not match an existing entity name).
The remaining two arguments correspond to the relations described in the
opening protocol directive and to the protocol directives.

For instance, the call:

     | ?- create_protocol(ppp, [extends(qqq)], [public([foo/1, bar/1])]).

is equivalent to compiling and loading the protocol:

     :- protocol(ppp,
         extends(qqq)).

         :- dynamic.

         :- public([foo/1, bar/1]).

     :- end_protocol.

If we need to create a lot of (dynamic) protocols at runtime, then it is
best to define a metaclass or a prototype with a predicate that will
call this built-in predicate in order to provide more sophisticated
behavior.


File: TheLogtalkHandbook-3.96.0.info,  Node: Abolishing an existing protocol,  Next: Protocol directives,  Prev: Creating a new protocol at runtime,  Up: Protocols

1.6.4 Abolishing an existing protocol
-------------------------------------

Dynamic protocols can be abolished using the *note abolish_protocol/1:
e6. built-in predicate:

     | ?- abolish_protocol(Protocol).

The argument must be an identifier of a defined dynamic protocol;
otherwise an error will be thrown.


File: TheLogtalkHandbook-3.96.0.info,  Node: Protocol directives,  Next: Protocol relationships,  Prev: Abolishing an existing protocol,  Up: Protocols

1.6.5 Protocol directives
-------------------------

Protocol directives are used to define protocol properties and
documentation.

* Menu:

* Dynamic protocols::
* Protocol documentation::
* Loading files into a protocol::


File: TheLogtalkHandbook-3.96.0.info,  Node: Dynamic protocols,  Next: Protocol documentation,  Up: Protocol directives

1.6.5.1 Dynamic protocols
.........................

As usually happens with Prolog code, a protocol can be either static or
dynamic.  A protocol created during the execution of a program is always
dynamic.  A protocol defined in a file can be either dynamic or static.
Dynamic protocols are declared by using the *note dynamic/0: b1.
directive in the protocol source code:

     :- dynamic.

The directive must precede any predicate directives.  Please be aware
that using dynamic code results in a performance hit when compared to
static code.  We should only use dynamic protocols when these need to be
abolished during program execution.


File: TheLogtalkHandbook-3.96.0.info,  Node: Protocol documentation,  Next: Loading files into a protocol,  Prev: Dynamic protocols,  Up: Protocol directives

1.6.5.2 Protocol documentation
..............................

A protocol can be documented with arbitrary user-defined information by
using the *note info/1: b4. entity directive.  See the *note
Documenting: b5. section for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading files into a protocol,  Prev: Protocol documentation,  Up: Protocol directives

1.6.5.3 Loading files into a protocol
.....................................

The *note include/1: b8. directive can be used to load the contents of a
file into a protocol.  See the *note Objects: 91. section for an example
of using this directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Protocol relationships,  Next: Protocol properties,  Prev: Protocol directives,  Up: Protocols

1.6.6 Protocol relationships
----------------------------

Logtalk provides two sets of built-in predicates that enable us to query
the system about the relationships that a protocol has with other
entities.

The *note extends_protocol/2-3: f0. built-in predicates return all pairs
of protocols so that the first one extends the second:

     | ?- extends_protocol(Protocol1, Protocol2).

or, if we also want to know the extension scope:

     | ?- extends_protocol(Protocol1, Protocol2, Scope).

To find which objects or categories implement which protocols, we can
call the *note implements_protocol/2-3: c1. built-in predicates:

     | ?- implements_protocol(ObjectOrCategory, Protocol).

or, if we also want to know the implementation scope:

     | ?- implements_protocol(ObjectOrCategory, Protocol, Scope).

Note that, if we use a non-instantiated variable for the first argument,
we will need to use the *note current_object/1: a6. or *note
current_category/1: f1. built-in predicates to identify the kind of
entity returned.


File: TheLogtalkHandbook-3.96.0.info,  Node: Protocol properties,  Next: Implementing protocols,  Prev: Protocol relationships,  Up: Protocols

1.6.7 Protocol properties
-------------------------

We can find the properties of defined protocols by calling the *note
protocol_property/2: f4. built-in predicate:

     | ?- protocol_property(Protocol, Property).

A protocol may have the property ‘static’, ‘dynamic’, or ‘built_in’.
Dynamic protocols can be abolished in runtime by calling the *note
abolish_protocol/1: e6. built-in predicate.  Depending on the *note
backend Prolog compiler: 34, a protocol may have additional properties
related to the source file where it is defined.

The following protocol properties are supported:

‘static’

     The protocol is static

‘dynamic’

     The protocol is dynamic (and thus can be abolished in runtime by
     calling the *note abolish_category/1: f5. built-in predicate)

‘built_in’

     The protocol is a built-in protocol (and thus always available)

‘source_data’

     Source data available for the protocol

‘file(Path)’

     Absolute path of the source file defining the protocol (if
     applicable)

‘file(Basename, Directory)’

     Basename and directory of the source file defining the protocol (if
     applicable); ‘Directory’ always ends with a ‘/’

‘lines(BeginLine, EndLine)’

     Source file begin and end lines of the protocol definition (if
     applicable)

‘directive(BeginLine, EndLine)’

     Source file begin and end lines of the protocol opening directive
     (if applicable)

‘public(Resources)’

     List of public predicates and operators declared by the protocol

‘protected(Resources)’

     List of protected predicates and operators declared by the protocol

‘private(Resources)’

     List of private predicates and operators declared by the protocol

‘declares(Predicate, Properties)’

     List of *note properties: c8. for a predicate declared by the
     protocol

‘alias(Predicate, Properties)’

     List of *note properties: c8. for a *note predicate alias: ca.
     declared by the protocol (the properties include ‘for(Original)’,
     ‘from(Entity)’, ‘non_terminal(NonTerminal)’, and ‘line_count(Line)’
     with ‘Line’ being the begin line of the alias directive)

Some of the properties, such as line numbers, are only available when
the protocol is defined in a source file compiled with the *note
source_data: cc. flag turned on.


File: TheLogtalkHandbook-3.96.0.info,  Node: Implementing protocols,  Next: Built-in protocols,  Prev: Protocol properties,  Up: Protocols

1.6.8 Implementing protocols
----------------------------

Any number of objects or categories can implement a protocol.  The
syntax is very simple:

     :- object(Object,
         implements(Protocol)).
         ...
     :- end_object.

or, in the case of a category:

     :- category(Object,
         implements(Protocol)).
         ...
     :- end_category.

To make all public predicates declared via an implemented protocol
protected or to make all public and protected predicates private we
prefix the protocol’s name with the corresponding keyword.  For
instance:

     :- object(Object,
         implements(private::Protocol)).
         ...
     :- end_object.

or:

     :- object(Object,
         implements(protected::Protocol)).
         ...
     :- end_object.

Omitting the scope keyword is equivalent to writing:

     :- object(Object,
         implements(public::Protocol)).
         ...
     :- end_object.

The same rules apply to protocols implemented by categories.


File: TheLogtalkHandbook-3.96.0.info,  Node: Built-in protocols,  Next: Multi-threading applications<2>,  Prev: Implementing protocols,  Up: Protocols

1.6.9 Built-in protocols
------------------------

Logtalk defines a set of built-in protocols that are always available
for any application.

* Menu:

* The built-in protocol expanding::
* The built-in protocol monitoring::
* The built-in protocol forwarding::


File: TheLogtalkHandbook-3.96.0.info,  Node: The built-in protocol expanding,  Next: The built-in protocol monitoring,  Up: Built-in protocols

1.6.9.1 The built-in protocol ‘expanding’
.........................................

The built-in expanding(1) protocol declares the *note term_expansion/2:
fc. and *note goal_expansion/2: fd. predicates.  See the description of
the *note hook: fe. compiler flag for more details.

   ---------- Footnotes ----------

   (1) ../../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: The built-in protocol monitoring,  Next: The built-in protocol forwarding,  Prev: The built-in protocol expanding,  Up: Built-in protocols

1.6.9.2 The built-in protocol ‘monitoring’
..........................................

The built-in monitoring(1) protocol declares the *note before/3: 101.
and *note after/3: 102. public event handler predicates.  See the *note
Event-driven programming: 6d. section for more details.

   ---------- Footnotes ----------

   (1) ../../apis/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.96.0.info,  Node: The built-in protocol forwarding,  Prev: The built-in protocol monitoring,  Up: Built-in protocols

1.6.9.3 The built-in protocol ‘forwarding’
..........................................

The built-in forwarding(1) protocol declares the *note forward/1: 105.
user-defined message forwarding handler, which is automatically called
(if defined) by the runtime for any message that the receiving object
does not understand.  See also the *note []/1: 81. control construct.

   ---------- Footnotes ----------

   (1) ../../apis/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Multi-threading applications<2>,  Prev: Built-in protocols,  Up: Protocols

1.6.10 Multi-threading applications
-----------------------------------

When writing multi-threading applications, user-defined predicates
calling built-in predicates such as ‘create_protocol/3’ and
‘abolish_protocol/1’ may need to be declared synchronized in order to
avoid race conditions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Categories,  Next: Predicates,  Prev: Protocols,  Up: User Manual

1.7 Categories
==============

Categories are 'fine-grained units of code reuse' and can be regarded as
a dual concept of protocols.  Categories provide a way to encapsulate a
set of related predicate declarations and definitions that do not
represent a complete object and that only make sense when composed with
other predicates.  Categories may also be used to break a complex object
into functional units.  A category can be imported by several objects
(without code duplication), including objects participating in prototype
or class-based hierarchies.  This concept of categories shares some
ideas with Smalltalk-80 functional categories *note [Goldberg83]: 1c,
Flavors mix-ins *note [Moon86]: 10a. (without necessarily implying
multi-inheritance), and Objective-C categories *note [Cox86]: 1d.
Categories may also 'complement' existing objects, thus providing a
*note hot patching: 10b. mechanism inspired by the Objective-C
categories functionality.

Logtalk defines a built-in category, core_messages(1), which is
described at the end of this section.

* Menu:

* Defining a new category::
* Hot patching::
* Finding defined categories::
* Creating a new category at runtime::
* Abolishing an existing category::
* Category directives::
* Category relationships::
* Category properties::
* Importing categories::
* Calling category predicates::
* Parametric categories::
* Built-in categories::
* Multi-threading applications: Multi-threading applications<3>.

   ---------- Footnotes ----------

   (1) ../../apis/core_messages_0.html#core-messages-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining a new category,  Next: Hot patching,  Up: Categories

1.7.1 Defining a new category
-----------------------------

We can define a new category in the same way we write Prolog code: by
using a text editor.  Logtalk source files may contain one or more
objects, categories, or protocols.  If you prefer to define each entity
in its own source file, it is recommended that the file be named after
the category.  By default, all Logtalk source files use the extension
‘.lgt’ but this is optional and can be set in the adapter files.
Intermediate Prolog source files (generated by the Logtalk compiler)
have, by default, a ‘_lgt’ suffix and a ‘.pl’ extension.  Again, this
can be set to match the needs of a particular Prolog compiler in the
corresponding adapter file.  For example, we may define a category named
‘documenting’ and save it in a ‘documenting.lgt’ source file that will
be compiled to a ‘documenting_lgt.pl’ Prolog file (depending on the
*note backend compiler: 34, the names of the intermediate Prolog files
may include a directory hash and a process identifier to prevent file
name clashes when embedding Logtalk applications or running parallel
Logtalk processes).

Category names can be atoms or compound terms (when defining parametric
categories).  Objects, categories, and protocols share the same name
space: we cannot have a category with the same name as an object or a
protocol.

Category code (directives and predicates) is textually encapsulated by
using two Logtalk directives: *note category/1-4: 10e. and *note
end_category/0: 10f.  The most simple category will be one that is
self-contained, not depending on any other Logtalk entity:

     :- category(Category).
         ...
     :- end_category.

If a category implements one or more protocols, then the opening
directive will be:

     :- category(Category,
         implements([Protocol1, Protocol2, ...])).
         ...
     :- end_category.

A category may be defined as a composition of other categories by
writing:

     :- category(Category,
         extends([Category1, Category2, ...])).
         ...
     :- end_category.

This feature should only be used when extending a category without
breaking its functional cohesion (for example, when a modified version
of a category is needed for importing on several unrelated objects).
The preferred way of composing several categories is by importing them
into an object.  When a category overrides a predicate defined in an
extended category, the overridden definition can still be called by
using the *note (^^)/1: 5d. control construct.

Categories cannot inherit from objects.  In addition, categories cannot
define clauses for dynamic predicates.  This restriction applies because
a category can be imported by several objects and because we cannot use
the database handling built-in methods with categories (messages can
only be sent to objects).  A consequence of this restriction is that a
category cannot declare a predicate (or non-terminal) as both multifile
and dynamic.  However, categories may contain declarations for dynamic
predicates, and they can contain predicates that handle dynamic
predicates.  For example:

     :- category(attributes).

         :- public(attribute/2).
         :- public(set_attribute/2).
         :- public(del_attribute/2).

         :- private(attribute_/2).
         :- dynamic(attribute_/2).

         attribute(Attribute, Value) :-
             % called in the context of "self"
             ::attribute_(Attribute, Value).

         set_attribute(Attribute, Value) :-
             % retract old clauses in "self"
             ::retractall(attribute_(Attribute, _)),
             % assert new clause in "self"
             ::assertz(attribute_(Attribute, Value)).

         del_attribute(Attribute, Value) :-
             % retract clause in "self"
             ::retract(attribute_(Attribute, Value)).

     :- end_category.

Each object importing this category will have its own ‘attribute_/2’
private and dynamic predicate.  The predicates ‘attribute/2’,
‘set_attribute/2’, and ‘del_attribute/2’ always access and modify the
dynamic predicate contained in the object receiving the corresponding
messages (i.e., 'self').  But it’s also possible to define predicates
that handle dynamic predicates in the context of 'this' instead of
'self'.  For example:

     :- category(attributes).

         :- public(attribute/2).
         :- public(set_attribute/2).
         :- public(del_attribute/2).

         :- private(attribute_/2).
         :- dynamic(attribute_/2).

         attribute(Attribute, Value) :-
             % call in the context of "this"
             attribute_(Attribute, Value).

         set_attribute(Attribute, Value) :-
             % retract old clauses in "this"
             retractall(attribute_(Attribute, _)),
             % asserts clause in "this"
             assertz(attribute_(Attribute, Value)).

         del_attribute(Attribute, Value) :-
             % retract clause in "this"
             retract(attribute_(Attribute, Value)).

     :- end_category.

When defining a category that declares and handles dynamic predicates,
working in the context of 'this' ties those dynamic predicates to the
object importing the category, while working in the context of 'self'
allows each object inheriting from the object that imports the category
to have its own set of clauses for those dynamic predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Hot patching,  Next: Finding defined categories,  Prev: Defining a new category,  Up: Categories

1.7.2 Hot patching
------------------

A category may also explicitly complement one or more existing objects,
thus providing *note hot patching: 10b. functionality inspired by
Objective-C categories:

     :- category(Category,
         complements([Object1, Object2, ....])).
         ...
     :- end_category.

This allows us to add missing directives (e.g., to define *note aliases:
ca. for complemented object predicates), replace broken predicate
definitions, add new predicates, and add protocols and categories to
existing objects without requiring access or modifications to their
source code.  Common scenarios are adding logging or debugging
predicates to a set of objects.  Complemented objects need to be
compiled with the *note complements: 112. compiler flag set ‘allow’ (to
allow both patching and adding functionality) or ‘restrict’ (to allow
only adding new functionality).  A complementing category takes
preference over a previously loaded complementing category for the same
object, thus allowing patching a previous patch if necessary.

When replacing a predicate definition, it is possible to call the
overridden definition in the object from the new definition in the
category by using the *note (@)/1: 113. control construct.  This
construct is only meaningful when used within categories and requires a
compile-time bound goal argument, which is called in *note this: 114.
(i.e., in the context of the complemented object or the object importing
a category).  As an example, consider the following object:

     :- object(bird).

         :- set_logtalk_flag(complements, allow).

         :- public(make_sound/0).
         make_sound :-
             write('Chirp, chirp!'), nl.

     :- end_object.

We can use the ‘(@)/1’ control construct to wrap the original
‘make_sound/0’ predicate definition by writing:

     :- category(logging,
         complements(bird)).

         make_sound :-
             write('Started making sound...'), nl,
             @make_sound,
             write('... finished making sound.'), nl.

     :- end_category.

After loading the object and the category, calling the ‘make_sound/0’
predicate will result in the following output:

     | ?- bird::make_sound.

     Started making sound...
     Chirp, chirp!
     ... finished making sound.
     yes

Note that *note super calls: 115. from predicates defined in
complementing categories lookup inherited definitions as if the calls
were made from the complemented object instead of the category
ancestors.  This allows more comprehensive object patching.  But it also
means that, if you want to patch an object so that it imports a category
that extends another category and uses super calls to access the
extended category predicates, you will need to define a (possibly empty)
complementing category that extends the category that you want to add.

An unfortunate consequence of allowing an object to be patched at
runtime using a complementing category is that it disables the use of
*note static binding: 35. optimizations for messages sent to the
complemented object, as it can always be later patched, thus rendering
the static binding optimizations invalid.

Another important caveat is that, while a complementing category can
replace a predicate definition, local callers of the replaced predicate
will still call the non-patched version of the predicate.  This is a
consequence of the lack of a portable solution at the *note backend
Prolog compiler: 34. level for replacing static predicate definitions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Finding defined categories,  Next: Creating a new category at runtime,  Prev: Hot patching,  Up: Categories

1.7.3 Finding defined categories
--------------------------------

We can find, by backtracking, all defined categories by using the *note
current_category/1: f1. built-in predicate with an unbound argument:

     | ?- current_category(Category).

This predicate can also be used to test if a category is defined by
calling it with a valid category identifier (an atom or a compound
term).


File: TheLogtalkHandbook-3.96.0.info,  Node: Creating a new category at runtime,  Next: Abolishing an existing category,  Prev: Finding defined categories,  Up: Categories

1.7.4 Creating a new category at runtime
----------------------------------------

A category can be dynamically created at runtime by using the *note
create_category/4: 11a. built-in predicate:

     | ?- create_category(Category, Relations, Directives, Clauses).

The first argument should be either a variable or the name of the new
category (a Prolog atom, which must not match with an existing entity
name).  The remaining three arguments correspond to the relations
described in the opening category directive and to the category code
contents (directives and clauses).

For example, the call:

     | ?- create_category(
              ccc,
              [implements(ppp)],
              [private(bar/1)],
              [(foo(X):-bar(X)), bar(1), bar(2)]
          ).

is equivalent to compiling and loading the category:

     :- category(ccc,
         implements(ppp)).

         :- dynamic.

         :- private(bar/1).

         foo(X) :-
             bar(X).

         bar(1).
         bar(2).

     :- end_category.

If we need to create a lot of (dynamic) categories at runtime, then it
is best to define a metaclass or a prototype with a predicate that will
call this built-in predicate in order to provide more sophisticated
behavior.


File: TheLogtalkHandbook-3.96.0.info,  Node: Abolishing an existing category,  Next: Category directives,  Prev: Creating a new category at runtime,  Up: Categories

1.7.5 Abolishing an existing category
-------------------------------------

Dynamic categories can be abolished using the *note abolish_category/1:
f5. built-in predicate:

     | ?- abolish_category(Category).

The argument must be an identifier of a defined dynamic category;
otherwise, an error will be thrown.


File: TheLogtalkHandbook-3.96.0.info,  Node: Category directives,  Next: Category relationships,  Prev: Abolishing an existing category,  Up: Categories

1.7.6 Category directives
-------------------------

Category directives are used to define category properties, document
category dependencies on other Logtalk entities, and load the contents
of files into a category.

* Menu:

* Dynamic categories::
* Category documentation::
* Loading files into a category::
* Declaring object aliases: Declaring object aliases<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Dynamic categories,  Next: Category documentation,  Up: Category directives

1.7.6.1 Dynamic categories
..........................

As usually happens with Prolog code, a category can be either static or
dynamic.  A category created during the execution of a program is always
dynamic.  A category defined in a file can be either dynamic or static.
Dynamic categories are declared by using the *note dynamic/0: b1.
directive in the category source code:

     :- dynamic.

The directive must precede any predicate directives or clauses.  Please
be aware that using dynamic code results in a performance hit when
compared to static code.  We should only use dynamic categories when
these need to be abolished during program execution.


File: TheLogtalkHandbook-3.96.0.info,  Node: Category documentation,  Next: Loading files into a category,  Prev: Dynamic categories,  Up: Category directives

1.7.6.2 Category documentation
..............................

A category can be documented with arbitrary user-defined information by
using the *note info/1: b4. entity directive.  See the *note
Documenting: b5. section for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading files into a category,  Next: Declaring object aliases<2>,  Prev: Category documentation,  Up: Category directives

1.7.6.3 Loading files into a category
.....................................

The *note include/1: b8. directive can be used to load the contents of a
file into a category.  See the *note Objects: 91. section for an example
of using this directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Declaring object aliases<2>,  Prev: Loading files into a category,  Up: Category directives

1.7.6.4 Declaring object aliases
................................

The *note uses/1: 4a. directive can be used to declare object aliases.
The typical uses of this directive are to shorten long object names and
to simplify experimenting with different object implementations of the
same protocol when using explicit message-sending.


File: TheLogtalkHandbook-3.96.0.info,  Node: Category relationships,  Next: Category properties,  Prev: Category directives,  Up: Categories

1.7.7 Category relationships
----------------------------

Logtalk provides two sets of built-in predicates that enable us to query
the system about the relationships that a category has with other
entities.

The built-in predicates *note implements_protocol/2-3: c1. and *note
conforms_to_protocol/2-3: c2. allow us to find which categories
implement which protocols:

     | ?- implements_protocol(Category, Protocol, Scope).

or, if we also want to consider inherited protocols:

     | ?- conforms_to_protocol(Category, Protocol, Scope).

Note that, if we use an unbound first argument, we will need to use the
*note current_category/1: f1. built-in predicate to ensure that the
returned entity is a category and not an object.

To find which objects import which categories, we can use the *note
imports_category/2-3: c0. built-in predicates:

     | ?- imports_category(Object, Category).

or, if we also want to know the importation scope:

     | ?- imports_category(Object, Category, Scope).

Note that a category may be imported by several objects.

To find which categories extend other categories, we can use the *note
extends_category/2-3: 129. built-in predicates:

     | ?- extends_category(Category1, Category2).

or, if we also want to know the extension scope:

     | ?- extends_category(Category1, Category2, Scope).

Note that a category may be extended by several categories.

To find which categories explicitly complement existing objects we can
use the *note complements_object/2: c3. built-in predicate:

     | ?- complements_object(Category, Object).

Note that a category may explicitly complement several objects.


File: TheLogtalkHandbook-3.96.0.info,  Node: Category properties,  Next: Importing categories,  Prev: Category relationships,  Up: Categories

1.7.8 Category properties
-------------------------

We can find the properties of defined categories by calling the built-in
predicate *note category_property/2: 12c.:

     | ?- category_property(Category, Property).

The following category properties are supported:

‘static’

     The category is static

‘dynamic’

     The category is dynamic (and thus can be abolished in runtime by
     calling the *note abolish_category/1: f5. built-in predicate)

‘built_in’

     The category is a built-in category (and thus always available)

‘file(Path)’

     Absolute path of the source file defining the category (if
     applicable)

‘file(Basename, Directory)’

     Basename and directory of the source file defining the category (if
     applicable); ‘Directory’ always ends with a ‘/’

‘lines(BeginLine, EndLine)’

     Source file begin and end lines of the category definition (if
     applicable)

‘directive(BeginLine, EndLine)’

     Source file begin and end lines of the category opening directive
     (if applicable)

‘events’

     Messages sent from the category generate events

‘source_data’

     Source data available for the category

‘public(Resources)’

     List of public predicates and operators declared by the category

‘protected(Resources)’

     List of protected predicates and operators declared by the category

‘private(Resources)’

     List of private predicates and operators declared by the category

‘declares(Predicate, Properties)’

     List of *note properties: c8. for a predicate declared by the
     category

‘defines(Predicate, Properties)’

     List of *note properties: c8. for a predicate defined by the
     category

‘includes(Predicate, Entity, Properties)’

     List of *note properties: c8. for an object multifile predicate
     that are defined in the specified entity (the properties include
     ‘number_of_clauses(Number)’, ‘number_of_rules(Number)’,
     ‘lines(Start,End)’, and ‘line_count(Start)’ with ‘Start-End’ being
     the line range of the first multifile predicate clause)

‘provides(Predicate, Entity, Properties)’

     List of *note properties: c8. for other entity multifile predicate
     that are defined in the category (the properties include
     ‘number_of_clauses(Number)’, ‘number_of_rules(Number)’,
     ‘lines(Start,End)’, and ‘line_count(Start)’ with ‘Start-End’ being
     the line range of the first multifile predicate clause)

‘references(Reference, Properties)’

     List of *note properties: c8. for other references to entities in
     calls to the execution-context built-in methods and in directives
     for multifile predicates and multifile non-terminals that are found
     in the category (the properties include ‘in(Context)’,
     ‘non_terminal(NonTerminal)’, ‘include(File)’, ‘lines(Start,End)’,
     and ‘line_count(Start)’ with ‘Start-End’ being the line range of
     the first reference, a directive, a predicate clause, or a
     non-terminal grammar rule; the possible values for ‘Context’ are
     ‘multifile’, ‘dynamic’, ‘discontiguous’, ‘meta_predicate’,
     ‘meta_non_terminal’, and ‘clause’); ‘Reference’ can be either
     ‘Entity’ or ‘Entity::Functor/Arity’

‘alias(Entity, Properties)’

     List of *note properties: c8. for an *note entity alias: c9.
     declared by the object (the properties include ‘object’ in case of
     an object alias, ‘module’ in case of a module alias,
     ‘for(Original)’, ‘lines(Start,End)’, and ‘line_count(Start)’ with
     ‘Start-End’ being the line range of the ‘uses/1’ or ‘use_module/1’
     directive)

‘alias(Predicate, Properties)’

     List of *note properties: c8. for a *note predicate alias: ca.
     declared by the category (the properties include ‘predicate’,
     ‘for(Original)’, ‘from(Entity)’, ‘non_terminal(NonTerminal)’,
     ‘lines(Start,End)’, and ‘line_count(Start)’ with ‘Start-End’ being
     the line range of the alias directive)

‘calls(Call, Properties)’

     List of *note properties: c8. for predicate calls made by the
     category (‘Call’ is either a predicate indicator or a control
     construct such as ‘(::)/1-2’ or ‘(^^)/1’ with a predicate indicator
     as argument; note that ‘Call’ may not be ground in case of a call
     to a control construct where its argument is only know at runtime;
     the properties include ‘caller(Caller)’, ‘alias(Alias)’,
     ‘non_terminal(NonTerminal)’, ‘lines(Start,End)’, and
     ‘line_count(Start)’ with ‘Caller’, ‘Alias’, and ‘NonTerminal’ being
     predicate indicators and ‘Start-End’ being the line range of the
     predicate clause or directive making the call)

‘updates(Predicate, Properties)’

     List of *note properties: c8. for dynamic predicate updates (and
     also access using the ‘clause/2’ predicate) made by the object
     (‘Predicate’ is either a predicate indicator or a control construct
     such as ‘(::)/1-2’ or ‘(:)/2’ with a predicate indicator as
     argument; note that ‘Predicate’ may not be ground in case of a
     control construct argument only know at runtime; the properties
     include ‘updater(Updater)’, ‘alias(Alias)’,
     ‘non_terminal(NonTerminal)’, ‘lines(Start,End)’, and
     ‘line_count(Start)’ with ‘Updater’ being a (possibly multifile)
     predicate indicator, ‘Alias’ and ‘NonTerminal’ being predicate
     indicators, and ‘Start-End’ being the line range of the predicate
     clause or directive updating the predicate)

‘number_of_clauses(Number)’

     Total number of predicate clauses defined in the category (includes
     both user-defined clauses and auxiliary clauses generated by the
     compiler or by the *note expansion hooks: cb. but does not include
     clauses for multifile predicates defined for other entities or
     clauses for the category own multifile predicates contributed by
     other entities)

‘number_of_rules(Number)’

     Total number of predicate rules defined in the category (includes
     both user-defined rules and auxiliary rules generated by the
     compiler or by the *note expansion hooks: cb. but does not include
     rules for multifile predicates defined for other entities or rules
     for the category own multifile predicates contributed by other
     entities)

‘number_of_user_clauses(Number)’

     Total number of user-defined predicate clauses defined in the
     category (does not include clauses for multifile predicates defined
     for other entities or clauses for the category own multifile
     predicates contributed by other entities)

‘number_of_user_rules(Number)’

     Total number of user-defined predicate rules defined in the
     category (does not include rules for multifile predicates defined
     for other entities or rules for the category own multifile
     predicates contributed by other entities)

Some properties, such as line numbers, are only available when the
category is defined in a source file compiled with the *note
source_data: cc. flag turned on.  Moreover, line numbers are only
supported in *note backend Prolog compilers: 34. that provide access to
the start line of a read term.  When such support is not available, the
value ‘-1’ is returned for the start and end lines.

The properties that return the number of clauses (rules) report the
clauses (rules) 'textually defined in the object' for both multifile and
non-multifile predicates.  Thus, these numbers exclude clauses (rules)
for multifile predicates 'contributed' by other entities.


File: TheLogtalkHandbook-3.96.0.info,  Node: Importing categories,  Next: Calling category predicates,  Prev: Category properties,  Up: Categories

1.7.9 Importing categories
--------------------------

Any number of objects can import a category.  In addition, an object may
import any number of categories.  The syntax is very simple:

     :- object(Object,
         imports([Category1, Category2, ...])).
         ...
     :- end_object.

To make all public predicates imported via a category protected, or to
make all public and protected predicates private, we prefix the
category’s name with the corresponding keyword:

     :- object(Object,
         imports(private::Category)).
         ...
     :- end_object.

or:

     :- object(Object,
         imports(protected::Category)).
         ...
     :- end_object.

Omitting the scope keyword is equivalent to writing:

     :- object(Object,
         imports(public::Category)).
         ...
     :- end_object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling category predicates,  Next: Parametric categories,  Prev: Importing categories,  Up: Categories

1.7.10 Calling category predicates
----------------------------------

Category predicates can be called from within an object by sending a
message to 'self' or using a 'super' call.  Consider the following
category:

     :- category(output).

         :- public(out/1).

         out(X) :-
             write(X), nl.

     :- end_category.

The predicate ‘out/1’ can be called from within an object importing the
category by simply sending a message to 'self'.  For example:

     :- object(worker,
         imports(output)).

         ...
         do(Task) :-
             execute(Task, Result),
             ::out(Result).
         ...

     :- end_object.

This is the recommended way of calling a category predicate that can be
specialized/overridden in a descendant object, as the predicate
definition lookup will start from 'self'.

A direct call to a predicate definition found in an imported category
can be made using the *note (^^)/1: 5d. control construct.  For example:

     :- object(worker,
         imports(output)).

         ...
         do(Task) :-
             execute(Task, Result),
             ^^out(Result).
         ...

     :- end_object.

This alternative should only be used when the user knows a priori that
the category predicates will not be specialized or redefined by
descendant objects of the object importing the category.  Its advantage
is that, when the *note optimize: 8c. flag is turned on, the Logtalk
compiler will try to optimize the calls by using *note static binding:
35.  When *note dynamic binding: 36. is used due to e.g.  the lack of
sufficient information at compilation time, the performance is similar
to calling the category predicate using a message to *note self: 69. (in
both cases, a predicate lookup caching mechanism is used).


File: TheLogtalkHandbook-3.96.0.info,  Node: Parametric categories,  Next: Built-in categories,  Prev: Calling category predicates,  Up: Categories

1.7.11 Parametric categories
----------------------------

Category predicates can be parameterized in the same way as object
predicates by using a compound term as the category identifier where all
the arguments of the compound term are variables.  These variables, the
'category parameters', can be accessed by calling the *note parameter/2:
a2. or *note this/1: 68. built-in local methods in the category
predicate clauses or by using *note parameter variables: a1.

Category parameter values can be defined by the importing objects.  For
example:

     :- object(speech(Season, Event),
         imports([dress(Season), speech(Event)])).
         ...
     :- end_object.

Note that access to category parameters is only possible from within the
category.  In particular, calls to the *note this/1: 68. built-in local
method from category predicates always access the importing object
identifier (and thus object parameters, not category parameters).


File: TheLogtalkHandbook-3.96.0.info,  Node: Built-in categories,  Next: Multi-threading applications<3>,  Prev: Parametric categories,  Up: Categories

1.7.12 Built-in categories
--------------------------

Logtalk defines a built-in category that is always available for any
application.

* Menu:

* The built-in category core_messages::


File: TheLogtalkHandbook-3.96.0.info,  Node: The built-in category core_messages,  Up: Built-in categories

1.7.12.1 The built-in category ‘core_messages’
..............................................

The built-in core_messages(1) category provides default translations for
all compiler and runtime printed messages, such as warnings and errors.
It does not define any public predicates.

   ---------- Footnotes ----------

   (1) ../../apis/core_messages_0.html#core-messages-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Multi-threading applications<3>,  Prev: Built-in categories,  Up: Categories

1.7.13 Multi-threading applications
-----------------------------------

When writing multi-threading applications, user-defined predicates
calling built-in predicates such as ‘create_category/4’ and
‘abolish_category/1’ may need to be declared synchronized in order to
avoid race conditions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Predicates,  Next: Inheritance,  Prev: Categories,  Up: User Manual

1.8 Predicates
==============

Predicate directives and clauses can be encapsulated inside objects and
categories.  Protocols can only contain predicate directives.  From the
point of view of a traditional imperative object-oriented language,
predicates allow both object state and object behavior to be
represented.  Mutable object state can be represented using dynamic
object predicates but should only be used when strictly necessary, as it
breaks declarative semantics.

* Menu:

* Reserved predicate names::
* Declaring predicates::
* Defining predicates::
* Definite clause grammar rules::
* Built-in methods::
* Predicate properties::
* Finding declared predicates::
* Calling Prolog predicates::
* Defining Prolog multifile predicates::
* Asserting and retracting Prolog predicates::


File: TheLogtalkHandbook-3.96.0.info,  Node: Reserved predicate names,  Next: Declaring predicates,  Up: Predicates

1.8.1 Reserved predicate names
------------------------------

For practical and performance reasons, some predicate names have a fixed
interpretation.  These predicates are declared in the built-in
protocols.  They are: *note goal_expansion/2: fd. and *note
term_expansion/2: fc, declared in the expanding(1) protocol; *note
before/3: 101. and *note after/3: 102, declared in the monitoring(2)
protocol; and *note forward/1: 105, declared in the forwarding(3)
protocol.  By default, the compiler prints a warning when a definition
for one of these predicates is found but the reference to the
corresponding built-in protocol is missing.

   ---------- Footnotes ----------

   (1) ../../apis/expanding_0.html#expanding-0

   (2) ../../apis/monitoring_0.html#monitoring-0

   (3) ../../apis/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Declaring predicates,  Next: Defining predicates,  Prev: Reserved predicate names,  Up: Predicates

1.8.2 Declaring predicates
--------------------------

Logtalk provides a clear distinction between 'declaring a predicate' and
'defining a predicate' and thus clear *note closed-world assumption: 6a.
semantics.  Messages or calls for declared but undefined predicates
fail.  Messages or calls for unknown (i.e., non-declared) predicates
throw an error.  Note that this is a fundamental requirement for
supporting *note protocols: d9.: we must be able to declare a predicate
without necessarily defining it.

All object (or category) predicates that we want to access from other
objects (or categories) must be explicitly declared.  A predicate
declaration must contain, at least, a 'scope' directive.  Other
directives may be used to document the predicate or to ensure proper
compilation of the predicate clauses.

* Menu:

* Scope directives::
* Mode directive::
* Meta-predicate directive::
* Discontiguous directive::
* Dynamic directive::
* Operator directive::
* Uses directive::
* Alias directive::
* Documenting directive::
* Multifile directive::
* Coinductive directive::
* Synchronized directive::


File: TheLogtalkHandbook-3.96.0.info,  Node: Scope directives,  Next: Mode directive,  Up: Declaring predicates

1.8.2.1 Scope directives
........................

A predicate scope directive specifies 'from where' the predicate can be
called, i.e.  its 'visibility'.  Predicates can be 'public',
'protected', 'private', or 'local'.  Public predicates can be called
from any object.  Protected predicates can only be called from the
container object or from a container descendant.  Private predicates can
only be called from the container object.  Predicates are local when
they are not declared in a scope directive.  Local predicates, like
private predicates, can only be called from the container object (or
category), but they are 'invisible' to the reflection built-in methods
(*note current_predicate/1: 141. and *note predicate_property/2: 142.)
and to the message error handling mechanisms (i.e., sending a message
corresponding to a local predicate results in a ‘predicate_declaration’
existence error instead of a scope error).

The scope declarations are made using the directives *note public/1:
143, *note protected/1: 144, and *note private/1: 145.  For example:

     :- public(init/1).

     :- protected(valid_init_option/1).

     :- private(process_init_options/1).

If a predicate does not have a (local or inherited) scope declaration,
it is assumed that the predicate is local.  Note that we do not need to
write scope declarations for all defined predicates.  One exception is
local dynamic predicates: declaring them as private predicates may allow
the Logtalk compiler to generate optimized code for asserting and
retracting clauses.

Note that a predicate scope directive doesn’t specify 'where' a
predicate is, or can be, defined.  For example, a private predicate can
only be called from an object holding its scope directive.  But it can
be defined in descendant objects.  A typical example is an object
playing the role of a class defining a private (possibly dynamic)
predicate for its descendant instances.  Only the class can call (and
possibly assert/retract clauses for) the predicate, but its clauses can
be found/defined in the instances themselves.

Scope directives may also be used to declare grammar rule non-terminals
and operators.  For example:

     :- public(url//1).

     :- public(op(800, fx, tag)).

Note that, in the case of operators, the operator definitions don’t
become global when the entity containing the directives is compiled and
loaded.  This prevents an application from breaking when, for example,
an updated third-party library adds new operators.  It also allows
loading entities that provide conflicting operator definitions.  Here
the usual programming idiom is to copy the operator definitions to a
‘uses/2’ directive.  For example, the *note lgtunit: 146. tool makes
available a ‘(=~=)/2’ predicate (for approximate float equality) that is
intended to be used as an infix operator:

     :- uses(lgtunit, [
         op(700, xfx, =~=), (=~=)/2
     ]).

Thus, in practice, the solution to use library entity operators in
client entities is the same for using library entity predicates with
implicit message-sending.


File: TheLogtalkHandbook-3.96.0.info,  Node: Mode directive,  Next: Meta-predicate directive,  Prev: Scope directives,  Up: Declaring predicates

1.8.2.2 Mode directive
......................

Often predicates can only be called using specific argument patterns.
The valid arguments and instantiation modes of those arguments can be
documented using the *note mode/2: 149. directive (in the case of
'non-terminals', there’s also a *note mode_non_terminal/2: 14a.
directive).  For example:

     :- mode(member(?term, ?list), zero_or_more).
The first directive argument describes a valid 'calling mode'.  The
minimum information will be the instantiation mode of each argument.
The first four possible values are described in the ISO Prolog Core
standard *note [ISO95]: 31. (but with the meaning of the ‘-’
instantiation mode redefined here).  The remaining two can also be found
in use in some Prolog systems.

‘+’

     Argument must be instantiated (but not necessarily ground).

‘-’

     Argument should be a free (non-instantiated) variable.  When bound,
     the call will unify the computed term with the given argument.

‘?’

     Argument can either be instantiated or free.

‘@’

     Argument will not be further instantiated (modified).

‘++’

     Argument must be ground.

‘--’

     Argument must be unbound.  Used mainly when returning an opaque
     term (e.g., a stream handle).

Note that the ‘+’ and ‘@’ instantiation modes have the same meaning for
atomic arguments.  E.g.  you can write either ‘+atom’ or ‘@atom’ but the
first alternative is preferred.

The ISO ‘-’ instantiation mode is equivalent to the Logtalk ‘--’ mode,
allowing the use ‘-’ to document predicates with output arguments that
don’t require those arguments to be unbound at call time and also accept
bound arguments without throwing an exception.

These six mode atoms are also declared as prefix operators by the
Logtalk compiler.  This makes it possible to include type information
for each argument as in the example above.  Some possible type values
are: ‘event’, ‘object’, ‘category’, ‘protocol’, ‘callable’, ‘term’,
‘nonvar’, ‘var’, ‘atomic’, ‘atom’, ‘number’, ‘integer’, ‘float’,
‘compound’, and ‘list’.  The first four are Logtalk specific.  The
remaining are common Prolog types.  We can also use our own types that
can be either atoms or ground compound terms.  See the *note types: 14c.
library documentation for an extensive list of pre-defined types that
cover most common use cases.  The second directive argument documents
the 'number of proofs', but not necessarily distinct solutions, for the
specified mode.  As an example, the ‘member(X, [1,1,1,1])’ goal has only
one distinct solution but four proofs for that solution.  Note that
different modes for the same predicate often have different determinism.
The possible values are:

‘zero’

     Predicate always fails (e.g., the ‘false/0’ standard predicate).

‘one’

     Predicate always succeeds once (e.g., the ‘flush_output/0’ standard
     predicate).

‘zero_or_one’

     Predicate either fails or succeeds (e.g., the ‘atom/1’ standard
     predicate).

‘zero_or_more’

     Predicate has zero or more proofs (e.g., the ‘current_predicate/1’
     standard predicate).

‘one_or_more’

     Predicate has one or more proofs (e.g., the ‘repeat/0’ standard
     predicate).

‘zero_or_error’

     Predicate either fails or throws an error.

‘one_or_error’

     Predicate either succeeds once or throws an error (e.g., the
     ‘open/3’ standard predicate).

‘zero_or_one_or_error’

     Predicate succeeds once or fails or throws an error (e.g., the
     ‘get_char/1’ standard predicate).

‘zero_or_more_or_error’

     Predicate may fail or succeed multiple times or throw an error
     (e.g., the ‘retract/1’ standard predicate).

‘one_or_more_or_error’

     Predicate may succeed one or more times or throw an error.

‘error’

     Predicate will throw an error (e.g., the ‘type_error/2’ built-in
     method).

The last six values support documenting that some call modes may throw
an error or will throw an error 'despite the call arguments complying
with the expected types and instantiation modes'.  As an example,
consider the ‘open/3’ standard predicate:

     :- mode(open(@source_sink, @io_mode, --stream), one_or_error).

In this case, the mode directive tells the user that a valid call can
still throw an error (there may be e.g.  a permission error opening the
specified source or sink).

Notice that using the ‘zero’, ‘one’, ‘zero_or_one’, ‘zero_or_more’, or
‘one_or_more’ modes is not only for predicates that never throw an
exception; they can also be used for any predicate that doesn’t throw an
exception when the arguments are valid.  For example, the
‘current_predicate/1’ standard predicate throws an exception if the
argument is neither a variable nor a predicate indicator, but it
succeeds zero or more times when its argument is valid:

     :- mode(current_predicate(?predicate_indicator), zero_or_more).

Some predicates have more than one valid mode, thus implying several
mode directives.  For example, to document the possible use modes of the
standard ‘atom_concat/3’ predicate, we would write:

     :- mode(atom_concat(?atom, ?atom, +atom), one_or_more).
     :- mode(atom_concat(+atom, +atom, -atom), one).

The first ‘mode/2’ directive specifies that the ‘atom_concat/3’
predicate can be used to split an atom into a prefix and a suffix.  The
second ‘mode/2’ directive specifies that concatenating two atoms results
in a new atom.  There are often several alternative ‘mode/2’ directives
that can be used to specify a predicate.  For example, an alternative to
the second ‘mode/2’ directive above would be:

     :- mode(atom_concat(+atom, +atom, ?atom), zero_or_one).

In this case, the same information is provided by both alternatives.
But the first alternative is simpler and thus preferred.

Some old Prolog compilers supported some sort of mode directives to
improve performance.  To the best of my knowledge, there is no modern
Prolog compiler supporting this kind of directive for that purpose.  The
current Logtalk version simply parses this directive for collecting its
information for use in the *note reflection API: 48. (assuming the *note
source_data: cc. flag is turned on).  In any case, the use of mode
directives is a good starting point for documenting your predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate directive,  Next: Discontiguous directive,  Prev: Mode directive,  Up: Declaring predicates

1.8.2.3 Meta-predicate directive
................................

Some predicates may have arguments that will be called as goals,
interpreted as *note closures: 14f. that will be used for constructing
goals, or passing meta-arguments to calls to other meta-predicates.  To
ensure that these goals will be executed in the correct context (i.e.,
in the *note calling context: 150, not in the meta-predicate *note
definition context: 151.), we need to use the *note meta_predicate/1:
152. directive (in the case of 'meta non-terminals', there’s also a
*note meta_non_terminal/1: 153. directive).  For example:

     :- meta_predicate(findall(*, 0, *)).
     :- meta_predicate(map(2, *, *)).

The meta-predicate mode arguments in this directive have the following
meaning:

‘0’

     Meta-argument that will be called as a goal.

‘N’

     Meta-argument that will be a closure used to construct a call by
     extending it with ‘N’ arguments.  The value of ‘N’ must be a
     positive integer.

‘::’

     Argument that is context-aware but that will not be called as a
     goal or a closure.  It can contain, however, sub-terms that will be
     called as goals or closures.

‘^’

     Goal that may be existentially quantified (‘Vars^Goal’).

‘*’

     Normal argument.

The following meta-predicate mode arguments are for use only when
writing backend Prolog *note adapter files: 154. to deal with
proprietary built-in meta-predicates and meta-directives:

‘/’

     Predicate indicator (‘Name/Arity’), list of predicate indicators,
     or conjunction of predicate indicators.

‘//’

     Non-terminal indicator (‘Name//Arity’), list of predicate
     indicators, or conjunction of predicate indicators.

‘[0]’

     List of goals.

‘[N]’

     List of closures.

‘[/]’

     List of predicate indicators.

‘[//]’

     List of non-terminal indicators.

To the best of my knowledge, the use of non-negative integers to specify
closures was first introduced on Quintus Prolog for providing
information for predicate cross-reference tools.

Note that Logtalk meta-predicate semantics are different from Prolog
meta-predicate semantics (assuming a predicate-based module system as
common):

   - Meta-arguments are always called in the meta-predicate calling
     context, independent of using explicit or implicit message-sending
     (to the object defining the meta-predicate when not local).  Most
     Prolog systems have different semantics for explicit versus
     implicit module qualification.

   - Logtalk is not based on a predicate prefixing mechanism.
     Therefore, the meta-predicate directive is required for any
     predicate with meta-arguments (including when simply passing the
     meta-arguments to a call to another meta-predicate).  This is
     usually not required in Prolog systems due to the module prefixing
     of meta-arguments.

   - Sending a message from a meta-predicate definition to call a
     meta-predicate defined in another object resets the calling context
     for any passed meta-argument to the object sending the message
     (including for messages to 'self').  Meta-arguments behave
     differently in Prolog systems due to their module prefixing.

   - Logtalk protects from common scenarios where specially crafted
     meta-predicate definitions are used to break object (and category)
     encapsulation by changing the meta-arguments passed by client code
     or trying to subvert the implicit calling context to call client
     predicates other than the predicates passed as meta-arguments.

     Warning: As each Logtalk entity is independently compiled, this
     directive must be included in every object or category that
     contains a definition for the described meta-predicate, even if the
     meta-predicate declaration is inherited from another entity, to
     ensure proper compilation of meta-arguments.


File: TheLogtalkHandbook-3.96.0.info,  Node: Discontiguous directive,  Next: Dynamic directive,  Prev: Meta-predicate directive,  Up: Declaring predicates

1.8.2.4 Discontiguous directive
...............................

The clause of an object (or category) predicate may not be contiguous.
In that case, we must declare the predicate discontiguous by using the
*note discontiguous/1: 157. directive:

     :- discontiguous(foo/1).

This is a directive that we should avoid using: it makes your code
harder to read, and it is not supported by some Prolog backends.

     Warning: As each Logtalk entity is compiled independently of other
     entities, this directive must be included in every object or
     category that contains a definition for the described predicate
     (even if the predicate declaration is inherited from another
     entity).


File: TheLogtalkHandbook-3.96.0.info,  Node: Dynamic directive,  Next: Operator directive,  Prev: Discontiguous directive,  Up: Declaring predicates

1.8.2.5 Dynamic directive
.........................

An object predicate can be static or dynamic.  By default, all
predicates (and non-terminals) of static objects defined in source files
are static.  To declare a dynamic predicate (or non-terminal), we use
the *note dynamic/1: 15a. directive.  For example:

     :- dynamic(foo/1).

Predicates of objects dynamically created at runtime (using the *note
create_object/4: 62. built-in predicate) and predicates of dynamic
objects defined in source files (using the *note dynamic/0: b1.
directive) are implicitly dynamic.

Dynamic predicates can be used to represent persistent mutable object
state.  Note that static objects may declare and define dynamic
predicates.  Categories can only declare dynamic predicates (with the
importing objects holding the predicate definitions).

     Warning: As each Logtalk entity is compiled independently from
     other entities, this directive must be included in every object
     that contains a definition for the described predicate (even if the
     predicate declaration is inherited from another object or imported
     from a category).  If we omit the dynamic declaration then the
     predicate definition will be compiled static.


File: TheLogtalkHandbook-3.96.0.info,  Node: Operator directive,  Next: Uses directive,  Prev: Dynamic directive,  Up: Declaring predicates

1.8.2.6 Operator directive
..........................

An object (or category) predicate can be declared as an operator using
the familiar *note op/3: 15d. directive:

     :- op(Priority, Specifier, Operator).

Operators are local to the object (or category) where they are declared.
This means that, if you declare a public predicate as an operator, you
cannot use operator notation when sending to an object (where the
predicate is visible) the respective message (as this would imply
visibility of the operator declaration in the context of the 'sender' of
the message).  If you want to declare global operators and, at the same
time, use them inside an entity, just write the corresponding directives
at the top of your source file, before the entity opening directive.

Note that operators can also be declared using a scope directive.  Only
these operators are visible to the *note current_op/3: 15e. reflection
method.

When the same operators are used on several entities within the same
source file, the corresponding directives must either be repeated in
each entity or appear before any entity that uses them.  But in the
later case, this results in a global scope for the operators.  If you
prefer the operators to be local to the source file, just 'undefine'
them at the end of the file.  For example:

     % before any entity that uses the operator
     :- op(400, xfx, results).

     ...

     % after all entities that used the operator
     :- op(0, xfx, results).

Global operators can be declared in the application loader file.


File: TheLogtalkHandbook-3.96.0.info,  Node: Uses directive,  Next: Alias directive,  Prev: Operator directive,  Up: Declaring predicates

1.8.2.7 Uses directive
......................

When a predicate makes heavy use of predicates defined on other objects,
its predicate clauses can be verbose due to all the necessary
message-sending goals.  Consider the following example:

     foo :-
         ...,
         findall(X, list::member(X, L), A),
         list::append(A, B, C),
         list::select(Y, C, R),
         ...

Logtalk provides a directive, *note uses/2: 4b, which allows us to
simplify the code above.  One of the usage templates for this directive
is:

     :- uses(Object, [
         Name1/Arity1, Name2/Arity2, ...
     ]).

Rewriting the code above using this directive results in a simplified
and more readable predicate definition:

     :- uses(list, [
         append/3, member/2, select/3
     ]).

     foo :-
         ...,
         findall(X, member(X, L), A),
         append(A, B, C),
         select(Y, C, R),
         ...

Logtalk also supports an extended version of this directive that allows
the declaration of *note predicate aliases: ca. using the notation
‘Predicate as Alias’ (or the alternative notation ‘Predicate::Alias’).
For example:

     :- uses(btrees, [new/1 as new_btree/1]).
     :- uses(queues, [new/1 as new_queue/1]).

You may use this extended version for solving conflicts between
predicates declared on several ‘uses/2’ directives or just for giving
new names to the predicates that will be more meaningful on their using
context.

Predicate aliases can also be used to define *note predicate shorthands:
161, simplifying code maintenance.  For example:

     :- uses(pretty_printer, [
         indent(4, Term) as indent(Term)
     ]).

Assuming multiple calls to the shorthand, a change to the indent value
will require a change to a single line instead of changing every call.

Another common use of predicate aliases is changing the order of the
predicate arguments without using *note lambda expressions: 162.  For
example:

     :- uses(meta, [
         fold_left(Closure, Result0, List, Result) as foldl(Closure, List, Result0, Result)
     ]).

See the directive documentation for details and other examples.

The ‘uses/2’ directive allows simpler predicate definitions as long as
there are no conflicts between the predicates declared in the directive
and the predicates defined in the object (or category) containing the
directive.  A predicate (or its alias if defined) cannot be listed in
more than one ‘uses/2’ directive.  In addition, a ‘uses/2’ directive
cannot list a predicate (or its alias if defined) that is defined in the
object (or category) containing the directive.  Any conflicts are
reported by Logtalk as compilation errors.

The object identifier argument can also be a *note parameter variable:
a1. when using the directive in a parametric object or a parametric
category.  In this case, *note dynamic binding: 36. will necessarily be
used for all listed predicates (and non-terminals).  The parameter
variable must be instantiated at runtime when the messages are sent.
This feature simplifies experimenting with multiple implementations of
the same protocol (for example, to evaluate the performance of each
implementation for a particular case).  It also simplifies writing tests
that check multiple implementations of the same protocol.

An object (or category) can make a predicate listed in a ‘uses/2’ (or
‘use_module/2’) directive part of its protocol by simply adding a scope
directive for the predicate.  For example, in the ‘statistics’ library
we have:

     :- public(modes/2).
     :- uses(numberlist, [modes/2]).

Therefore, a goal such as ‘sample::modes(Sample, Modes)’ implicitly
calls ‘numberlist::modes(Sample, Modes)’ without requiring an explicit
local definition for the ‘modes/2’ predicate (which would trigger a
compilation error).


File: TheLogtalkHandbook-3.96.0.info,  Node: Alias directive,  Next: Documenting directive,  Prev: Uses directive,  Up: Declaring predicates

1.8.2.8 Alias directive
.......................

Logtalk allows the definition of an alternative name for an inherited or
imported predicate (or for an inherited or imported grammar rule
non-terminal) through the use of the *note alias/2: 165. directive:

     :- alias(Entity, [
         Predicate1 as Alias1,
         Predicate2 as Alias2,
         ...
     ]).

This directive can be used in objects, protocols, or categories.  The
first argument, ‘Entity’, must be an entity referenced in the opening
directive of the entity containing the ‘alias/2’ directive.  It can be
an extended or implemented protocol, an imported category, an extended
prototype, an instantiated class, or a specialized class.  The second
argument is a list of pairs of predicate indicators (or grammar rule
non-terminal indicators) using the ‘as’ infix operator.

A common use for the ‘alias/2’ directive is to give an alternative name
to an inherited predicate in order to improve readability.  For example:

     :- object(square,
         extends(rectangle)).

         :- alias(rectangle, [width/1 as side/1]).

         ...

     :- end_object.

The directive allows both ‘width/1’ and ‘side/1’ to be used as messages
to the object ‘square’.  Thus, using this directive, there is no need to
explicitly declare and define a “new” ‘side/1’ predicate.  Note that the
‘alias/2’ directive does not rename a predicate, it only provides an
alternative, additional name; the original name continues to be
available (although it may be masked due to the default inheritance
conflict mechanism).

Another common use for this directive is to solve conflicts when two
inherited predicates have the same name and arity.  We may want to call
the predicate that is masked out by the Logtalk lookup algorithm (see
the *note Inheritance: 8. section) or we may need to call both
predicates.  This is simply accomplished by using the ‘alias/2’
directive to give alternative names to masked-out or conflicting
predicates.  Consider the following example:

     :- object(my_data_structure,
         extends(list, set)).

         :- alias(list, [member/2 as list_member/2]).
         :- alias(set,  [member/2 as set_member/2]).

         ...

     :- end_object.

Assuming that both ‘list’ and ‘set’ objects define a ‘member/2’
predicate, without the ‘alias/2’ directives, only the definition of
‘member/2’ predicate in the object ‘list’ would be visible on the object
‘my_data_structure’, as a result of the application of the Logtalk
predicate lookup algorithm.  By using the ‘alias/2’ directives, all the
following messages would be valid (assuming a public scope for the
predicates):

     % uses list member/2
     | ?- my_data_structure::list_member(X, L).

     % uses set member/2
     | ?- my_data_structure::set_member(X, L).

     % uses list member/2
     | ?- my_data_structure::member(X, L).

When used this way, the ‘alias/2’ directive provides functionality
similar to programming constructs of other object-oriented languages
that support multi-inheritance (the most notable example probably being
the renaming of inherited features in Eiffel).

Note that the ‘alias/2’ directive never hides a predicate that is
visible on the entity containing the directive as a result of the
Logtalk lookup algorithm.  However, it may be used to make visible a
predicate that otherwise would be masked by another predicate, as
illustrated in the above example.

The ‘alias/2’ directive may also be used to give access to an inherited
predicate, which otherwise would be masked by another inherited
predicate, while keeping the original name as follows:

     :- object(my_data_structure,
         extends(list, set)).

         :- alias(list, [member/2 as list_member/2]).
         :- alias(set,  [member/2 as set_member/2]).

         member(X, L) :-
             ^^set_member(X, L).

         ...

     :- end_object.

Thus, when sending the message ‘member/2’ to ‘my_data_structure’, the
predicate definition in ‘set’ will be used instead of the one contained
in ‘list’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Documenting directive,  Next: Multifile directive,  Prev: Alias directive,  Up: Declaring predicates

1.8.2.9 Documenting directive
.............................

A predicate can be documented with arbitrary user-defined information by
using the *note info/2: 168. directive:

     :- info(Name/Arity, List).

The second argument is a list of ‘Key is Value’ terms.  See the *note
Documenting: b5. section for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Multifile directive,  Next: Coinductive directive,  Prev: Documenting directive,  Up: Declaring predicates

1.8.2.10 Multifile directive
............................

A predicate can be declared *note multifile: 16b. by using the *note
multifile/1: 16c. directive:

     :- multifile(Name/Arity).

This allows clauses for a predicate to be defined in several objects
and/or categories.  This is a directive that should be used with care.
It’s commonly used in the definition of *note hook predicates: 16d.
Multifile predicates (and non-terminals) may also be declared dynamic
using the same predicate (or non-terminal) notation (multifile
predicates are static by default).

Logtalk precludes using a multifile predicate for breaking object
encapsulation by checking that the object (or category) declaring the
predicate (using a scope directive) defines it also as multifile.  This
entity is said to contain the 'primary declaration' for the multifile
predicate.  Entities containing primary multifile predicate declarations
must always be compiled before entities defining clauses for those
multifile predicates.  The Logtalk compiler will print a warning if the
scope directive is missing.  Note also that the ‘multifile/1’ directive
is mandatory when defining multifile predicates.

Consider the following simple example:

     :- object(main).

         :- public(a/1).
         :- multifile(a/1).
         a(1).

     :- end_object.

After compiling and loading the ‘main’ object, we can define other
objects (or categories) that contribute with clauses for the multifile
predicate.  For example:

     :- object(other).

         :- multifile(main::a/1).
         main::a(2).
         main::a(X) :-
             b(X).

         b(3).
         b(4).

     :- end_object.

After compiling and loading the above objects, you can use queries such
as:

     | ?- main::a(X).

     X = 1 ;
     X = 2 ;
     X = 3 ;
     X = 4
     yes

Note that the order of multifile predicate clauses depends on several
factors, including loading order and compiler implementation details.
Therefore, your code should never assume or rely on a specific order of
the multifile predicate clauses.

When a clause of a multifile predicate is a rule, its body is compiled
within the context of the object or category defining the clause.  This
allows clauses for multifile predicates to call local object or category
predicates.  But the values of the 'sender', 'this', and 'self' in the
implicit execution context are passed from the clause head to the clause
body.  This is necessary to ensure that these values are always valid
and to allow multifile predicate clauses to be defined in categories.  A
call to the ‘parameter/2’ execution context methods, however, retrieves
parameters of the entity defining the clause, not from the entity for
which the clause is defined.  The parameters of the entity for which the
clause is defined can be accessed by simple unification at the clause
head.

Multifile predicate rules should not contain cuts, as these may prevent
other clauses for the predicate from being used by callers.  The
compiler prints by default a warning when a cut is found in a multifile
predicate definition.

Local calls to the database methods from multifile predicate clauses
defined in an object take place in the object’s own database instead of
the database of the entity holding the multifile predicate primary
declaration.  Similarly, local calls to the ‘expand_term/2’ and
‘expand_goal/2’ methods from a multifile predicate clause look for
clauses of the ‘term_expansion/2’ and ‘goal_expansion/2’ hook predicates
starting from the entity defining the clause instead of the entity
holding the multifile predicate primary declaration.  Local calls to the
‘current_predicate/1’, ‘predicate_property/2’, and ‘current_op/3’
methods from multifile predicate clauses defined in an object also
lookup predicates and their properties in the object’s own database
instead of the database of the entity holding the multifile predicate
primary declaration.


File: TheLogtalkHandbook-3.96.0.info,  Node: Coinductive directive,  Next: Synchronized directive,  Prev: Multifile directive,  Up: Declaring predicates

1.8.2.11 Coinductive directive
..............................

A predicate can be declared *note coinductive: 170. by using the *note
coinductive/1: 171. directive.  For example:

     :- coinductive(comember/2).

Logtalk support for coinductive predicates is experimental and requires
a *note backend Prolog compiler: 34. with minimal support for cyclic
terms.  The value of the read-only *note coinduction flag: 172. is set
to ‘supported’ for the backend Prolog compilers providing that support.


File: TheLogtalkHandbook-3.96.0.info,  Node: Synchronized directive,  Prev: Coinductive directive,  Up: Declaring predicates

1.8.2.12 Synchronized directive
...............................

A predicate can be declared *note synchronized: 175. by using the *note
synchronized/1: 74. directive.  For example:

     :- synchronized(write_log_entry/2).
     :- synchronized([produce/1, consume/1]).

See the section on *note synchronized predicates: 176. for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining predicates,  Next: Definite clause grammar rules,  Prev: Declaring predicates,  Up: Predicates

1.8.3 Defining predicates
-------------------------

* Menu:

* Object predicates::
* Category predicates::
* Meta-predicates::
* Lambda expressions::
* Redefining built-in predicates::


File: TheLogtalkHandbook-3.96.0.info,  Node: Object predicates,  Next: Category predicates,  Up: Defining predicates

1.8.3.1 Object predicates
.........................

We define object predicates as we have always defined Prolog predicates,
the only difference being that we have four more control structures (the
three message-sending operators plus the external call operator) to play
with.  For example, if we wish to define an object containing common
utility list predicates like ‘append/2’ or ‘member/2’ we could write
something like:

     :- object(list).

         :- public(append/3).
         append([], L, L).
         append([H| T], L, [H| T2]) :-
             append(T, L, T2).

         :- public(member/2).
         member(H, [H| _]).
         member(H, [_| T]) :-
             member(H, T).

     :- end_object.

Note that, abstracting from the opening and closing object directives
and the scope directives, what we have written is also valid Prolog
code.  Calls in a predicate definition body default to the local
predicates unless we use the message-sending operators or the external
call operator.  This simplifies conversion from plain Prolog code to
Logtalk objects: often we just need to add the necessary encapsulation
and scope directives to the old code.


File: TheLogtalkHandbook-3.96.0.info,  Node: Category predicates,  Next: Meta-predicates,  Prev: Object predicates,  Up: Defining predicates

1.8.3.2 Category predicates
...........................

A category can only contain clauses for static predicates.  But there
are no restrictions in declaring and calling dynamic predicates from
inside a category.  Because a category can be imported by multiple
objects, dynamic predicates must be called either in the context of
*note self: 69, using the *note message to self: 17d. control structure,
*note (;;)/1: 5c, or in the context of *note this: 114. (i.e., in the
context of the object importing the category).  For example, if we want
to define a category implementing attributes using the dynamic database
of 'self' we could write:

     :- category(attributes).

         :- public(get/2).
         :- public(set/2).

         :- private(attribute_/2).
         :- dynamic(attribute_/2).

         get(Var, Value) :-
             ::attribute_(Var, Value).

         set(Var, Value) :-
             ::retractall(attribute_(Var, _)),
             ::asserta(attribute_(Var, Value).

     :- end_category.

In this case, the ‘get/2’ and ‘set/2’ predicates will always
access/update the correct definition, contained in the object receiving
the messages.

In alternative, if we want a category implementing attributes using the
dynamic database of 'this', we would write instead:

     :- category(attributes).

         :- public(get/2).
         :- public(set/2).

         :- private(attribute_/2).
         :- dynamic(attribute_/2).

         get(Var, Value) :-
             attribute_(Var, Value).

         set(Var, Value) :-
             retractall(attribute_(Var, _)),
             asserta(attribute_(Var, Value).

     :- end_category.

In this case, each object importing the category will have its own
clauses for the ‘attribute_/2’ private dynamic predicate.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicates,  Next: Lambda expressions,  Prev: Category predicates,  Up: Defining predicates

1.8.3.3 Meta-predicates
.......................

Meta-predicates may be defined inside objects and categories as any
other predicate.  A meta-predicate is declared using the *note
meta_predicate/1: 152. directive as described earlier in this section.
When defining a meta-predicate, the arguments in the clause heads
corresponding to the meta-arguments must be variables.  All
meta-arguments are called in the context of the object or category
calling the meta-predicate.  In particular, when sending a message that
corresponds to a meta-predicate, the meta-arguments are called in the
context of the object or category sending the message.

The most simple example is a meta-predicate with a meta-argument that is
called as a goal.  E.g.  the *note ignore/1: 180. built-in predicate
could be defined as:

     :- public(ignore/1).
     :- meta_predicate(ignore(0)).

     ignore(Goal) :-
        (Goal -> true; true).

The ‘0’ in the meta-predicate template tells us that the meta-argument
is a goal that will be called by the meta-predicate.

Some meta-predicates have meta-arguments that are not goals but *note
closures: 14f.  Logtalk supports the definition of meta-predicates that
are called with closures instead of goals as long as the definition uses
the *note call/1-N: 181. built-in predicate to call the closure with the
additional arguments.  A classical example is a list mapping predicate:

     :- public(map/2).
     :- meta_predicate(map(1, *)).

     map(_, []).
     map(Closure, [Arg| Args]) :-
         call(Closure, Arg),
         map(Closure, Args).

Note that in this case the meta-predicate directive specifies that the
closure will be extended with exactly one additional argument.  When
calling a meta-predicate, a closure can correspond to a user-defined
predicate, a built-in predicate, a *note lambda expression: 182, or a
control construct.

In some cases, it is not a meta-argument but one of its sub-terms that
is called as a goal or used as a closure.  For example:

     :- public(call_all/1).
     :- meta_predicate(call_all(::)).

     call_all([]).
     call_all([Goal| Goals]) :-
         call(Goal),
         call_all(Goals).

The ‘::’ mode indicator in the meta-predicate template allows the
corresponding argument in the meta-predicate definition to be a
non-variable term and instructs the compiler to look into the argument
sub-terms for goal and closure *note meta-variables: 183.

When a meta-predicate calls another meta-predicate, both predicates
require ‘meta_predicate/1’ directives.  For example, the ‘map/2’
meta-predicate defined above is usually implemented by exchanging the
argument order to take advantage of first-argument indexing:

     :- meta_predicate(map(1, *)).
     map(Closure, List) :-
         map_(List, Closure).

     :- meta_predicate(map_(*, 1)).
     map_([], _).
     map_([Head| Tail], Closure) :-
         call(Closure, Head),
         map_(Tail, Closure).

Note that Logtalk, unlike most Prolog module systems, is not based on a
predicate prefixing mechanism.  Thus, the meta-argument calling context
is not part of the meta-argument itself.


File: TheLogtalkHandbook-3.96.0.info,  Node: Lambda expressions,  Next: Redefining built-in predicates,  Prev: Meta-predicates,  Up: Defining predicates

1.8.3.4 Lambda expressions
..........................

The use of lambda expressions(1) as meta-predicate goal and *note
closure: 14f. arguments often saves writing auxiliary predicates for the
sole purpose of calling the meta-predicates.  A simple example of a
lambda expression is:

     | ?- meta::map([X,Y]>>(Y is 2*X), [1,2,3], Ys).
     Ys = [2,4,6]
     yes

In this example, a lambda expression, ‘[X,Y]>>(Y is 2*X)’, is used as an
argument to the ‘map/3’ list mapping predicate, defined in the library
object ‘meta’, in order to double the elements of a list of integers.
Using a lambda expression avoids writing an auxiliary predicate for the
sole purpose of doubling the list elements.  The 'lambda parameters' are
represented by the list ‘[X,Y]’, which is connected to the 'lambda
goal', ‘(Y is 2*X)’, by the ‘(>>)/2’ operator.  The ‘map/3’ predicate
calls the lambda goal with fresh/unique variables, represented by the
‘X’ and ‘Y’ parameters, for each pair of elements of the second and
third list arguments.

Currying is supported.  I.e.  it is possible to write a lambda
expression whose goal is another lambda expression.  The above example
can be rewritten as:

     | ?- meta::map([X]>>([Y]>>(Y is 2*X)), [1,2,3], Ys).
     Ys = [2,4,6]
     yes

Lambda expressions may also contain 'lambda-free variables'.  I.e.
variables that are global to the lambda expression and shared with the
surrounding meta-call context.  Consider the following variant of the
previous example:

     | ?- between(1, 3, N), meta::map({N}/[X,Y]>>(Y is N*X), [1,2,3], L).
     N = 1, L = [1,2,3] ;
     N = 2, L = [2,4,6] ;
     N = 3, L = [3,6,9]
     yes

In this case, the lambda-free variable, ‘N’, bound by the ‘between/3’
goal, is fixed across all implicit calls made by the ‘map/3’ goal.

A second example of free variables in a lambda expression using GNU
Prolog as the backend compiler:

     | ?- meta::map({Z}/[X,Y]>>(Z#=X+Y), [1,2,3], Zs).
     Z = _#22(3..268435455)
     Zs = [_#3(2..268435454),_#66(1..268435453),_#110(0..268435452)]
     yes

The ISO Prolog construct ‘{}/1’ is used for representing the lambda-free
variables as this representation is often associated with set
representation.  Note that the order of the free variables is of no
consequence (on the other hand, a list is used for the lambda parameters
as their order does matter).

Both lambda free variables and lambda parameters can be any Prolog term.
Consider the following example by Markus Triska:

     | ?- meta::map([A-B,B-A]>>true, [1-a,2-b,3-c], Zs).
     Zs = [a-1,b-2,c-3]
     yes

Lambda expressions can be used, as expected, in non-deterministic
queries, as in the following example using SWI-Prolog as the backend
compiler and Markus Triska’s CLP(FD) library:

     | ?- meta::map({Z}/[X,Y]>>(clpfd:(Z#=X+Y)), Xs, Ys).
     Xs = [],
     Ys = [] ;
     Xs = [_G1369],
     Ys = [_G1378],
     _G1369+_G1378#=Z ;
     Xs = [_G1579, _G1582],
     Ys = [_G1591, _G1594],
     _G1582+_G1594#=Z,
     _G1579+_G1591#=Z ;
     Xs = [_G1789, _G1792, _G1795],
     Ys = [_G1804, _G1807, _G1810],
     _G1795+_G1810#=Z,
     _G1792+_G1807#=Z,
     _G1789+_G1804#=Z ;
     ...

As illustrated by the above examples, lambda expression syntax reuses
the ISO Prolog construct ‘{}/1’ and the standard operators ‘(/)/2’ and
‘(>>)/2’, thus avoiding defining new operators, which is always tricky
for a portable system such as Logtalk.  The operator ‘(>>)/2’ was chosen
as it suggests an arrow, similar to the syntax used in other languages
such as OCaml and Haskell to connect lambda parameters with lambda
functions.  This syntax was also chosen in order to simplify parsing,
error checking, and compilation of lambda expressions.  The full
specification of the lambda expression syntax can be found in the *note
language grammar: 185.

The compiler checks whenever possible that all variables in a lambda
expression are either classified as free variables or as lambda
parameters.  Non-classified variables in a lambda goal (including any
anonymous variables) should be regarded as a programming error.  The
compiler also checks whenever possible if a variable is classified as
both a free variable and a lambda parameter.  There are a few cases
where a variable playing a dual role is intended, but, in general, this
also results from a programming error.  A third check verifies that no
lambda parameter variable is used elsewhere in a clause.  Such cases are
either programming errors, when the variable appears before the lambda
expression, or bad programming style, when the variable is used after
the lambda expression.  These linter warnings are controlled by the
*note lambda_variables: 186. flag.  Note that the dynamic features of
the language and lack of sufficient information at compile-time may
prevent the compiler from checking all uses of lambda expressions.  To
improve linter coverage, compile code using lambda expressions with the
*note optimize flag: 8c. turned on, as that will result in additional
cases of meta-arguments being evaluated for possible optimizations.

     Warning: Variables listed in lambda parameters must not be shared
     with other goals in a clause.

An optimizing meta-predicate and lambda expression compiler, based on
the *note term-expansion mechanism: cb, is provided as a standard
library for practical performance.

A common use of lambda expressions as closure meta-arguments is to
workaround closures always being extended by 'appending' additional
arguments to construct a goal.  For example, assume that we want to
filter a list of atoms by a given length.  We can use the standard
‘atom_length/2’ predicate despite the argument order by writing:

     filter(Length, Atoms, Filtered) :-
         meta::include({Length}/[Atom]>>atom_length(Atom,Length), Atoms, Filtered).

But Logtalk supports a faster alternative by using predicate aliases to
change the argument order when calling library or built-in predicates:

     :- uses(user, [
        atom_length(Atom, Length) as length_atom(Length, Atom)
     ]).

     filter(Length, Atoms, Filtered) :-
         meta::include(length_atom(Length), Atoms, Filtered).

In this case, the performance is no longer dependent on compiling away
lambda expressions.  The resulting code is also easier to read (and thus
debug and maintain).  But the ‘uses/2’ directive is implicitly defining
an auxiliary predicate, which is exactly what we wanted to avoid in the
first place by using a lambda expression.

   ---------- Footnotes ----------

   (1) https://en.wikipedia.org/wiki/Lambda_calculus


File: TheLogtalkHandbook-3.96.0.info,  Node: Redefining built-in predicates,  Prev: Lambda expressions,  Up: Defining predicates

1.8.3.5 Redefining built-in predicates
......................................

Logtalk built-in predicates and Prolog built-in predicates can be
redefined inside objects and categories.  Although the redefinition of
Logtalk built-in predicates should be avoided, the support for
redefining Prolog built-in predicates is a practical requirement given
the different sets of proprietary built-in predicates provided by
backend Prolog systems.

The compiler supports a *note redefined_built_ins: 189. flag, whose
default value is ‘silent’, that can be set to ‘warning’ to alert the
user of any redefined Logtalk or Prolog built-in predicate.

The redefinition of Prolog built-in predicates can be combined with the
*note conditional compilation directives: 18a. when writing portable
applications where some of the supported backends don’t provide a
built-in predicate found in the other backends.  As an example, consider
the de facto standard ‘msort/2’ predicate (which sorts a list while
keeping duplicates).  This predicate is provided as a built-in predicate
in most but not all backends.  The ‘list’ library object includes the
code:

     :- if(predicate_property(msort(_, _), built_in)).

         msort(List, Sorted) :-
             {msort(List, Sorted)}.

     :- else.

         length(List, Length) :-
             ...

     :- endif.

I.e.  the object will use the built-in predicate when available.
Otherwise, it will use the predicate definition provided by the ‘list’
object.

The redefinition of built-in predicates can also be accomplished using
*note predicate shorthands: 161.  This can be useful when porting code
while minimizing the changes.  For example, assume that existing code
uses the ‘format/2’ de facto standard predicate for writing messages.
To convert the code to use the *note message printing mechanism: 18b, we
could write:

     :- uses(logtalk, [
         print_message(comment, core, Format+Arguments) as format(Format, Arguments)
     ]).

     process(Crate, Contents) :-
         format('Processing crate ~w...', [Crate]),
         ...,
         format('Filing with ~w...', [Contents]),
         ....

The predicate shorthand instructs the compiler to rewrite all ‘format/2’
goals as ‘logtalk::print_message/3’ goals, thus allowing us to reuse the
code without changes.


File: TheLogtalkHandbook-3.96.0.info,  Node: Definite clause grammar rules,  Next: Built-in methods,  Prev: Defining predicates,  Up: Predicates

1.8.4 Definite clause grammar rules
-----------------------------------

Definite clause grammar rules (DCGs) provide a convenient notation to
represent the parsing and rewrite rules common of most grammars in
Prolog.  In Logtalk, definite clause grammar rules can be encapsulated
in objects and categories.  Currently, the ISO/IEC WG17 group is working
on a draft specification for a definite clause grammars Prolog standard.
Therefore, in the meantime, Logtalk follows the common practice of
Prolog compilers supporting definite clause grammars, extending it to
support calling grammar rules contained in categories and objects.  A
common example of a definite clause grammar is the definition of a set
of rules for parsing simple arithmetic expressions:

     :- object(calculator).

         :- public(parse/2).

         parse(Expression, Value) :-
             phrase(expr(Value), Expression).

         expr(Z) --> term(X), "+", expr(Y), {Z is X + Y}.
         expr(Z) --> term(X), "-", expr(Y), {Z is X - Y}.
         expr(X) --> term(X).

         term(Z) --> number(X), "*", term(Y), {Z is X * Y}.
         term(Z) --> number(X), "/", term(Y), {Z is X / Y}.
         term(Z) --> number(Z).

         number(C) --> "+", number(C).
         number(C) --> "-", number(X), {C is -X}.
         number(X) --> [C], {0'0 =< C, C =< 0'9, X is C - 0'0}.

     :- end_object.

After compiling and loading this object, we can test the grammar rules
using the ‘parse/2’ message:

     | ?- calculator::parse("1+2-3*4", Result).

     Result = -9
     yes

The non-terminals can be called from predicates using the private
built-in methods *note phrase/2: 18e. and *note phrase/3: 18f. as shown
in the example above.  When we want to use the built-in methods
‘phrase/2’ and ‘phrase/3’, the non-terminal used as in the first
argument must be within the scope of the 'sender'.  For the above
example, assuming that we want the predicate corresponding to the
‘expr//1’ non-terminal to be public, the corresponding scope directive
would be:

     :- public(expr//1).

The ‘//’ infix operator used above tells the Logtalk compiler that the
scope directive refers to a grammar rule non-terminal, not to a
predicate.  The idea is that the predicate corresponding to the
translation of the ‘expr//1’ non-terminal will have a number of
arguments equal to one plus the number of additional arguments necessary
for processing the implicit difference list of tokens.

In the body of a grammar rule, we can call rules that are inherited from
ancestor objects, imported from categories, or contained in other
objects.  This is accomplished by using non-terminals as messages.
Using a non-terminal as a message to 'self' allows us to call grammar
rules in categories and ancestor objects.  To call grammar rules
encapsulated in other objects, we use a non-terminal as a message to
those objects.  Consider the following example, containing grammar rules
for parsing natural language sentences:

     :- object(sentence,
         imports(determiners, nouns, verbs)).

         :- public(parse/2).

         parse(List, true) :-
             phrase(sentence, List).
         parse(_, false).

         sentence --> noun_phrase, verb_phrase.

         noun_phrase --> ::determiner, ::noun.
         noun_phrase --> ::noun.

         verb_phrase --> ::verb.
         verb_phrase --> ::verb, noun_phrase.

     :- end_object.

The categories imported by the object would contain the necessary
grammar rules for parsing determiners, nouns, and verbs.  For example:

     :- category(determiners).

         :- private(determiner//0).

         determiner --> [the].
         determiner --> [a].

     :- end_category.

Along with the message-sending operators (‘(::)/1’, ‘(::)/2’, and
‘(^^)/1’), we may also use other control constructs such as ‘(<<)/2’,
‘(\+)/1’, ‘!/0’, ‘(;)/2’, ‘(->)/2’, ‘{}/1’, ‘call//1-N’, and ‘catch/3’
in the body of a grammar rule.  When using a backend Prolog compiler
that supports modules, we may also use the ‘(:)/2’ control construct.

     Warning: The semantics of ‘(\+)/1’ and ‘(->)/2’ control constructs
     in grammar rules with a terminal or a non-terminal in the 'first'
     argument are problematic due to unrestricted lookahead that may or
     may not be valid depending on the grammar rule implicit arguments.
     By default, the linter will print warnings for such calls
     (controlled by the *note grammar_rules: 190. flag).  Preferably
     restrict the use of the ‘(\+)/1’ control construct to ‘{}/1’
     arguments and the use of the ‘(->)/2’ control construct to ‘{}/1’
     test arguments.

In addition, grammar rules may contain meta-calls (a variable taking the
place of a non-terminal), which are translated to calls of the built-in
method ‘phrase//1’.  The *note meta_non_terminal/1: 153. directive
allows the declaration of non-terminals that have arguments that are
meta-called from grammar rules.  For example:

     :- meta_non_terminal(zero_or_more(1, *)).

     zero_or_more(Closure, [Terminal| Terminals]) -->
         call(Closure, Terminal), !, zero_or_more(Closure, Terminals).
     zero_or_more(_, []) -->
         [].

You may have noticed that Logtalk defines *note {}/1: 191. as a control
construct for bypassing the compiler when compiling a clause body goal.
As exemplified above, this is the same control construct that is used in
grammar rules for bypassing the expansion of rule body goals when a rule
is converted into a clause.  Both control constructs can be combined in
order to call a goal from a grammar rule body, while bypassing at the
same time the Logtalk compiler.  Consider the following example:

     bar :-
         write('bar predicate called'), nl.


     :- object(bypass).

         :- public(foo//0).

         foo --> {{bar}}.

     :- end_object.

After compiling and loading this code, we may try the following query:

     | ?- logtalk << phrase(bypass::foo, _, _).

     bar predicate called
     yes

This is the expected result, as the expansion of the grammar rule into a
clause leaves the ‘{bar}’ goal untouched, which, in turn, is converted
into the goal ‘bar’ when the clause is compiled.  Note that we tested
the ‘bypass::foo//0’ non-terminal by calling the ‘phrase/3’ built-in
method in the context of the ‘logtalk’ built-in object.  This workaround
is necessary due to the Prolog backend implementation of the ‘phrase/3’
predicate not being aware of the Logtalk ‘(::)/2’ message-sending
control construct semantics.

A grammar rule non-terminal may be declared as dynamic or discontiguous,
as any object predicate, using the same ‘Name//Arity’ notation
illustrated above for the scope directives.  In addition, grammar rule
non-terminals can be documented using the *note info/2: 168. directive,
as in the following example:

     :- public(sentence//0).

     :- info(sentence//0, [
         comment is 'Rewrites sentence into noun and verb phrases.'
     ]).

     Note: Future Logtalk versions may compile grammar rules differently
     from Prolog traditional compilation to prevent name clashes between
     non-terminals and predicates.  Therefore, you should always call
     non-terminals from predicates using the ‘phrase/2-3’ built-in
     methods and always call predicates from grammar rules using the
     ‘call//1’ built-in method.  This recommended practice, besides
     making your code forward compatible with future Logtalk versions,
     also makes the code more clear.  The linter prints warnings when
     these guidelines are not followed (notably, when a predicate is
     called as a non-terminal or a non-terminal is called as a
     predicate).


File: TheLogtalkHandbook-3.96.0.info,  Node: Built-in methods,  Next: Predicate properties,  Prev: Definite clause grammar rules,  Up: Predicates

1.8.5 Built-in methods
----------------------

Built-in methods are built-in object and category predicates.  These
include methods to access message execution context, to find sets of
solutions, to inspect objects, for database handling, for term and goal
expansion, and for printing messages.  Some of them are counterparts to
standard Prolog built-in predicates that take into account Logtalk
semantics.  Similar to Prolog built-in predicates, built-in methods
cannot be redefined.

* Menu:

* Logic and control methods::
* Execution context methods::
* Error handling and throwing methods::
* Database methods::
* Meta-call methods::
* All solutions methods::
* Reflection methods::
* Definite clause grammar parsing methods and non-terminals::


File: TheLogtalkHandbook-3.96.0.info,  Node: Logic and control methods,  Next: Execution context methods,  Up: Built-in methods

1.8.5.1 Logic and control methods
.................................

The *note !/0: 196, *note true/0: 197, *note fail/0: 198, *note false/0:
199, and *note repeat/0: 19a. standard control constructs and logic
predicates are interpreted as built-in public methods and thus can be
used as messages to any object.  In practice, they are only used as
messages when sending multiple messages to the same object (see the
section on *note message broadcasting: 84.).


File: TheLogtalkHandbook-3.96.0.info,  Node: Execution context methods,  Next: Error handling and throwing methods,  Prev: Logic and control methods,  Up: Built-in methods

1.8.5.2 Execution context methods
.................................

Logtalk defines five built-in private methods to access an object
execution context.  These methods are in the common usage scenarios
translated to a single unification performed at compile-time with a
clause head context argument.  Therefore, they can be freely used
without worrying about performance penalties.  When called from inside a
category, these methods refer to the execution context of the object
importing the category.  These methods are private and cannot be used as
messages to objects.

To find the object that received the message under execution, we may use
the *note self/1: 67. method.  We may also retrieve the object that has
sent the message under execution using the *note sender/1: 19d. method.

The method *note this/1: 68. enables us to retrieve the name of the
object for which the predicate clause whose body is being executed is
defined instead of using the name directly.  This helps to avoid
breaking the code if we decide to change the object name and forget to
change the name references.  This method may also be used from within a
category.  In this case, the method returns the object importing the
category on whose behalf the predicate clause is being executed.

Here is a short example including calls to these three object execution
context methods:

     :- object(test).

         :- public(test/0).

         test :-
             this(This),
             write('Calling predicate definition in '),
             writeq(This), nl,
             self(Self),
             write('to answer a message received by '),
             writeq(Self), nl,
             sender(Sender),
             write('that was sent by '),
             writeq(Sender), nl, nl.

     :- end_object.


     :- object(descendant,
         extends(test)).

     :- end_object.

After compiling and loading these two objects, we can try the following
goal:

     | ?- descendant::test.

     Calling predicate definition in test
     to answer a message received by descendant
     that was sent by user
     yes

Note that the goals ‘self(Self)’, ‘sender(Sender)’, and ‘this(This)’,
being translated to unifications with the clause head context arguments
at compile-time, are effectively removed from the clause body.
Therefore, a clause such as:

     predicate(Arg) :-
         self(Self),
         atom(Arg),
         ... .

is compiled with the goal ‘atom(Arg)’ as the first condition on the
clause body.  As such, the use of these context execution methods does
not interfere with the optimizations that some Prolog compilers perform
when the first clause body condition is a call to a built-in type-test
predicate or a comparison operator.

For parametric objects and categories, the method *note parameter/2: a2.
enables us to retrieve current parameter values (see the section on
*note parametric objects: 66. for a detailed description).  For example:

     :- object(block(_Color)).

         :- public(test/0).

         test :-
             parameter(1, Color),
             write('Color parameter value is '),
             writeq(Color), nl.

     :- end_object.

An alternative to the ‘parameter/2’ predicate is to use *note parameter
variables: a1.:

     :- object(block(_Color_)).

         :- public(test/0).

         test :-
             write('Color parameter value is '),
             writeq(_Color_), nl.

     :- end_object.

After compiling and loading either version of the object, we can try the
following goal:

     | ?- block(blue)::test.

     Color parameter value is blue
     yes

Calls to the ‘parameter/2’ method are translated to a compile-time
unification when the second argument is a variable.  When the second
argument is bound, the calls are translated to a call to the built-in
predicate ‘arg/3’.

When type-checking predicate arguments, it is often useful to include
the predicate execution context when reporting an argument error.  The
*note context/1: 19e. method provides access to that context.  For
example, assume a predicate ‘foo/2’ that takes an atom and an integer as
arguments.  We could type-check the arguments by writing (using the
library ‘type’ object):

     foo(A, N) :-
         % type-check arguments
         context(Context),
         type::check(atom, A, Context),
         type::check(integer, N, Context),
         % arguments are fine; go ahead
         ... .


File: TheLogtalkHandbook-3.96.0.info,  Node: Error handling and throwing methods,  Next: Database methods,  Prev: Execution context methods,  Up: Built-in methods

1.8.5.3 Error handling and throwing methods
...........................................

Besides the *note catch/3: 1a1. and *note throw/1: 1a2. methods
inherited from Prolog, Logtalk also provides a set of convenience
methods to throw standard ‘error/2’ exception terms: *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note existence_error/2:
1a7, *note permission_error/3: 1a8, *note representation_error/1: 1a9,
*note evaluation_error/1: 1aa, *note resource_error/1: 1ab, *note
syntax_error/1: 1ac, and *note system_error/0: 1ad.  When using these
methods, the second argument of the ‘error/2’ exception term is bound to
the execution context (as it would be provided by the *note context/1:
19e. method).


File: TheLogtalkHandbook-3.96.0.info,  Node: Database methods,  Next: Meta-call methods,  Prev: Error handling and throwing methods,  Up: Built-in methods

1.8.5.4 Database methods
........................

Logtalk provides a set of built-in methods for *note object database:
1b0. handling similar to the usual database Prolog predicates: *note
abolish/1: 1b1, *note asserta/1: 1b2, *note assertz/1: 1b3, *note
clause/2: 1b4, *note retract/1: 1b5, and *note retractall/1: 1b6.  These
methods always operate on the database of the object receiving the
corresponding message.  When called locally, these predicates take into
account any *note uses/2: 4b. or *note use_module/2: 4d. directives that
refer to the dynamic predicate being handled.  For example, in the
following object, the clauses for the ‘data/1’ predicate are retracted
and asserted in ‘user’ due to the ‘uses/2’ directive:

     :- object(an_object).

         :- uses(user, [data/1]).

         :- public(some_predicate/1).
         some_predicate(Arg) :-
             retractall(data(_)),
             assertz(data(Arg)).

     :- end_object.

When working with dynamic grammar rule non-terminals, you may use the
built-in method *note expand_term/2: 1b7. convert a grammar rule into a
clause that can then be used with the database methods.

Logtalk also supports ‘asserta/2’, ‘assertz/2’, ‘clause/3’, and
‘erase/1’ built-in methods when run with a backend that supports the
corresponding legacy built-in predicates that work with *note clause
references: 1b8.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-call methods,  Next: All solutions methods,  Prev: Database methods,  Up: Built-in methods

1.8.5.5 Meta-call methods
.........................

Logtalk supports the generalized *note call/1-N: 181. meta-predicate.
This built-in private meta-predicate must be used in the implementation
of meta-predicates that work with *note closures: 14f. instead of goals.
In addition, Logtalk supports the built-in private meta-predicates *note
ignore/1: 180, *note once/1: 1bb, and *note (\+)/1: 1bc.  These methods
cannot be used as messages to objects.


File: TheLogtalkHandbook-3.96.0.info,  Node: All solutions methods,  Next: Reflection methods,  Prev: Meta-call methods,  Up: Built-in methods

1.8.5.6 All solutions methods
.............................

The usual all solutions meta-predicates are built-in private methods in
Logtalk: *note bagof/3: 1bf, *note findall/3: 1c0, *note findall/4: 1c1,
and *note setof/3: 1c2.  There is also a *note forall/2: 1c3. method
that implements generate-and-test loops.  These methods cannot be used
as messages to objects.


File: TheLogtalkHandbook-3.96.0.info,  Node: Reflection methods,  Next: Definite clause grammar parsing methods and non-terminals,  Prev: All solutions methods,  Up: Built-in methods

1.8.5.7 Reflection methods
..........................

Logtalk provides a comprehensive set of built-in predicates and built-in
methods for querying about entities and predicates.  Some of the
information, however, requires that the source files are compiled with
the *note source_data: cc. flag turned on.

The *note reflection API: 48. supports two different views on entities
and their contents, which we may call the 'transparent box view' and the
'black box view'.  In the transparent box view, we look into an entity
disregarding how it will be used and returning all information available
on it, including predicate declarations and predicate definitions.  This
view is supported by the entity property built-in predicates.  In the
black box view, we look into an entity from a usage point of view using
built-in methods for inspecting object operators and predicates that are
within scope from where we are making the call: *note current_op/3: 15e,
which returns operator specifications; *note predicate_property/2: 142,
which returns predicate properties; and *note current_predicate/1: 141,
which enables us to query about user-defined predicate definitions.  See
below for a more detailed description of these methods.


File: TheLogtalkHandbook-3.96.0.info,  Node: Definite clause grammar parsing methods and non-terminals,  Prev: Reflection methods,  Up: Built-in methods

1.8.5.8 Definite clause grammar parsing methods and non-terminals
.................................................................

Logtalk supports two definite clause grammar parsing built-in private
methods, *note phrase/2: 18e. and *note phrase/3: 18f, with definitions
similar to the predicates with the same name found on most Prolog
compilers that support definite clause grammars.  These methods cannot
be used as messages to objects.

Logtalk also supports *note phrase//1: 1c8, *note call//1-N: 1c9, and
*note eos//0: 1ca. built-in non-terminals.  The ‘call//1-N’
non-terminals take a *note closure: 14f. (which can be a lambda
expression) plus zero or more additional arguments and are processed by
appending the input list of tokens and the list of remaining tokens to
the arguments.


File: TheLogtalkHandbook-3.96.0.info,  Node: Predicate properties,  Next: Finding declared predicates,  Prev: Built-in methods,  Up: Predicates

1.8.6 Predicate properties
--------------------------

We can find the properties of visible predicates by calling the *note
predicate_property/2: 142. built-in method.  For example:

     | ?- bar::predicate_property(foo(_), Property).

Note that this method takes into account the predicate’s scope
declarations.  In the above example, the call will only return
properties for public predicates.

An object’s set of visible predicates is the union of all the predicates
declared for the object with all the built-in methods and all the
Logtalk and Prolog built-in predicates.

The following predicate properties are supported:

‘scope(Scope)’

     The predicate scope (useful for finding the predicate scope with a
     single call to ‘predicate_property/2’)

‘public’, ‘protected’, ‘private’

     The predicate scope (useful for testing if a predicate has a
     specific scope)

‘static’, ‘dynamic’

     All predicates are either static or dynamic (note, however, that a
     dynamic predicate can only be abolished if it was dynamically
     declared)

‘logtalk’, ‘prolog’, ‘foreign’

     A predicate can be defined in Logtalk source code, Prolog code, or
     in foreign code (e.g., in C)

‘built_in’

     The predicate is a built-in predicate

‘multifile’

     The predicate is declared multifile (i.e., it can have clauses
     defined in multiple files or entities)

‘meta_predicate(Template)’

     The predicate is declared as a meta-predicate with the specified
     template

‘coinductive(Template)’

     The predicate is declared as a coinductive predicate with the
     specified template

‘declared_in(Entity)’

     The predicate is declared (using a scope directive) in the
     specified entity

‘defined_in(Entity)’

     The predicate definition is looked up in the specified entity (note
     that this property does not necessarily imply that clauses for the
     predicate exist in ‘Entity’; the predicate can simply be false as
     per the *note closed-world assumption: 6a.)

‘redefined_from(Entity)’

     The predicate is a redefinition of a predicate definition inherited
     from the specified entity

‘non_terminal(NonTerminal//Arity)’

     The predicate resulted from the compilation of the specified
     grammar rule non-terminal

‘alias_of(Predicate)’

     The predicate (name) is an alias for the specified predicate

‘alias_declared_in(Entity)’

     The predicate alias is declared in the specified entity

‘synchronized’

     The predicate is declared as synchronized (i.e., it’s a
     deterministic predicate synchronized using a mutex when using a
     backend Prolog compiler supporting a compatible multi-threading
     implementation)

Some properties are only available when the entities are defined in
source files and when those source files are compiled with the *note
source_data: cc. flag turned on:

‘recursive’

     The predicate definition includes at least one recursive rule

‘inline’

     The predicate definition is inlined

‘auxiliary’

     The predicate is not user-defined but rather automatically
     generated by the compiler or the *note term-expansion mechanism:
     cb.

‘mode(Mode, Solutions)’

     Instantiation, type, and determinism mode for the predicate (which
     can have multiple modes)

‘info(ListOfPairs)’

     Documentation key-value pairs as specified in the user-defined
     ‘info/2’ directive

‘number_of_clauses(N)’

     The number of clauses for the predicate existing at compilation
     time (note that this property is not updated at runtime when
     asserting and retracting clauses for dynamic predicates)

‘number_of_rules(N)’

     The number of rules for the predicate existing at compilation time
     (note that this property is not updated at runtime when asserting
     and retracting clauses for dynamic predicates)

‘declared_in(Entity, Line)’

     The predicate is declared (using a scope directive) in the
     specified entity in a source file at the specified line (if
     applicable)

‘defined_in(Entity, Line)’

     The predicate is defined in the specified entity in a source file
     at the specified line (if applicable)

‘redefined_from(Entity, Line)’

     The predicate is a redefinition of a predicate definition inherited
     from the specified entity, which is defined in a source file at the
     specified line (if applicable)

‘alias_declared_in(Entity, Line)’

     The *note predicate alias: ca. is declared in the specified entity
     in a source file at the specified line (if applicable)

The properties ‘declared_in/1-2’, ‘defined_in/1-2’, and
‘redefined_from/1-2’ do not apply to built-in methods and Logtalk or
Prolog built-in predicates.  Note that if a predicate is declared in a
category imported by the object, it will be the category name — not the
object name — that will be returned by the property ‘declared_in/1’.
The same is true for protocol declared predicates.

Some properties, such as line numbers, are only available when the
entity holding the predicates is defined in a source file compiled with
the *note source_data: cc. flag turned on.  Moreover, line numbers are
only supported in *note backend Prolog compilers: 34. that provide
access to the start line of a read term.  When such support is not
available, the value ‘-1’ is returned for the start and end lines.


File: TheLogtalkHandbook-3.96.0.info,  Node: Finding declared predicates,  Next: Calling Prolog predicates,  Prev: Predicate properties,  Up: Predicates

1.8.7 Finding declared predicates
---------------------------------

We can find, by backtracking, all visible user predicates by calling the
*note current_predicate/1: 141. built-in method.  This method takes into
account predicate scope declarations.  For example, the following call
will only return user predicates that are declared public:

     | ?- some_object::current_predicate(Name/Arity).

The predicate property ‘non_terminal/1’ may be used to retrieve all
grammar rule non-terminals declared for an object.  For example:

     current_non_terminal(Object, Name//Args) :-
         Object::current_predicate(Name/Arity),
         functor(Predicate, Functor, Arity),
         Object::predicate_property(Predicate, non_terminal(Name//Args)).

Usually, the non-terminal and the corresponding predicate share the same
functor, but users should not rely on this always being true.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling Prolog predicates,  Next: Defining Prolog multifile predicates,  Prev: Finding declared predicates,  Up: Predicates

1.8.8 Calling Prolog predicates
-------------------------------

Logtalk is designed for both 'robustness' and 'portability'.  In the
context of calling Prolog predicates, robustness requires that the
compilation of Logtalk source code must not have 'accidental'
dependencies on Prolog code that happens to be loaded at the time of the
compilation.  One immediate consequence is that only Prolog 'built-in'
predicates are visible from within objects and categories.  But Prolog
systems provide a widely diverse set of built-in predicates, easily
raising portability issues.  Relying on non-standard predicates is often
unavoidable, however, due to the narrow scope of Prolog standards.
Logtalk applications may also require calling user-defined Prolog
predicates, either in ‘user’ or in Prolog modules.

* Menu:

* Calling Prolog built-in predicates::
* Calling Prolog non-standard built-in meta-predicates::
* Calling Prolog foreign predicates::
* Calling Prolog user-defined plain predicates::
* Calling Prolog module predicates::
* Calling Prolog module meta-predicates::


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling Prolog built-in predicates,  Next: Calling Prolog non-standard built-in meta-predicates,  Up: Calling Prolog predicates

1.8.8.1 Calling Prolog built-in predicates
..........................................

In predicate clauses and object ‘initialization/1’ directives, predicate
calls that are not prefixed with a message-sending, super call, or
module qualification operator (‘::’, ‘^^’, or ‘:’), are compiled to
either calls to local predicates or as calls to Logtalk/Prolog built-in
predicates.  A predicate call is compiled as a call to a local predicate
if the object (or category) contains a scope directive, a multifile
directive, a dynamic directive, or a definition for the called
predicate.  When that is not the case, the compiler checks if the call
corresponds to a Logtalk or Prolog built-in predicate.  Consider the
following example:

     foo :-
         ...,
         write(bar),
         ...

The call to the ‘write/1’ predicate will be compiled as a call to the
corresponding Prolog standard built-in predicate unless the object (or
category) containing the above definition also contains a predicate
named ‘write/1’ or a directive for the predicate.

When calling non-standard Prolog built-in predicates or using
non-standard Prolog arithmetic functions, we may run into portability
problems while trying your applications with different backend Prolog
compilers.  We can use the compiler *note portability flag: 1d1. to
generate warnings for calls to non-standard predicates and arithmetic
functions.  We can also help document those calls using the *note
uses/2: 4b. directive.  For example, a few Prolog systems provide an
‘atom_string/2’ non-standard predicate.  We can write (in the object or
category calling the predicate):

     :- uses(user, [atom_string/2])

This directive is based on the fact that built-in predicates are visible
in plain Prolog (i.e., in ‘user’).  Besides helping to document the
dependency on a non-standard built-in predicate, this directive will
also silence the compiler portability warning.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling Prolog non-standard built-in meta-predicates,  Next: Calling Prolog foreign predicates,  Prev: Calling Prolog built-in predicates,  Up: Calling Prolog predicates

1.8.8.2 Calling Prolog non-standard built-in meta-predicates
............................................................

Prolog built-in meta-predicates may only be called locally within
objects or categories, i.e.  they cannot be used as messages.  Compiling
calls to non-standard, Prolog built-in meta-predicates can be tricky,
however, as there is no standard way of checking if a built-in predicate
is also a meta-predicate and finding out which are its meta-arguments.
But Logtalk supports overriding the original meta-predicate template
when not programmatically available or usable.  For example, assume a
‘det_call/1’ Prolog built-in meta-predicate that takes a goal as
argument.  We can add to the object (or category) calling it the
directive:

     :- meta_predicate(user::det_call(0)).

Another solution is to explicitly declare non-standard built-in Prolog
meta-predicates in the corresponding adapter file using the internal
predicate ‘'$lgt_prolog_meta_predicate'/3’.  For example:

     '$lgt_prolog_meta_predicate'(det_call(_), det_call(0), predicate).

The third argument can be either the atom ‘predicate’ or the atom
‘control_construct’, a distinction that is useful when compiling in
debug mode.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling Prolog foreign predicates,  Next: Calling Prolog user-defined plain predicates,  Prev: Calling Prolog non-standard built-in meta-predicates,  Up: Calling Prolog predicates

1.8.8.3 Calling Prolog foreign predicates
.........................................

Prolog systems often support defining ‘foreign’ predicates, i.e.
predicates defined using languages other than Prolog using a ‘foreign
language interface’.  There isn’t, however, any standard for defining,
making available, and recognizing foreign predicates.  From a Logtalk
perspective, the two most common scenarios are calling a foreign
predicate (from within an object or a category) and making a set of
foreign predicates available as part of an object (or category)
protocol.  Assuming, as this is the most common case, that foreign
predicates are globally visible once made available (using a Prolog
system-specific loading or linking procedure), we can simply call them
as user-defined plain predicates, as explained in the next section.
When defining an object (or category) that makes available foreign
predicates, the advisable solution is to name the predicates after the
object (or category) and then define object (or category) predicates
that call the foreign predicates.  Most backend adapter files include
support for recognizing foreign predicates that allows the Logtalk
compiler to inline calls to the predicates (thus avoiding call
indirection overheads).


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling Prolog user-defined plain predicates,  Next: Calling Prolog module predicates,  Prev: Calling Prolog foreign predicates,  Up: Calling Prolog predicates

1.8.8.4 Calling Prolog user-defined plain predicates
....................................................

User-defined Prolog plain predicates (i.e., predicates that are not
defined in a Prolog module) can be called from within objects or
categories by sending the corresponding message to ‘user’.  For example:

     foo :-
         ...,
         user::bar,
         ...

In alternative, we can use the *note uses/2: 4b. directive and write:

     :- uses(user, [bar/0]).

     foo :-
         ...,
         bar,
         ...

Note that ‘user’ is a pseudo-object in Logtalk containing all predicate
definitions that are not encapsulated (either in a Logtalk entity or a
Prolog module).

When the Prolog predicate is not a meta-predicate, we can also use the
*note {}/1: 191. compiler bypass control construct.  For example:

     foo :-
         ...,
         {bar},
         ...

But note that in this case the *note reflection API: 48. will not record
the dependency of the ‘foo/0’ predicate on the Prolog ‘bar/0’ predicate
as we are effectively bypassing the compiler.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling Prolog module predicates,  Next: Calling Prolog module meta-predicates,  Prev: Calling Prolog user-defined plain predicates,  Up: Calling Prolog predicates

1.8.8.5 Calling Prolog module predicates
........................................

Prolog module predicates can be called from within objects or categories
by using explicit qualification.  For example:

     foo :-
         ...,
         module:bar,
         ...

You can also use the *note use_module/2: 4d. directive to call the
module predicates using implicit qualification:

     :- use_module(module, [bar/0]).

     foo :-
         ...,
         bar,
         ...

Note that the first argument of the ‘use_module/2’ directive, when used
within an object or a category, is a 'module name', not a 'file
specification' (also be aware that Prolog modules are sometimes defined
in files with names that differ from the module names).

As loading a Prolog module varies between Prolog systems, the actual
loading directive or goal is preferably done from the application *note
loader file: 4f.  An advantage of this approach is that it contributes
to a clean separation between 'loading' and 'using' a resource, with the
loader file being the central point that loads all application resources
(complex applications often use a 'hierarchy' of loader files, but the
main idea remains the same).

As an example, assume that we need to call predicates defined in a
CLP(FD) Prolog library, which can be loaded using ‘library(clpfd)’ as
the file specification.  In the loader file, we would add:

     :- use_module(library(clpfd), []).

Specifying an empty import list is often used to avoid adding the
module-exported predicates to plain Prolog.  In the objects and
categories we can then call the library predicates, using implicit or
explicit qualification, as explained.  For example:

     :- object(puzzle).

         :- public(puzzle/1).

         :- use_module(clpfd, [
             all_different/1, ins/2, label/1,
             (#=)/2, (#\=)/2,
             op(700, xfx, #=), op(700, xfx, #\=)
         ]).

         puzzle([S,E,N,D] + [M,O,R,E] = [M,O,N,E,Y]) :-
             Vars = [S,E,N,D,M,O,R,Y],
             Vars ins 0..9,
             all_different(Vars),
                       S*1000 + E*100 + N*10 + D +
                       M*1000 + O*100 + R*10 + E #=
             M*10000 + O*1000 + N*100 + E*10 + Y,
             M #\= 0, S #\= 0,
             label([M,O,N,E,Y]).

     :- end_object.

     Warning: The actual module code 'must' be loaded prior to the
     compilation of Logtalk source code that uses it.  In particular,
     programmers should not expect that the module be auto-loaded
     (including when using a backend Prolog compiler that supports an
     auto-loading mechanism).

The module identifier argument can also be a *note parameter variable:
a1. when using the directive in a parametric object or a parametric
category.  In this case, dynamic binding will necessarily be used for
all listed predicates (and non-terminals).  The parameter variable must
be instantiated at runtime when the calls are made.

Logtalk supports the declaration of *note predicate aliases: ca. and
*note predicate shorthands: 161. in ‘use_module/2’ directives used
within objects and categories.  For example, the ECLiPSe IC Constraint
Solvers define a ‘(::)/2’ variable domain operator that clashes with the
Logtalk ‘(::)/2’ message-sending operator.  We can solve the conflict by
writing:

     :- use_module(ic, [(::)/2 as ins/2]).

With this directive, calls to the ‘ins/2’ predicate alias will be
automatically compiled by Logtalk to calls to the ‘(::)/2’ predicate in
the ‘ic’ module.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling Prolog module meta-predicates,  Prev: Calling Prolog module predicates,  Up: Calling Prolog predicates

1.8.8.6 Calling Prolog module meta-predicates
.............................................

The Logtalk library provides implementations of common meta-predicates,
which can be used in place of module meta-predicates (e.g., list mapping
meta-predicates).  If that is not the case, the Logtalk compiler may
need help to understand the module meta-predicate templates.  Despite
some recent progress in standardization of the syntax of
‘meta_predicate/1’ directives and of the ‘meta_predicate/1’ property
returned by the ‘predicate_property/2’ reflection predicate, portability
is still a major problem.  Thus, Logtalk allows the original
‘meta_predicate/1’ directive to be 'overridden' with a local directive
that Logtalk can make sense of.  It also allows providing a
‘meta_predicate/1’ directive when it’s missing from the module defining
the meta-predicate.  Note that Logtalk is not based on a predicate
prefixing mechanism as found in module systems.  This fundamental
difference precludes an automated solution at the Logtalk compiler
level.

As an example, assume that you want to call from an object (or a
category) a module meta-predicate with the following meta-predicate
directive:

     :- module(foo, [bar/2]).

     :- meta_predicate(bar(*, :)).

The ‘:’ meta-argument specifier is ambiguous.  It tell us that the
second argument of the meta-predicate is module sensitive, but it does
not tell us 'how'.  Some legacy module libraries and some Prolog systems
use ‘:’ to mean ‘0’ (i.e., a meta-argument that will be meta-called).
Some others use ‘:’ for meta-arguments that are not meta-called but that
still need to be augmented with module information.  Whichever the case,
the Logtalk compiler doesn’t have enough information to unambiguously
parse the directive and correctly compile the meta-arguments in the
meta-predicate call.  Therefore, the Logtalk compiler will generate an
error stating that ‘:’ is not a valid meta-argument specifier when
trying to compile a ‘foo:bar/2’ goal.  There are two alternative
solutions for this problem.  The advised solution is to override the
meta-predicate directive by writing, inside the object (or category)
where the meta-predicate is called:

     :- meta_predicate(foo:bar(*, *)).

or:

     :- meta_predicate(foo:bar(*, 0)).

depending on the true meaning of the second meta-argument.  The second
alternative, only usable when the meta-argument can be handled as a
normal argument, is to simply use the *note {}/1: 191. compiler bypass
control construct to call the meta-predicate as-is:

     ... :- {foo:bar(..., ...)}, ...

The downside of this alternative is that it hides the dependency on the
module library from the reflection API and thus from the developer
tools.


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining Prolog multifile predicates,  Next: Asserting and retracting Prolog predicates,  Prev: Calling Prolog predicates,  Up: Predicates

1.8.9 Defining Prolog multifile predicates
------------------------------------------

Some Prolog module libraries, e.g.  constraint packages, expect clauses
for some library predicates to be defined in other modules.  This is
accomplished by declaring the library predicate 'multifile' and by
explicitly prefixing predicate clause heads with the library module
identifier.  For example:

     :- multifile(clpfd:run_propagator/2).
     clpfd:run_propagator(..., ...) :-
         ...

Logtalk supports the definition of Prolog module multifile predicates in
objects and categories.  While the clause head is compiled as-is, the
clause body is compiled in the same way as a regular object or category
predicate, thus allowing calls to local object or category predicates.
For example:

     :- object(...).

         :- multifile(clpfd:run_propagator/2).
         clpfd:run_propagator(..., ...) :-
             % calls to local object predicates
             ...

     :- end_object.

The Logtalk compiler will print a warning if the ‘multifile/1’ directive
is missing.  These multifile predicates may also be declared dynamic
using the same ‘Module:Name/Arity’ notation.


File: TheLogtalkHandbook-3.96.0.info,  Node: Asserting and retracting Prolog predicates,  Prev: Defining Prolog multifile predicates,  Up: Predicates

1.8.10 Asserting and retracting Prolog predicates
-------------------------------------------------

To assert and retract clauses for Prolog dynamic predicates, we can use
an explicitly qualified module argument.  For example:

     :- object(...).

         :- dynamic(m:bar/1).

         foo(X) :-
             retractall(m:bar(_)),
             assertz(m:bar(X)),
             ...

     :- end_object.

In alternative, we can use *note use_module/2: 4d. directives to declare
the module predicates.  For example:

     :- object(...).

         :- use_module(m, [bar/1]).
         :- dynamic(m:bar/1).

         foo(X) :-
             % retract and assert bar/1 clauses in module m
             retractall(bar(_)),
             assertz(bar(X)),
             ...

     :- end_object.

When the Prolog dynamic predicates are defined in ‘user’, the
recommended and most portable practice (as not all backends support a
module system) is to use a *note uses/2: 4b. directive:

     :- object(...).

         :- uses(user, [bar/1]).
         :- dynamic(user::bar/1).

         foo(X) :-
             % retract and assert bar/1 clauses in user
             retractall(bar(_)),
             assertz(bar(X)),
             ...

     :- end_object.

Note that in the alternatives using ‘uses/2’ or ‘use_module/2’
directives, the argument of the database handling predicates must be
known at compile-time.  If that is not the case, you must use either an
explicitly-qualified argument or the *note {}/1: 191. control construct
instead.  For example:

     :- object(...).

         add(X) :-
             % assert clause X in module m
             assertz(m:X),
             ...

         remove(Y) :-
             % retract all clauses in user whose head unifies with Y
             {retractall(Y)},
             ...

     :- end_object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Inheritance,  Next: Event-driven programming,  Prev: Predicates,  Up: User Manual

1.9 Inheritance
===============

The inheritance mechanisms found in object-oriented programming
languages allow the specialization of previously defined objects,
avoiding the unnecessary repetition of code and allowing the definition
of common functionality for sets of objects.  In the context of logic
programming, we can interpret inheritance as a form of 'theory
extension': an object will virtually contain, besides its own
predicates, all the predicates inherited from other objects that are not
redefined locally.  Inheritance is not, however, the only mechanism for
theory extension.  Logtalk also supports 'composition' using *note
categories: 109.

Logtalk uses a depth-first lookup procedure for finding predicate
declarations and predicate definitions, as explained below, when a *note
message: 79. is sent to an object.  The lookup procedures locate the
entity holding the *note predicate declaration: 57. and the entity
holding the *note predicate definition: 58. using the predicate name and
arity.  The *note alias/2: 165. predicate directive may be used for
defining alternative names for inherited predicates, for solving
inheritance conflicts, and for giving access to all inherited
definitions (thus overriding the default lookup procedure).

The lookup procedures are used when sending a message (using the *note
(;;)/2: 7e, *note (;;)/1: 5c, and *note []/1: 81. control constructs)
and when making 'super' calls (using the *note (^^)/1: 5d. control
construct).  The exact details of the lookup procedures depend on the
*note role: 93. played by the object receiving the message or making the
'super' call, as explained next.  The lookup procedures are also used by
the *note current_predicate/1: 141. and *note predicate_property/2: 142.
reflection predicates.

* Menu:

* Protocol inheritance::
* Implementation inheritance::
* Public, protected, and private inheritance: Public protected and private inheritance.
* Multiple inheritance::
* Composition versus multiple inheritance::


File: TheLogtalkHandbook-3.96.0.info,  Node: Protocol inheritance,  Next: Implementation inheritance,  Up: Inheritance

1.9.1 Protocol inheritance
--------------------------

Protocol inheritance refers to the inheritance of predicate declarations
(*note scope directives: 1e4.).  These can be contained in objects,
protocols, or categories.  Logtalk supports single and multi-inheritance
of protocols: an object or a category may implement several protocols,
and a protocol may extend several protocols.

* Menu:

* Lookup order for prototype hierarchies::
* Lookup order for class hierarchies::


File: TheLogtalkHandbook-3.96.0.info,  Node: Lookup order for prototype hierarchies,  Next: Lookup order for class hierarchies,  Up: Protocol inheritance

1.9.1.1 Lookup order for prototype hierarchies
..............................................

The lookup order for predicate declarations is first the object, second
the implemented protocols (and the protocols that these may extend),
third the imported categories (and the protocols that they may
implement), and finally the objects that the object extends (following
their declaration order).  This lookup is performed in depth-first
order.  When an object inherits two different declarations for the same
predicate, by default, only the first one will be considered.


File: TheLogtalkHandbook-3.96.0.info,  Node: Lookup order for class hierarchies,  Prev: Lookup order for prototype hierarchies,  Up: Protocol inheritance

1.9.1.2 Lookup order for class hierarchies
..........................................

The lookup order for predicate declarations is first the object classes
(following their declaration order), second the classes implemented
protocols (and the protocols that these may extend), third the classes
imported categories (and the protocols that they may implement), and
finally the superclasses of the object classes.  This lookup is
performed in depth-first order.  If the object inherits two different
declarations for the same predicate, by default, only the first one will
be considered.


File: TheLogtalkHandbook-3.96.0.info,  Node: Implementation inheritance,  Next: Public protected and private inheritance,  Prev: Protocol inheritance,  Up: Inheritance

1.9.2 Implementation inheritance
--------------------------------

Implementation inheritance refers to the inheritance of predicate
definitions.  These can be contained in objects or in categories.
Logtalk supports multi-inheritance of implementation: an object may
import several categories or extend, specialize, or instantiate several
objects.

* Menu:

* Lookup order for prototype hierarchies: Lookup order for prototype hierarchies<2>.
* Lookup order for class hierarchies: Lookup order for class hierarchies<2>.
* Redefining inherited predicate definitions::
* Specializing inherited predicate definitions::
* Union of inherited and local predicate definitions::
* Selective inheritance of predicate definitions::


File: TheLogtalkHandbook-3.96.0.info,  Node: Lookup order for prototype hierarchies<2>,  Next: Lookup order for class hierarchies<2>,  Up: Implementation inheritance

1.9.2.1 Lookup order for prototype hierarchies
..............................................

The lookup order for predicate definitions is similar to the lookup for
predicate declarations, except that implemented protocols are ignored
(as they can only contain predicate directives).


File: TheLogtalkHandbook-3.96.0.info,  Node: Lookup order for class hierarchies<2>,  Next: Redefining inherited predicate definitions,  Prev: Lookup order for prototype hierarchies<2>,  Up: Implementation inheritance

1.9.2.2 Lookup order for class hierarchies
..........................................

The lookup order for predicate definitions is similar to the lookup for
predicate declarations, except that implemented protocols are ignored
(as they can only contain predicate directives) and that the lookup
starts at the instance itself (that received the message) before
proceeding, if no predicate definition is found there, to the instance
classes imported categories and then to the class superclasses.


File: TheLogtalkHandbook-3.96.0.info,  Node: Redefining inherited predicate definitions,  Next: Specializing inherited predicate definitions,  Prev: Lookup order for class hierarchies<2>,  Up: Implementation inheritance

1.9.2.3 Redefining inherited predicate definitions
..................................................

When we define a predicate that is already inherited from an ancestor
object or an imported category, the inherited definition is hidden by
the new definition.  This is called inheritance overriding: a local
definition overrides any inherited definitions.  For example, assume
that we have the following two objects:

     :- object(root).

         :- public(bar/1).
         bar(root).

         :- public(foo/1).
         foo(root).

     :- end_object.


     :- object(descendant,
         extends(root)).

         foo(descendant).

     :- end_object.

After compiling and loading these objects, we can check the overriding
behavior by trying the following queries:

     | ?- root::(bar(Bar), foo(Foo)).

     Bar = root
     Foo = root
     yes


     | ?- descendant::(bar(Bar), foo(Foo)).

     Bar = root
     Foo = descendant
     yes

However, we can explicitly code other behaviors.  Some examples follow.


File: TheLogtalkHandbook-3.96.0.info,  Node: Specializing inherited predicate definitions,  Next: Union of inherited and local predicate definitions,  Prev: Redefining inherited predicate definitions,  Up: Implementation inheritance

1.9.2.4 Specializing inherited predicate definitions
....................................................

Specialization of inherited definitions: the new definition calls the
inherited definition and makes additional calls.  This is accomplished
by calling the *note (^^)/1: 5d. 'super call' operator in the new
definition.  For example, assume a ‘init/0’ predicate that must account
for object specific initializations along the inheritance chain:

     :- object(root).

         :- public(init/0).

         init :-
             write('root init'), nl.

     :- end_object.


     :- object(descendant,
         extends(root)).

         init :-
             write('descendant init'), nl,
             ^^init.

     :- end_object.

     | ?- descendant::init.

     descendant init
     root init
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Union of inherited and local predicate definitions,  Next: Selective inheritance of predicate definitions,  Prev: Specializing inherited predicate definitions,  Up: Implementation inheritance

1.9.2.5 Union of inherited and local predicate definitions
..........................................................

Union of the new with the inherited definitions: all the definitions are
taken into account, the calling order being defined by the inheritance
mechanisms.  This can be accomplished by writing a clause that just
calls, using the *note (^^)/1: 5d. 'super call' operator, the inherited
definitions.  The relative position of this clause among the other
definition clauses sets the calling order for the local and inherited
definitions.  For example:

     :- object(root).

         :- public(foo/1).

         foo(1).
         foo(2).

     :- end_object.


     :- object(descendant,
         extends(root)).

         foo(3).
         foo(Foo) :-
             ^^foo(Foo).

     :- end_object.

     | ?- descendant::foo(Foo).

     Foo = 3 ;
     Foo = 1 ;
     Foo = 2 ;
     no


File: TheLogtalkHandbook-3.96.0.info,  Node: Selective inheritance of predicate definitions,  Prev: Union of inherited and local predicate definitions,  Up: Implementation inheritance

1.9.2.6 Selective inheritance of predicate definitions
......................................................

Selective inheritance of predicate definitions (also known as
differential inheritance) is normally used in the representation of
exceptions to inherited default definitions.  We can use the *note
(^^)/1: 5d. 'super call' operator to test and possibly reject some of
the inherited definitions.  A common example is representing flightless
birds:

     :- object(bird).

         :- public(mode/1).

         mode(walks).
         mode(flies).

     :- end_object.


     :- object(penguin,
         extends(bird)).

         mode(swims).
         mode(Mode) :-
             ^^mode(Mode),
             Mode \== flies.

     :- end_object.

     | ?- penguin::mode(Mode).

     Mode = swims ;
     Mode = walks ;
     no


File: TheLogtalkHandbook-3.96.0.info,  Node: Public protected and private inheritance,  Next: Multiple inheritance,  Prev: Implementation inheritance,  Up: Inheritance

1.9.3 Public, protected, and private inheritance
------------------------------------------------

To make all *note public predicates: 53. declared via implemented
protocols, imported categories, or ancestor objects *note protected
predicates: 54. or to make all public and protected predicates *note
private predicates: 55, we prefix the entity’s name with the
corresponding keyword.  For example:

     :- object(Object,
         implements(private::Protocol)).

         % all the Protocol public and protected
         % predicates become private predicates
         % for the Object clients

         ...

     :- end_object.

or:

     :- object(Class,
         specializes(protected::Superclass)).

         % all the Superclass public predicates become
         % protected predicates for the Class clients

         ...

     :- end_object.

Omitting the scope keyword is equivalent to using the public scope
keyword.  For example:

     :- object(Object,
         imports(public::Category)).

         ...

     :- end_object.

This is the same as:

     :- object(Object,
         imports(Category)).

         ...

     :- end_object.

This way we ensure backward compatibility with older Logtalk versions
and a simplified syntax when protected or private inheritance is not
used.


File: TheLogtalkHandbook-3.96.0.info,  Node: Multiple inheritance,  Next: Composition versus multiple inheritance,  Prev: Public protected and private inheritance,  Up: Inheritance

1.9.4 Multiple inheritance
--------------------------

Logtalk supports multiple inheritance by enabling an object to extend,
instantiate, or specialize more than one object.  Likewise, a protocol
may extend multiple protocols, and a category may extend multiple
categories.  In this case, the depth-first lookup algorithms described
above traverse the list of entities per relation from left to right.
Consider as an example the following object opening directive:

     :- object(foo,
         extends((bar, baz))).

The lookup procedure will look first into the parent object ‘bar’ and
its related entities before looking into the parent object ‘baz’.  The
*note alias/2: 165. predicate directive can always be used to solve
multiple inheritance conflicts.  It should also be noted that the
multi-inheritance support does not affect performance when we use single
inheritance.


File: TheLogtalkHandbook-3.96.0.info,  Node: Composition versus multiple inheritance,  Prev: Multiple inheritance,  Up: Inheritance

1.9.5 Composition versus multiple inheritance
---------------------------------------------

It is not possible to discuss inheritance mechanisms without referring
to the long and probably endless debate on single versus multiple
inheritance.  The single inheritance mechanism can be implemented
efficiently, but it imposes several limitations on reusing, even if the
multiple characteristics we intend to inherit are orthogonal.  On the
other hand, the multiple inheritance mechanisms are attractive in their
apparent capability of modeling complex situations.  However, they
include a potential for conflict between inherited definitions whose
variety does not allow a single and satisfactory solution for all the
cases.

No solution that we might consider satisfactory for all the problems
presented by the multiple inheritance mechanisms has been found.  From
the simplicity of some extensions that use the Prolog search strategy,
such as *note [McCabe92]: 28. or *note [Moss94]: 1fc, to the
sophisticated algorithms of CLOS *note [Bobrow_et_al_88]: 1fd, there is
no adequate solution for all the situations.  Besides, the use of
multiple inheritance carries some complex problems in the domain of
software engineering, particularly in the reuse and maintenance of the
applications.  All these problems are substantially reduced if we
preferably use in our software development composition mechanisms
instead of specialization mechanisms *note [Taenzer89]: 1fe.  Multiple
inheritance is best used as an analysis and project abstraction, rather
than as an implementation technique *note [Shan_et_al_93]: 1ff.  Note
that Logtalk provides first-class support for composition using *note
categories: 109.


File: TheLogtalkHandbook-3.96.0.info,  Node: Event-driven programming,  Next: Multi-threading programming,  Prev: Inheritance,  Up: User Manual

1.10 Event-driven programming
=============================

The addition of event-driven programming capacities to the Logtalk
language *note [Moura94]: 9d. is based on a simple but powerful idea:

     The computations must result not only from message-sending but also
     from the 'observation' of message-sending.

The need to associate computations to the occurrence of events was very
early recognized in knowledge representation languages, programming
languages *note [Stefik_et_al_86]: 202, *note [Moon86]: 10a, operative
systems *note [Tanenbaum87]: 203, and graphical user interfaces.

With the integration between object-oriented and event-driven
programming, we intend to achieve the following goals:

   * Minimize the 'coupling' between objects.  An object should only
     contain what is intrinsic to it.  If an object observes another
     object, that means that it should depend only on the public
     protocol of the object observed and not on the implementation of
     that protocol.

   * Provide a mechanism for building 'reflexive systems' in Logtalk
     based on the dynamic behavior of objects in complement to the
     reflective information on object predicates and relations.

   * Provide a mechanism for easily defining method 'pre- and
     post-conditions' that can be toggled using the *note events: 89.
     compiler flag.  The pre- and post-conditions may be defined in the
     same object containing the methods or distributed between several
     objects acting as method monitors.

   * Provide a 'publish-subscribe' mechanism where public messages play
     the role of events.

* Menu:

* Definitions::
* Event generation::
* Communicating events to monitors::
* Performance concerns::
* Monitor semantics::
* Activation order of monitors::
* Event handling::


File: TheLogtalkHandbook-3.96.0.info,  Node: Definitions,  Next: Event generation,  Up: Event-driven programming

1.10.1 Definitions
------------------

The words 'event' and 'monitor' have multiple meanings in computer
science.  To avoid misunderstandings, we start by defining them in the
Logtalk context.

* Menu:

* Event::
* Monitor::


File: TheLogtalkHandbook-3.96.0.info,  Node: Event,  Next: Monitor,  Up: Definitions

1.10.1.1 Event
..............

In an object-oriented system, all computations start through message
sending.  It thus becomes quite natural to declare that the only event
that can occur in this kind of system is precisely the sending of a
message.  An event can thus be represented by the ordered tuple
‘(Object, Message, Sender)’.

If we consider message processing an indivisible activity, we can
interpret the sending of a message and the return of the control to the
object that has sent the message as two distinct events.  This
distinction allows us to have more precise control over a system’s
dynamic behavior.  In Logtalk, these two types of events have been named
‘before’ and ‘after’, respectively for sending a message and for
returning control to the sender.  Therefore, we refine our event
representation using the ordered tuple ‘(Event, Object, Message,
Sender)’.

The implementation of events in Logtalk enjoys the following properties:

Independence between the two types of events

     We can choose to watch only one event type or to process each one
     of the events associated with a message-sending goal in an
     independent way.

All events are automatically generated by the message-sending mechanism

     The task of generating events is transparently accomplished by the
     message-sending mechanism.  The user only needs to define the
     events that will be monitored.

The events watched at any moment can be dynamically changed during program execution

     The notion of event allows the user not only to have the
     possibility of observing but also of controlling and modifying an
     application behavior, namely by dynamically changing the observed
     events during program execution.  It is our goal to provide the
     user with the possibility of modeling the largest number of
     situations.


File: TheLogtalkHandbook-3.96.0.info,  Node: Monitor,  Prev: Event,  Up: Definitions

1.10.1.2 Monitor
................

Complementary to the notion of event is the notion of monitor.  A
monitor is an object that is automatically notified by the
message-sending mechanism whenever a registered event occurs.  Any
object that defines the event-handling predicates can play the role of a
monitor.

The implementation of monitors in Logtalk enjoys the following
properties:

Any object can act as a monitor

     The monitor status is a role that any object can perform during its
     existence.  The minimum protocol necessary is declared in the
     built-in monitoring(1) protocol.  Strictly speaking, the reference
     to this protocol is only needed when specializing event handlers.
     Nevertheless, it is considered good programming practice to always
     refer to the protocol when defining event handlers.

Unlimited number of monitors for each event

     Several monitors can observe the same event for distinct reasons.
     Therefore, the number of monitors per event is bounded only by the
     available computing resources.

The monitor status of an object can be dynamically changed at runtime

     This property does not imply that an object must be dynamic to act
     as a monitor (the monitor status of an object is not stored in the
     object).

Event handlers cannot modify the event arguments

     Notably, if the message contains unbound variables, these cannot be
     bound by the calls to the monitor event handlers.

   ---------- Footnotes ----------

   (1) ../../apis/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Event generation,  Next: Communicating events to monitors,  Prev: Definitions,  Up: Event-driven programming

1.10.2 Event generation
-----------------------

Assuming that the *note events: 89. flag is set to ‘allow’ for the
object (or category) sending the messages we want to observe, for each
message that is sent using the *note (;;)/2: 7e. control construct, the
runtime system automatically generates two events.  The first — 'before
event' — is generated when the message is sent.  The second — 'after
event' — is generated after the message has successfully been executed.

Note that 'self' messages (using the *note (;;)/1: 5c. control
construct) and 'super' calls (using the *note (^^)/1: 5d. control
construct) don’t generate events.


File: TheLogtalkHandbook-3.96.0.info,  Node: Communicating events to monitors,  Next: Performance concerns,  Prev: Event generation,  Up: Event-driven programming

1.10.3 Communicating events to monitors
---------------------------------------

Whenever a spied event occurs, the message-sending mechanism calls the
corresponding event handlers directly for all registered monitors.
These calls are internally made, thus bypassing the message-sending
primitives in order to avoid potential endless loops.  The event
handlers consist of user definitions for the public predicates declared
in the built-in monitoring(1) protocol (see below for more details).

   ---------- Footnotes ----------

   (1) ../../apis/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Performance concerns,  Next: Monitor semantics,  Prev: Communicating events to monitors,  Up: Event-driven programming

1.10.4 Performance concerns
---------------------------

Ideally, the existence of monitored messages should not affect the
processing of the remaining messages.  On the other hand, for each
message that has been sent, the system must verify if its respective
event is monitored.  Whenever possible, this verification should be
performed in constant time and independently of the number of monitored
events.  The representation of events takes advantage of the first
argument indexing performed by most Prolog compilers, which ensure — in
the general case — access in constant time.

Event support can be turned off on a per-object (or per-category) basis
using the *note events: 89. compiler flag.  With event support turned
off, Logtalk uses optimized code for processing message-sending calls
that skips the checking of monitored events, resulting in a small but
measurable performance improvement.


File: TheLogtalkHandbook-3.96.0.info,  Node: Monitor semantics,  Next: Activation order of monitors,  Prev: Performance concerns,  Up: Event-driven programming

1.10.5 Monitor semantics
------------------------

The established semantics for monitor actions consists of considering
its success as a necessary condition so that a message can succeed:

   - All actions associated with events of type ‘before’ must succeed so
     that the message processing can start.

   - All actions associated with events of type ‘after’ also have to
     succeed so that the message itself succeeds.  The failure of any
     action associated with an event of type ‘after’ forces backtracking
     over the message execution (the failure of a monitor never causes
     backtracking over the preceding monitor actions).

Note that this is the most general choice.  If we require a transparent
presence of monitors in a message processing, we just have to define the
monitor actions in such a way that they never fail (which is very simple
to accomplish).


File: TheLogtalkHandbook-3.96.0.info,  Node: Activation order of monitors,  Next: Event handling,  Prev: Monitor semantics,  Up: Event-driven programming

1.10.6 Activation order of monitors
-----------------------------------

Ideally, whenever there are several monitors defined for the same event,
the calling order should not interfere with the result.  However, this
is not always possible.  In the case of an event of type ‘before’, the
failure of a monitor prevents a message from being sent and prevents the
execution of the remaining monitors.  In the case of an event of type
‘after’, a monitor failure will force backtracking over message
execution.  Different orders of monitor activation can therefore lead to
different results if the monitor actions imply object modifications
unrecoverable in case of backtracking.  Therefore, the order for monitor
activation should be assumed as arbitrary.  In effect, to assume or to
try to impose a specific sequence requires a global knowledge of an
application dynamics, which is not always possible.  Furthermore, that
knowledge can reveal itself as incorrect if there is any change in the
execution conditions.  Note that, given the independence between
monitors, it does not make sense that a failure forces backtracking over
the actions previously executed.


File: TheLogtalkHandbook-3.96.0.info,  Node: Event handling,  Prev: Activation order of monitors,  Up: Event-driven programming

1.10.7 Event handling
---------------------

Logtalk provides three built-in predicates for event handling.  These
predicates support defining, enumerating, and abolishing events.
Applications that use events extensively usually define a set of objects
that use these built-in predicates to implement more sophisticated and
higher-level behavior.

* Menu:

* Defining new events::
* Abolishing defined events::
* Finding defined events::
* Defining event handlers::


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining new events,  Next: Abolishing defined events,  Up: Event handling

1.10.7.1 Defining new events
............................

New events can be defined using the *note define_events/5: 218. built-in
predicate:

     | ?- define_events(Event, Object, Message, Sender, Monitor).

Note that if any of the ‘Event’, ‘Object’, ‘Message’, and ‘Sender’
arguments is a free variable or contains free variables, this call will
define a 'set' of matching events.


File: TheLogtalkHandbook-3.96.0.info,  Node: Abolishing defined events,  Next: Finding defined events,  Prev: Defining new events,  Up: Event handling

1.10.7.2 Abolishing defined events
..................................

Events that are no longer needed may be abolished using the *note
abolish_events/5: 21b. built-in predicate:

     | ?- abolish_events(Event, Object, Message, Sender, Monitor).

If called with free variables, this goal will remove all matching
events.


File: TheLogtalkHandbook-3.96.0.info,  Node: Finding defined events,  Next: Defining event handlers,  Prev: Abolishing defined events,  Up: Event handling

1.10.7.3 Finding defined events
...............................

The events that are currently defined can be retrieved using the *note
current_event/5: 21e. built-in predicate:

     | ?- current_event(Event, Object, Message, Sender, Monitor).

Note that this predicate will return 'sets' of matching events if some
of the returned arguments are free variables or contain free variables.


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining event handlers,  Prev: Finding defined events,  Up: Event handling

1.10.7.4 Defining event handlers
................................

The monitoring(1) built-in protocol declares two public predicates,
*note before/3: 101. and *note after/3: 102, that are automatically
called to handle ‘before’ and ‘after’ events.  Any object that plays the
role of monitor must define one or both of these event handler methods:

     before(Object, Message, Sender) :-
         ... .

     after(Object, Message, Sender) :-
         ... .

The arguments in both methods are instantiated by the message-sending
mechanism when a monitored event occurs.  For example, assume that we
want to define a monitor called ‘tracer’ that will track any message
sent to an object by printing a descriptive text to the standard output.
Its definition could be something like:

     :- object(tracer,
         % built-in protocol for event handler methods
         implements(monitoring)).

         before(Object, Message, Sender) :-
             write('call: '), writeq(Object),
             write(' <-- '), writeq(Message),
             write(' from '), writeq(Sender), nl.

         after(Object, Message, Sender) :-
             write('exit: '), writeq(Object),
             write(' <-- '), writeq(Message),
             write(' from '), writeq(Sender), nl.

     :- end_object.

Assume that we also have the following object:

     :- object(any).

         :- public(bar/1).
         bar(bar).

         :- public(foo/1).
         foo(foo).

     :- end_object.

After compiling and loading both objects and setting the *note events:
89. flag to ‘allow’, we can start tracing every message sent to any
object by calling the *note define_events/5: 218. built-in predicate:

     | ?- set_logtalk_flag(events, allow).

     yes

     | ?- define_events(_, _, _, _, tracer).

     yes

From now on, every message sent from ‘user’ to any object will be traced
to the standard output stream:

     | ?- any::bar(X).

     call: any <-- bar(X) from user
     exit: any <-- bar(bar) from user
     X = bar

     yes

To stop tracing, we can use the *note abolish_events/5: 21b. built-in
predicate:

     | ?- abolish_events(_, _, _, _, tracer).

     yes

The monitoring(2) protocol declares the event handlers as public
predicates.  If necessary, *note protected or private implementation of
the protocol: f7. may be used in order to change the scope of the event
handler predicates.  Note that the message-sending processing mechanism
is able to call the event handlers irrespective of their scope.
Nevertheless, the scope of the event handlers may be restricted in order
to prevent other objects from calling them.

The pseudo-object *note user: cf. can also act as a monitor.  This
object expects the ‘before/3’ and ‘after/3’ predicates to be defined in
the plain Prolog database.  To avoid predicate existence errors when
setting ‘user’ as a monitor, this object declares the predicates
multifile.  Thus, any plain Prolog code defining the predicates should
include the directives:

     :- multifile(before/3).
     :- multifile(after/3).

   ---------- Footnotes ----------

   (1) ../../apis/monitoring_0.html#monitoring-0

   (2) ../../apis/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Multi-threading programming,  Next: Error handling,  Prev: Event-driven programming,  Up: User Manual

1.11 Multi-threading programming
================================

Logtalk provides 'experimental' support for multi-threading programming
on selected Prolog compilers.  Logtalk makes use of the low-level Prolog
built-in predicates that implement message queues and interface with
POSIX threads and mutexes (or a suitable emulation), providing a small
set of high-level predicates and directives that allows programmers to
easily take advantage of modern multi-processor and multi-core computers
without worrying about the tricky details of creating, synchronizing, or
communicating with threads, mutexes, and message queues.  Logtalk
multi-threading programming integrates with object-oriented programming
by providing a 'threaded engines' API, enabling objects and categories
to prove goals concurrently, and supporting synchronous and asynchronous
messages.

* Menu:

* Enabling multi-threading support::
* Enabling objects to make multi-threading calls::
* Multi-threading built-in predicates::
* One-way asynchronous calls::
* Asynchronous calls and synchronized predicates::
* Synchronizing threads through notifications::
* Threaded engines::
* Multi-threading performance::


File: TheLogtalkHandbook-3.96.0.info,  Node: Enabling multi-threading support,  Next: Enabling objects to make multi-threading calls,  Up: Multi-threading programming

1.11.1 Enabling multi-threading support
---------------------------------------

Multi-threading support may be disabled by default.  It can be enabled
on the Prolog adapter files of supported compilers by setting the
read-only *note threads: 225. compiler flag to ‘supported’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Enabling objects to make multi-threading calls,  Next: Multi-threading built-in predicates,  Prev: Enabling multi-threading support,  Up: Multi-threading programming

1.11.2 Enabling objects to make multi-threading calls
-----------------------------------------------------

The *note threaded/0: 228. object directive is used to enable an object
to make multi-threading calls:

     :- threaded.


File: TheLogtalkHandbook-3.96.0.info,  Node: Multi-threading built-in predicates,  Next: One-way asynchronous calls,  Prev: Enabling objects to make multi-threading calls,  Up: Multi-threading programming

1.11.3 Multi-threading built-in predicates
------------------------------------------

Logtalk provides a small set of built-in predicates for multi-threading
programming.  For simple tasks where you simply want to prove a set of
goals, each one in its own thread, Logtalk provides a *note threaded/1:
22b. built-in predicate.  The remaining predicates allow for
fine-grained control, including postponing retrieval of thread goal
results at a later time, supporting non-deterministic thread goals, and
making 'one-way' asynchronous calls.  Together, these predicates provide
high-level support for multi-threading programming, covering most common
use cases.

* Menu:

* Proving goals concurrently using threads::
* Proving goals asynchronously using threads::


File: TheLogtalkHandbook-3.96.0.info,  Node: Proving goals concurrently using threads,  Next: Proving goals asynchronously using threads,  Up: Multi-threading built-in predicates

1.11.3.1 Proving goals concurrently using threads
.................................................

A set of goals may be proved concurrently by calling the Logtalk
built-in predicate *note threaded/1: 22b.  Each goal in the set runs in
its own thread.

When the ‘threaded/1’ predicate argument is a 'conjunction' of goals,
the predicate call is akin to 'and-parallelism'.  For example, assume
that we want to find all the prime numbers in a given interval, ‘[N,
M]’.  We can split the interval into two parts and then span two threads
to compute the prime numbers in each sub-interval:

     prime_numbers(N, M, Primes) :-
         M > N,
         N1 is N + (M - N) // 2,
         N2 is N1 + 1,
         threaded((
             prime_numbers(N2, M, [], Acc),
             prime_numbers(N, N1, Acc, Primes)
         )).

     prime_numbers(N, M, Acc, Primes) :-
         ...

The ‘threaded/1’ call terminates when the two implicit threads
terminate.  In a computer with two or more processors (or with a
processor with two or more cores), the code above can be expected to
provide better computation times when compared with single-threaded code
for sufficiently large intervals.

When the ‘threaded/1’ predicate argument is a 'disjunction' of goals,
the predicate call is akin to 'or-parallelism', here reinterpreted as a
set of goals 'competing' to find a solution.  For example, consider the
different methods that we can use to find the roots of real functions.
Depending on the function, some methods will be faster than others.
Some methods will converge to the solution while others may diverge and
never find it.  We can try all the methods simultaneously by writing:

     find_root(Function, A, B, Error, Zero) :-
         threaded((
             bisection::find_root(Function, A, B, Error, Zero)
         ;   newton::find_root(Function, A, B, Error, Zero)
         ;   muller::find_root(Function, A, B, Error, Zero)
         )).

The above ‘threaded/1’ goal succeeds when one of the implicit threads
succeeds in finding the function root, leading to the termination of all
the remaining competing threads.

The ‘threaded/1’ built-in predicate is most useful for lengthy,
independent, deterministic computations where the computational costs of
each goal outweigh the overhead of the implicit thread creation and
management.


File: TheLogtalkHandbook-3.96.0.info,  Node: Proving goals asynchronously using threads,  Prev: Proving goals concurrently using threads,  Up: Multi-threading built-in predicates

1.11.3.2 Proving goals asynchronously using threads
...................................................

A goal may be proved asynchronously using a new thread by calling the
*note threaded_call/1-2: 230. built-in predicate .  Calls to this
predicate are always true and return immediately (assuming a callable
argument).  The term representing the goal is copied, not shared with
the thread.  The thread computes the first solution to the goal, posts
it to the implicit message queue of the object from where the
‘threaded_call/1’ predicate was called, and suspends waiting for either
a request for an alternative solution or for the program to commit to
the current solution.

The results of proving a goal asynchronously in a new thread may be
later retrieved by calling the *note threaded_exit/1-2: 231. built-in
predicate within the same object where the call to the ‘threaded_call/1’
predicate was made.  The ‘threaded_exit/1’ calls suspend execution until
the results of the ‘threaded_call/1’ calls are sent back to the object
message queue.

The ‘threaded_exit/1’ predicate allows us to retrieve alternative
solutions through backtracking (if you want to commit to the first
solution, you may use the *note threaded_once/1-2: 232. predicate
instead of the ‘threaded_call/1’ predicate).  For example, assuming a
‘lists’ object implementing the usual ‘member/2’ predicate, we could
write:

     | ?- threaded_call(lists::member(X, [1,2,3])).

     X = _G189
     yes

     | ?- threaded_exit(lists::member(X, [1,2,3])).

     X = 1 ;
     X = 2 ;
     X = 3 ;
     no

In this case, the ‘threaded_call/1’ and the ‘threaded_exit/1’ calls are
made within the pseudo-object ‘user’.  The implicit thread running the
‘lists::member/2’ goal suspends itself after providing a solution,
waiting for a request for an alternative solution; the thread is
automatically terminated when the runtime engine detects that
backtracking to the ‘threaded_exit/1’ call is no longer possible.

Calls to the ‘threaded_exit/1’ predicate block the caller until the
object message queue receives the reply to the asynchronous call.  The
predicate *note threaded_peek/1-2: 233. may be used to check if a reply
is already available without removing it from the thread queue.  The
‘threaded_peek/1’ predicate call succeeds or fails immediately without
blocking the caller.  However, keep in mind that repeated use of this
predicate is equivalent to polling a message queue, which may hurt
performance.

Be careful when using the ‘threaded_exit/1’ predicate inside
failure-driven loops.  When all the solutions have been found (and the
thread generating them is therefore terminated), re-calling the
predicate will generate an exception.  Note that failing instead of
throwing an exception is not an acceptable solution, as it could be
misinterpreted as a failure of the ‘threaded_call/1’ argument.

The example in the previous section with prime numbers could be
rewritten using the ‘threaded_call/1’ and ‘threaded_exit/1’ predicates:

     prime_numbers(N, M, Primes) :-
         M > N,
         N1 is N + (M - N) // 2,
         N2 is N1 + 1,
         threaded_call(prime_numbers(N2, M, [], Acc)),
         threaded_call(prime_numbers(N, N1, Acc, Primes)),
         threaded_exit(prime_numbers(N2, M, [], Acc)),
         threaded_exit(prime_numbers(N, N1, Acc, Primes)).

     prime_numbers(N, M, Acc, Primes) :-
         ...

When using asynchronous calls, the link between a ‘threaded_exit/1’ call
and the corresponding ‘threaded_call/1’ call is established using
unification.  If there are multiple ‘threaded_call/1’ calls for a
matching ‘threaded_exit/1’ call, the connection can potentially be
established with any of them (this is akin to what happens with
tabling).  Nevertheless, you can easily use a call 'tag' by using the
alternative *note threaded_call/2: 230, *note threaded_once/2: 232, and
*note threaded_exit/2: 231. built-in predicates.  For example:

     ?- threaded_call(member(X, [1,2,3]), Tag).

     Tag = 1
     yes

     ?- threaded_call(member(X, [1,2,3]), Tag).

     Tag = 2
     yes

     ?- threaded_exit(member(X, [1,2,3]), 2).

     X = 1 ;
     X = 2 ;
     X = 3
     yes

When using these predicates, the tags shall be considered as an opaque
term; users shall not rely on its type.  Tagged asynchronous calls can
be canceled by using the *note threaded_cancel/1: 234. predicate.


File: TheLogtalkHandbook-3.96.0.info,  Node: One-way asynchronous calls,  Next: Asynchronous calls and synchronized predicates,  Prev: Multi-threading built-in predicates,  Up: Multi-threading programming

1.11.4 One-way asynchronous calls
---------------------------------

Sometimes we want to prove a goal in a new thread without caring about
the results.  This may be accomplished by using the built-in predicate
*note threaded_ignore/1: 237.  For example, assume that we are
developing a multi-agent application where an agent may send a “happy
birthday” message to another agent.  We could write:

     ..., threaded_ignore(agent::happy_birthday), ...

The call succeeds with no reply of the goal success, failure, or even
exception ever being sent back to the object making the call.  Note that
this predicate implicitly performs a deterministic call of its argument.


File: TheLogtalkHandbook-3.96.0.info,  Node: Asynchronous calls and synchronized predicates,  Next: Synchronizing threads through notifications,  Prev: One-way asynchronous calls,  Up: Multi-threading programming

1.11.5 Asynchronous calls and synchronized predicates
-----------------------------------------------------

Proving a goal asynchronously using a new thread may lead to problems
when the goal results in side effects such as input/output operations or
modifications to an *note object database: 1b0.  For example, if a new
thread is started with the same goal before the first one finished its
job, we may end up with mixed output, a corrupted database, or
unexpected goal failures.  In order to solve this problem, predicates
(and grammar rule non-terminals) with side effects can be declared as
'synchronized' by using the *note synchronized/1: 74. predicate
directive.  Proving a query to a synchronized predicate (or synchronized
non-terminal) is internally protected by a mutex, thus allowing for easy
thread synchronization.  For example:

     % ensure thread synchronization
     :- synchronized(db_update/1).

     db_update(Update) :-
         % predicate with side-effects
         ...

A second example: assume an object defining two predicates for writing,
respectively, even and odd numbers in a given interval to the standard
output.  Given a large interval, a goal such as:

     | ?- threaded_call(obj::odd_numbers(1,100)),
          threaded_call(obj::even_numbers(1,100)).

     1 3 2 4 6 8 5 7 10 ...
     ...

will most likely result in a mixed-up output.  By declaring the
‘odd_numbers/2’ and ‘even_numbers/2’ predicates synchronized:

     :- synchronized([
         odd_numbers/2,
         even_numbers/2]).

one goal will only start after the other one finished:

     | ?- threaded_ignore(obj::odd_numbers(1,99)),
          threaded_ignore(obj::even_numbers(1,99)).

     1 3 5 7 9 11 ...
     ...
     2 4 6 8 10 12 ...
     ...

Note that, in a more realistic scenario, the two ‘threaded_ignore/1’
calls would be made concurrently from different objects.  Using the same
synchronized directive for a set of predicates implies that they all use
the same mutex, as required for this example.

As each Logtalk entity is independently compiled, this directive must be
included in every object or category that contains a definition for the
described predicate, even if the predicate declaration is inherited from
another entity, in order to ensure proper compilation.  Note that a
synchronized predicate cannot be declared dynamic.  To ensure atomic
updates of a dynamic predicate, declare as synchronized the predicate
performing the update.

Synchronized predicates may be used as wrappers for messages sent to
objects that are not multi-threading aware.  For example, assume a ‘log’
object defining a ‘write_log_entry/2’ predicate that writes log entries
to a file, thus using side effects on its implementation.  We can
specify and define, for example, a ‘sync_write_log_entry/2’ predicate as
follows:

     :- synchronized(sync_write_log_entry/2).

     sync_write_log_entry(File, Entry) :-
         log::write_log_entry(File, Entry).

and then call the ‘sync_write_log_entry/2’ predicate instead of the
‘write_log_entry/2’ predicate from multi-threaded code.

The synchronization directive may be used when defining objects that may
be reused in both single-threaded and multi-threaded Logtalk
applications.  The directive simply makes calls to the synchronized
predicates deterministic when the objects are used in a single-threaded
application.


File: TheLogtalkHandbook-3.96.0.info,  Node: Synchronizing threads through notifications,  Next: Threaded engines,  Prev: Asynchronous calls and synchronized predicates,  Up: Multi-threading programming

1.11.6 Synchronizing threads through notifications
--------------------------------------------------

Declaring a set of predicates as synchronized can only ensure that they
are not executed at the same time by different threads.  Sometimes we
need to suspend a thread not on a synchronization lock but on some
condition that must hold true for a thread goal to proceed.  I.e.  we
want a thread goal to be suspended until a condition becomes true
instead of simply failing.  The built-in predicate *note
threaded_wait/1: 23b. allows us to suspend a predicate execution
(running in its own thread) until a notification is received.
Notifications are posted using the built-in predicate *note
threaded_notify/1: 23c.  A notification is a Prolog term that a
programmer chooses to represent some condition becoming true.  Any
Prolog term can be used as a notification argument for these predicates.
Related calls to the ‘threaded_wait/1’ and ‘threaded_notify/1’ must be
made within the same object, 'this', as the object message queue is used
internally for posting and retrieving notifications.

Each notification posted by a call to the ‘threaded_notify/1’ predicate
is consumed by a single ‘threaded_wait/1’ predicate call (i.e., these
predicates implement a peer-to-peer mechanism).  Care should be taken to
avoid deadlocks when two (or more) threads both wait and post
notifications to each other.


File: TheLogtalkHandbook-3.96.0.info,  Node: Threaded engines,  Next: Multi-threading performance,  Prev: Synchronizing threads through notifications,  Up: Multi-threading programming

1.11.7 Threaded engines
-----------------------

Threaded engines provide an alternative to the multi-threading
predicates described in the previous sections.  An 'engine' is a
computing thread whose solutions can be lazily computed and retrieved.
In addition, an engine also supports a term queue that allows passing
arbitrary terms to the engine.

An engine is created by calling the *note threaded_engine_create/3: 23f.
built-in predicate.  For example:

     | ?- threaded_engine_create(X, member(X, [1,2,3]), worker).
     yes

The first argument is an 'answer template' to be used for retrieving
solution bindings.  The user can name the engine, as in this example
where the atom ‘worker’ is used, or have the runtime generate a name,
which should be treated as an opaque term.

Engines are scoped by the object within which the
‘threaded_engine_create/3’ call takes place.  Thus, different objects
can create engines with the same names with no conflicts.  Moreover,
engines share the visible predicates of the object creating them.

The engine computes the first solution of its goal argument and suspends
waiting for it to be retrieved.  Solutions can be retrieved one at a
time using the *note threaded_engine_next/2: 240. built-in predicate:

     | ?- threaded_engine_next(worker, X).
     X = 1
     yes

The call blocks until a solution is available and fails if there are no
solutions left.  After returning a solution, this predicate signals the
engine to start computing the next one.  Note that this predicate is
deterministic.  In contrast with the ‘threaded_exit/1-2’ built-in
predicates, retrieving the next solution requires calling the predicate
again instead of backtracking into its call.  For example:

     collect_all(Engine, [Answer| Answers]) :-
         threaded_engine_next(Engine, Answer),
         !,
         collect_all(Engine, Answers).
     collect_all(_, []).

There is also a reified alternative version of the predicate, *note
threaded_engine_next_reified/2: 241, which returns ‘the(Answer)’, ‘no’,
and ‘exception(Error)’ terms as answers.  Using this predicate,
collecting all solutions to an engine uses a different programming
pattern:

     ... :-
         ...,
         threaded_engine_next_reified(Engine, Reified),
         collect_all_reified(Reified, Engine, Answers),
         ...

     collect_all_reified(no, _, []).
     collect_all_reified(the(Answer), Engine, [Answer| Answers]) :-
         threaded_engine_next_reified(Engine, Reified),
         collect_all_reified(Reified, Engine, Answers).

Engines must be explicitly terminated using the *note
threaded_engine_destroy/1: 242. built-in predicate:

     | ?- threaded_engine_destroy(worker).
     yes

A common usage pattern for engines is to define a recursive predicate
that uses the engine term queue to retrieve a task to be performed.  For
example, assume we define the following predicate:

     loop :-
         threaded_engine_fetch(Task),
         handle(Task),
         loop.

The *note threaded_engine_fetch/1: 243. built-in predicate fetches a
task for the engine term queue.  The engine clients would use the *note
threaded_engine_post/2: 244. built-in predicate to post tasks into the
engine term queue.  The engine would be created using the call:

     | ?- threaded_engine_create(none, loop, worker).

     yes

The ‘handle/1’ predicate, after performing a task, can use the *note
threaded_engine_yield/1: 245. built-in predicate to make the task
results available for consumption using the ‘threaded_engine_next/2’ and
‘threaded_engine_next_reified/2’ built-in predicates.  Blocking
semantics are used by these two predicates: the
‘threaded_engine_yield/1’ predicate blocks until the returned solution
is consumed, while the ‘threaded_engine_next/2’ predicate blocks until a
solution becomes available.


File: TheLogtalkHandbook-3.96.0.info,  Node: Multi-threading performance,  Prev: Threaded engines,  Up: Multi-threading programming

1.11.8 Multi-threading performance
----------------------------------

The performance of multi-threading applications is highly dependent on
the *note backend Prolog compiler: 34, the operating-system, and the use
of *note dynamic binding: 36. and dynamic predicates.  All compatible
backend Prolog compilers that support multi-threading features make use
of POSIX threads or 'pthreads'.  The performance of the underlying
pthreads implementation can exhibit significant differences between
operating systems.  An important point is synchronized access to dynamic
predicates.  As different threads may try to simultaneously access and
update dynamic predicates, these operations may use a lock-free
algorithm or be protected by a lock, usually implemented using a mutex.
In the latter case, poor mutex lock operating-system performance,
combined with a large number of collisions by several threads trying to
acquire the same lock, can result in severe performance penalties.
Thus, whenever possible, avoid using dynamic predicates and dynamic
binding.


File: TheLogtalkHandbook-3.96.0.info,  Node: Error handling,  Next: Reflection,  Prev: Multi-threading programming,  Up: User Manual

1.12 Error handling
===================

Error handling is accomplished in Logtalk by using the standard
‘catch/3’ and ‘throw/1’ predicates *note [ISO95]: 31. together with a
set of built-in methods that simplify generating errors decorated with
expected context.

Errors thrown by Logtalk have, whenever possible, the following format:

     error(Error, logtalk(Goal, ExecutionContext))

In this exception term, ‘Goal’ is the goal that triggered the error
‘Error’ and ‘ExecutionContext’ is the context in which ‘Goal’ is called.
For example:

     error(
         permission_error(modify,private_predicate,p/0),
         logtalk(foo::abolish(p/0), _)
     )

Note, however, that ‘Goal’ and ‘ExecutionContext’ can be unbound or only
partially instantiated when the corresponding information is not
available (e.g., due to compiler optimizations that throw away the
necessary error context information).  The ‘ExecutionContext’ argument
is an opaque term that can be decoded using the
logtalk::execution_context/7(1) predicate.

* Menu:

* Raising Exceptions::
* Type-checking::
* Expected terms::
* Compiler warnings and errors::
* Runtime errors::

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0-execution-context-7


File: TheLogtalkHandbook-3.96.0.info,  Node: Raising Exceptions,  Next: Type-checking,  Up: Error handling

1.12.1 Raising Exceptions
-------------------------

The *note error handling section: 24c. in the reference manual lists a
set of convenient built-in methods that generate ‘error/2’ exception
terms with the expected context argument.  For example, instead of
manually constructing a type error as in:

     ...,
     context(Context),
     throw(error(type_error(atom, 42), Context)).

we can simply write:

     ...,
     type_error(atom, 42).

The provided error built-in methods cover all standard error types found
in the ISO Prolog Core standard.


File: TheLogtalkHandbook-3.96.0.info,  Node: Type-checking,  Next: Expected terms,  Prev: Raising Exceptions,  Up: Error handling

1.12.2 Type-checking
--------------------

One of the most common cases where errors may be generated is when
type-checking predicate arguments and input data before processing it.
The standard library includes a type(1) object that defines an extensive
set of types, together with predicates for validating and checking
terms.  The set of types is user extensible.  New types can be defined
by adding clauses for the ‘type/1’ and ‘check/2’ multifile predicates.
For example, assume that we want to be able to check 'temperatures'
expressed in Celsius, Fahrenheit, or Kelvin scales.  We start by
declaring (in an object or category) the new type:

     :- multifile(type::type/1).
     type::type(temperature(_Unit)).

Next, we need to define the actual code that would verify that a
temperature is valid.  As the different scales use a different value for
absolute zero, we can write:

     :- multifile(type::check/2).
     type::check(temperature(Unit), Term) :-
         check_temperature(Unit, Term).

     % given that temperature has only a lower bound, we make use of the library
     % property/2 type to define the necessary test expression for each unit
     check_temperature(celsius, Term) :-
         type::check(property(float, [Temperature]>>(Temperature >= -273.15)), Term).
     check_temperature(fahrenheit, Term) :-
         type::check(property(float, [Temperature]>>(Temperature >= -459.67)), Term).
     check_temperature(kelvin, Term) :-
         type::check(property(float, [Temperature]>>(Temperature >= 0.0)), Term).

With this definition, a term is first checked that it is a float value
before checking that it is in the expected open interval.  But how do we
use this new type?  If we just want to test if a temperature is valid,
we can write:

     ..., type::valid(temperature(celsius), 42.0), ...

The type::valid/2(2) predicate succeeds or fails depending on the second
argument being of the type specified in the first argument.  If instead
of success or failure we want to generate an error for invalid values,
we can use the type::check/2(3) predicate instead:

     ..., type::check(temperature(celsius), 42.0), ...

If we require an ‘error/2’ exception term with the error context, we can
use instead the type::check/3(4) predicate:

     ...,
     context(Context),
     type::check(temperature(celsius), 42.0, Context),
     ...

Note that ‘context/1’ calls are inlined and messages to the library
‘type’ object use *note static binding: 35. when compiling with the
*note optimize flag: 8c. turned on, thus enabling efficient
type-checking.

   ---------- Footnotes ----------

   (1) ../../apis/type_0.html#type-0

   (2) ../../apis/type_0.html#type-0-valid-2

   (3) ../../apis/type_0.html#type-0-check-2

   (4) ../../apis/type_0.html#type-0-check-3


File: TheLogtalkHandbook-3.96.0.info,  Node: Expected terms,  Next: Compiler warnings and errors,  Prev: Type-checking,  Up: Error handling

1.12.3 Expected terms
---------------------

Support for representing and handling 'expected terms' is provided by
the *note expecteds: 24f. library.  Expected terms allow deferring
errors to later stages of an application in lieu to raising an exception
as soon as an error is detected.


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiler warnings and errors,  Next: Runtime errors,  Prev: Expected terms,  Up: Error handling

1.12.4 Compiler warnings and errors
-----------------------------------

The current Logtalk compiler uses the standard ‘read_term/3’ built-in
predicate to read and compile a Logtalk source file.  This improves the
compatibility with *note backend Prolog compilers: 34. and their
proprietary syntax extensions and standard compliance quirks.  But one
consequence of this design choice is that invalid Prolog terms or syntax
errors may abort the compilation process with limited information given
to the user (due to the inherent limitations of the ‘read_term/3’
predicate).

Assuming that all the terms in a source file are valid, there is a set
of errors and potential errors, described below, that the compiler will
try to detect and report, depending on the used compiler flags (see the
*note Compiler flags: 251. section of this manual on lint flags for
details).

* Menu:

* Unknown entities::
* Singleton variables::
* Redefinition of Prolog built-in predicates::
* Redefinition of Logtalk built-in predicates::
* Redefinition of Logtalk built-in methods::
* Misspell calls of local predicates::
* Portability warnings::
* Deprecated elements::
* Missing directives::
* Duplicated directives::
* Duplicated clauses::
* Goals that are always true or false::
* Trivial fails::
* Suspicious calls::
* Lambda variables::
* Redefinition of predicates declared in uses/2 or use_module/2 directives::
* Other warnings and errors::


File: TheLogtalkHandbook-3.96.0.info,  Node: Unknown entities,  Next: Singleton variables,  Up: Compiler warnings and errors

1.12.4.1 Unknown entities
.........................

The Logtalk compiler warns about any referenced entity that is not
currently loaded.  The warning may reveal a misspelled entity name or
just an entity that will be loaded later.  Out-of-order loading should
be avoided when possible as it prevents some code optimizations, such as
*note static binding: 35. of messages to methods.


File: TheLogtalkHandbook-3.96.0.info,  Node: Singleton variables,  Next: Redefinition of Prolog built-in predicates,  Prev: Unknown entities,  Up: Compiler warnings and errors

1.12.4.2 Singleton variables
............................

Singleton variables in a clause are often misspelled variables and, as
such, are one of the most common errors when programming in Prolog.
Assuming that the *note backend Prolog compiler: 34. implementation of
the ‘read_term/3’ predicate supports the standard ‘singletons/1’ option,
the compiler warns about any singleton variable found while compiling a
source file.


File: TheLogtalkHandbook-3.96.0.info,  Node: Redefinition of Prolog built-in predicates,  Next: Redefinition of Logtalk built-in predicates,  Prev: Singleton variables,  Up: Compiler warnings and errors

1.12.4.3 Redefinition of Prolog built-in predicates
...................................................

The Logtalk compiler will warn us of any redefinition of a Prolog
built-in predicate inside an object or category.  Sometimes the
redefinition is intended.  In other cases, the user may not be aware
that a particular *note backend Prolog compiler: 34. may already provide
the predicate as a built-in predicate or may want to ensure code
portability among several Prolog compilers with different sets of
built-in predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Redefinition of Logtalk built-in predicates,  Next: Redefinition of Logtalk built-in methods,  Prev: Redefinition of Prolog built-in predicates,  Up: Compiler warnings and errors

1.12.4.4 Redefinition of Logtalk built-in predicates
....................................................

Similar to the redefinition of Prolog built-in predicates, the Logtalk
compiler will warn us if we try to redefine a Logtalk built-in.  But the
redefinition will probably be an error in most (if not all) cases.


File: TheLogtalkHandbook-3.96.0.info,  Node: Redefinition of Logtalk built-in methods,  Next: Misspell calls of local predicates,  Prev: Redefinition of Logtalk built-in predicates,  Up: Compiler warnings and errors

1.12.4.5 Redefinition of Logtalk built-in methods
.................................................

An error will be thrown if we attempt to redefine a Logtalk built-in
method inside an entity.  The default behavior is to report the error
and abort the compilation of the offending entity.


File: TheLogtalkHandbook-3.96.0.info,  Node: Misspell calls of local predicates,  Next: Portability warnings,  Prev: Redefinition of Logtalk built-in methods,  Up: Compiler warnings and errors

1.12.4.6 Misspell calls of local predicates
...........................................

A warning will be reported if Logtalk finds (in the body of a predicate
definition) a call to a local predicate that is not defined, built-in
(either in Prolog or in Logtalk) or declared dynamic.  In most cases
these calls are simple misspell errors.


File: TheLogtalkHandbook-3.96.0.info,  Node: Portability warnings,  Next: Deprecated elements,  Prev: Misspell calls of local predicates,  Up: Compiler warnings and errors

1.12.4.7 Portability warnings
.............................

A warning will be reported if a predicate clause contains a call to a
non-standard built-in predicate or arithmetic function.  Portability
warnings are also reported for non-standard flags or flag values.  These
warnings often cannot be avoided due to the limited scope of the ISO
Prolog standard.


File: TheLogtalkHandbook-3.96.0.info,  Node: Deprecated elements,  Next: Missing directives,  Prev: Portability warnings,  Up: Compiler warnings and errors

1.12.4.8 Deprecated elements
............................

A warning will be reported if a deprecated directive, control construct,
or predicate is used.  These warnings should be fixed as soon as
possible, as support for any deprecated features will likely be
discontinued in future versions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Missing directives,  Next: Duplicated directives,  Prev: Deprecated elements,  Up: Compiler warnings and errors

1.12.4.9 Missing directives
...........................

A warning will be reported for any missing dynamic, discontiguous,
meta-predicate, and public predicate directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Duplicated directives,  Next: Duplicated clauses,  Prev: Missing directives,  Up: Compiler warnings and errors

1.12.4.10 Duplicated directives
...............................

A warning will be reported for any duplicated scope, multifile, dynamic,
discontiguous, meta-predicate, and meta-non-terminal directives.  Note
that conflicting directives for the same predicate are handled as
errors, not as duplicated directive warnings.


File: TheLogtalkHandbook-3.96.0.info,  Node: Duplicated clauses,  Next: Goals that are always true or false,  Prev: Duplicated directives,  Up: Compiler warnings and errors

1.12.4.11 Duplicated clauses
............................

A warning will be reported for any duplicated entity clauses.  This
check is computationally heavy, however, and usually turned off by
default.


File: TheLogtalkHandbook-3.96.0.info,  Node: Goals that are always true or false,  Next: Trivial fails,  Prev: Duplicated clauses,  Up: Compiler warnings and errors

1.12.4.12 Goals that are always true or false
.............................................

A warning will be reported for any goal that is always true or false.
This is usually caused by typos in the code.  For example, writing ‘X ==
y’ instead of ‘X == Y’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Trivial fails,  Next: Suspicious calls,  Prev: Goals that are always true or false,  Up: Compiler warnings and errors

1.12.4.13 Trivial fails
.......................

A warning will be reported for any call to a local static predicate with
no matching clause.


File: TheLogtalkHandbook-3.96.0.info,  Node: Suspicious calls,  Next: Lambda variables,  Prev: Trivial fails,  Up: Compiler warnings and errors

1.12.4.14 Suspicious calls
..........................

A warning will be reported for calls that are syntactically correct but
most likely a semantic error.  An example is *note (;;)/1: 5c. calls in
clauses that apparently are meant to implement recursive predicate
definitions where the user intention is to call the local predicate
definition.


File: TheLogtalkHandbook-3.96.0.info,  Node: Lambda variables,  Next: Redefinition of predicates declared in uses/2 or use_module/2 directives,  Prev: Suspicious calls,  Up: Compiler warnings and errors

1.12.4.15 Lambda variables
..........................

A warning will be reported for *note lambda expressions: 182. with
unclassified variables (not listed as either *note lambda free: 270. or
*note lambda parameter: 271. variables), for variables playing a dual
role (as both lambda free and lambda parameter variables), and for
lambda parameters used elsewhere in a clause.


File: TheLogtalkHandbook-3.96.0.info,  Node: Redefinition of predicates declared in uses/2 or use_module/2 directives,  Next: Other warnings and errors,  Prev: Lambda variables,  Up: Compiler warnings and errors

1.12.4.16 Redefinition of predicates declared in ‘uses/2’ or ‘use_module/2’ directives
......................................................................................

A error will be reported for any attempt to define locally a predicate
that is already declared in an *note uses/2: 4b. or *note use_module/2:
4d. directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Other warnings and errors,  Prev: Redefinition of predicates declared in uses/2 or use_module/2 directives,  Up: Compiler warnings and errors

1.12.4.17 Other warnings and errors
...................................

The Logtalk compiler will throw an error if it finds a predicate clause
or a directive that cannot be parsed.  The default behavior is to report
the error and abort the compilation.


File: TheLogtalkHandbook-3.96.0.info,  Node: Runtime errors,  Prev: Compiler warnings and errors,  Up: Error handling

1.12.5 Runtime errors
---------------------

This section briefly describes runtime errors that result from misuse of
Logtalk built-in predicates, built-in methods, or from message-sending.
For a complete and detailed description of runtime errors, please
consult the Reference Manual.

* Menu:

* Logtalk built-in predicates::
* Logtalk built-in methods::
* Message sending::


File: TheLogtalkHandbook-3.96.0.info,  Node: Logtalk built-in predicates,  Next: Logtalk built-in methods,  Up: Runtime errors

1.12.5.1 Logtalk built-in predicates
....................................

Most Logtalk built-in predicates check the type and mode of the calling
arguments, throwing an exception in case of misuse.


File: TheLogtalkHandbook-3.96.0.info,  Node: Logtalk built-in methods,  Next: Message sending,  Prev: Logtalk built-in predicates,  Up: Runtime errors

1.12.5.2 Logtalk built-in methods
.................................

Most Logtalk built-in method check the type and mode of the calling
arguments, throwing an exception in case of misuse.


File: TheLogtalkHandbook-3.96.0.info,  Node: Message sending,  Prev: Logtalk built-in methods,  Up: Runtime errors

1.12.5.3 Message sending
........................

The message-sending mechanisms always check if the receiver of a message
is a defined object and if the message corresponds to a declared
predicate within the scope of the sender.  The built-in protocol
forwarding(1) declares a predicate, *note forward/1: 105, which is
automatically called (if defined) by the runtime for any message that
the receiving object does not understand.  The usual definition for this
error handler is to delegate or forward the message to another object
that might be able to answer it:

     forward(Message) :-
         % forward the message while preserving the sender
         [Object::Message].

If preserving the original sender is not required, this definition can
be simplified to:

     forward(Message) :-
         Object::Message.

More sophisticated definitions are, of course, possible.

   ---------- Footnotes ----------

   (1) ../../apis/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Reflection,  Next: Writing and running applications,  Prev: Error handling,  Up: User Manual

1.13 Reflection
===============

Logtalk provides support for both 'structural' and 'behavioral'
reflection.  Structural reflection supports computations over an
application structure.  Behavioral reflection supports computations over
what an application does while running.  The structural and behavioral
reflection APIs are used by all the *note developer tools: 280, which
are regular applications.

* Menu:

* Structural reflection::
* Behavioral reflection::


File: TheLogtalkHandbook-3.96.0.info,  Node: Structural reflection,  Next: Behavioral reflection,  Up: Reflection

1.13.1 Structural reflection
----------------------------

Structural reflection allows querying the properties of objects,
categories, protocols, and predicates.  This API provides two views on
the structure of an application: a 'transparent-box view' and a
'black-box view', described next.

* Menu:

* Transparent-box view::
* Black-box view::


File: TheLogtalkHandbook-3.96.0.info,  Node: Transparent-box view,  Next: Black-box view,  Up: Structural reflection

1.13.1.1 Transparent-box view
.............................

The transparent-box view provides a structural view of the contents and
properties of entities, predicates, and source files akin to accessing
the corresponding source code.  I.e.  this is the view we use when
asking questions such as: 'What predicates are declared in this
protocol?'  'Which predicates are called by this predicate?'  'Where are
clauses for this multifile predicate defined?'

For entities, built-in predicates are provided for *note enumerating
entities: 284, *note enumerating entity properties: 6f. (including
entity declared, defined, called, and updated predicates; i.e.  full
predicate cross-referencing data), and *note enumerating entity
relations: 285. (for full entity cross-referencing data).  For a
detailed description of the supported entity properties, see the
sections on *note object properties: c5, *note protocol properties: f3,
and *note category properties: 12a.  For examples of querying entity
relations, see the sections on *note object relations: bc, *note
protocol relations: ef, and *note category relations: 127.

     Note: Some entity and predicate properties are only available when
     the source files are compiled with the *note source_data: cc. flag
     turned on.

The logtalk(1) built-in object provides predicates for querying loaded
source files and their properties.

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Black-box view,  Prev: Transparent-box view,  Up: Structural reflection

1.13.1.2 Black-box view
.......................

The black-box view provides a view that takes into account entity
encapsulation and thus only allows querying about predicates and
operators that are within the scope of the entity calling the reflection
methods.  This is the view we use when asking questions such as: 'What
messages can be sent to this object?'

Built-in methods are provided for querying the *note predicates that are
declared and can be called or used as messages: 141. and for querying
the *note predicate properties: 142.  It is also possible to enumerate
*note entity operators: 15e.  See the sections on *note finding declared
predicates: 1ce. and on *note predicate properties: 1cc. for more
details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Behavioral reflection,  Prev: Structural reflection,  Up: Reflection

1.13.2 Behavioral reflection
----------------------------

Behavioral reflection provides insight on what an application does when
running.  Specifically, by observing and acting on the messages being
exchanged between objects.  See the section on *note event-driven
programming: 6d. for details.  There is also a *note dependents: 289.
library that provides an implementation of Smalltalk dependents
mechanism.

For use in debugging tools, there is also a small reflection API
providing *note trace and debug event predicates: d5. provided by the
logtalk(1) built-in object.

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Writing and running applications,  Next: Printing messages and asking questions,  Prev: Reflection,  Up: User Manual

1.14 Writing and running applications
=====================================

For successful programming in Logtalk, you need a good working knowledge
of Prolog and an understanding of the principles of object-oriented
programming.  Most guidelines for writing good Prolog code apply as well
to Logtalk programming.  To those guidelines, you should add the basics
of good object-oriented design.

One of the advantages of a system like Logtalk is that it enables us to
use the currently available object-oriented methodologies, tools, and
metrics *note [Champaux92]: 28d. in logic programming.  That said,
writing applications in Logtalk is similar to writing applications in
Prolog: we define new predicates describing what is true about our
domain objects, about our problem solution.  We encapsulate our
predicate directives and definitions inside new objects, categories, and
protocols that we create by hand with a text editor or by using the
Logtalk built-in predicates.  Some of the information collected during
the analysis and design phases can be integrated into the objects,
categories, and protocols that we define by using the available entity
and predicate documenting directives.

* Menu:

* Starting Logtalk::
* Running parallel Logtalk processes::
* Source files::
* Multi-pass compiler::
* Compiling and loading your applications::
* Compiler errors, warnings, and comments: Compiler errors warnings and comments.
* Loader files::
* Libraries of source files::
* Settings files::
* Compiler linter::
* Compiler flags::
* Reloading source files::
* Batch processing::
* Optimizing performance::
* Portable applications::
* Conditional compilation::
* Avoiding common errors::
* Coding style guidelines::


File: TheLogtalkHandbook-3.96.0.info,  Node: Starting Logtalk,  Next: Running parallel Logtalk processes,  Up: Writing and running applications

1.14.1 Starting Logtalk
-----------------------

We run Logtalk inside a normal Prolog session, after loading the
necessary files.  Logtalk extends but does not modify your Prolog
compiler.  We can freely mix Prolog queries with the sending of
messages, and our applications can be made of both normal Prolog clauses
and object definitions.

Depending on your Logtalk installation, you may use a script or a
shortcut to start Logtalk with your chosen Prolog compiler.  On POSIX
operating-systems, Bash shell integration scripts should be available
from the command-line.  On Windows, PowerShell integration scripts
should be available from the command-line and integration shortcuts
should be available from the Start Menu.  Scripts are named upon the
used backend Prolog compilers.

For example, assuming a POSIX operating-system and GNU Prolog as the
backend:

     $ gplgt
     ...

Depending on your Logtalk installation, you may need to type instead
‘gplgt.sh’.  On Windows, using PowerShell 7.2 or a later version and
ECLiPSe as the backend:

     PS> eclipselgt.ps1
     ...


File: TheLogtalkHandbook-3.96.0.info,  Node: Running parallel Logtalk processes,  Next: Source files,  Prev: Starting Logtalk,  Up: Writing and running applications

1.14.2 Running parallel Logtalk processes
-----------------------------------------

Running parallel Logtalk processes is enabled by setting the *note
clean: 292. flag to ‘on’.  This is the default flag value in the backend
adapter files.  With this setting, the intermediate Prolog files
generated by the Logtalk compiler include the process identifier in the
names, thus preventing file name clashes when running parallel
processes.  When the flag is turned off, the generated intermediate
Prolog file names don’t include the process identifier and are kept
between runs.  This is usually done to avoid repeated recompilation of
stable code when developing large applications or when running multiple
test sets for performance (by avoiding repeated recompilation of the
*note lgtunit: 146. tool).

To run parallel Logtalk processes with the ‘clean’ flag turned off, each
process must use its own *note scratch directory: 293.  This is
accomplished by defining the ‘scratch_directory’ library alias to a
per-process location 'before' loading the compiler/runtime.  For
example, assuming we’re using GNU Prolog as the backend, a possible
definition could be:

     :- multifile(logtalk_library_path/2).
     :- dynamic(logtalk_library_path/2).

     logtalk_library_path(scratch_directory, Directory) :-
         temporary_name(lgtXXXXXX, Name),
         decompose_file_name(Name, _, Prefix, _),
         atom_concat('/tmp/', Prefix, Directory),
         (   file_exists(Directory) ->
             true
         ;   make_directory(Directory)
         ).

Assuming the code above is saved in a
‘parallel_logtalk_processes_setup.pl’ file, we would then start Logtalk
using:

     $ gplgt --init-goal "consult('parallel_logtalk_processes_setup.pl')"

The details on how to define and load the definition of the
‘scratch_directory’ library alias are, however, backend specific (due to
the lack of Prolog standardization) and possibly also operating-system
specific (different locations for the temporary directory).  The Logtalk
library includes a ‘parallel_logtalk_processes_setup.pl’ file with
support for selected backends and usage instructions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Source files,  Next: Multi-pass compiler,  Prev: Running parallel Logtalk processes,  Up: Writing and running applications

1.14.3 Source files
-------------------

Logtalk source files may define any number of entities (objects,
categories, or protocols).  Source files may also contain Prolog code
interleaved with Logtalk entity definitions.  Plain Prolog code is
usually copied as-is to the corresponding Prolog output file (except, of
course, if subject to the *note term-expansion mechanism: cb.).  Prolog
modules are compiled as objects.  The following Prolog directives are
processed when read (thus affecting the compilation of the source code
that follows): ‘ensure_loaded/1’, ‘use_module/1-2’, ‘op/3’, and
‘set_prolog_flag/2’.  The *note initialization/1: 42. directive may be
used for defining an initialization goal to be executed when loading a
source file.

Logtalk source files can include the text of other files by using the
*note include/1: b8. directive.  Although there is also a standard
Prolog ‘include/1’ directive, any occurrences of this directive in a
Logtalk source file is handled by the Logtalk compiler, not by the *note
backend Prolog compiler: 34, to improve portability.

When writing a Logtalk source file, the following advice applies:

   - When practical and when performance is critical, define each entity
     on its own source file.

   - Source file loading order can impact performance (e.g., if an
     object imports a category defined in a source file loaded after the
     object source file, no static binding optimizations will be
     possible).

   - Initialization directives that result in the compilation and
     loading of other source files (e.g., libraries) should preferably
     be written in the application loader file to ensure the
     availability of the entities they define when compiling the
     application source files (thus enabling static binding
     optimizations).

Note that you can use the logtalk::loaded_files_topological_sort/1(1)
and logtalk::loaded_files_topological_sort/2(2) predicates to find an
optimal file loading order to eliminate compilation warnings due to
files being loaded before their dependencies.  In the case of simple
applications with no library dependencies:

     ?- {loader}.  % load you application code
     ...

     ?- logtalk::loaded_files_topological_sort(Sorted).
     Sorted = [...]

Use the file basenames from the returned list to update the application
driver files (typically, ‘loader.lgt’ and ‘tester.lgt’).

In more complex applications with external library dependencies, define
a library alies for your application (e.g., ‘my_app’) and use ot get an
initial list of your application files:

     ?- {my_app(loader)}.  % load you application code
     ...

     ?- findall(Path, logtalk::loaded_file_property(Path, library(my_app)), Paths),
        logtalk::loaded_files_topological_sort(Paths, Sorted).
        Sorted = [...]

Note that the ‘Sorted’ list will include the loader file itself.

* Menu:

* Naming conventions::
* Source file text encoding::

   ---------- Footnotes ----------

   (1) 
../../apis/logtalk_0.html#logtalk-0-loaded-files-topological-sort-1

   (2) 
../../apis/logtalk_0.html#logtalk-0-loaded-files-topological-sort-2


File: TheLogtalkHandbook-3.96.0.info,  Node: Naming conventions,  Next: Source file text encoding,  Up: Source files

1.14.3.1 Naming conventions
...........................

When defining each entity in its own source file, it is recommended that
the source file be named after the entity identifier.  For parametric
objects, the identifier arity can be appended to the identifier functor.
By default, all Logtalk source files use the extension ‘.lgt’ but this
is optional and can be set in the adapter files.  For example, we may
define an object named ‘vehicle’ and save it in a ‘vehicle.lgt’ source
file.  A ‘sort(_)’ parametric object would be saved it on a ‘sort_1.lgt’
source file.


File: TheLogtalkHandbook-3.96.0.info,  Node: Source file text encoding,  Prev: Naming conventions,  Up: Source files

1.14.3.2 Source file text encoding
..................................

The text encoding used in a source file may be declared using the *note
encoding/1: 298. directive when running Logtalk with backend Prolog
compilers that support multiple encodings (check the *note
encoding_directive: 299. flag in the adapter file of your Prolog
compiler).


File: TheLogtalkHandbook-3.96.0.info,  Node: Multi-pass compiler,  Next: Compiling and loading your applications,  Prev: Source files,  Up: Writing and running applications

1.14.4 Multi-pass compiler
--------------------------

Logtalk is implemented using a 'multi-pass' compiler.  In comparison,
some Prolog systems use a multi-pass compiler while others use a
single-pass compiler.  While there are pros and cons with each solution,
the most relevant consequence in this context is for the content of
source files.  In Logtalk, entities and predicates only become available
(for the runtime system) after the source file is successfully compiled
and loaded.  This may prevent some compiler optimizations, notably *note
static binding: 35, if some of the referred entities are defined in the
same source file.  On the other hand, the order of predicate directives
and predicate definitions is irrelevant.  In contrast, in a system
implemented using a single-pass compiler, the order of the source file
terms can and often is significant for proper and successful
compilation.  In these systems, predicates may become available for
calling as soon as they are compiled, even if the rest of the source
file is yet to be compiled.

The Logtalk compiler reads source files using the Prolog standard
‘read_term/3’ predicate.  This ensures compatibility with any syntax
extensions that the used backend may implement.  In the first compiler
stage, all source file terms are read, and data about all defined
entities, directives, predicates, and grammar rules is collected.  Any
defined *note term-expansion rules: cb. are applied to the read terms.
Grammar rules are expanded into predicate clauses unless expanded by
user-defined term-expansion rules.  The second stage compiles all
initialization goals and clause bodies, taking advantage of the data
collected in the first stage and applying any defined goal-expansion
rules.  Depending on the compilation mode, the generated code can be
instrumented for debugging tools or optimized for performance.  Linter
checks are performed during these two first stages.  The final step in
the second stage is to write the generated intermediate Prolog code into
a temporary file.  In the third and final stage, this intermediate
Prolog file is compiled and loaded by the used backend.  These
intermediate files are deleted by default after loading (see the *note
clean: 292. flag description for details).


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiling and loading your applications,  Next: Compiler errors warnings and comments,  Prev: Multi-pass compiler,  Up: Writing and running applications

1.14.5 Compiling and loading your applications
----------------------------------------------

Your applications will be made of source files containing your objects,
protocols, and categories.  The source files can be compiled to disk by
calling the *note logtalk_compile/1: 29e. built-in predicate:

     | ?- logtalk_compile([source_file1, source_file2, ...]).

This predicate runs the compiler on each file and, if no fatal errors
are found, outputs Prolog source files that can then be consulted or
compiled in the usual way by your Prolog compiler.

To compile to disk and also load into memory the source files, we can
use the *note logtalk_load/1: 46. built-in predicate:

     | ?- logtalk_load([source_file1, source_file2, ...]).

This predicate works in the same way as the predicate
‘logtalk_compile/1’ but also loads the compiled files into memory.

Both predicates expect a source file name or a list of source file names
as an argument.  The Logtalk source file name extension, as defined in
the adapter file (by default, ‘.lgt’), can be omitted.

If you have more than a few source files, then you may want to use a
*note loader file: 4f. helper file containing the calls to the
‘logtalk_load/1-2’ predicates.  Consulting or compiling the loader file
will then compile and load all your Logtalk entities into memory (see
below for details).

With most *note backend Prolog compilers: 34, you can use the shorthand
‘{File}’ for ‘logtalk_load(File)’ and ‘{File1, File2, ...}’ for
‘logtalk_load([File1, File2, ...])’.  The use these shorthands should be
restricted to the Logtalk/Prolog top-level interpreter, as they are not
part of the language specification and may be commented out in case of
conflicts with backend Prolog compiler features.

The built-in predicate *note logtalk_make/0: 29f. can be used to reload
all modified source files.  With most backend Prolog compilers, you can
also use the ‘{*}’ top-level shortcut.  Files are also reloaded when the
compilation mode changes.  An extended version of this predicate, *note
logtalk_make/1: 2a0, accepts multiple targets, including ‘all’, ‘clean’,
‘check’, ‘circular’, ‘documentation’, ‘caches’, ‘debug’, ‘normal’, and
‘optimal’.  For example, assume that you have loaded your application
files and found a bug.  You can easily recompile the files in debug mode
by using the ‘logtalk_make(debug)’ goal.  After debugging and fixing the
bug, you can reload the files in normal mode using the
‘logtalk_make(normal)’ or in optimized mode using the
‘logtalk_make(optimal)’ goal.  See the predicates documentation for a
complete list of targets and top-level shortcuts.  In particular, the
‘logtalk_make(clean)’ goal can be specially useful before switching
backend Prolog compilers, as the generated intermediate files may not be
compatible.  The ‘logtalk_make(caches)’ goal is usually used when
benchmarking compiler performance improvements.


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiler errors warnings and comments,  Next: Loader files,  Prev: Compiling and loading your applications,  Up: Writing and running applications

1.14.6 Compiler errors, warnings, and comments
----------------------------------------------

Following a Prolog tradition inherited from Quintus Prolog, the compiler
prefixes (by default) errors with a ‘!’ and warnings with a ‘*’.  For
example:

     !     Existence error: directive object/1 does not exist
     !       in directive end_object/0
     !       in file /home/jdoe/logtalk/examples/errors/unmatched_directive.lgt at or above line 27

     *     No matching clause for goal: baz(a)
     *       while compiling object main_include_compiler_warning
     *       in file /home/jdoe/logtalk/examples/errors/include_compiler_warning.lgt between lines 38-39

Compiler comments are prefixed by ‘%’.  For example:

     ?- {ack(loader)}.
     % [ /home/jdoe/logtalk/examples/ack/ack.lgt loaded ]
     % [ /home/jdoe/logtalk/examples/ack/loader.lgt loaded ]
     % (0 warnings)
     true.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loader files,  Next: Libraries of source files,  Prev: Compiler errors warnings and comments,  Up: Writing and running applications

1.14.7 Loader files
-------------------

If you look into the Logtalk distribution, you will notice that most
source code directories (e.g., of tools, libraries, and examples)
contain a 'driver file' that can be used to load all included source
files and any required libraries.  These loader files are usually named
‘loader.lgt’ or contain the word 'loader' in their name.  Loader files
are ordinary source files and thus compiled and loaded like any source
file.  By also defining a loader file for your project, you can then
load it by simply typing:

     | ?- {loader}.

Another driver file, usually named ‘tester.lgt’ (or containing the word
'tester' in its name) is commonly used to load and run tests.  By also
defining a tester file for your project, you can then run its tests by
simply typing:

     | ?- {tester}.

Usually these driver files contain calls to the built-in predicates
*note set_logtalk_flag/2: 51. (e.g., for setting global,
'project-specific', flag values) and *note logtalk_load/1: 46. or *note
logtalk_load/2: 4e. (for loading project files), wrapped inside a Prolog
‘initialization/1’ directive for portability.  For instance, if your
code is split into three source files named ‘source1.lgt’,
‘source2.lgt’, and ‘source3.lgt’, then the contents of your loader file
could be:

     :- initialization((
         % set project-specific global flags
         set_logtalk_flag(events, allow),
         % load the project source files
         logtalk_load([source1, source2, source3])
     )).

Another example of directives that are often used in a loader file would
be ‘op/3’ directives declaring global operators needed by your project.
Loader files are also often used for setting source file-specific
compiler flags (this is useful even when you only have a single source
file if you always load it with the same set of compiler flags).  For
example:

     :- initialization((
         % set project-specific global flags
         set_logtalk_flag(source_data, off),
         % load the project source files
         logtalk_load(
             [source1, source2, source3],
             % source file-specific flags
             [portability(warning)]),
         logtalk_load(
             [source4, source5],
             % source file-specific flags
             [portability(silent)])
     )).

To take the best advantage of loader and tester files, define a clause
for the multifile and dynamic ‘logtalk_library_path/2’ predicate for the
directory containing your source files as explained in the next section.

When your project also uses Prolog module resources, the loader file is
also the advised place to load them, preferably without any exports.
For example:

     :- use_module(library(clpfd), []).
     ...

     :- initialization((
         ...
     )).

Complex projects often use a main loader file that loads the loader
files of each of the project components.  Thus, loader files provide a
central point to understand a project organization and dependencies.

It is worth mentioning a common mistake when writing the first loader
files.  New users sometimes try to set compiler flags using
‘logtalk_load/2’ when loading a loader file.  For example, by writing:

     | ?- logtalk_load(loader, [optimize(on)]).

This will not work as you might expect, as the compiler flags will only
be used in the compilation of the ‘loader.lgt’ file itself and will not
affect the compilation of files loaded through the ‘initialization/1’
directive contained on the loader file.


File: TheLogtalkHandbook-3.96.0.info,  Node: Libraries of source files,  Next: Settings files,  Prev: Loader files,  Up: Writing and running applications

1.14.8 Libraries of source files
--------------------------------

Logtalk defines a 'library' simply as a directory containing source
files.  Library locations can be specified by defining or asserting
clauses for the dynamic and multifile predicate *note
logtalk_library_path/2: 2a7.  For example:

     :- multifile(logtalk_library_path/2).
     :- dynamic(logtalk_library_path/2).

     logtalk_library_path(shapes, '$LOGTALKUSER/examples/shapes/').

The first argument of the predicate is used as an alias for the path on
the second argument.  Library aliases may also be used on the second
argument.  For example:

     :- multifile(logtalk_library_path/2).
     :- dynamic(logtalk_library_path/2).

     logtalk_library_path(lgtuser, '$LOGTALKUSER/').
     logtalk_library_path(examples, lgtuser('examples/')).
     logtalk_library_path(viewpoints, examples('viewpoints/')).

This allows us to load a library source file without the need to first
change the current working directory to the library directory and then
back to the original directory.  For example, in order to load a
‘loader.lgt’ file, contained in a library named ‘viewpoints’, we just
need to type:

     | ?- logtalk_load(viewpoints(loader)).

The best way to take advantage of this feature is to load at startup a
source file containing clauses for the ‘logtalk_library_path/2’
predicate needed for all available libraries (typically, using a *note
settings file: 49, as discussed below).  This allows us to load library
source files or entire libraries without worrying about library paths,
improving code portability.  The directory paths on the second argument
should always end with the path directory separator character.  Most
backend Prolog compilers allow the use of environment variables in the
second argument of the ‘logtalk_library_path/2’ predicate.  Use of POSIX
relative paths (e.g., ‘'../'’ or ‘'./'’) for top-level library
directories (e.g., ‘lgtuser’ in the example above) is not advised, as
different backend Prolog compilers may start with different initial
working directories, which may result in portability problems of your
loader files.

This *note library notation: 2a8. provides functionality inspired by the
‘file_search_path/2’ mechanism introduced by Quintus Prolog and later
adopted by some other Prolog compilers but with a key difference: there
is no fragile search mechanism, and the Logtalk ‘make’ can be used to
check for duplicated library aliases.  Multiple definitions for the same
alias are problematic when using external dependencies, as any
third-party update to those dependencies can introduce file name
clashes.  Note that the potential for these clashes cannot be reliably
minimized by a careful ordering of the ‘logtalk_library_path/2’
predicate clauses due to this predicate being multifile and dynamic.


File: TheLogtalkHandbook-3.96.0.info,  Node: Settings files,  Next: Compiler linter,  Prev: Libraries of source files,  Up: Writing and running applications

1.14.9 Settings files
---------------------

Although it is always possible to edit the *note backend Prolog
compiler: 34. adapter files, the recommended solution to customize
compiler flags is to create a ‘settings.lgt’ file in the Logtalk user
folder or in the user home folder.  Depending on the backend Prolog
compiler and the operating-system, is also possible to define
per-project settings files by creating a ‘settings.lgt’ file in the
project directory and by starting Logtalk from this directory.  At
startup, Logtalk tries to load a ‘settings.lgt’ file from the following
directories, searched in sequence:

   - Startup directory (‘$LOGTALK_STARTUP_DIRECTORY’)

   - Logtalk user directory (‘$LOGTALKUSER’)

   - User home directory (‘$HOME’; ‘%USERPROFILE%’ on Windows if
     ‘%HOME%’ is not defined)

   - Application data directory (‘%APPDATA%\Logtalk’; only on Windows)

   - Config directory (‘$XDG_CONFIG_HOME/logtalk’)

   - Default config directory (‘$HOME/.config/logtalk/’)

The startup directory is only searched when the read-only *note
settings_file: 2ab. flag is set to ‘allow’.  When no settings files are
found, Logtalk will use the default compiler flag values set on the
backend Prolog compiler adapter files.  When limitations of the backend
Prolog compiler or the operating-system prevent Logtalk from finding the
settings files, these can always be loaded manually after Logtalk
startup.

Settings files are normal Logtalk source files (although when
automatically loaded by Logtalk they are compiled and loaded silently
with any errors being reported but otherwise ignored).  The usual
contents is an ‘initialization/1’ Prolog directive containing calls to
the *note set_logtalk_flag/2: 51. Logtalk built-in predicate and
asserting clauses for the *note logtalk_library_path/2: 2a7. multifile
dynamic predicate.  Note that the *note set_logtalk_flag/2: 50.
directive cannot be used as its scope is local to the source file being
compiled.

One of the troubles of writing portable applications is the different
feature sets of Prolog compilers.  Using the Logtalk support for
conditional compilation and the *note prolog_dialect: 2ac. flag we can
write a single settings file that can be used with several *note backend
Prolog compilers: 34.:

     :- if(current_logtalk_flag(prolog_dialect, yap)).

         % YAP specific settings
         ...

     :- elif(current_logtalk_flag(prolog_dialect, gnu)).

         % GNU Prolog specific settings
         ...

     :- else.

         % generic Prolog settings

     :- endif.

The Logtalk distribution includes a ‘samples/settings-sample.lgt’ sample
file with commented out code snippets for common settings.


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiler linter,  Next: Compiler flags,  Prev: Settings files,  Up: Writing and running applications

1.14.10 Compiler linter
-----------------------

The compiler includes a *note linter: 2af. that checks for a wide range
of possible problems in source files.  Notably, the compiler checks for
unknown entities, unknown predicates, undefined predicates (i.e.,
predicates that are declared but not defined), missing directives
(including missing ‘dynamic/1’ and ‘meta_predicate/1’ directives),
redefined built-in predicates, calls to non-portable predicates,
singleton variables, goals that are always true or always false (i.e.,
goals that can be replaced by ‘true’ or ‘fail’), and trivial fails
(i.e., calls to predicates with no match clauses).  Most of the linter
warnings are controlled by *note compiler flags: 2b0.  See the next
section for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiler flags,  Next: Reloading source files,  Prev: Compiler linter,  Up: Writing and running applications

1.14.11 Compiler flags
----------------------

The *note logtalk_load/1: 46. and *note logtalk_compile/1: 29e. always
use the current set of default compiler flags as specified in your
settings file and the Logtalk adapter files or changed for the current
session using the built-in predicate *note set_logtalk_flag/2: 51.
Although the default flag values cover the usual cases, you may want to
use a different set of flag values while compiling or loading some of
your Logtalk source files.  This can be accomplished by using the *note
logtalk_load/2: 4e. or the *note logtalk_compile/2: 2b2. built-in
predicates.  These two predicates accept a list of options affecting how
a Logtalk source file is compiled and loaded:

     | ?- logtalk_compile(Files, Options).

or:

     | ?- logtalk_load(Files, Options).

In fact, the ‘logtalk_load/1’ and ‘logtalk_compile/1’ predicates are
just shortcuts to the extended versions called with the default compiler
flag values.  The options are represented by a compound term where the
functor is the flag name and the sole argument is the flag value.

We may also change the default flag values from the ones loaded from the
adapter file by using the *note set_logtalk_flag/2: 51. built-in
predicate.  For example:

     | ?- set_logtalk_flag(unknown_entities, silent).

The current default flags values can be enumerated using the *note
current_logtalk_flag/2: 2b3. built-in predicate:

     | ?- current_logtalk_flag(unknown_entities, Value).

     Value = silent
     yes

Logtalk also implements a *note set_logtalk_flag/2: 50. directive, which
can be used to set flags within a source file or within an entity.  For
example:

     % compile objects in this source file with event support
     :- set_logtalk_flag(events, allow).

     :- object(foo).

         % compile this object with support
         % for dynamic predicate declarations
         :- set_logtalk_flag(dynamic_declarations, allow).
         ...

     :- end_object.

     ...

Note that the scope of the ‘set_logtalk_flag/2’ directive is local to
the entity or to the source file containing it.

     Note: Applications should never rely on default flag values for
     working properly.  Whenever the compilation of a source file or an
     entity requires a specific flag value, the flag should be set
     explicitly in the entity, in the source file, or in the loader
     file.

* Menu:

* Read-only flags::
* Version flags::
* Lint flags::
* Optional features compilation flags::
* Backend Prolog compiler and loader flags::
* Other flags::
* User-defined flags::


File: TheLogtalkHandbook-3.96.0.info,  Node: Read-only flags,  Next: Version flags,  Up: Compiler flags

1.14.11.1 Read-only flags
.........................

Some flags have read-only values and thus cannot be changed at runtime.
Their values are defined in the Prolog backend *note adapter files: 154.
These are:

‘settings_file’

     Allows or disables loading of a *note settings file: 49. at
     startup.  Possible values are ‘allow’, ‘restrict’, and ‘deny’.  The
     usual default value is ‘allow’ but it can be changed by editing the
     adapter file when e.g.  embedding Logtalk in a compiled
     application.  With a value of ‘allow’, settings files are searched
     in the startup directory, in the Logtalk user directory, in the
     user home directory, in the ‘APPDATA’ if running on Windows, and in
     the XDG configuration directory.  With a value of ‘restrict’, the
     search for the settings files skips the startup directory.

‘prolog_dialect’

     Identifier of the *note backend Prolog compiler: 34. (an atom).
     This flag can be used for *note conditional compilation: 18a. of
     Prolog compiler specific code.

‘prolog_version’

     Version of the *note backend Prolog compiler: 34. (a compound term,
     ‘v(Major, Minor, Patch)’, whose arguments are integers).  This flag
     availability depends on the Prolog compiler.  Checking the value of
     this flag fails for any Prolog compiler that does not provide
     access to version data.

‘prolog_compatible_version’

     Compatible version of the *note backend Prolog compiler: 34. (a
     compound term, usually with the format ‘@>=(v(Major, Minor,
     Patch))’, whose arguments are integers).  This flag availability
     depends on the Prolog compiler.  Checking the value of this flag
     fails for any Prolog compiler that does not provide access to
     version data.

‘unicode’

     Informs Logtalk if the *note backend Prolog compiler: 34. supports
     the Unicode standard.  Possible flag values are ‘unsupported’,
     ‘full’ (all Unicode planes supported), and ‘bmp’ (supports only the
     Basic Multilingual Plane).

‘encoding_directive’

     Informs Logtalk if the *note backend Prolog compiler: 34. supports
     the *note encoding/1: 298. directive.  This directive is used for
     declaring the text encoding of source files.  Possible flag values
     are ‘unsupported’, ‘full’ (can be used in both Logtalk source files
     and compiler generated Prolog files), and ‘source’ (can be used
     only in Logtalk source files).

‘tabling’

     Informs Logtalk if the *note backend Prolog compiler: 34. provides
     tabling programming support.  Possible flag values are
     ‘unsupported’ and ‘supported’.

‘engines’

     Informs if the *note backend Prolog compiler: 34. provides the
     required low level multi-threading programming support for Logtalk
     *note threaded engines: 2ba.  Possible flag values are
     ‘unsupported’ and ‘supported’.

‘threads’

     Informs if the *note backend Prolog compiler: 34. provides the
     required low level multi-threading programming support for all
     high-level Logtalk *note multi-threading features: 73.  Possible
     flag values are ‘unsupported’ and ‘supported’.

‘modules’

     Informs Logtalk if the *note backend Prolog compiler: 34. provides
     suitable module support.  Possible flag values are ‘unsupported’
     and ‘supported’ (independently of this flag, Logtalk provides
     limited support for compiling Prolog modules as objects).

‘coinduction’

     Informs Logtalk if the *note backend Prolog compiler: 34. provides
     the required minimal support for cyclic terms necessary for working
     with *note coinductive predicates: 170.  Possible flag values are
     ‘unsupported’ and ‘supported’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Version flags,  Next: Lint flags,  Prev: Read-only flags,  Up: Compiler flags

1.14.11.2 Version flags
.......................

‘version_data(Value)’

     Read-only flag whose value is the compound term
     ‘logtalk(Major,Minor,Patch,Status)’.  The first three arguments are
     integers and the last argument is an atom, possibly empty,
     representing version status: ‘aN’ for alpha versions, ‘bN’ for beta
     versions, ‘rcN’ for release candidates (with ‘N’ being a natural
     number), and ‘stable’ for stable versions.  The ‘version_data’ flag
     is also a de facto standard for Prolog compilers.


File: TheLogtalkHandbook-3.96.0.info,  Node: Lint flags,  Next: Optional features compilation flags,  Prev: Version flags,  Up: Compiler flags

1.14.11.3 Lint flags
....................

‘linter(Option)’

     Meta-flag for managing the values of all the linter flags as a
     group.  Possible option values are ‘on’ to set all the individual
     linter flags to ‘warning’, ‘off’ to set all the individual linter
     flags to ‘silent’, and ‘default’ to set all the individual linter
     flag values to their defaults as defined in the backend adapter
     files (the usual default).  This flag 'must' always be defined in
     the backend adapter files with the value of ‘default’.

‘unknown_entities(Option)’

     Controls the unknown entity warnings, resulting from loading an
     entity that references some other entity that is not currently
     loaded.  Possible option values are ‘warning’ (the usual default)
     and ‘silent’.  Note that these warnings are not always avoidable,
     specially when using reflective designs of class-based hierarchies.

‘unknown_predicates(Option)’

     Defines the compiler behavior when unknown messages or calls to
     unknown predicates (or non-terminals) are found.  An unknown
     message is a message sent to an object that is not part of the
     object protocol.  An unknown predicate is a called predicate that
     is neither locally declared or defined.  Possible option values are
     ‘error’, ‘warning’ (the usual default), and ‘silent’ (not
     recommended).

‘undefined_predicates(Option)’

     Defines the compiler behavior when calls to declared but undefined
     predicates (or non-terminals) are found.  Note that these calls
     will fail at runtime as per closed-world assumption.  Possible
     option values are ‘error’, ‘warning’ (the usual default), and
     ‘silent’ (not recommended).

‘steadfastness(Option)’

     Controls warnings about 'possible' non *note steadfast: 2c4.
     predicate definitions due to variable aliasing at a clause head and
     a cut in the clause body.  Possible option values are ‘warning’ and
     ‘silent’ (the usual default due to the possibility of false
     positives).

‘portability(Option)’

     Controls the non-ISO specified Prolog built-in predicate and
     non-ISO specified Prolog built-in arithmetic function calls
     warnings plus use of non-standard Prolog flags and/or flag values.
     Possible option values are ‘warning’ and ‘silent’ (the usual
     default).

‘deprecated(Option)’

     Controls the deprecated predicate warnings.  Possible option values
     are ‘warning’ (the usual default) and ‘silent’.

‘missing_directives(Option)’

     Controls the missing predicate directive warnings.  Possible option
     values are ‘warning’ (the usual default) and ‘silent’ (not
     recommended).

‘duplicated_directives(Option)’

     Controls the duplicated predicate directive warnings.  Possible
     option values are ‘warning’ (the usual default) and ‘silent’ (not
     recommended).  Note that conflicting directives for the same
     predicate are handled as errors, not as duplicated directive
     warnings.

‘trivial_goal_fails(Option)’

     Controls the printing of warnings for calls to local static
     predicates with no matching clauses.  Possible option values are
     ‘warning’ (the usual default) and ‘silent’ (not recommended).

‘always_true_or_false_goals(Option)’

     Controls the printing of warnings for goals that are always true or
     false.  Possible option values are ‘warning’ (the usual default)
     and ‘silent’ (not recommended).  A unexpected exception in the goal
     being checked is also reported.

‘grammar_rules(Option)’

     Controls the printing of grammar rules related warnings.  Possible
     option values are ‘warning’ (the usual default) and ‘silent’ (not
     recommended).

‘arithmetic_expressions(Option)’

     Controls the printing of arithmetic expressions related warnings.
     Possible option values are ‘warning’ (the usual default) and
     ‘silent’ (not recommended).

‘lambda_variables(Option)’

     Controls the printing of lambda variable related warnings.
     Possible option values are ‘warning’ (the usual default) and
     ‘silent’ (not recommended).

‘suspicious_calls(Option)’

     Controls the printing of suspicious call warnings.  Possible option
     values are ‘warning’ (the usual default) and ‘silent’ (not
     recommended).

‘redefined_built_ins(Option)’

     Controls the Logtalk and Prolog built-in predicate redefinition
     warnings.  Possible option values are ‘warning’ and ‘silent’ (the
     usual default).  Warnings about redefined Prolog built-in
     predicates are often the result of running a Logtalk application on
     several Prolog compilers, as each Prolog compiler defines its set
     of built-in predicates.

‘redefined_operators(Option)’

     Controls the Logtalk and Prolog built-in operator redefinition
     warnings.  Possible option values are ‘warning’ (the usual default)
     and ‘silent’.  Redefining Logtalk operators or standard Prolog
     operators can break term parsing, causing syntax errors or change
     how terms are parsed, introducing bugs.

‘singleton_variables(Option)’

     Controls the singleton variable warnings.  Possible option values
     are ‘warning’ (the usual default) and ‘silent’ (not recommended).

‘naming(Option)’

     Controls warnings about entity, predicate, and variable names per
     official coding guidelines (which advise using underscores for
     entity and predicate names and camel case for variable names).
     Additionally, variable names should not differ only in case.
     Possible option values are ‘warning’ and ‘silent’ (the usual
     default due to the current limitation to ASCII names and the
     computational cost of the checks).

‘duplicated_clauses(Option)’

     Controls warnings of duplicated entity clauses (and duplicated
     entity grammar rules).  Possible option values are ‘warning’ and
     ‘silent’ (the usual default due to the required heavy
     computations).  When the term-expansion mechanism is used and
     results in duplicated clauses, the reported line numbers are for
     lines of the original clauses that were expanded.

‘disjunctions(Option)’

     Controls warnings on clauses where the body is a disjunction.
     Possible option values are ‘warning’ (the usual default) and
     ‘silent’.  As per coding guidelines, in most cases, these clauses
     can be rewritten using a clause per disjunction branch for improved
     code readability.

‘conditionals(Option)’

     Controls warnings on if-then-else and soft-cut control constructs.
     Possible option values are ‘warning’ (the usual default) and
     ‘silent’.  Warnings include misuse of cuts, potential bugs in the
     test part, and missing else part (lack of compliance with coding
     guidelines).

‘catchall_catch(Option)’

     Controls warnings on ‘catch/3’ goals that catch all exceptions.
     Possible option values are ‘warning’ and ‘silent’ (the usual
     default).  Lack of standardization often makes it tricky or
     cumbersome to avoid too generic ‘catch/3’ goals when writing
     portable code.

‘left_recursion(Option)’

     Controls warnings of left-recursion on clauses and grammar rules.
     Specifically, when the clause or grammar rule head and the leftmost
     goal in the body are variants.  Possible option values are
     ‘warning’ (the usual default) and ‘silent’.

‘tail_recursive(Option)’

     Controls warnings of non-tail recursive predicate (and
     non-terminal) definitions.  The lint check does not detect all
     cases of non-tail recursive predicate definitions, however.  Also,
     definitions that make two or more recursive calls are not reported
     as usually they cannot be changed to be tail recursive.  Possible
     option values are ‘warning’ and ‘silent’ (the usual default).

‘encodings(Option)’

     Controls the source file text encoding warnings.  Possible option
     values are ‘warning’ (the usual default) and ‘silent’.

‘general(Option)’

     Controls warnings that are not controlled by a specific flag.
     Possible option values are ‘warning’ (the usual default) and
     ‘silent’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Optional features compilation flags,  Next: Backend Prolog compiler and loader flags,  Prev: Lint flags,  Up: Compiler flags

1.14.11.4 Optional features compilation flags
.............................................

‘complements(Option)’

     Allows objects to be compiled with support for complementing
     categories turned off in order to improve performance and security.
     Possible option values are ‘allow’ (allow complementing categories
     to override local object predicate declarations and definitions),
     ‘restrict’ (allow complementing categories to add predicate
     declarations and definitions to an object but not to override
     them), and ‘deny’ (ignore complementing categories; the usual
     default).  This option can be used on a per-object basis.  Note
     that changing this option is of no consequence for objects already
     compiled and loaded.

‘dynamic_declarations(Option)’

     Allows objects to be compiled with support for dynamic declaration
     of new predicates turned off in order to improve performance and
     security.  Possible option values are ‘allow’ and ‘deny’ (the usual
     default).  This option can be used on a per-object basis.  Note
     that changing this option is of no consequence for objects already
     compiled and loaded.  This option is only checked when sending an
     *note asserta/1: 1b2. or *note assertz/1: 1b3. message to an
     object.  Local asserting of new predicates is always allowed.

‘events(Option)’

     Allows message-sending calls to be compiled with or without *note
     event-driven programming: 6d. support.  Possible option values are
     ‘allow’ and ‘deny’ (the usual default).  Objects (and categories)
     compiled with this option set to ‘deny’ use optimized code for
     message-sending calls that do not trigger events.  As such, this
     option can be used on a per-object (or per-category) basis.  Note
     that changing this option is of no consequence for objects already
     compiled and loaded.

‘context_switching_calls(Option)’

     Allows context-switching calls (‘(<<)/2’) to be either allowed or
     denied.  Possible option values are ‘allow’ and ‘deny’.  The
     default flag value is ‘allow’.  Note that changing this option is
     of no consequence for objects already compiled and loaded.


File: TheLogtalkHandbook-3.96.0.info,  Node: Backend Prolog compiler and loader flags,  Next: Other flags,  Prev: Optional features compilation flags,  Up: Compiler flags

1.14.11.5 Backend Prolog compiler and loader flags
..................................................

‘underscore_variables(Option)’

     Controls the interpretation of variables that start with an
     underscore (excluding the anonymous variable) that occur once in a
     term as either don’t care variables or singleton variables.
     Possible option values are ‘dont_care’ (the default for all
     supported backends) and ‘singletons’.  Although a changeable flag,
     its value is backend dependent and thus expected to be set only in
     the backend adapter files.

‘prolog_compiler(Flags)’

     List of compiler flags for the generated Prolog files.  The valid
     flags are specific to the used Prolog backend compiler.  The usual
     default is the empty list.  These flags are passed to the backend
     Prolog compiler built-in predicate that is responsible for
     compiling to disk a Prolog file.  For Prolog compilers that don’t
     provide separate predicates for compiling and loading a file, use
     instead the *note prolog_loader: 2dd. flag.

‘prolog_loader(Flags)’

     List of loader flags for the generated Prolog files.  The valid
     flags are specific to the used Prolog backend compiler.  The usual
     default is the empty list.  These flags are passed to the backend
     Prolog compiler built-in predicate that is responsible for loading
     a (compiled) Prolog file.


File: TheLogtalkHandbook-3.96.0.info,  Node: Other flags,  Next: User-defined flags,  Prev: Backend Prolog compiler and loader flags,  Up: Compiler flags

1.14.11.6 Other flags
.....................

‘scratch_directory(Directory)’

     Sets the directory to be used to store the temporary files
     generated when compiling Logtalk source files.  This directory can
     be specified using an atom or using *note library notation: 2a8.
     The directory must always end with a slash.  The default value is a
     sub-directory of the source files directory, either ‘'./lgt_tmp/'’
     or ‘'./.lgt_tmp/'’ (depending on the backend Prolog compiler and
     operating-system).  Relative directories must always start with
     ‘'./'’ due to the lack of a portable solution to check if a path is
     relative or absolute.  The default value set on the *note backend
     Prolog compiler: 34. adapter file can be overridden by defining the
     ‘scratch_directory’ library alias (see the *note
     logtalk_library_path/2: 2a7. predicate documentation for details).

‘report(Option)’

     Controls the default printing of messages.  Possible option values
     are ‘on’ (by usual default, print all messages that are not
     intercepted by the user), ‘warnings’ (only print warning and error
     messages that are not intercepted by the user), and ‘off’ (do not
     print any messages that are not intercepted by the user).

‘code_prefix(Character)’

     Enables the definition of prefix for all functors of Prolog code
     generated by the Logtalk compiler.  The option value must be a
     single character atom.  Its default value is ‘'$'’.  Specifying a
     code prefix provides a way to solve possible conflicts between
     Logtalk compiled code and other Prolog code.  In addition, some
     Prolog compilers automatically hide predicates whose functor starts
     with a specific prefix, such as the character ‘$’.  Although this
     is not a read-only flag, it should only be changed at startup time
     and 'before' loading any source files.  When changing this flag
     (e.g., from a *note settings file: 49.), restart with the *note
     clean: 292. flag turned on to ensure that any compiled files using
     the old ‘code_prefix’ value will be recompiled.

‘optimize(Option)’

     Controls the compiler optimizations.  Possible option values are
     ‘on’ (used by default for deployment) and ‘off’ (used by default
     for development).  Compiler optimizations include the use of static
     binding whenever possible, the removal of redundant calls to
     ‘true/0’ from predicate clauses, the removal of redundant
     unifications when compiling grammar rules, and inlining of
     predicate definitions with a single clause that links to a local
     predicate, to a plain Prolog built-in (or foreign) predicate, or to
     a Prolog module predicate with the same arguments.  Care should be
     taken when developing applications with this flag turned on as
     changing and reloading a file may render *note static binding: 35.
     optimizations invalid for code defined in other loaded files.
     Turning on this flag automatically turns off the *note debug: 2e2.
     flag.

‘source_data(Option)’

     Defines how much information is retained when compiling a source
     file.  Possible option values are ‘on’ (the usual default for
     development) and ‘off’.  With this flag set to ‘on’, Logtalk will
     keep the information represented using documenting directives plus
     source location data (including source file names and line
     numbers).  This information can be retrieved using the *note
     reflection API: 48. and is useful for documenting, debugging, and
     integration with third-party development tools.  This flag can be
     turned off in order to generate more compact code.

‘debug(Option)’

     Controls the compilation of source files in debug mode (the Logtalk
     default debugger can only be used with files compiled in this
     mode).  Also controls, by default, printing of ‘debug>’ and
     ‘debug(Topic)’ messages.  Possible option values are ‘on’ and ‘off’
     (the usual default).  Turning on this flag automatically turns off
     the *note optimize: 8c. flag.

‘reload(Option)’

     Defines the reloading behavior for source files.  Possible option
     values are ‘skip’ (skip reloading of already loaded files; this
     value can be used to get similar functionality to the Prolog
     directive ‘ensure_loaded/1’ but should be used only with fully
     debugged code), ‘changed’ (the usual default; reload files only
     when they are changed since last loaded, provided that any explicit
     flags and the compilation mode are the same as before), and
     ‘always’ (always reload files).

‘relative_to(Directory)’

     Defines a base directory for resolving relative source file paths.
     The default value is the directory of the source file being
     compiled.

‘hook(Object)’

     Allows the definition of an object (which can be the pseudo-object
     user(1)) implementing the expanding(2) built-in protocol.  The hook
     object must be compiled and loaded when this option is used.  It’s
     also possible to specify a Prolog module instead of a Logtalk
     object, but the module must be pre-loaded, and its identifier must
     be different from any object identifier.

‘clean(Option)’

     Controls cleaning of the intermediate Prolog files generated when
     compiling Logtalk source files.  Possible option values are ‘off’
     and ‘on’ (the usual default).  When turned on, intermediate files
     are deleted after loading, and all source files are recompiled
     disregarding any existing intermediate files.  When turned off, the
     intermediate files are kept.  This is useful when embedding
     applications, which requires collecting the intermediate code, and
     when working on large applications to avoid repeated recompilation
     of stable code.  The flag must be turned on when changing
     compilation modes, changing flags such as *note code_prefix: 2e1,
     or when turning on linter flags that are off by default without at
     the same time making changes to the application source files
     themselves, as any existing intermediate files would not be
     recompiled as necessary due to file timestamps not changing.

   ---------- Footnotes ----------

   (1) ../../apis/user_0.html#user-0

   (2) ../../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: User-defined flags,  Prev: Other flags,  Up: Compiler flags

1.14.11.7 User-defined flags
............................

Logtalk provides a *note create_logtalk_flag/3: 2e6. predicate that can
be used for defining new flags.


File: TheLogtalkHandbook-3.96.0.info,  Node: Reloading source files,  Next: Batch processing,  Prev: Compiler flags,  Up: Writing and running applications

1.14.12 Reloading source files
------------------------------

As a general rule, reloading source files should never occur in
production code and should be handled with care in development code.
Reloading a Logtalk source file usually requires reloading the
intermediate Prolog file that is generated by the Logtalk compiler.  The
problem is that there is no standard behavior for reloading Prolog
files.  For static predicates, almost all Prolog compilers replace the
old definitions with the new ones.  However, for dynamic predicates, the
behavior depends on the Prolog compiler.  Most compilers replace the old
definitions, but some of them simply append the new ones, which usually
leads to trouble.  See the compatibility notes for the backend Prolog
compiler you intend to use for more information.  There is an additional
potential problem when using multi-threading programming.  Reloading a
threaded object does not recreate from scratch its old message queue,
which may still be in use (e.g., threads may be waiting on it).

When using library entities and stable code, you can avoid reloading the
corresponding source files (and, therefore, recompiling them) by setting
the *note reload: 2e3. compiler flag to ‘skip’.  For code under
development, you can turn off the *note clean: 292. flag to avoid
recompiling files that have not been modified since the last compilation
(assuming that backend Prolog compiler that you are using supports
retrieving file modification dates).  You can disable deleting the
intermediate files generated when compiling source files by changing the
default flag value in your settings file, by using the corresponding
compiler flag with the compiling and loading built-in predicates, or,
for the remaining of a working session, by using the call:

     | ?- set_logtalk_flag(clean, off).

Some caveats that you should be aware of.  First, some warnings that
might be produced when compiling a source file will not show up if the
corresponding object file is up-to-date because the source file is not
being (re)compiled.  Second, if you are using several Prolog compilers
with Logtalk, be sure to perform the first compilation of your source
files with the ‘clean’ flag turned off: the intermediate Prolog files
generated by the Logtalk compiler may not be compatible across Prolog
compilers or even for the same Prolog compiler across operating systems
(e.g., due to the use of different character encodings or end-of-line
characters).


File: TheLogtalkHandbook-3.96.0.info,  Node: Batch processing,  Next: Optimizing performance,  Prev: Reloading source files,  Up: Writing and running applications

1.14.13 Batch processing
------------------------

When doing batch processing, you probably want to turn off the *note
report: 2e0. flag to suppress all messages of type ‘banner’, ‘comment’,
‘comment(_)’, ‘warning’, and ‘warning(_)’ that are normally printed.
Note that error messages and messages providing information requested by
the user will still be printed.


File: TheLogtalkHandbook-3.96.0.info,  Node: Optimizing performance,  Next: Portable applications,  Prev: Batch processing,  Up: Writing and running applications

1.14.14 Optimizing performance
------------------------------

The default compiler flag settings are appropriate for the 'development'
but not necessarily for the 'deployment' of applications.  To minimize
the generated code size, turn the *note source_data: cc. flag off.  To
optimize runtime performance, turn on the *note optimize: 8c. flag.
Your chosen backend Prolog compiler may also provide performance-related
flags; check its documentation.

Pay special attention to file compilation/loading order.  Whenever
possible, compile and load your files by taking into account file
dependencies.  By default, the compiler will print a warning whenever a
file references an entity that is not yet loaded.  Solving these
warnings is key for optimal performance by enabling *note static
binding: 35. optimizations.  For a clear picture of file dependencies,
use the *note diagrams: 2ed. tool to generate a file dependency diagram
for your application.

Minimize the use of dynamic predicates.  Parametric objects can often be
used in alternative.  When dynamic predicates cannot be avoided, try to
make them private.  Declaring a dynamic predicate also as a private
predicate allows the compiler to optimize local calls to the database
methods (e.g., *note assertz/1: 1b3. and *note retract/1: 1b5.) that
modify the predicate.

Sending a *note message to self: 17d. implies *note dynamic binding: 36,
but there are often cases where *note (;;)/1: 5c. is misused to call an
imported or inherited predicate that is never going to be redefined in a
descendant.  In these cases, a *note super call: 115, *note (^^)/1: 5d,
can be used instead with the benefit of often enabling static binding.
Most of the guidelines for writing efficient Prolog code also apply to
Logtalk code.  In particular, define your predicates to take advantage
of first-argument indexing.  In the case of recursive predicates, define
them as tail-recursive predicates whenever possible.

See the *note section on performance: 38. for a detailed discussion on
Logtalk performance.


File: TheLogtalkHandbook-3.96.0.info,  Node: Portable applications,  Next: Conditional compilation,  Prev: Optimizing performance,  Up: Writing and running applications

1.14.15 Portable applications
-----------------------------

Logtalk is compatible with most modern standards-compliant Prolog
compilers.  However, this does not necessarily imply that your Logtalk
applications will have the same level of portability.  If possible, you
should only use in your applications Logtalk built-in predicates and ISO
Prolog-specified built-in predicates and arithmetic functions.  If you
need to use built-in predicates (or built-in arithmetic functions) that
may not be available in other Prolog compilers, you should try to
encapsulate the non-portable code in a small number of objects and
provide a portable 'interface' for that code through the use of Logtalk
protocols.  An example will be code that access operating-system
specific features.  The Logtalk compiler can warn you of the use of
non-ISO-specified built-in predicates and arithmetic functions by using
the *note portability: 1d1. compiler flag.


File: TheLogtalkHandbook-3.96.0.info,  Node: Conditional compilation,  Next: Avoiding common errors,  Prev: Portable applications,  Up: Writing and running applications

1.14.16 Conditional compilation
-------------------------------

Logtalk supports conditional compilation within source files using the
*note if/1: 2f2, *note elif/1: 2f3, *note else/0: 2f4, and *note
endif/0: 2f5. directives.  This support is similar to the support found
in several Prolog systems such as ECLiPSe, GNU Prolog, SICStus Prolog,
SWI-Prolog, XSB, and YAP.


File: TheLogtalkHandbook-3.96.0.info,  Node: Avoiding common errors,  Next: Coding style guidelines,  Prev: Conditional compilation,  Up: Writing and running applications

1.14.17 Avoiding common errors
------------------------------

Try to write objects and protocol documentation 'before' writing any
other code; if you are having trouble documenting a predicate, perhaps
you need to go back to the design stage.

Try to avoid lengthy hierarchies.  Composition is often a better choice
over inheritance for defining new objects (Logtalk supports
component-based programming through the use of *note categories: 109.).
In addition, prototype-based hierarchies are semantically simpler than
class-based hierarchies.

Dynamic predicates or dynamic entities are sometimes needed, but we
should always try to minimize the use of non-logical features such as
asserts and retracts.

Since each Logtalk entity is independently compiled, if an object
inherits a dynamic or a meta-predicate predicate, then the respective
directives must be repeated to ensure a correct compilation.

In general, Logtalk does not verify if a user predicate call/return
arguments comply with the declared modes.  On the other hand, Logtalk
built-in predicates, built-in methods, and message-sending control
structures are fully checked for calling mode errors.

Logtalk error handling strongly depends on the ISO compliance of the
chosen Prolog compiler.  For instance, the error terms that are
generated by some Logtalk built-in predicates assume that the Prolog
built-in predicates behave as defined in the ISO standard regarding
error conditions.  In particular, if your Prolog compiler does not
support a ‘read_term/3’ built-in predicate compliant with the ISO Prolog
Standard definition, then the current version of the Logtalk compiler
may not be able to detect misspelled variables in your source code.


File: TheLogtalkHandbook-3.96.0.info,  Node: Coding style guidelines,  Prev: Avoiding common errors,  Up: Writing and running applications

1.14.18 Coding style guidelines
-------------------------------

It is suggested that all code between an entity opening and closing
directives be indented by one tab stop.  When defining entity code, both
directives and predicates, Prolog coding style guidelines may be
applied.  All Logtalk source files, examples, and standard library
entities use tabs (the recommended setting is a tab width equivalent to
4 spaces) for laying out code.  Closely related entities can be defined
in the same source file.  However, for the best performance, is often
necessary to have an entity per source file.  Entities that might be
useful in different contexts (such as library entities) are best defined
in their own source files.

A detailed coding style guide is available at the Logtalk official
website.


File: TheLogtalkHandbook-3.96.0.info,  Node: Printing messages and asking questions,  Next: Term and goal expansion,  Prev: Writing and running applications,  Up: User Manual

1.15 Printing messages and asking questions
===========================================

Applications, components, and libraries often print all sorts of
messages.  These include banners, logging, debugging, and computation
results messages.  But also, in some cases, user interaction messages.
However, the authors of applications, components, and libraries often
cannot anticipate the context where their software will be used and thus
decide which and when messages should be displayed, suppressed, or
diverted.  Consider the different components in a Logtalk application
development and deployment.  At the base level, you have the Logtalk
compiler and runtime.  The compiler writes messages related to e.g.
compiling and loading files, compiling entities, and compilation
warnings and errors.  The runtime may write banner messages or throw
execution errors that may result in printing human-level messages.  The
development environment can be console-based, or you may be using a GUI
tool such as PDT. In the latter case, PDT needs to intercept the Logtalk
compiler and runtime messages to present the relevant information using
its GUI. Then you have all the other components in a typical
application.  For example, your own libraries and third-party libraries.
The libraries may want to print messages on their own, e.g.  banners,
debugging information, or logging information.  As you assemble all your
application components, you want to have the final word on which
messages are printed, where, and when.  Uncontrolled message printing by
libraries could potentially disrupt application flow, expose
implementation details, spam the user with irrelevant details, or break
user interfaces.

The solution is to decouple the calls to print a message from the actual
printing of the output text.  The same is true for calls to read user
input.  By decoupling the call to input some data from the actual read
of the data, we can easily switch from, for example, a command-line
interface to a GUI input dialog or even automate providing the data
(e.g., when automating testing of the user interaction).

Logtalk provides a solution based on the 'structured message printing
mechanism' that was introduced by Quintus Prolog, where it was
apparently implemented by Dave Bowen (thanks to Richard O’Keefe for the
historical bits).  This mechanism gives the programmer full control of
message printing, allowing it to filter, rewrite, or redirect any
message.  Variations of this mechanism can also be found in some Prolog
systems, including SICStus Prolog, SWI-Prolog, and YAP. Based on this
mechanism, Logtalk introduces an extension that also allows abstracting
asking a user for input.  Both mechanisms are implemented by the
logtalk(1) built-in object and described in this section.  The message
printing mechanism is extensively used by the Logtalk compiler itself
and by the developer tools.  The question-asking mechanism is used e.g.
in the *note debugger: 2fc. tool.

* Menu:

* Printing messages::
* Message tokenization::
* Meta-messages::
* Defining message prefixes and output streams::
* Defining message prefixes and output files::
* Intercepting messages::
* Asking questions::
* Intercepting questions::
* Multi-threading applications: Multi-threading applications<4>.

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Printing messages,  Next: Message tokenization,  Up: Printing messages and asking questions

1.15.1 Printing messages
------------------------

The main predicate for printing a message is *note
logtalk;;print_message/3: 2fe.  A simple example, using the Logtalk
runtime, is:

     | ?- logtalk::print_message(banner, core, banner).

     Logtalk 3.23.0
     Copyright (c) 1998-2018 Paulo Moura
     yes

The first argument of the predicate is the kind of message that we want
to print.  In this case, we use ‘banner’ to indicate that we are
printing a product name and copyright banner.  An extensive list of
message kinds is supported by default:

‘banner’

     banner messages (used e.g.  when loading tools or main application
     components; can be suppressed by setting the *note report: 2e0.
     flag to ‘warnings’ or ‘off’)

‘help’

     messages printed in reply to the user asking for help (mostly for
     helping port existing Prolog code)

‘information’ and ‘information(Group)’

     messages usually printed in reply to a user’s request for
     information

‘silent’ and ‘silent(Group)’

     not printed by default (but can be intercepted using the
     ‘message_hook/4’ predicate)

‘comment’ and ‘comment(Group)’

     useful but usually not essential messages (can be suppressed by
     setting the *note report: 2e0. flag to ‘warnings’ or ‘off’)

‘warning’ and ‘warning(Group)’

     warning messages (generated e.g.  by the compiler; can be
     suppressed by turning off the *note report: 2e0. flag)

‘error’ and ‘error(Group)’

     error messages (generated e.g.  by the compiler)

‘debug, debug(Group)’

     debugging messages (by default, only printed when the *note debug:
     2e2. flag is turned on; the ‘print_message/3’ goals for these
     messages are suppressed by the compiler when the *note optimize:
     8c. flag is turned on)

‘question, question(Group)’

     questions to a user

Using a compound term allows easy partitioning of messages of the same
kind in different groups.  Note that you can define your own alternative
message kind identifiers for your own components, together with suitable
definitions for their associated prefixes and output streams.

The second argument of ‘print_message/3’ represents the 'component'
defining the message being printed.  In this context, 'component' is a
generic term that can designate, e.g., a tool, a library, or some
sub-system in a large application.  In our example, the component name
is ‘core’, identifying the Logtalk compiler/runtime.  This argument was
introduced to provide multiple namespaces for message terms and thus
simplify programming-in-the-large by allowing easy filtering of all
messages from a specific component and also avoiding conflicts when two
components happen to define the same message term (e.g., ‘banner’).
Users should choose and use a unique name for a component, which usually
is the name of the component itself.  For example, all messages from the
*note lgtunit: 146. tool use ‘lgtunit’ for the component argument.  The
compiler and runtime are interpreted as a single component designated as
‘core’.

The third argument of ‘print_message/3’ is the message itself,
represented by a term.  In the above example, the message term is
‘banner’.  Using a term to represent a message instead of a string with
the message text itself has significant advantages.  Notably, it allows
using a compound term for easy parameterization of the message text and
simplifies machine processing, localization of applications, and message
interception.  For example:

     | ?- logtalk::print_message(comment, core, redefining_entity(object, foo)).

     % Redefining object foo
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Message tokenization,  Next: Meta-messages,  Prev: Printing messages,  Up: Printing messages and asking questions

1.15.2 Message tokenization
---------------------------

The use of message terms requires a solution for generating the actual
text of the messages.  This is supported by defining grammar rules for
the *note logtalk;;message_tokens//2: 300. multifile non-terminal, which
translates a message term, for a given component, to a list of tokens.
For example:

     :- multifile(logtalk::message_tokens//2).
     :- dynamic(logtalk::message_tokens//2).

     logtalk::message_tokens(redefining_entity(Type, Entity), core) -->
         ['Redefining ~w ~q'-[Type, Entity], nl].

The following tokens can be used when translating a message:

‘at_same_line’

     Signals a following part to a multi-part message with no line break
     in between; this token is ignored when it’s not the first in the
     list of tokens

‘tab(Expression)’

     Evaluate the argument as an arithmetic expression and write the
     resulting number of spaces; this token is ignored when the number
     of spaces is not positive

‘nl’

     Change line in the output stream

‘flush’

     Flush the output stream (by calling the ‘flush_output/1’ standard
     predicate)

‘Format-Arguments’

     ‘Format’ must be an atom and ‘Arguments’ must be a list of format
     arguments (the token arguments are passed to a call to the
     ‘format/3’ de facto standard predicate)

‘term(Term, Options)’

     ‘Term’ can be any term and ‘Options’ must be a list of valid
     ‘write_term/3’ output options (the token arguments are passed to a
     call to the ‘write_term/3’ standard predicate)

‘ansi(Attributes, Format, Arguments)’

     Taken from SWI-Prolog; by default, do nothing; can be used for
     styled output

‘begin(Kind, Var)’

     Taken from SWI-Prolog; by default, do nothing; can be used together
     with ‘end(Var)’ to wrap a sequence of message tokens

‘end(Var)’

     Taken from SWI-Prolog; by default, do nothing

The ‘logtalk’ object also defines public predicates for printing a list
of tokens, for hooking into printing an individual token, and for
setting default output streams and message prefixes.  For example, the
SWI-Prolog adapter file uses the print message token hook predicate to
enable coloring of messages printed on a console.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-messages,  Next: Defining message prefixes and output streams,  Prev: Message tokenization,  Up: Printing messages and asking questions

1.15.3 Meta-messages
--------------------

Defining tokenization rules for every message is not always necessary,
however.  Logtalk defines several 'meta-messages' that are handy for
simple cases and temporary messages only used during application
development, notably debugging messages.  See the *note Debugging
messages: 302. section and the logtalk built-in object(1) remarks
section for details.

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining message prefixes and output streams,  Next: Defining message prefixes and output files,  Prev: Meta-messages,  Up: Printing messages and asking questions

1.15.4 Defining message prefixes and output streams
---------------------------------------------------

The *note logtalk;;message_prefix_stream/4: 304. hook predicate can be
used to define a message line prefix and an output stream for printing
messages of a given kind and component.  For example:

     :- multifile(logtalk::message_prefix_stream/4).
     :- dynamic(logtalk::message_prefix_stream/4).

     logtalk::message_prefix_stream(comment, my_app, '% ', user_output).
     logtalk::message_prefix_stream(warning, my_app, '* ', user_error).

A single clause at most is expected per message kind and component pair.
When this predicate is not defined for a given kind and component pair,
the following defaults are used:

     kind_prefix_stream(banner,         '',       user_output).
     kind_prefix_stream(help,           '',       user_output).
     kind_prefix_stream(question,       '',       user_output).
     kind_prefix_stream(question(_),    '',       user_output).
     kind_prefix_stream(information,    '% ',     user_output).
     kind_prefix_stream(information(_), '% ',     user_output).
     kind_prefix_stream(comment,        '% ',     user_output).
     kind_prefix_stream(comment(_),     '% ',     user_output).
     kind_prefix_stream(warning,        '*     ', user_error).
     kind_prefix_stream(warning(_),     '*     ', user_error).
     kind_prefix_stream(error,          '!     ', user_error).
     kind_prefix_stream(error(_),       '!     ', user_error).
     kind_prefix_stream(debug,          '>>> ',   user_error).
     kind_prefix_stream(debug(_),       '>>> ',   user_error).

When the message kind is unknown, ‘information’ is used instead.


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining message prefixes and output files,  Next: Intercepting messages,  Prev: Defining message prefixes and output streams,  Up: Printing messages and asking questions

1.15.5 Defining message prefixes and output files
-------------------------------------------------

Some applications require copying and saving messages without diverting
them from their default stream.  For simple cases, this can be
accomplished by intercepting the messages using the *note
logtalk;;message_hook/4: 306. multifile hook predicate (see next
section).  In more complex cases, where messages are already intercepted
for a different purpose, it can be tricky to use multiple definitions of
the ‘message_hook/4’ predicate as the order of the clauses of a multiple
predicate cannot be assumed in general (for all ‘message_hook/4’
predicate definitions to run, all but the last one to be called must
fail).  Using a single 'master' definition is also not ideal as it would
result in strong coupling instead of a clean separation of concerns.

The experimental *note logtalk;;message_prefix_file/6: 307. hook
predicate can be used to define a message line prefix and an output file
for copying messages of a given kind and component pair.  For example:

     :- multifile(logtalk::message_prefix_file/6).
     :- dynamic(logtalk::message_prefix_file/6).

     logtalk::message_prefix_file(error,   app, '! ', 'log.txt', append, []).
     logtalk::message_prefix_file(warning, app, '! ', 'log.txt', append, []).

A single clause at most is expected per message kind and component pair.

This predicate is called by default by the message printing mechanism.
Definitions of the ‘message_hook/4’ hook predicate are free to decide if
the ‘logtalk::message_prefix_file/6’ predicate should be called and
acted upon.


File: TheLogtalkHandbook-3.96.0.info,  Node: Intercepting messages,  Next: Asking questions,  Prev: Defining message prefixes and output files,  Up: Printing messages and asking questions

1.15.6 Intercepting messages
----------------------------

Calls to the *note logtalk;;print_message/3: 2fe. predicate can be
intercepted by defining clauses for the *note logtalk;;message_hook/4:
306. multifile hook predicate.  This predicate can suppress, rewrite,
and divert messages.

As a first example, assume that you want to make Logtalk startup less
verbose by suppressing printing of the default compiler flag values.
This can be easily accomplished by defining the following category in a
settings file:

     :- category(my_terse_logtalk_startup_settings).

         :- multifile(logtalk::message_hook/4).
         :- dynamic(logtalk::message_hook/4).

         logtalk::message_hook(default_flags, comment(settings), core, _).

     :- end_category.

The printing message mechanism automatically calls the ‘message_hook/4’
hook predicate.  When this call succeeds, the mechanism assumes that the
message has been successfully handled.

As another example, assume that you want to print all otherwise silent
compiler messages:

     :- category(my_verbose_logtalk_message_settings).

         :- multifile(logtalk::message_hook/4).
         :- dynamic(logtalk::message_hook/4).

         logtalk::message_hook(_Message, silent, core, Tokens) :-
             logtalk::message_prefix_stream(comment, core, Prefix, Stream),
             logtalk::print_message_tokens(Stream, Prefix, Tokens).

         logtalk::message_hook(_Message, silent(Key), core, Tokens) :-
             logtalk::message_prefix_stream(comment(Key), core, Prefix, Stream),
             logtalk::print_message_tokens(Stream, Prefix, Tokens).

     :- end_category.


File: TheLogtalkHandbook-3.96.0.info,  Node: Asking questions,  Next: Intercepting questions,  Prev: Intercepting messages,  Up: Printing messages and asking questions

1.15.7 Asking questions
-----------------------

Logtalk 'structured question-asking' mechanism complements the message
printing mechanism.  It provides an abstraction for the common task of
asking a user a question and reading back its reply.  By default, this
mechanism writes the question, writes a prompt, and reads the answer
using the current user input and output streams but allows all steps to
be intercepted, filtered, rewritten, and redirected.  Two typical
examples are using a GUI dialog for asking questions and automatically
providing answers to specific questions.

The question-asking mechanism works in tandem with the message printing
mechanism, using it to print the question text and a prompt.  It
provides an asking predicate and a hook predicate, both declared and
defined in the ‘logtalk’ built-in object.  The asking predicate, *note
logtalk;;ask_question/5: 30b, is used for asking a question and reading
the answer.  Assume that we defined the following message tokenization
and question prompt and stream:

     :- category(hitchhikers_guide_to_the_galaxy).

         :- multifile(logtalk::message_tokens//2).
         :- dynamic(logtalk::message_tokens//2).

         % abstract the question text using the atom ultimate_question;
         % the second argument, hitchhikers, is the application component
         logtalk::message_tokens(ultimate_question, hitchhikers) -->
             ['The answer to the ultimate question of life, the universe and everything is?'-[], nl].

        :- multifile(logtalk::question_prompt_stream/4).
        :- dynamic(logtalk::question_prompt_stream/4).

        % the prompt is specified here instead of being part of the question text
        % as it will be repeated if the answer doesn't satisfy the question closure
        logtalk::question_prompt_stream(question, hitchhikers, '> ', user_input).

     :- end_category.

After compiling and loading this category, we can now ask the ultimate
question:

     | ?- logtalk::ask_question(question, hitchhikers, ultimate_question, '=='(42), N).

     The answer to the ultimate question of life, the universe and everything is?
     > 42.

     N = 42
     yes

Note that the fourth argument, ‘'=='(42)’ in our example, is a *note
closure: 14f. that is used to check the answers provided by the user.
The question is repeated until the goal constructed by extending the
closure with the user answer succeeds.  For example:

     | ?- logtalk::ask_question(question, hitchhikers, ultimate_question, '=='(42), N).
     The answer to the ultimate question of life, the universe and everything is?
     > icecream.
     > tea.
     > 42.

     N = 42
     yes

Practical usage examples of this mechanism can be found, e.g., in the
‘debugger’ tool where it’s used to abstract the user interaction when
tracing a goal execution in debug mode.


File: TheLogtalkHandbook-3.96.0.info,  Node: Intercepting questions,  Next: Multi-threading applications<4>,  Prev: Asking questions,  Up: Printing messages and asking questions

1.15.8 Intercepting questions
-----------------------------

Calls to the *note logtalk;;ask_question/5: 30b. predicate can be
intercepted by defining clauses for the *note logtalk;;question_hook/6:
30d. multifile hook predicate.  This predicate can suppress, rewrite,
and divert questions.  For example, assume that we want to automate
testing and thus cannot rely on someone manually providing answers:

     :- category(hitchhikers_fixed_answers).

         :- multifile(logtalk::question_hook/6).
         :- dynamic(logtalk::question_hook/6).

         logtalk::question_hook(ultimate_question, question, hitchhikers, _, _, 42).

     :- end_category.

After compiling and loading this category, trying the question again
will now skip asking the user:

     | ?- logtalk::ask_question(question, hitchhikers, ultimate_question, '=='(42), N).

     N = 42
     yes

In a practical case, the fixed answer would be used for follow-up goals
being tested.  The question-answer read loop (which calls the question
check closure) is not used when a fixed answer is provided using the
‘logtalk::question_hook/6’ predicate thus preventing the creation of
endless loops.  For example, the following query succeeds:

     | ?- logtalk::ask_question(question, hitchhikers, ultimate_question, '=='(41), N).

     N = 42
     yes

Note that the ‘logtalk::question_hook/6’ predicate takes as argument the
closure specified in the ‘logtalk::ask_question/5’ call, allowing a
fixed answer to be checked before being returned.


File: TheLogtalkHandbook-3.96.0.info,  Node: Multi-threading applications<4>,  Prev: Intercepting questions,  Up: Printing messages and asking questions

1.15.9 Multi-threading applications
-----------------------------------

When writing multi-threading applications, user-defined predicates
calling methods such as ‘print_message/3’ or ‘ask_question/5’ may need
to be declared synchronized in order to avoid race conditions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Term and goal expansion,  Next: Documenting,  Prev: Printing messages and asking questions,  Up: User Manual

1.16 Term and goal expansion
============================

Logtalk supports a 'term and goal expansion mechanism' that can be used
to define source-to-source transformations.  Two common uses are the
definition of language extensions and domain-specific languages.

Logtalk improves upon the term-expansion mechanism found on some Prolog
systems by providing the user with fine-grained control on 'if', 'when',
and 'how' expansions are applied.  It allows declaring in a source file
itself which expansions, if any, will be used when compiling it.  It
allows declaring which expansions will be used when compiling a file
using compile and loading predicate options.  It also allows defining a
default expansion for all source files.  It defines a concept of 'hook
objects' that can be used as building blocks to create custom and
reusable 'expansion workflows' with explicit and well-defined semantics.
It prevents the simple act of loading expansion rules affecting
subsequent compilation of files.  It prevents conflicts between groups
of expansion rules of different origins.  It avoids a set of buggy
expansion rules from breaking other sets of expansion rules.

* Menu:

* Defining expansions::
* Expanding grammar rules::
* Bypassing expansions::
* Hook objects::
* Virtual source file terms and loading context::
* Default compiler expansion workflow::
* User defined expansion workflows::
* Using Prolog defined expansions::
* Debugging expansions::


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining expansions,  Next: Expanding grammar rules,  Up: Term and goal expansion

1.16.1 Defining expansions
--------------------------

Term and goal expansions are defined using, respectively, the predicates
*note term_expansion/2: fc. and *note goal_expansion/2: fd, which are
declared in the expanding(1) built-in protocol.  Note that, unlike
Prolog systems also providing these two predicates, they are 'not'
declared as *note multifile predicates: 16b. in the protocol.  This
design decision is key for giving the programmer full control of the
expansion process and preventing the problems inflicting most of the
Prolog systems that provide a term-expansion mechanism.

An example of an object defining expansion rules:

     :- object(an_object,
         implements(expanding)).

         term_expansion(ping, pong).
         term_expansion(
             colors,
             [white, yellow, blue, green, read, black]
         ).

         goal_expansion(a, b).
         goal_expansion(b, c).
         goal_expansion(X is Expression, true) :-
             catch(X is Expression, _, fail).

     :- end_object.

These predicates can be explicitly called using the *note expand_term/2:
1b7. and *note expand_goal/2: 312. built-in methods or called
automatically by the compiler when compiling a source file (see the
section below on 'hook objects').

In the case of source files referenced in *note include/1: b8.
directives, expansions are only applied automatically when the
directives are found in source files, not when used as arguments in the
*note create_object/4: 62, *note create_protocol/3: e3, and *note
create_category/4: 11a, predicates.  This restriction prevents
inconsistent results when, for example, an expansion is defined for a
predicate with clauses found in both an included file and as argument in
a call to the ‘create_object/4’ predicate.

Clauses for the ‘term_expansion/2’ predicate are called until one of
them succeeds.  The returned expansion can be a single term or a list of
terms (including the empty list).  For example:

     | ?- an_object::expand_term(ping, Term).

     Term = pong
     yes

     | ?- an_object::expand_term(colors, Colors).

     Colors = [white, yellow, blue, green, read, black]
     yes

When no ‘term_expansion/2’ clause applies, the same term that we are
trying to expand is returned:

     | ?- an_object::expand_term(sounds, Sounds).

     Sounds = sounds
     yes

Clauses for the ‘goal_expansion/2’ predicate are recursively called on
the expanded goal until a fixed point is reached.  For example:

     | ?- an_object::expand_goal(a, Goal).

     Goal = c
     yes

     | ?- an_object::expand_goal(X is 3+2*5, Goal).

     X = 13,
     Goal = true
     yes

When no ‘goal_expansion/2’ clause applies, the same goal that we are
trying to expand is returned:

     | ?- an_object::expand_goal(3 =:= 5, Goal).

     Goal = (3=:=5)
     yes

The goal-expansion mechanism prevents an infinite loop when expanding a
goal by checking that a goal to be expanded was not the result from a
previous expansion of the same goal.  For example, consider the
following object:

     :- object(fixed_point,
         implements(expanding)).

         goal_expansion(a, b).
         goal_expansion(b, c).
         goal_expansion(c, (a -> b; c)).

     :- end_object.

The expansion of the goal ‘a’ results in the goal ‘(a -> b; c)’ with no
attempt to further expand the ‘a’, ‘b’, and ‘c’ goals as they have
already been expanded.

Goal-expansion applies to goal arguments of control constructs,
meta-arguments in built-in or ‘user’ defined meta-predicates,
meta-arguments in local user-defined meta-predicates, meta-arguments in
meta-predicate messages when static binding is possible, and
‘initialization/1’, ‘if/1’, and ‘elif/1’ directives.

   ---------- Footnotes ----------

   (1) ../../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Expanding grammar rules,  Next: Bypassing expansions,  Prev: Defining expansions,  Up: Term and goal expansion

1.16.2 Expanding grammar rules
------------------------------

A common term expansion is the translation of grammar rules into
predicate clauses.  This transformation is performed automatically by
the compiler when a source file entity defines grammar rules.  It can
also be done explicitly by calling the ‘expand_term/2’ built-in method.
For example:

     | ?- logtalk::expand_term((a --> b, c), Clause).

     Clause = (a(A,B) :- b(A,C), c(C,B))
     yes

Note that the default translation of grammar rules can be overridden by
defining clauses for the *note term_expansion/2: fc. predicate.


File: TheLogtalkHandbook-3.96.0.info,  Node: Bypassing expansions,  Next: Hook objects,  Prev: Expanding grammar rules,  Up: Term and goal expansion

1.16.3 Bypassing expansions
---------------------------

Terms and goals wrapped by the *note {}/1: 191. control construct are
not expanded.  For example:

     | ?- an_object::expand_term({ping}, Term).

     Term = {ping}
     yes

     | ?- an_object::expand_goal({a}, Goal).

     Goal = {a}
     yes

This also applies to source file terms and source file goals when using
hook objects (discussed next).


File: TheLogtalkHandbook-3.96.0.info,  Node: Hook objects,  Next: Virtual source file terms and loading context,  Prev: Bypassing expansions,  Up: Term and goal expansion

1.16.4 Hook objects
-------------------

Term and goal expansion of a source file during its compilation is
performed by using 'hook objects'.  A hook object is simply an object
implementing the expanding(1) built-in protocol and defining clauses for
the term and goal expansion hook predicates.  Hook objects must be
compiled and loaded prior to being used to expand a source file.

To compile a source file using a hook object, we can use the *note hook:
fe. compiler flag in the second argument of the *note logtalk_compile/2:
2b2. and *note logtalk_load/2: 4e. built-in predicates.  For example:

     | ?- logtalk_load(source_file, [hook(hook_object)]).
     ...

In alternative, we can use a *note set_logtalk_flag/2: 50. directive in
the source file itself.  For example:

     :- set_logtalk_flag(hook, hook_object).

To use multiple hook objects in the same source file, simply write each
directive before the block of code that it should handle.  For example:

     :- object(h1,
         implements(expanding)).

         term_expansion((:- public(a/0)), (:- public(b/0))).
         term_expansion(a, b).

     :- end_object.

     :- object(h2,
         implements(expanding)).

         term_expansion((:- public(a/0)), (:- public(c/0))).
         term_expansion(a, c).

     :- end_object.

     :- set_logtalk_flag(hook, h1).

     :- object(s1).

         :- public(a/0).
         a.

     :- end_object.


     :- set_logtalk_flag(hook, h2).

     :- object(s2).

         :- public(a/0).
         a.

     :- end_object.

     | ?- {h1, h2, s}.
     ...

     | ?- s1::b.
     yes

     | ?- s2::c.
     yes

It is also possible to define a default hook object by defining a global
value for the ‘hook’ flag by calling the *note set_logtalk_flag/2: 51.
predicate.  For example:

     | ?- set_logtalk_flag(hook, hook_object).

     yes

Note that, due to the ‘set_logtalk_flag/2’ directive being local to a
source file, using it to specify a hook object will override any defined
default hook object or any hook object specified as a
‘logtalk_compile/2’ or ‘logtalk_load/2’ predicate compiler option for
compiling or loading the source file.

     Note: Clauses for the ‘term_expansion/2’ and ‘goal_expansion/2’
     predicates defined within an object or a category are never used in
     the compilation of the object or the category itself.

   ---------- Footnotes ----------

   (1) ../../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Virtual source file terms and loading context,  Next: Default compiler expansion workflow,  Prev: Hook objects,  Up: Term and goal expansion

1.16.5 Virtual source file terms and loading context
----------------------------------------------------

When using a hook object to expand the terms of a source file, two
virtual file terms are generated: ‘begin_of_file’ and ‘end_of_file’.
These terms allow the user to define term-expansions before and after
the actual source file terms.

Logtalk also provides a *note logtalk_load_context/2: 317. built-in
predicate that can be used to access the compilation/loading context
when performing expansions.  The *note logtalk: d1. built-in object also
provides a set of predicates that can be useful, notably when adding
Logtalk support for language extensions originally developed for Prolog.

As an example of using the virtual terms and the
‘logtalk_load_context/2’ predicate, assume that you want to convert
plain Prolog files to Logtalk by wrapping the Prolog code in each file
using an object (named after the file) that implements a given protocol.
This could be accomplished by defining the following hook object:

     :- object(wrapper(_Protocol_),
         implements(expanding)).

         term_expansion(begin_of_file, (:- object(Name,implements(_Protocol_)))) :-
             logtalk_load_context(file, File),
             os::decompose_file_name(File,_ , Name, _).

         term_expansion(end_of_file, (:- end_object)).

     :- end_object.

Assuming, e.g., ‘my_car.pl’ and ‘lease_car.pl’ files to be wrapped and a
‘car_protocol’ protocol, we could then load them using:

     | ?- logtalk_load(
              ['my_car.pl', 'lease_car.pl'],
              [hook(wrapper(car_protocol))]
          ).

     yes

     Note: When a source file also contains plain Prolog directives and
     predicates, these are term-expanded but not goal-expanded (with the
     exception of the ‘initialization/1’, ‘if/1’, and ‘elif/1’
     directives, where the goal argument is expanded to improve code
     portability across backends).


File: TheLogtalkHandbook-3.96.0.info,  Node: Default compiler expansion workflow,  Next: User defined expansion workflows,  Prev: Virtual source file terms and loading context,  Up: Term and goal expansion

1.16.6 Default compiler expansion workflow
------------------------------------------

When *note compiling a source file: 29b, the compiler will first try, by
default, the source file-specific hook object specified using a local
‘set_logtalk_flag/2’ directive, if defined.  If that expansion fails, it
tries the hook object specified using the ‘hook/1’ compiler option in
the ‘logtalk_compile/2’ or ‘logtalk_load/2’ goal that compiles or loads
the file, if defined.  If that expansion fails, it tries the default
hook object, if defined.  If that expansion also fails, the compiler
tries the Prolog dialect-specific expansion rules found in the *note
adapter file: 154. (which are used to support non-standard Prolog
features).


File: TheLogtalkHandbook-3.96.0.info,  Node: User defined expansion workflows,  Next: Using Prolog defined expansions,  Prev: Default compiler expansion workflow,  Up: Term and goal expansion

1.16.7 User defined expansion workflows
---------------------------------------

Sometimes we have multiple hook objects that we need to combine and use
in the compilation of a source file.  Logtalk includes a *note
hook_flows: 31a. library that supports two basic expansion workflows: a
pipeline(1) of hook objects, where the expansion results from a hook
object are fed to the next hook object in the pipeline, and a set(2) of
hook objects, where expansions are tried until one of them succeeds.
These workflows are implemented as parametric objects, allowing
combining them to implement more sophisticated expansion workflows.
There is also a *note hook_objects: 31b. library that provides
convenient hook objects for defining custom expansion workflows.  This
library includes a hook object that can be used to restore the default
expansion workflow used by the compiler.

For example, assuming that you want to apply the Prolog backend-specific
expansion rules defined in its adapter file, using the
backend_adapter_hook(3) library object, passing the resulting terms to
your own expansion when compiling a source file, we could use the goal:

     | ?- logtalk_load(
              source,
              [hook(hook_pipeline([backend_adapter_hook, my_expansion]))]
          ).

As a second example, we can prevent expansion of a source file using the
library object identity_hook(4) by adding as the first term in a source
file the directive:

     :- set_logtalk_flag(hook, identity_hook).

The file will be compiled as-is as any hook object (specified as a
compiler option or as a default hook object) and any backend adapter
expansion rules are overridden by the directive.

   ---------- Footnotes ----------

   (1) ../../apis/hook_pipeline_1.html#hook-pipeline-1

   (2) ../../apis/hook_set_1.html#hook-set-1

   (3) ../../apis/backend_adapter_hook_0.html#backend-adapter-hook-0

   (4) ../../apis/identity_hook_0.html#identity-hook-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Using Prolog defined expansions,  Next: Debugging expansions,  Prev: User defined expansion workflows,  Up: Term and goal expansion

1.16.8 Using Prolog defined expansions
--------------------------------------

In order to use clauses for the ‘term_expansion/2’ and
‘goal_expansion/2’ predicates defined in plain Prolog, simply specify
the pseudo-object ‘user’ as the hook object when compiling source files.
When using *note backend Prolog compilers: 34. that support a module
system, it can also be specified a module containing clauses for the
expanding predicates as long as the module name doesn’t coincide with an
object name.  When defining a custom workflow, the library object
prolog_module_hook/1(1) can be used as a workflow step.  For example,
assuming a module ‘functions’ defining expansion rules that we want to
use:

     | ?- logtalk_load(
              source,
              [hook(hook_set([prolog_module_hook(functions), my_expansion]))]
          ).

But note that Prolog module libraries may provide definitions of the
expansion predicates that are not compatible with the Logtalk compiler.
In particular, when setting the hook object to ‘user’, be aware of any
Prolog library that is loaded, possibly by default or implicitly by the
Prolog system, that may be contributing definitions of the expansion
predicates.  It is usually safer to define a specific hook object for
combining multiple expansions in a fully controlled way.

     Note: The ‘user’ object declares ‘term_expansion/2’ and
     ‘goal_expansion/2’ as multifile and dynamic predicates.  This helps
     in avoiding predicate existence errors when compiling source files
     with the ‘hook’ flag set to ‘user’ as these predicates are only
     natively declared by some of the supported backend Prolog
     compilers.

   ---------- Footnotes ----------

   (1) ../../apis/prolog_module_hook_1.html#prolog-module-hook-1


File: TheLogtalkHandbook-3.96.0.info,  Node: Debugging expansions,  Prev: Using Prolog defined expansions,  Up: Term and goal expansion

1.16.9 Debugging expansions
---------------------------

The ‘term_expansion/2’ and ‘goal_expansion/2’ predicates can be *note
debugged: 47. like any other object predicates.  Note that expansions
can often be manually tested by sending *note expand_term/2: 1b7. and
*note expand_goal/2: 312. messages to a hook object with the term or
goal whose expansion you want to check as argument.  An alternative to
the debugging tools is to use a *note monitor: 31e. for the runtime
messages that call the predicates.  For example, assume a
‘expansions_debug.lgt’ file with the contents:

     :- initialization(
         define_events(after, edcg, _, _, expansions_debug)
     ).


     :- object(expansions_debug,
         implements(monitoring)).

         after(edcg, term_expansion(T,E), _) :-
             writeq(term_expansion(T,E)), nl.

     :- end_object.

We can use this monitor to help debug the expansion rules of the *note
edcg: 31f. library when applied to the ‘edcgs’ example using the
queries:

     | ?- {expansions_debug}.
     ...

     | ?- set_logtalk_flag(events, allow).
     yes

     | ?- {edcgs(loader)}.
     ...
     term_expansion(begin_of_file,begin_of_file)
     term_expansion((:-object(gemini)),[(:-object(gemini)),(:-op(1200,xfx,-->>))])
     term_expansion(acc_info(castor,A,B,C,true),[])
     term_expansion(pass_info(pollux),[])
     term_expansion(pred_info(p,1,[castor,pollux]),[])
     term_expansion(pred_info(q,1,[castor,pollux]),[])
     term_expansion(pred_info(r,1,[castor,pollux]),[])
     term_expansion((p(A)-->>B is A+1,q(B),r(B)),(p(A,C,D,E):-B is A+1,q(B,C,F,E),r(B,F,D,E)))
     term_expansion((q(A)-->>[]),(q(A,B,B,C):-true))
     term_expansion((r(A)-->>[]),(r(A,B,B,C):-true))
     term_expansion(end_of_file,end_of_file)
     ...

This solution does not require compiling the ‘edcg’ hook object in debug
mode or access to its source code (e.g., to modify its expansion rules
to emit debug messages).  We could also simply use the ‘user’
pseudo-object as the monitor object:

     | ?- assertz((
              after(_, term_expansion(T,E), _) :-
                 writeq(term_expansion(T,E)), nl
          )).
     yes

     | ?- define_events(after, edcg, _, Sender, user).
     yes

Another alternative is to use a pipeline of hook objects with the
library ‘hook_pipeline/1’ and ‘write_to_stream_hook’ objects to write
the expansion results to a file.  For example, using the ‘unique.lgt’
test file from the ‘edcgs’ library directory:

     | ?- {hook_flows(loader), hook_objects(loader)}.
     ...

     | ?- open('unique_expanded.lgt', write, Stream),
          logtalk_compile(
              unique,
              [hook(hook_pipeline([edcg,write_to_stream_hook(Stream,[quoted(true)])]))]
          ),
          close(Stream).
     ...

The generated ‘unique_expanded.lgt’ file will contain the clauses
resulting from the expansion of the EDCG rules found in the ‘unique.lgt’
file by the ‘edcg’ hook object expansion.


File: TheLogtalkHandbook-3.96.0.info,  Node: Documenting,  Next: Debugging,  Prev: Term and goal expansion,  Up: User Manual

1.17 Documenting
================

Assuming that the *note source_data: cc. flag is turned on, the compiler
saves all relevant documenting information collected when compiling a
source file.  The provided *note lgtdoc: 322. tool can access this
information by using the *note reflection: 48. support and generate a
documentation file for each compiled entity (object, protocol, or
category) in XML format.  Contents of the XML file include the entity
name, type, and compilation mode (static or dynamic), the entity
relations with other entities, and a description of any declared
predicates (name, compilation mode, scope, …).  The XML documentation
files can be enriched with arbitrary user-defined information, either
about an entity or about its predicates, by using documentation
directives.  The ‘lgtdoc’ tool includes POSIX and Windows scripts for
converting the XML documentation files to several final formats (such as
HTML and PDF).

Logtalk supports two documentation directives for providing arbitrary
user-defined information about an entity or a predicate.  These two
directives complement other directives that also provide important
documentation information, such as the *note mode/2: 149. and *note
meta_predicate/1: 152. directives.

* Menu:

* Entity documenting directives::
* Predicate documenting directives::
* Describing predicates::
* Documenting predicate exceptions::
* Processing and viewing documenting files::
* Inline formatting in comments text::
* Diagrams::


File: TheLogtalkHandbook-3.96.0.info,  Node: Entity documenting directives,  Next: Predicate documenting directives,  Up: Documenting

1.17.1 Entity documenting directives
------------------------------------

Arbitrary user-defined entity information can be represented using the
*note info/1: b4. directive:

     :- info([
         Key1 is Value1,
         Key2 is Value2,
         ...
     ]).

In this pattern, keys should be atoms and values should be bound terms.
The following keys are predefined and may be processed specially by
Logtalk tools:

‘comment’

     Comment describing the entity purpose (an atom).  End the comment
     with a period (full stop).  As a style guideline, don’t use overly
     long comments.  If you need to provide additional details, use the
     ‘fails_if’ and ‘remarks’ keys.

‘author’

     Entity author(s) (an atom or a compound term ‘{entity}’ where
     ‘entity’ is the name of an XML entity in a user-defined
     ‘custom.ent’ file).

‘version’

     Version number (a ‘Major:Minor:Patch’ compound term) Following the
     Semantic Versioning guidelines(1) is strongly advised.

‘date’

     Date of last modification in ISO 8601 standard format
     (‘Year-Month-Day’ where ‘Year’, ‘Month’, and ‘Day’ are integers).

‘parameters’

     Parameter names and descriptions for parametric entities (a list of
     ‘Name-Description’ pairs where both names and descriptions are
     atoms).  End the ‘Description’ with a period (full stop).

‘parnames’

     Parameter names for parametric entities (a list of atoms; a simpler
     version of the previous key, used when parameter descriptions are
     deemed unnecessary).

‘copyright’

     Copyright notice for the entity source code (an atom or a compound
     term ‘{entity}’ where ‘entity’ is the name of an XML entity defined
     in a user-defined ‘custom.ent’ file).

‘license’

     License terms for the entity source code; usually, just the license
     name (an atom or a compound term ‘{entity}’ where ‘entity’ is the
     name of an XML entity in a user-defined ‘custom.ent’ file).
     License names should, whenever possible, be a license identifier as
     specified in the SPDX standard(2).

‘remarks’

     List of general remarks about the entity using ‘Topic-Text’ pairs
     where both the topic and the text must be atoms.  End the ‘Text’
     with a period (full stop).

‘see_also’

     List of related entities (using the entity identifiers, which can
     be atoms or compound terms).

For example:

     :- info([
         version is 2:1:0,
         author is 'Paulo Moura',
         date is 2000-11-20,
         comment is 'Building representation.',
         diagram is 'UML Class Diagram #312'
     ]).

Use only the keywords that make sense for your application, and remember
that you are free to invent your own keywords.  All key-value pairs can
be retrieved programmatically using the *note reflection API: 48. and
are visible to the *note lgtdoc: 322. tool (which includes them in the
generated documentation).

   ---------- Footnotes ----------

   (1) https://semver.org

   (2) https://spdx.org/licenses/


File: TheLogtalkHandbook-3.96.0.info,  Node: Predicate documenting directives,  Next: Describing predicates,  Prev: Entity documenting directives,  Up: Documenting

1.17.2 Predicate documenting directives
---------------------------------------

Arbitrary user-defined predicate information can be represented using
the *note info/2: 168. directive:

     :- info(Name/Arity, [
         Key1 is Value1,
         Key2 is Value2,
         ...
     ]).

The first argument can also a grammar rule non-terminal indicator,
‘Name//Arity’.  Keys should be atoms.  Values should be bound terms.
The following keys are predefined and may be processed specially by
Logtalk tools:

‘comment’

     Comment describing the predicate (or non-terminal) purpose (an
     atom).  End the comment with a period (full stop).  As a style
     guideline, don’t use overly long comments.  If you need to provide
     additional details, use the ‘remarks’ key.

‘fails_if’

     Comment describing failing conditions for the predicate.  As a
     style guideline, don’t use overly long comments.  If you need to
     provide additional details, use the ‘remarks’ key.

‘arguments’

     Names and descriptions of predicate arguments for pretty print
     output (a list of ‘Name-Description’ pairs where both names and
     descriptions are atoms).  End the ‘Description’ with a period (full
     stop).

‘argnames’

     Names of predicate arguments for pretty print output (a list of
     atoms; a simpler version of the previous key, used when argument
     descriptions are deemed unnecessary).

‘allocation’

     Objects where we should define the predicate.  Some possible values
     are ‘container’, ‘descendants’, ‘instances’, ‘classes’,
     ‘subclasses’, and ‘any’.

‘redefinition’

     Describes if a predicate is expected to be redefined and, if so, in
     what way.  Some possible values are ‘never’, ‘free’, ‘specialize’,
     ‘call_super_first’, ‘call_super_last’.

‘exceptions’

     List of possible exceptions thrown by the predicate using
     ‘Description-Exception’ pairs.  The description must be an atom.
     The exception term must be a ground term.

‘examples’

     List of typical predicate call examples using the format
     ‘Description-Goal-Bindings’.  The description must be an atom with
     the goal term sharing variables with the bindings.  The variable
     bindings term uses the format ‘{Variable = Term, ...}’.  When there
     are no variable bindings, the success or failure of the predicate
     call should be represented by the terms ‘{true}’ or ‘{false}’,
     respectively (you can also use in alternative the terms ‘{yes}’ or
     ‘{no}’).

‘remarks’

     List of general remarks about the predicate using ‘Topic-Text’
     pairs where both the topic and the text must be atoms.  End the
     ‘Text’ with a period (full stop).

‘since’

     Version that added the predicate (‘Major:Minor:Patch’).

‘see_also’

     List of related predicates and non-terminals (using the predicate
     and non-terminal indicators).

For example:

     :- info(color/1, [
         comment is 'Table of defined colors.',
         argnames is ['Color'],
         constraint is 'Up to four visible colors allowed.',
         examples is [
            'Check that the color blue is defined' - color(blue) - {true}
         ]
     ]).

As with the ‘info/1’ directive, use only the keywords that make sense
for your application and remember that you are free to invent your own
keywords.  All key-value pairs can also be retrieved programmatically
using the *note reflection API: 48. and are visible to the *note lgtdoc:
322. tool (which includes them in the generated documentation).


File: TheLogtalkHandbook-3.96.0.info,  Node: Describing predicates,  Next: Documenting predicate exceptions,  Prev: Predicate documenting directives,  Up: Documenting

1.17.3 Describing predicates
----------------------------

The value of the ‘comment’ key, possibly extended with the ‘remarks’
key, should describe a predicate purpose and, when applicable, the
circumstances under which a call may fail.  Descriptions should be
consistent across library and application APIs.  Some guidelines:

1.  When starting the description with a verb, use the 'third-person
singular simple present form'.  For example, write ‘'Runs ...'’, ‘'Calls
...'’, ‘'Compares ...'’, ‘'Parses ...'’, ‘'Generates ...'’, ‘'Converts
...'’, ‘'Creates ...'’, ‘'Maps ...'’, ‘'Merges ...'’, ‘'Finds ...'’,
etc.

2.  Predicates that are pure logical relations often have descriptions
starting with ‘'True iff ...'’ or ‘'True if ...'’.

3.  Predicates with multiple solutions often have descriptions starting
with ‘'Enumerates, by backtracking, all ...'’ or ‘'Enumerates, by
backtracking, the ...'’.

4.  Predicate call failure conditions often have descriptions with one
or more sentences starting with ‘'Fails when ...'’ or ‘'Fails if ...'’.

If you’re not sure how best to describe a predicate, look for examples
in the Logtalk libraries and developer tools APIs documentation.


File: TheLogtalkHandbook-3.96.0.info,  Node: Documenting predicate exceptions,  Next: Processing and viewing documenting files,  Prev: Describing predicates,  Up: Documenting

1.17.4 Documenting predicate exceptions
---------------------------------------

As described above, the ‘info/2’ predicate directive supports an
‘exceptions’ key that allows us to list all exceptions that may occur
when calling a predicate.  For example:

     :- info(check_option/1, [
         comment is 'Succeeds if the option is valid. Throws an error otherwise.',
         argnames is ['Option'],
         exceptions is [
             '``Option`` is a variable' - instantiation_error,
             '``Option`` is neither a variable nor a compound term' - type_error(compound, 'Option'),
             '``Option`` is a compound term but not a valid option' - domain_error(option, 'Option')
         ]
     ]).

When possible, only standard exceptions should be used.  See e.g.  the
*note error handling methods: 24c. section for a full list.  The
argument names should be the same as those provided in the ‘arguments’
or ‘argnames’ keys.  Exceptions are usually listed starting with
instantiation and uninstantiation errors, followed by type errors, and
then domain errors.  These may then be followed by permission,
existence, evaluation, representation, or resource errors.

For each exception, use of 'controlled language' as found, e.g., in the
ISO Prolog Core standard and this Handbook is advised.  Some examples:

Instantiation error when one or more arguments cannot be a variable

     ‘Argument’ is a variable

     ‘Argument1’ and ‘Argument2’ are variables

Instantiation error when a closed list with bound elements is required

     ‘Argument’ is a partial list or a list with an element ‘Element’
     which is a variable

Uninstantiation error when an argument is not a variable

     ‘Argument’ is not a variable

Type error when an argument is not a variable but also not of the expected type

     ‘Argument’ is neither a variable nor a TYPE

     ‘Argument’ is neither a partial list nor a list

Type error when an element of a list is not a variable but is not of the expected type

     An element ‘Element’ of the ‘Argument’ list is neither a variable
     nor a TYPE

Domain error when an argument is of the correct type but not in the expected domain

     ‘Argument’ is a TYPE but not a valid DOMAIN

     ‘Argument’ is an integer that is less than zero

Domain error when an element of a list is of the correct type but not in the expected domain

     An element ‘Element’ of the ‘Argument’ list is a TYPE but not a
     valid DOMAIN

Existence error when an entity of a given kind does not exist

     The KIND ‘Argument’ does not exist

Other classes of errors have a less rigid style.  In case of doubt, look
for examples in this Handbook, in the APIs documentation, and in
standard documents.


File: TheLogtalkHandbook-3.96.0.info,  Node: Processing and viewing documenting files,  Next: Inline formatting in comments text,  Prev: Documenting predicate exceptions,  Up: Documenting

1.17.5 Processing and viewing documenting files
-----------------------------------------------

The *note lgtdoc: 322. tool generates an XML documenting file per
entity.  It can also generate library, directory, entity, and predicate
indexes when documenting libraries and directories.  For example,
assuming the default filename extensions, a ‘trace’ object and a
‘sort(_)’ parametric object will result in ‘trace_0.xml’ and
‘sort_1.xml’ XML files.

Each entity XML file contains references to two other files, an XML
specification file and a XSLT stylesheet file.  The XML specification
file can be either a DTD file (‘logtalk_entity.dtd’) or an XML Scheme
file (‘logtalk_entity.xsd’).  The XSLT stylesheet file is responsible
for converting the XML files to some desired format such as HTML or PDF.
The default names for the XML specification file and the XSL stylesheet
file are defined by the *note lgtdoc: 322. tool but can be overridden by
passing a list of options to the tool predicates.  The ‘lgtdoc/xml’
sub-directory in the Logtalk installation directory contains the XML
specification files described above, along with several sample XSL
stylesheet files and sample scripts for converting XML documenting files
to several formats (e.g., reStructuredText, Markdown, HTML, and PDF).
For example, assume that you want to generate the API documentation for
the ‘types’ library:

     | ?- {types(loader)}.
     ....

     | ?- {lgtdoc(loader)}.
     ....

     | ?- lgtdoc::library(types).
     ...

The above queries will result in the creation of a ‘xml_docs’ in your
current directory by default.  Assuming that we want to generate
Sphinx-based documentation and that we are using a POSIX
operating-system, the next steps would be:

     $ cd xml_docs
     $ lgt2rst -s -m

The ‘lgt2rst’ script will ask a few questions (project name, author,
version, …).  After its completion, the generated HTML files will be
found in the ‘_build/html’ directory by default:

     $ open _build/html/index.html

For Windows operating-systems, PowerShell scripts are available.  For
example, assuming that we want to generate HTML documentation, we could
run in a PowerShell window:

     PS > cd xml_docs
     PS > lgt2html.ps1 -p saxon

After completion, the generated HTML files will be found in the
‘xml_docs’ directory by default.

See the ‘NOTES’ file in the tool directory for details, specially on the
XSLT processor dependencies.  You may use the supplied sample files as a
starting point for generating the documentation of your Logtalk
applications.

The Logtalk DTD file, ‘logtalk_entity.dtd’, contains a reference to a
user-customizable file, ‘custom.ent’, which declares XML entities for
source code author names, license terms, and copyright strings.  After
editing the ‘custom.ent’ file to reflect your personal data, you may use
the XML entities on ‘info/1’ documenting directives.  For example,
assuming that the XML entities are named 'author', 'license', and
'copyright' we may write:

     :- info([
         version is 1:1:0,
         author is {author},
         license is {license},
         copyright is {copyright}
     ]).

The entity references are replaced by the value of the corresponding XML
entity when the XML documenting files are processed ('not' when they are
generated; this notation is just a shortcut to take advantage of XML
entities).

The *note lgtdoc: 322. tool supports a set of options that can be used
to control the generation of the XML documentation files.  See the tool
documentation for details.  There is also a *note doclet: 32d. tool that
allows automating the steps required to generate the documentation for
an application.


File: TheLogtalkHandbook-3.96.0.info,  Node: Inline formatting in comments text,  Next: Diagrams,  Prev: Processing and viewing documenting files,  Up: Documenting

1.17.6 Inline formatting in comments text
-----------------------------------------

Inline formatting in comments text can be accomplished by using Markdown
or reStructuredText syntax and converting XML documenting files to
Markdown or reStructuredText files (and these, if required, to e.g.
HTML, ePub, or PDF formats).  Note that Markdown and reStructuredText
common syntax elements are enough for most API documentation:

     Mark *italic text* with one asterisk.
     Mark **bold text** with two asterisks.
     Mark ``monospaced text`` with two backquotes.

Rendering this block as markup gives:

     Mark 'italic text' with one asterisk.  Mark 'bold text' with two
     asterisks.  Mark ‘monospaced text’ with two backquotes.

As single backquotes have different purposes in Markdown (monospaced
text) and reStructuredText (domain- or application-dependent meaning),
never use them.  This also avoids doubts if there’s an inline formatting
typo in text meant to be rendered as monospaced text (usually inline
code fragments).


File: TheLogtalkHandbook-3.96.0.info,  Node: Diagrams,  Prev: Inline formatting in comments text,  Up: Documenting

1.17.7 Diagrams
---------------

The *note diagrams: 2ed. tool supports a wide range of diagrams that can
also help in documenting an application.  The generated diagrams can
include URL links to both source code and API documentation.  They can
also be linked, connecting, for example, high level diagrams to detail
diagrams.  These features allow diagrams to be an effective solution for
navigating and understanding the structure and implementation of an
application.  This tool uses the same *note reflection API: 48. as the
‘lgtdoc’ tool and thus has access to the same source data.  See the tool
documentation for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Debugging,  Next: Performance<2>,  Prev: Documenting,  Up: User Manual

1.18 Debugging
==============

The Logtalk distribution includes a command-line *note debugger: 2fc.
tool implemented as a Logtalk application using the debugging API. It
can be loaded at the top-level interpreter by typing:

     | ?- logtalk_load(debugger(loader)).

It can also be loaded automatically at startup time by using a *note
settings file: 49.

The *note debugger: 2fc. tool includes the debugging features found in
traditional Prolog debuggers.  There are some differences, however,
between the usual implementation of Prolog debuggers and the current
implementation of the Logtalk debugger that you should be aware of.
First, unlike most Prolog debuggers, the Logtalk debugger is not a
built-in feature but a regular Logtalk application using documented
debugging hook predicates.  This translates to a different, although
similar, set of debugging features when compared with some of the more
sophisticated Prolog debuggers.  Second, debugging is only possible for
entities compiled in debug mode.  When compiling an entity in debug
mode, Logtalk decorates clauses with source information to allow tracing
of the goal execution.  Third, the tool provides several types of
breakpoints (for pausing and interacting with the debugger) and also log
points, while most Prolog systems are limited to traditional predicate
spy points.

* Menu:

* Compiling source files in debug mode::
* Procedure box model::
* Activating the debugger::
* Defining breakpoints::
* Defining log points::
* Tracing program execution::
* Debugging using breakpoints::
* Debugging commands::
* Customizing term writing::
* Context-switching calls::
* Debugging messages::
* Using the term-expansion mechanism for debugging::
* Ports profiling::
* Debug and trace events::
* Source-level debugger::


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiling source files in debug mode,  Next: Procedure box model,  Up: Debugging

1.18.1 Compiling source files in debug mode
-------------------------------------------

Compilation of source files in debug mode is controlled by the *note
debug: 2e2. compiler flag.  The default value for this flag, usually
‘off’, is defined in the *note backend adapter files: 154.  Its default
value may be changed globally at runtime by calling:

     | ?- set_logtalk_flag(debug, on).

Implicitly, this goal also turns off the ‘optimize’ flag.  In
alternative, if we want to compile only some source files in debug mode,
we may instead write:

     | ?- logtalk_load([file1, file2, ...], [debug(on)]).

The *note logtalk_make/1: 2a0. built-in predicate can also be used to
recompile all loaded files (that were compiled without using explicit
values for the *note debug: 2e2. and *note optimize: 8c. compiler flags
in a ‘logtalk_load/2’ call or in a *note loader file: 4f, if used) in
debug mode:

     | ?- logtalk_make(debug).

With most *note backend Prolog compilers: 34, the ‘{+d}’ top-level
shortcut can also be used.  After debugging, the files can be recompiled
in normal or optimized mode using, respectively, the ‘{+n}’ or ‘{+o}’
top-level shortcuts.

     Warning: The *note clean: 292. compiler flag should be turned on
     whenever the *note debug: 2e2. flag is turned on at runtime.  This
     is necessary because debug code would not be generated for files
     previously compiled in normal or optimized mode if there are no
     changes to the source files.

After loading the debugger, we may check (or enumerate by backtracking),
all loaded entities compiled in debug mode as follows:

     | ?- debugger::debugging(Entity).

To compile only a specific entity in debug mode, use the *note
set_logtalk_flag/2: 50. directive inside the entity.  To compile all
entities in a source file in debug mode, use the *note
set_logtalk_flag/2: 50. directive at the beginning of the file.


File: TheLogtalkHandbook-3.96.0.info,  Node: Procedure box model,  Next: Activating the debugger,  Prev: Compiling source files in debug mode,  Up: Debugging

1.18.2 Procedure box model
--------------------------

Logtalk uses a 'procedure box model' similar to those found on most
Prolog systems.  The traditional Prolog procedure box model defines four
ports ('call', 'exit', 'redo', and 'fail') for describing control flow
when calling a predicate:

     ‘call’
          predicate call
     ‘exit’
          success of a predicate call
     ‘redo’
          backtracking into a predicate call
     ‘fail’
          failure of a predicate call

Logtalk, as found on some recent Prolog systems, adds a port for dealing
with exceptions thrown when calling a predicate:

     ‘exception’
          predicate call throws an exception

In addition to the ports described above, Logtalk adds two more ports,
‘fact’ and ‘rule’, which show the result of the unification of a goal
with, respectively, a fact and a rule head:

     ‘fact’
          unification success between a goal and a fact
     ‘rule’
          unification success between a goal and a rule head

Following Prolog tradition, the user may define for which ports the
debugger should pause for user interaction by specifying a list of
'leashed' ports.  Unleashed ports are just printed with no pause for
user interaction when tracing.  For example:

     | ?- debugger::leash([call, exit, fail]).

Alternatively, the user may use an atom abbreviation for a pre-defined
set of ports.  For example:

     | ?- debugger::leash(loose).

The abbreviations defined in Logtalk are similar to those defined on
some Prolog compilers:

     ‘none’
          ‘[]’
     ‘loose’
          ‘[fact, rule, call]’
     ‘half’
          ‘[fact, rule, call, redo]’
     ‘tight’
          ‘[fact, rule, call, redo, fail, exception]’
     ‘full’
          ‘[fact, rule, call, exit, redo, fail, exception]’

By default, the debugger pauses at every port for user interaction.


File: TheLogtalkHandbook-3.96.0.info,  Node: Activating the debugger,  Next: Defining breakpoints,  Prev: Procedure box model,  Up: Debugging

1.18.3 Activating the debugger
------------------------------

The debuggerp::trace/0(1) and debuggerp::debug/0(2) predicates
implicitly select the ‘debugger’ tool as the active *note debug handler:
338.  If you have additional debug handlers loaded (e.g., the
‘ports_profiler’ tool), those would no longer be active (there can be
only one active debug handler at any given time).  The
debuggerp::nodebug/0(3) predicate implicitly deselects the ‘debugger’
tool as the active debug handler.

   ---------- Footnotes ----------

   (1) ../../apis/debuggerp_0.html#debuggerp-0-trace-0

   (2) ../../apis/debuggerp_0.html#debuggerp-0-debug-0

   (3) ../../apis/debuggerp_0.html#debuggerp-0-nodebug-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining breakpoints,  Next: Defining log points,  Prev: Activating the debugger,  Up: Debugging

1.18.4 Defining breakpoints
---------------------------

The ‘debugger’ tool provides the following breakpoint types where the
debugger pauses at a leashed port for user interaction:

   - 

     Predicate breakpoints

          Traditional Prolog spy points are defined using a predicate
          (or a non-terminal) indicator.

   - 

     Clause breakpoints

          Defined using the location of a clause.

   - 

     Conditional breakpoints

          Defined using the location of a clause and a condition for
          pausing.

   - 

     Hit count breakpoints

          Defined using the location of a clause and an unification
          count expression as a condition for pausing.

   - 

     Triggered breakpoints

          Defined using the location of a clause and another breakpoint
          that must be hit first as a condition for pausing.

   - 

     Context breakpoints

          Defined using execution context and goal templates as a
          condition for pausing.

Clause breakpoints are checked when the current goal successfully
unifies with a clause head.  To simplify their definition, these are
specified using the entity identifier instead of the file name (as all
entities share a single namespace, an entity can only be defined in a
single file) and the first line number of the clause head.  But note
that only some Prolog backends provide accurate source file term line
numbers.  Check the *note debugger: 2fc. tool documentation for details.

* Menu:

* Defining predicate and clause breakpoints::
* Defining conditional breakpoints::
* Defining hit count breakpoints::
* Defining triggered breakpoints::
* Defining context breakpoints::
* Removing all breakpoints::


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining predicate and clause breakpoints,  Next: Defining conditional breakpoints,  Up: Defining breakpoints

1.18.4.1 Defining predicate and clause breakpoints
..................................................

Predicate and clause breakpoints can be defined using the debugger
‘spy/1’ predicate.  The argument can be a predicate indicator
(‘Name/Arity’), a non-terminal indicator (‘Name//Arity’), a clause
location (expressed as an ‘Entity-Line’ pair), or a list of breakpoints.
Predicate and non-terminal indicators can also be qualified with a
specific object or category identifiers.  For example:

     | ?- debugger::spy(person-42).

     Clause breakpoint added.
     yes

     | ?- debugger::spy(foo/2).

     Predicate breakpoint added.
     yes

     | ?- debugger::spy(qux::baz/3).

     Entity predicate breakpoint added.
     yes

     | ?- debugger::spy([foo/4, bar//1, agent-99]).

     All specified breakpoints added.
     yes

Note that setting a clause breakpoint implicitly removes any existing
conditional breakpoint, triggered breakpoint, or log point for the same
clause.

Unconditional clause and predicate breakpoints can be removed by using
the debugger ‘nospy/1’ predicate.  The argument can also be a list of
breakpoints or a non-instantiated variable, in which case all
breakpoints will be removed.  For example:

     | ?- debugger::nospy(_).

     All matching predicate and clause breakpoints removed.
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining conditional breakpoints,  Next: Defining hit count breakpoints,  Prev: Defining predicate and clause breakpoints,  Up: Defining breakpoints

1.18.4.2 Defining conditional breakpoints
.........................................

Conditional clause breakpoints are specified using the debugger ‘spy/3’
predicate.  The first two arguments are the entity and the line of a
clause head.  The third argument is the condition, which can be a lambda
expression, an unification count expression (see next section), or
another breakpoint (see next below).

The supported lambda expressions are ‘[Count, N, Goal]>>Condition’ and
‘[Goal]>>Condition’ where ‘Count’ is the unification count, ‘N’ is the
goal invocation number, and ‘Goal’ is the goal that unified with the
clause head; ‘Condition’ is called in the context of the ‘user’
pseudo-object and must not have any side effects.  Some examples:

     | ?- debugger::spy(planet, 76, [weight(m1,_)]>>true).

     Conditional breakpoint added.
     yes

Note that setting a conditional breakpoint will remove any existing
clause breakpoint or log point for the same location.

Conditional breakpoints can be removed by using the debugger ‘nospy/3’
predicate.  For example:

     | ?- debugger::nospy(planet, _, _).

     All matching conditional breakpoints removed.
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining hit count breakpoints,  Next: Defining triggered breakpoints,  Prev: Defining conditional breakpoints,  Up: Defining breakpoints

1.18.4.3 Defining hit count breakpoints
.......................................

Conditional clause breakpoints that depend on the unification count are
known as 'hit count' clause breakpoints.  The debugger pauses at a hit
count breakpoint depending on an unification count expression:

   - ‘>(Count)’ - break when the unification count is greater than
     ‘Count’

   - ‘>=(Count)’ - break when the unification count is greater than or
     equal to ‘Count’

   - ‘=:=(Count)’ - break when the unification count is equal to ‘Count’

   - ‘=<(Count)’ - break when the unification count is less than or
     equal to ‘Count’

   - ‘<(Count)’ - break when the unification count is less than ‘Count’

   - ‘mod(M)’ - break when the unification count modulo ‘M’ is zero

   - ‘Count’ - break when the unification count is greater than or equal
     to ‘Count’

For example:

     | ?- debugger::spy(planet, 41, =<(2)).

     Conditional breakpoint added.
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining triggered breakpoints,  Next: Defining context breakpoints,  Prev: Defining hit count breakpoints,  Up: Defining breakpoints

1.18.4.4 Defining triggered breakpoints
.......................................

Conditional clause breakpoints that depend on other clause breakpoint or
on a log point are known as 'triggered' clause breakpoints.  The
debugger only pauses at a triggered breakpoint if the clause breakpoint
or log point it depends on is hit first.  For example:

     | ?- debugger::spy(mars, 98, planet-76).

     Triggered breakpoint added.
     yes

In this case, the debugger will break for user interaction at the
unification port for the clause in the source file defining the ‘mars’
object at line 98 if and only if the debugger paused earlier at the
unification port for the clause in the source file defining the ‘planet’
category at line 76.

The debugger prints a ‘^’ character at the beginning of the line for
easy recognition of triggered breakpoints.


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining context breakpoints,  Next: Removing all breakpoints,  Prev: Defining triggered breakpoints,  Up: Defining breakpoints

1.18.4.5 Defining context breakpoints
.....................................

A context breakpoint is a tuple describing a message execution context
and a goal:

     (Sender, This, Self, Goal)

The debugger pauses for user interaction whenever the breakpoint goal
and execution context subsume the goal currently being executed and its
execution context.  The user may establish any number of context
breakpoints as necessary.  For example, in order to call the debugger
whenever a predicate defined on an object named ‘foo’ is called, we may
define the following context breakpoint:

     | ?- debugger::spy(_, foo, _, _).

     Context breakpoint set.
     yes

For example, we can spy all calls to a ‘foo/2’ predicate with a ‘bar’
atom in the second argument by setting the condition:

     | ?- debugger::spy(_, _, _, foo(_, bar)).

     Context breakpoint set.
     yes

The debugger ‘nospy/4’ predicate may be used to remove all matching
breakpoints.  For example, the call:

     | ?- debugger::nospy(_, _, foo, _).

     All matching context breakpoints removed.
     yes

will remove all context breakpoints where the value of *note self: 69.
is the atom ‘foo’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Removing all breakpoints,  Prev: Defining context breakpoints,  Up: Defining breakpoints

1.18.4.6 Removing all breakpoints
.................................

We can remove all breakpoints by using the debugger ‘nospyall/0’
predicate:

     | ?- debugger::nospyall.

     All breakpoints removed.
     yes

There’s also a ‘reset/0’ predicate that can be used to reset the
debugger to its default settings and delete all defined breakpoints and
log points.


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining log points,  Next: Tracing program execution,  Prev: Defining breakpoints,  Up: Debugging

1.18.5 Defining log points
--------------------------

Logtalk log points are similar to breakpoints.  Therefore, the line
number must correspond to the first line of an entity clause.  When the
debugger reaches a log point, it prints a log message and continues
without pausing execution for reading a port command.  When the log
message is an empty atom, the default port output message is printed.
When the log message starts with a ‘%’ character, the default port
output message is printed, followed by the log message.  In these two
cases, the debugger prints a ‘@’ character at the beginning of the line
for easy recognition of log points output.  When the log message is
neither empty nor starts with a ‘%’ character, the log message is
printed instead of the default port output message.  In this case, the
message can contain ‘$KEYWORD’ placeholders that are expanded at
runtime.  The valid keywords are:

   - ‘PORT’

   - ‘ENTITY’

   - ‘CLAUSE_NUMBER’

   - ‘FILE’

   - ‘LINE’

   - ‘UNIFICATION_COUNT’

   - ‘INVOCATION_NUMBER’

   - ‘GOAL’

   - ‘PREDICATE’

   - ‘EXECUTION_CONTEXT’

   - ‘SENDER’

   - ‘THIS’

   - ‘SELF’

   - ‘METACALL_CONTEXT’

   - ‘COINDUCTION_STACK’

   - ‘THREAD’

Log points are defined using the ‘log/3’ predicate.  For example:

     | ?- debugger::log(agent, 99, '% At the secret headquarters!').
          Log point added.
     yes

     | ?- debugger::log(loop, 42, 'Message $PREDICATE from $SENDER at thread $THREAD').
          Log point added.
     yes

The ‘logging/3’ and ‘nolog/3’ predicate can be used to, respectively,
query and remove log points.  There’s also a ‘nologall/0’ predicate that
removes all log points.

Note that setting a log point will remove any existing clause breakpoint
for the same location.


File: TheLogtalkHandbook-3.96.0.info,  Node: Tracing program execution,  Next: Debugging using breakpoints,  Prev: Defining log points,  Up: Debugging

1.18.6 Tracing program execution
--------------------------------

Logtalk allows tracing of execution for all objects compiled in debug
mode.  To start the debugger in trace mode, write:

     | ?- debugger::trace.

     yes

Next, type the query to be debugged.  For example, using the ‘family’
example in the Logtalk distribution compiled for debugging:

     | ?- addams::sister(Sister, Sibling).
          Call: (1) sister(_1082,_1104) ?
          Rule: (1) sister(_1082,_1104) ?
          Call: (2) ::female(_1082) ?
          Call: (3) female(_1082) ?
          Fact: (3) female(morticia) ?
         *Exit: (3) female(morticia) ?
         *Exit: (2) ::female(morticia) ?
         ...

While tracing, the debugger will pause for user input at each leashed
port, printing an informative message.  Each trace line starts with the
port, followed by the goal invocation number, followed by the goal.  The
invocation numbers are unique and allow us to correlate the ports used
for a goal.  In the output above, you can see, for example, that the
goal ‘::female(_1082)’ succeeds with the answer ‘::female(morticia)’.
The debugger also provides determinism information by prefixing the
‘exit’ port with a ‘*’ character when a call succeeds with choice-points
pending, thus indicating that there might be alternative solutions for
the goal.

Note that breakpoints are ignored when tracing.  But when a breakpoint
is set for the current predicate or clause, the debugger prints, before
the port name and number, a ‘+’ character for predicate breakpoints, a
‘#’ character for clause breakpoints, a ‘?’ character for conditional
clause breakpoints, a ‘^’ for triggered breakpoints, and a ‘*’ character
for context breakpoints.  For example:

     | ?- debugger::spy(female/2).

     yes

     | ?- addams::sister(Sister, Sibling).
          Call: (1) sister(_1078,_1100) ?
          Rule: (1) sister(_1078,_1100) ?
          Call: (2) ::female(_1078) ?
       +  Call: (3) female(_1078) ?

To stop tracing (but still allowing the debugger to pause at the defined
breakpoints), write:

     | ?- debugger::notrace.

     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Debugging using breakpoints,  Next: Debugging commands,  Prev: Tracing program execution,  Up: Debugging

1.18.7 Debugging using breakpoints
----------------------------------

Tracing a program execution may generate large amounts of debugging
data.  Debugging using breakpoints allows the user to concentrate on
specific points of the code.  To start a debugging session using
breakpoints, write:

     | ?- debugger::debug.

     yes

For example, assuming the predicate breakpoint we set in the previous
section on the ‘female/1’ predicate:

     | ?- addams::sister(Sister, Sibling).
       +  Call: (3) female(_1078) ?

To stop the debugger, write:

     | ?- debugger::nodebug.

     yes

Note that stopping the debugger does not remove any defined breakpoints
or log points.


File: TheLogtalkHandbook-3.96.0.info,  Node: Debugging commands,  Next: Customizing term writing,  Prev: Debugging using breakpoints,  Up: Debugging

1.18.8 Debugging commands
-------------------------

The debugger pauses for user interaction at leashed ports when tracing
and when hitting a breakpoint.  The following commands are available:

‘c’ — creep

     go on; you may use the spacebar, return, or enter keys in
     alternative

‘l’ — leap

     continues execution until the next breakpoint is found

‘s’ — skip

     skips tracing for the current goal; valid at call, redo, and
     unification ports

‘S’ - Skip

     similar to skip but displaying all intermediate ports unleashed

‘q’ — quasi-skip

     skips tracing until returning to the current goal or reaching a
     breakpoint; valid at call and redo ports

‘r’ — retry

     retries the current goal but side-effects are not undone; valid at
     the fail port

‘j’ — jump

     reads invocation number and continues execution until a port is
     reached for that number

‘z’ — zap

     reads either a port name and continues execution until that port is
     reached or a negated port name (e.g.  ‘-exit’) and continues
     execution until a port other than the negated port is reached

‘i’ — ignore

     ignores goal, assumes that it succeeded; valid at call and redo
     ports

‘f’ — fail

     forces backtracking; may also be used to convert an exception into
     a failure

‘n’ — nodebug

     turns off debugging

‘N’ — notrace

     turns off tracing

‘@’ — command; ‘!’ can be used in alternative

     reads and executes a query

‘b’ — break

     suspends execution and starts new interpreter; type ‘end_of_file’
     to terminate

‘a’ — abort

     returns to top level interpreter

‘Q’ — quit

     quits Logtalk

‘p’ — print

     writes current goal using the ‘print/1’ predicate if available

‘d’ — display

     writes current goal without using operator notation

‘w’ — write

     writes current goal quoting atoms if necessary

‘$’ — dollar

     outputs the compiled form of the current goal (for low-level
     debugging)

‘x’ — context

     prints execution context

‘.’ — file

     prints file, entity, predicate, and line number information at an
     unification port

‘e’ — exception

     prints exception term thrown by the current goal

‘E’ — raise exception

     reads and throws an exception term

‘=’ — debugging

     prints debugging information

‘<’ — write depth

     sets the write term depth (set to ‘0’ to reset)

‘*’ — add

     adds a context breakpoint for the current goal

‘/’ — remove

     removes a context breakpoint for the current goal

‘+’ — add

     adds a predicate breakpoint for the current goal

‘-’ — remove

     removes a predicate breakpoint for the current goal

‘#’ — add

     adds a breakpoint for the current clause

‘|’ — remove

     removes a breakpoint for the current clause

‘h’ — condensed help

     prints list of command options

‘?’ — extended help

     prints list of command options


File: TheLogtalkHandbook-3.96.0.info,  Node: Customizing term writing,  Next: Context-switching calls,  Prev: Debugging commands,  Up: Debugging

1.18.9 Customizing term writing
-------------------------------

Debugging complex applications often requires customizing term writing.
The available options are limiting the writing depth of large compound
terms and using the ‘p’ command at a leashed port.  This command uses
the ‘format/3’ de facto standard predicate with the ‘~p’ formatting
option to delegate writing the term to the ‘print/1’ predicate.  But
note that some backends don’t support this formatting option.

* Menu:

* Term write depth::
* Custom term writing::


File: TheLogtalkHandbook-3.96.0.info,  Node: Term write depth,  Next: Custom term writing,  Up: Customizing term writing

1.18.9.1 Term write depth
.........................

The terms written by the debugger can be quite large depending on the
application being debugged.  As described in the previous section, the
debugger accepts the ‘<’ command to set the maximum write term depth for
compound terms.  This command requires that the used *note backend
Prolog compiler: 34. supports the non-standard but common ‘max_depth/1’
option for the ‘write_term/3’ predicate.  When the compound term being
written is deeply nested, the sub-terms are only written up to the
specified depth with the omitted sub-terms replaced usually by ‘...’.
For example:

     | ?- write_term([0,1,2,3,4,5,6,7,8,9], [max_depth(5)]).

     [0,1,2,3,4|...]
     yes

The default maximum depth depends on the backend.  To print compound
terms without a depth limit, set it explicitly to zero if necessary.
The debuggerp::write_max_depth/1(1) and
debuggerp::set_write_max_depth/1(2) predicates can be used to query and
set the default maximum depth.

   ---------- Footnotes ----------

   (1) ../../apis/debuggerp_0.html#debuggerp-0-write-max-depth-1

   (2) ../../apis/debuggerp_0.html#debuggerp-0-set-write-max-depth-1


File: TheLogtalkHandbook-3.96.0.info,  Node: Custom term writing,  Prev: Term write depth,  Up: Customizing term writing

1.18.9.2 Custom term writing
............................

The implicit use of the traditional ‘print/1’ predicate (using the ‘p’
command) and the ‘portray/1’ user-defined hook predicate requires
backend Prolog compiler support for these predicates.  See the
documentation of the backend you intend to use for details.  As an
example, assuming the following ‘portray/1’ definition:

     portray(e(V1,V2)) :-
         format('~q ---> ~q~n', [V1,V2]).

Calling the ‘print/1’ predicate with e.g.  a ‘e(x1,x7)’ compound term
argument will output:

     | ?- print(e(x1,x7)).

     x1 ---> x7
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Context-switching calls,  Next: Debugging messages,  Prev: Customizing term writing,  Up: Debugging

1.18.10 Context-switching calls
-------------------------------

Logtalk provides a debugging control construct, *note (<<)/2: c7, which
allows the execution of a query within the context of an object.  Common
debugging uses include checking an object local predicates (e.g.
predicates representing internal dynamic state) and sending a message
from within an object.  This control construct may also be used to write
unit tests.

Consider the following toy example:

     :- object(broken).

         :- public(a/1).

         a(A) :- b(A, B), c(B).
         b(1, 2). b(2, 4). b(3, 6).
         c(3).

     :- end_object.

Something is wrong when we try the object public predicate, ‘a/1’:

     | ?- broken::a(A).

     no

For helping in diagnosing the problem, instead of compiling the object
in debug mode and doing a 'trace' of the query to check the clauses for
the non-public predicates, we can instead simply type:

     | ?- broken << c(C).

     C = 3
     yes

The ‘(<<)/2’ control construct works by switching the execution context
to the object in the first argument and then compiling and executing the
second argument within that context:

     | ?- broken << (self(Self), sender(Sender), this(This)).

     Self = broken
     Sender = broken
     This = broken

     yes

As exemplified above, the ‘(<<)/2’ control construct allows you to call
an object local and private predicates.  However, it is important to
stress that we are not bypassing or defeating an object predicate scope
directives.  The calls take place within the context of the specified
object, not within the context of the object making the ‘(<<)/2’ call.
Thus, the ‘(<<)/2’ control construct implements a form of
'execution-context-switching'.

The availability of the ‘(<<)/2’ control construct is controlled by the
*note context_switching_calls: 2d9. compiler flag (its default value is
defined in the adapter files of the backend Prolog compilers).


File: TheLogtalkHandbook-3.96.0.info,  Node: Debugging messages,  Next: Using the term-expansion mechanism for debugging,  Prev: Context-switching calls,  Up: Debugging

1.18.11 Debugging messages
--------------------------

Messages generated by calls to the *note logtalk;;print_message/3: 2fe.
predicate where the message kind is either ‘debug’ or ‘debug(Group)’ are
only printed, by default, when the *note debug: 2e2. flag is turned on.
Moreover, these predicate calls are suppressed by the compiler when the
*note optimize: 8c. flag is turned on.  Note that actual printing of
debug messages does not require compiling the code in debug mode, only
turning on the ‘debug’ flag.

* Menu:

* Meta-messages: Meta-messages<2>.
* Selective printing of debug messages::


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-messages<2>,  Next: Selective printing of debug messages,  Up: Debugging messages

1.18.11.1 Meta-messages
.......................

To avoid having to define *note message_tokens//2: 300. grammar rules
for translating each and every debug message, Logtalk provides default
tokenization for seven 'meta-messages' that cover the most common cases:

‘@Message’

     By default, the message is printed as passed to the ‘write/1’
     predicate followed by a newline.

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

‘Format+Arguments’

     By default, the message is printed as passed to the ‘format/2’
     predicate.

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

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

‘[Stream,Prefix]>>Goal’

     By default, call user-defined printing ‘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.

‘[Stream]>>Goal’

     By default, call user-defined printing ‘Goal’ in the context of
     ‘user’.  The use of a lambda expression allows passing the message
     stream.

Some simple examples of using these meta-messages:

     | ?- logtalk::print_message(debug, core, @'Phase 1 completed').
     yes

     | ?- logtalk::print_message(debug, core, [Stream]>>write(Stream,foo)).
     yes

     | ?- set_logtalk_flag(debug, on).
     yes

     | ?- logtalk::print_message(debug, core, [Stream]>>write(Stream,foo)).
     foo
     yes

     | ?- logtalk::print_message(debug, core, @'Phase 1 completed').
     >>> Phase 1 completed
     yes

     | ?- logtalk::print_message(debug, core, answer-42).
     >>> answer: 42
     yes

     | ?- logtalk::print_message(debug, core, 'Position: <~d,~d>'+[42,23]).
     >>> Position: <42,23>
     yes

     | ?- logtalk::print_message(debug, core, [arthur,ford,marvin]).
     >>> - arthur
     >>> - ford
     >>> - marvin
     yes

     | ?- logtalk::print_message(debug, core, names::[arthur,ford,marvin]).
     >>> names:
     >>> - arthur
     >>> - ford
     >>> - marvin
     yes

The ‘>>>’ prefix is the default message prefix for ‘debug’ messages.  It
can be redefined using the *note logtalk;;message_prefix_stream/4: 304.
hook predicate.  For example:

     :- multifile(logtalk::message_prefix_stream/4).
     :- dynamic(logtalk::message_prefix_stream/4).

     logtalk::message_prefix_stream(debug, core, '(dbg) ', user_error).

Debugging messages only output information by default.  These messages
can, however, be *note intercepted: 309. to perform other actions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Selective printing of debug messages,  Prev: Meta-messages<2>,  Up: Debugging messages

1.18.11.2 Selective printing of debug messages
..............................................

By default, all debug messages are either printed or skipped, depending
on the *note debug: 2e2. and *note optimize: 8c. flags.  When the code
is not compiled in optimal mode, the *note debug_messages: 352. tool
allows selective enabling of debug messages per *note component: 353.
and per debug group.  For example, to enable all ‘debug’ and
‘debug(Group)’ messages for the ‘parser’ component:

     % upon loading the tool, all messages are disabled by default:
     | ?- logtalk_load(debug_messages(loader)).
     ...

     % enable both debug and debug(_) messages:
     | ?- debug_messages::enable(parser).
     yes

To enable only ‘debug(tokenization)’ messages for the ‘parser’
component:

     % first disable any and all enabled messages:
     | ?- debug_messages::disable(parser).
     yes

     % enable only debug(tokenization) messages:
     | ?- debug_messages::enable(parser, tokenization).
     yes

See the tool documentation for more details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Using the term-expansion mechanism for debugging,  Next: Ports profiling,  Prev: Debugging messages,  Up: Debugging

1.18.12 Using the term-expansion mechanism for debugging
--------------------------------------------------------

The *note term-expansion mechanism: cb. can also be used for conditional
compilation of debugging goals.  For example, the *note hook_objects:
31b. library provides a print_goal_hook(1) object that simplifies
printing entity goals before or after calling them by simply prefixing
them with an operator.  See the library and hook object documentation
for details.  You can also define your own specialized hook objects for
custom debugging tasks.

   ---------- Footnotes ----------

   (1) ../../apis/print_goal_hook_0.html#print-goal-hook-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Ports profiling,  Next: Debug and trace events,  Prev: Using the term-expansion mechanism for debugging,  Up: Debugging

1.18.13 Ports profiling
-----------------------

The Logtalk distribution includes a *note ports_profiler: 358. tool
based on the same procedure box model described above.  This tool is
specially useful for debugging performance issues (e.g., due to lack of
determinism or unexpected backtracking).  See the tool documentation for
details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Debug and trace events,  Next: Source-level debugger,  Prev: Ports profiling,  Up: Debugging

1.18.14 Debug and trace events
------------------------------

The debugging API defines two multifile predicates,
logtalk::trace_event/2(1) and logtalk::debug_handler/3(2) for handling
trace and debug events.  It also provides a logtalk::debug_handler/1(3)
multifile predicate that allows an object (or a category) to declare
itself as a debug handler provider.  The Logtalk ‘debugger’ and
‘ports_profiler’ tools are regular applications that are implemented
using this API, which can also be used to implement alternative or new
debugging-related tools.  See the API documentation for details and the
source code of the ‘debugger’ and ‘ports_profiler’ tools for usage
examples.

To define a new debug handler provider, add (to an object or category)
clauses for the ‘debug_handler/1’ and ‘debug_handler/3’ predicates.  For
example:

     % declare my_debug_handler as a debug handler provider
     :- multifile(logtalk::debug_handler/1).
     logtalk::debug_handler(my_debug_handler).

     % handle debug events
     :- multifile(logtalk::debug_handler/3).
     logtalk::debug_handler(my_debug_handler, Event, ExCtx) :-
         debug_handler(Event, ExCtx).

     debug_handler(fact(Entity,Fact,Clause,File,Line), ExCtx) :-
         ...
     debug_handler(rule(Entity,Head,Clause,File,Line), ExCtx) :-
         ...
     debug_handler(top_goal(Goal, TGoal), ExCtx) :-
         ...
     debug_handler(goal(Goal, TGoal), ExCtx) :-
         ...

Your debug handler provider should also either automatically call the
logtalk::activate_debug_handler/1(4) and
logtalk::deactivate_debug_handler/0(5) predicate or provide public
predicates to simplify calling these predicates.  For example:

     :- public(start/0).
     start :-
        logtalk::activate_debug_handler(my_debug_handler).

     :- public(stop/0).
     stop :-
        logtalk::deactivate_debug_handler.

If you only need to define a trace event handler, then simply define
clauses for the logtalk::trace_event/2(6) multifile predicate:

     :- multifile(logtalk::trace_event/2).
     :- dynamic(logtalk::trace_event/2).

     % the Logtalk runtime calls all defined logtalk::trace_event/2 hooks using
     % a failure-driven loop; thus we don't have to worry about handling all
     % events or failing after handling an event to give other hooks a chance
     logtalk::trace_event(fact(Entity, Fact, N, _, _), _) :-
         ...
     logtalk::trace_event(rule(Entity, Head, N, _, _), _) :-
         ...

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0-trace-event-2

   (2) ../../apis/logtalk_0.html#logtalk-0-debug-handler-3

   (3) ../../apis/logtalk_0.html#logtalk-0-debug-handler-1

   (4) ../../apis/logtalk_0.html#logtalk-0-activate-debug-handler-1

   (5) ../../apis/logtalk_0.html#logtalk-0-deactivate-debug-handler-0

   (6) ../../apis/logtalk_0.html#logtalk-0-trace-event-2


File: TheLogtalkHandbook-3.96.0.info,  Node: Source-level debugger,  Prev: Debug and trace events,  Up: Debugging

1.18.15 Source-level debugger
-----------------------------

A minimal source-level debugger is provided by the Logtalk for VSCode
extension: when debugging in the integrated terminal using the
‘debugger’ tool, the current clause (at leashed unification ports) is
shown in the active editor window.  The extension can also be used with
VSCodium.  See its documentation for more details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Performance<2>,  Next: Installing Logtalk,  Prev: Debugging,  Up: User Manual

1.19 Performance
================

Logtalk is implemented as a 'trans-compiler' to Prolog.  When compiling
predicates, it preserves in the generated Prolog code all cases of
first-argument indexing and tail-recursion.  In practice, this means
that if you know how to write efficient Prolog predicates, you already
know the basics of how to write efficient Logtalk predicates.

The Logtalk compiler appends a single argument to the compiled form of
all entity predicate clauses.  This hidden argument is used to pass the
*note execution-context: 35e. when proving a query.  In the common case
where a predicate makes no calls to the *note execution-context
predicates: 35f. and *note message-sending control constructs: 360. and
is neither a meta-predicate nor a coinductive predicate, the
execution-context is simply passed between goals.  In this case, with
most backend Prolog virtual machines, the cost of this extra argument is
null or negligible.  When the execution-context needs to be accessed
(e.g. to fetch the value of *note self: 69. for a *note (;;)/1: 5c.
call) there may be a small inherent overhead due to the access to the
individual arguments of the compound term used to represent the
execution-context.

* Menu:

* Source code compilation modes::
* Source code compilation order::
* Local predicate calls::
* Calls to imported or inherited predicates::
* Calls to module predicates::
* Messages: Messages<2>.
* Automatic expansion of built-in meta-predicates::
* Inlining::
* Generated code simplification and optimizations::
* Size of the generated code::
* Circular references::
* Debug mode overhead::
* Other considerations::


File: TheLogtalkHandbook-3.96.0.info,  Node: Source code compilation modes,  Next: Source code compilation order,  Up: Performance<2>

1.19.1 Source code compilation modes
------------------------------------

Source code can be compiled in 'optimal', 'normal', or 'debug' mode,
depending on the *note optimize: 8c. and *note debug: 2e2. compiler
flags.  Optimal mode is used when deploying an application, while normal
and debug modes are used when developing an application.  Compiling code
in optimal mode enables several optimizations, notably the use of *note
static binding: 35. whenever enough information is available at
compile-time.  In debug mode, most optimizations are turned off, and the
code is instrumented to generate *note debug events: d5. that enable
developer tools such as the *note command-line debugger: 2fc. and the
*note ports profiler: 358.


File: TheLogtalkHandbook-3.96.0.info,  Node: Source code compilation order,  Next: Local predicate calls,  Prev: Source code compilation modes,  Up: Performance<2>

1.19.2 Source code compilation order
------------------------------------

Static binding optimizations, notably message sending and super calls,
require referenced code to be compiled before the calls so that the
calls can be resolved at compile time.  The compiler prints warnings
when the file compilation/loading order is not ideal (controlled by the
*note unknown_entities: 2c0. flag).  See the *note Source files: 294.
section on using the logtalk::loaded_files_topological_sort/1(1) and
logtalk::loaded_files_topological_sort/2(2) predicates to find an
optimal file loading order.  See the *note Source files: 294. section
for details.  See also the section below on circular references.

   ---------- Footnotes ----------

   (1) 
../../apis/logtalk_0.html#logtalk-0-loaded-files-topological-sort-1

   (2) 
../../apis/logtalk_0.html#logtalk-0-loaded-files-topological-sort-2


File: TheLogtalkHandbook-3.96.0.info,  Node: Local predicate calls,  Next: Calls to imported or inherited predicates,  Prev: Source code compilation order,  Up: Performance<2>

1.19.3 Local predicate calls
----------------------------

Local calls to object (or category) predicates have zero overhead in
terms of the number of inferences, as expected, compared with local
Prolog calls.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calls to imported or inherited predicates,  Next: Calls to module predicates,  Prev: Local predicate calls,  Up: Performance<2>

1.19.4 Calls to imported or inherited predicates
------------------------------------------------

Assuming the *note optimize: 8c. flag is turned on and a static
predicate, *note (^^)/1: 5d. calls have zero overhead in terms of number
of inferences.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calls to module predicates,  Next: Messages<2>,  Prev: Calls to imported or inherited predicates,  Up: Performance<2>

1.19.5 Calls to module predicates
---------------------------------

Local calls from an object (or category) to a module predicate have zero
overhead (assuming both the module and the predicate are bound at
compile-time).


File: TheLogtalkHandbook-3.96.0.info,  Node: Messages<2>,  Next: Automatic expansion of built-in meta-predicates,  Prev: Calls to module predicates,  Up: Performance<2>

1.19.6 Messages
---------------

Logtalk implements *note static binding: 35. and *note dynamic binding:
36. for message-sending calls.  For dynamic binding, a caching mechanism
is used by the runtime.  It’s useful to measure the performance overhead
in 'number of logic inferences' compared with plain Prolog and Prolog
modules.  Note that the number of logic inferences is a metric
independent of the chosen backend Prolog compiler.  The results for
Logtalk 3.17.0 and later versions are:

   - Static binding: 0

   - Dynamic binding (object bound at compile-time): +1

   - Dynamic binding (object bound at runtime): +2

Static binding is the common case with libraries and most application
code; it requires compiling code with the *note optimize: 8c. flag
turned on.  Dynamic binding numbers are after the first call (i.e.
after the generalization of the query is cached).  All numbers with the
*note events: 89. flag set to ‘deny’ (setting this flag to ‘allow’ adds
an overhead of +5 inferences to the results above; note that this flag
can be defined on a per-object basis as needed instead of globally and
thus minimizing the performance impact).

The dynamic binding caches assume the used *note backend Prolog
compiler: 34. does indexing of dynamic predicates.  This is a common
feature of modern Prolog systems, but the actual details vary from
system to system and may have an impact on dynamic binding performance.

Note that messages to 'self' (*note (;;)/1: 5c. calls) and messages to
an object (*note (;;)/2: 7e. calls) from the top-level interpreter
always use dynamic binding, as the object that receives the message is
only known at runtime.

Messages sent from Prolog modules may use static binding depending on
the used backend Prolog compiler native support for goal-expansion.
Consult the Prolog compiler documentation and adapter file notes for
details.

     Warning: Some Prolog systems provide a ‘time/1’ predicate that also
     reports the number of inferences.  But the reported numbers are
     often misleading when the predicate is called from the top-level.
     Besides common top-level bookkeeping operations (e.g., keeping
     track of goal history or applying goal-expansion) that may
     influence the inference counting, the Logtalk runtime code for a
     ‘(::)/2’ top-level goal is necessarily different from the code
     generated for a ‘(::)/2’ goal from a compiled object, as it
     requires 'runtime' compilation of the goal into the same low-level
     message-sending primitive (assuming dynamic-binding is also
     required for the compiled object goal).


File: TheLogtalkHandbook-3.96.0.info,  Node: Automatic expansion of built-in meta-predicates,  Next: Inlining,  Prev: Messages<2>,  Up: Performance<2>

1.19.7 Automatic expansion of built-in meta-predicates
------------------------------------------------------

The compiler always expands calls to the *note forall/2: 1c3, *note
once/1: 1bb, and *note ignore/1: 180. meta-predicates into equivalent
definitions using the negation and conditional control constructs.  It
also expands calls to the *note call/1-N: 181, *note phrase/2: 18e, and
*note phrase/3: 18f. meta-predicates when the first argument is bound.
These expansions are performed independently of the ‘optimize’ flag
value.


File: TheLogtalkHandbook-3.96.0.info,  Node: Inlining,  Next: Generated code simplification and optimizations,  Prev: Automatic expansion of built-in meta-predicates,  Up: Performance<2>

1.19.8 Inlining
---------------

When the *note optimize: 8c. flag is turned on, the Logtalk compiler
performs 'inlining' of predicate calls whenever possible.  This includes
calls to Prolog predicates that are either built-in, foreign, or defined
in a module (including ‘user’).  Inlining notably allows wrapping module
or foreign predicates using an object without introducing any overhead.
In the specific case of the *note execution-context predicates: 19c,
calls are inlined independently of the ‘optimize’ flag value.


File: TheLogtalkHandbook-3.96.0.info,  Node: Generated code simplification and optimizations,  Next: Size of the generated code,  Prev: Inlining,  Up: Performance<2>

1.19.9 Generated code simplification and optimizations
------------------------------------------------------

When the *note optimize: 8c. flag is turned on, the Logtalk compiler
simplifies and optimizes generated clauses (including those resulting
from the compilation of grammar rules), by flattening conjunctions,
folding left unifications (e.g. generated as a by-product of the
compilation of grammar rules), and removing redundant calls to ‘true/0’.

When using *note lambda expressions: 162. and library meta-predicates,
use the *note meta_compiler: 36a. library to avoid most meta-call
overheads.


File: TheLogtalkHandbook-3.96.0.info,  Node: Size of the generated code,  Next: Circular references,  Prev: Generated code simplification and optimizations,  Up: Performance<2>

1.19.10 Size of the generated code
----------------------------------

The size of the intermediate Prolog code generated by the compiler is
proportional to the size of the source code.  Assuming that the *note
term-expansion mechanism: cb. is not used, each predicate clause in the
source code is compiled into a single predicate clause.  But the Logtalk
compiler also generates internal tables for the defined entities, for
the entity relations, and for the declared and defined predicates.
These tables enable support for fundamental features such as *note
inheritance: 8. and *note reflection: 48.  The size of these tables is
proportional to the number of entities, entity relations, and predicate
declarations and definitions.  When the *note source_data: cc. is turned
on (the default when 'developing' an application), the generated code
also includes additional data about the source code, such as entity and
predicate positions in a source file.  This data enables advanced
developer tool functionality.  But it is usually not required when
'deploying' an application.  Thus, turning this flag off is a common
setting for minimizing an application footprint.


File: TheLogtalkHandbook-3.96.0.info,  Node: Circular references,  Next: Debug mode overhead,  Prev: Size of the generated code,  Up: Performance<2>

1.19.11 Circular references
---------------------------

Circular references, i.e.  two objects sending messages to each other,
are relatively costly and should be avoided if possible as they prevent
using static binding for the messages sent from the first loaded object
to the second object.  The *note logtalk_make(circular): 2a0. goal (or
its ‘{@}’ top-level abbreviation) can be used to scan for circular
entity dependencies.


File: TheLogtalkHandbook-3.96.0.info,  Node: Debug mode overhead,  Next: Other considerations,  Prev: Circular references,  Up: Performance<2>

1.19.12 Debug mode overhead
---------------------------

Code compiled in debug mode runs slower, as expected, when compared with
normal or optimized mode.  The overhead depends on the number of 'debug
events' generated when running the application.  A debug event is simply
a pass on a call or unification port of the *note procedure box model:
335.  These debug events can be intercepted by defined clauses for the
logtalk::trace_event/2(1) and logtalk::debug_handler/3(2) multifile
predicates.  With no application (such as a debugger or a port profiler)
loaded defining clauses for these predicates, each goal has an overhead
of four extra inferences due to the runtime checking for a definition of
the hook predicates and a meta-call of the user goal.  The clause head
unification events result in one or more inferences per goal (depending
on the number of clauses whose head unifies with the goal and
backtracking).  In practice, this overhead translates to code compiled
in debug mode running typically ~2x to ~7x slower than code compiled in
normal or optimized mode, depending on the application (the exact
overhead is proportional to the number of passes on the call and
unification ports; deterministic code often results in a relatively
larger overhead when compared with code performing significant
backtracking).

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0-trace-event-2

   (2) ../../apis/logtalk_0.html#logtalk-0-debug-handler-3


File: TheLogtalkHandbook-3.96.0.info,  Node: Other considerations,  Prev: Debug mode overhead,  Up: Performance<2>

1.19.13 Other considerations
----------------------------

One aspect of performance that affects both Logtalk and Prolog code is
the characteristics of the Prolog VM. The Logtalk distribution includes
two examples, bench(1) and benchmarks(2), to help evaluate performance
with specific backend Prolog systems.  A table with benchmark results(3)
for a subset of the supported systems is also available at the Logtalk
website.  But note that multiple factors affect the performance of an
application.  The benchmark examples and their results only provide a
partial assessment.

   ---------- Footnotes ----------

   (1) 
https://github.com/LogtalkDotOrg/logtalk3/tree/master/examples/bench

   (2) 
https://github.com/LogtalkDotOrg/logtalk3/tree/master/examples/benchmarks

   (3) https://logtalk.org/performance.html


File: TheLogtalkHandbook-3.96.0.info,  Node: Installing Logtalk,  Next: Prolog integration and migration,  Prev: Performance<2>,  Up: User Manual

1.20 Installing Logtalk
=======================

This page provides an overview of Logtalk installation requirements and
instructions and a description of the files contained in the Logtalk
distribution.  For detailed, up-to-date installation and configuration
instructions, please see the ‘README.md’, ‘INSTALL.md’, and
‘CUSTOMIZE.md’ files distributed with Logtalk.  The broad compatibility
of Logtalk, both with Prolog compilers and operating-systems, together
with all the possible user scenarios, means that installation can vary
from very simple, by running an installer or a couple of scripts, to the
need of patching both Logtalk and Prolog compilers to workaround the
lack of strong Prolog standards or to cope with the requirements of less
common operating-systems.

The preferred installation scenario is to have Logtalk installed in a
system-wide location, thus available for all users, and a local copy of
user-modifiable files on each user home directory (even when you are the
single user of your computer).  This scenario allows each user to
independently customize Logtalk and to freely modify the provided
libraries and programming examples.  Logtalk installers, installation
shell scripts, and Prolog integration scripts favor this installation
scenario, although alternative installation scenarios are always
possible.  The installers set two environment variables, ‘LOGTALKHOME’
and ‘LOGTALKUSER’, pointing, respectively, to the Logtalk installation
folder and to the Logtalk user folder.

User applications should preferably be kept outside of the Logtalk user
folder created by the installation process, as updating Logtalk often
results in updating the contents of this folder.  If your applications
depend on customizations to the distribution files, backup those changes
before updating Logtalk.

* Menu:

* Hardware and software requirements::
* Logtalk installers::
* Source distribution::
* Distribution overview::


File: TheLogtalkHandbook-3.96.0.info,  Node: Hardware and software requirements,  Next: Logtalk installers,  Up: Installing Logtalk

1.20.1 Hardware and software requirements
-----------------------------------------

* Menu:

* Computer and operating system::
* Prolog compiler::


File: TheLogtalkHandbook-3.96.0.info,  Node: Computer and operating system,  Next: Prolog compiler,  Up: Hardware and software requirements

1.20.1.1 Computer and operating system
......................................

Logtalk is compatible with almost any computer/operating-system with a
modern, standards-compliant, Prolog compiler available.


File: TheLogtalkHandbook-3.96.0.info,  Node: Prolog compiler,  Prev: Computer and operating system,  Up: Hardware and software requirements

1.20.1.2 Prolog compiler
........................

Logtalk requires a *note backend Prolog compiler: 34. supporting
official and de facto standards.  Capabilities needed by Logtalk that
are not defined in the official ISO Prolog Core standard include:

   - access to predicate properties

   - operating-system access predicates

   - de facto standard predicates not (yet) specified in the official
     standard

Logtalk needs access to the predicate property ‘built_in’ to properly
compile objects and categories that contain Prolog built-in predicate
calls.  In addition, some Logtalk built-ins need to know the
dynamic/static status of predicates to ensure correct application.  The
ISO standard for Prolog modules defines a ‘predicate_property/2’
predicate that is already implemented by most Prolog compilers.  Note
that if these capabilities are not built-in the user cannot easily
define them.

For optimal performance, Logtalk requires that the Prolog compiler
supports 'first-argument indexing' for both static and dynamic code
(most modern compilers support this feature).

Since most Prolog compilers are moving closer to the ISO Prolog standard
*note [ISO95]: 31, it is advisable that you try to use the most recent
version of your favorite Prolog compiler.


File: TheLogtalkHandbook-3.96.0.info,  Node: Logtalk installers,  Next: Source distribution,  Prev: Hardware and software requirements,  Up: Installing Logtalk

1.20.2 Logtalk installers
-------------------------

Logtalk installers are available for macOS, Linux, and Microsoft
Windows.  Depending on the chosen installer, some tasks (e.g., setting
environment variables or integrating Logtalk with some Prolog compilers)
may need to be performed manually.


File: TheLogtalkHandbook-3.96.0.info,  Node: Source distribution,  Next: Distribution overview,  Prev: Logtalk installers,  Up: Installing Logtalk

1.20.3 Source distribution
--------------------------

Logtalk sources are available in a ‘tar’ archive compressed with
‘bzip2’, ‘lgt3xxx.tar.bz2’.  You may expand the archive by using a
decompressing utility or by typing the following commands at the
command-line:

     % tar -jxvf lgt3xxx.tar.bz2

This will create a sub-directory named ‘lgt3xxx’ in your current
directory.  Almost all files in the Logtalk distribution are text files.
Different operating-systems use different end-of-line codes for text
files.  Ensure that your decompressing utility converts the end-of-lines
of all text files to match your operating system.


File: TheLogtalkHandbook-3.96.0.info,  Node: Distribution overview,  Prev: Source distribution,  Up: Installing Logtalk

1.20.4 Distribution overview
----------------------------

In the Logtalk installation directory, you will find the following files
and directories:

‘ACKNOWLEDGMENTS.md’ - List of authors, contributors, sponsors, and open
source credits

‘BIBLIOGRAPHY.bib’ – Logtalk bibliography in BibTeX format

‘CITATION.cff’ - Information on how to cite Logtalk

‘CODE_OF_CONDUCT.md’ - Code of conduct for contributors and users
posting on support forums

‘CUSTOMIZE.md’ – Logtalk end-user customization instructions

‘INSTALL.md’ – Logtalk installation instructions

‘LICENSE.txt’ – Logtalk user license

‘NOTICE.txt’ – Logtalk copyright notice

‘QUICK_START.md’ – Quick start instructions for those that do not like
to read manuals

‘README.md’ – several useful pieces of information

‘RELEASE_NOTES.md’ – release notes for this version

‘UPGRADING.md’ – instructions on how to upgrade your programs to the
current Logtalk version

‘VERSION.txt’ – file containing the current Logtalk version number (used
for compatibility checking when upgrading Logtalk)

‘adapters’

     ‘NOTES.md’ – notes on the provided adapter files

     ‘template.pl’ – template adapter file

     ‘...’ – specific adapter files

‘coding’

     ‘NOTES.md’ – notes on syntax highlighter and text editor support
     files providing syntax coloring for publishing and editing Logtalk
     source code

     ‘...’ – syntax coloring support files

‘contributions’

     ‘NOTES.md’ – notes on the user-contributed code

     ‘...’ – user-contributed code files

‘core’

     ‘NOTES.md’ – notes on the current status of the compiler and
     runtime

     ‘...’ – core source files

‘docs/apis’

     ‘NOTES.md’ – notes on the provided documentation for core, library,
     tools, and contributions entities

     ‘index.html’ – root document for all entities documentation

     ‘...’ – other entity documentation files

‘docs/handbook’

     ‘NOTES.md’ – notes on the provided documentation

     ‘bibliography.html’ – bibliography

     ‘glossary.html’ – glossary

     ‘index.html’ – root document for all documentation

     ‘...’ – other documentation files

‘docs/man’

     ‘...’ – POSIX man pages for the shell scripts

‘examples’

     ‘NOTES.md’ – short description of the provided examples

     ‘ack’

          ‘NOTES.md’ – example notes and sample queries

          ‘loader.lgt’ – loader utility file for the example objects

          ‘...’ – ack example source files

     ‘...’ – other examples

‘integration’

     ‘NOTES.md’ – notes on scripts for Logtalk integration with Prolog
     compilers

     ‘...’ – Prolog integration scripts

‘library’

     ‘NOTES.md’ – short description of the library contents

     ‘all_loader.lgt’ – loader utility file for all library entities

     ‘...’ – library source files

‘paths’

     ‘NOTES.md’ – description on how to setup library and example paths

     ‘paths.pl’ – default library and example paths

‘ports’

     ‘NOTES.md’ – description of included ports of third-party software

     ‘...’ – ports

‘samples’

     ‘loader-sample.lgt’ – sample loader file for user applications

     ‘settings-sample.lgt’ – sample file for user-defined Logtalk
     settings

     ‘tester-sample.lgt’ – sample file for helping to automate running
     user application unit tests

     ‘tests-sample.lgt’ – sample file for writing user application unit
     tests

‘scratch’

     ‘NOTES.md’ – notes on the scratch directory

‘scripts’

     ‘NOTES.md’ – notes on scripts for Logtalk user setup, packaging,
     and installation

     ‘...’ – packaging, installation, and setup scripts

‘tests’

     ‘NOTES.md’ – notes on the current status of the unit tests

     ‘...’ – unit tests for built-in features

‘tools’

     ‘NOTES.md’ – notes on the provided programming tools

     ‘...’ – programming tools

* Menu:

* Adapter files::
* Compiler and runtime::
* Library::
* Examples::
* Logtalk source files::


File: TheLogtalkHandbook-3.96.0.info,  Node: Adapter files,  Next: Compiler and runtime,  Up: Distribution overview

1.20.4.1 Adapter files
......................

Adapter files provide the glue code between the Logtalk compiler/runtime
and a Prolog compiler.  Each adapter file contains two sets of
predicates: ISO Prolog standard predicates and directives not built-in
in the target Prolog compiler and Logtalk specific predicates.

Logtalk already includes ready-to-use adapter files for most academic
and commercial Prolog compilers.  If an adapter file is not available
for the compiler that you intend to use, then you need to build a new
one, starting from the included ‘template.pl’ file.  Start by making a
copy of the template file.  Carefully check (or complete if needed) each
listed definition.  If your Prolog compiler conforms to the ISO
standard, this task should only take you a few minutes.  In most cases,
you can borrow code from the predefined adapter files.  If you are
unsure that your Prolog compiler provides all the ISO predicates needed
by Logtalk, try to run the system by setting the unknown predicate error
handler to report as an error any call to a missing predicate.  Better
yet, switch to a modern, ISO-compliant, Prolog compiler.  If you send me
your adapter file, with a reference to the target Prolog compiler, maybe
I can include it in the next release of Logtalk.

The adapter files specify 'default' values for most of the Logtalk *note
compiler flags: 251.  They also specify values for read-only flags that
are used to describe Prolog backend-specific features.


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiler and runtime,  Next: Library,  Prev: Adapter files,  Up: Distribution overview

1.20.4.2 Compiler and runtime
.............................

The ‘core’ sub-directory contains the Prolog and Logtalk source files
that implement the Logtalk compiler and the Logtalk runtime.  The
compiler and the runtime may be split in two (or more) separate files or
combined into a single file, depending on the Logtalk release that you
are installing.


File: TheLogtalkHandbook-3.96.0.info,  Node: Library,  Next: Examples,  Prev: Compiler and runtime,  Up: Distribution overview

1.20.4.3 Library
................

The Logtalk distribution includes a standard library of useful objects,
categories, and protocols.  Read the corresponding ‘NOTES.md’ file for
details about the library contents.


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples,  Next: Logtalk source files,  Prev: Library,  Up: Distribution overview

1.20.4.4 Examples
.................

The Logtalk distribution includes a large number of programming
examples.  The sources of each one of these examples can be found
included in a subdirectory with the same name, inside the directory
examples.  The majority of these examples include tests and a file named
‘SCRIPT.txt’ with sample calls.  Some examples may depend on other
examples and library objects to work properly.  Read the corresponding
‘NOTES.md’ file for details before running an example.


File: TheLogtalkHandbook-3.96.0.info,  Node: Logtalk source files,  Prev: Examples,  Up: Distribution overview

1.20.4.5 Logtalk source files
.............................

Logtalk source files are text files containing one or more entity
definitions (objects, categories, or protocols).  The Logtalk source
files may also contain plain Prolog code.  The extension ‘.lgt’ is
normally used.  Logtalk compiles these files to plain Prolog by
appending to the file name a suffix derived from the extension and by
replacing the ‘.lgt’ extension with ‘.pl’ (‘.pl’ is the default Prolog
extension; if your Prolog compiler expects the Prolog source filenames
to end with a specific, different extension, you can set it in the
corresponding adapter file).


File: TheLogtalkHandbook-3.96.0.info,  Node: Prolog integration and migration,  Prev: Installing Logtalk,  Up: User Manual

1.21 Prolog integration and migration
=====================================

This section provides suggestions for integrating and migrating plain
Prolog code and Prolog module code to Logtalk.  Detailed instructions
are provided for encapsulating plain Prolog code in objects, converting
Prolog modules into objects, and compiling and reusing Prolog modules as
objects from inside Logtalk.  An interesting application of the
techniques described in this section is a solution for running a Prolog
application that uses modules on a Prolog compiler with no module
system.  The *note wrapper: 38b. tool can be used to help in migrating
Prolog code.

* Menu:

* Source files with both Prolog code and Logtalk code::
* Encapsulating plain Prolog code in objects::
* Converting Prolog modules into objects::
* Compiling Prolog modules as objects::
* Dealing with proprietary Prolog directives and predicates::
* Calling Prolog module predicates: Calling Prolog module predicates<2>.
* Loading converted Prolog applications::


File: TheLogtalkHandbook-3.96.0.info,  Node: Source files with both Prolog code and Logtalk code,  Next: Encapsulating plain Prolog code in objects,  Up: Prolog integration and migration

1.21.1 Source files with both Prolog code and Logtalk code
----------------------------------------------------------

Logtalk source files may contain plain Prolog code intermixed with
Logtalk code.  The Logtalk compiler simply copies the plain Prolog code
as-is to the generated Prolog file.  With Prolog modules, it is assumed
that the module code starts with a ‘module/1-2’ directive and ends at
the end of the file.  There is no module ending directive that would
allow us to define more than one module per file.  In fact, most, if not
all, Prolog module systems always define a single module per file.  Some
of them mandate that the ‘module/1-2’ directive be the first term in a
source file.  As such, when the Logtalk compiler finds a ‘module/1-2’
directive, it assumes that all code that follows until the end of the
file belongs to the module.


File: TheLogtalkHandbook-3.96.0.info,  Node: Encapsulating plain Prolog code in objects,  Next: Converting Prolog modules into objects,  Prev: Source files with both Prolog code and Logtalk code,  Up: Prolog integration and migration

1.21.2 Encapsulating plain Prolog code in objects
-------------------------------------------------

Most applications consist of several plain Prolog source files, each one
defining a few top-level predicates and auxiliary predicates that are
not meant to be directly called by the user.  Encapsulating plain Prolog
code in objects allows us to make clear the different roles of each
predicate, to hide implementation details, to prevent auxiliary
predicates from being called outside the object, and to take advantage
of Logtalk advanced code encapsulating and reusing features.  It also
simplifies using its developer tools.

Encapsulating Prolog code using Logtalk objects is simple.  First, for
each source file, add an opening object directive, *note object/1-5: 9a,
to the beginning of the file and an ending object directive, *note
end_object/0: 9b, to the end of the file.  Choose an object name that
reflects the purpose of the source file code (this is a good opportunity
for code refactoring if necessary).  Second, add *note public/1: 143.
predicate directives for the top-level predicates that are used directly
by the user or called from other source files.  Third, we need to be
able to call from inside an object predicates defined in other source
files/objects.  The easiest solution, which has the advantage of not
requiring any changes to the predicate definitions, is to use the *note
uses/2: 4b. directive.  If your Prolog compiler supports
cross-referencing tools, you may use them to help you make sure that all
calls to predicates on other source files/objects are listed in the
*note uses/2: 4b. directives.  The Logtalk ‘wrapper’ tool can also help
in detecting cross-predicate calls.  Compiling the resulting objects
with the Logtalk *note unknown_predicates: 2c1. and *note portability:
1d1. flags set to ‘warning’ will help you identify calls to predicates
defined in other converted source files and possible portability issues.

* Menu:

* Prolog multifile predicates::


File: TheLogtalkHandbook-3.96.0.info,  Node: Prolog multifile predicates,  Up: Encapsulating plain Prolog code in objects

1.21.2.1 Prolog multifile predicates
....................................

Prolog 'multifile' predicates are used when clauses for the same
predicate are spread among several source files.  When encapsulating
plain Prolog code that uses multifile predicates, it’s often the case
that the clauses of the multifile predicates get spread between
different objects and categories, but conversion is straight-forward.
In the Logtalk object (or category) holding the multifile predicate
*note primary declaration: 392, add a *note predicate scope directive:
13f. and a *note multifile/1: 16a. directive.  In all other objects (or
categories) defining clauses for the multifile predicate, add a
‘multifile/1’ directive and predicate clauses using the format:

     :- multifile(Entity::Name/Arity).

     Entity::Functor(...) :-
         ...

See the *note section: 16a. on the ‘multifile/1’ predicate directive for
more information.  An alternative solution is to simply keep the clauses
for the multifile predicates as plain Prolog code and define, if
necessary, a parametric object to encapsulate all predicates working
with the multifile predicate clauses.  For example, assume the following
‘multifile/1’ directive:

     % city(Name, District, Population, Neighbors)
     :- multifile(city/4).

We can define a parametric object with ‘city/4’ as its identifier:

     :- object(city(_Name, _District, _Population, _Neighbors)).

         % predicates for working with city/4 clauses

     :- end_object.

This solution is preferred when the multifile predicates are used to
represent large tables of data.  See the section on *note parametric
objects: 66. for more details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Converting Prolog modules into objects,  Next: Compiling Prolog modules as objects,  Prev: Encapsulating plain Prolog code in objects,  Up: Prolog integration and migration

1.21.3 Converting Prolog modules into objects
---------------------------------------------

Converting Prolog modules into objects may allow an application to run
on a wider range of Prolog compilers, overcoming portability problems.
Some Prolog compilers don’t support a module system.  Among those Prolog
compilers that support a module system, the lack of standardization
leads to several issues, notably with semantics, operators, and
meta-predicates.  In addition, the conversion allows you to take
advantage of Logtalk more powerful abstraction and reuse mechanisms,
such as separation between interface and implementation, inheritance,
parametric objects, and categories.  It also allows you to take full
advantage of Logtalk developer tools for improved productivity.

Converting a Prolog module into an object is simplified when the
directives used in the module are supported by Logtalk (see the listing
in the next section).  Assuming that this is the case, apply the
following steps:

  1. Convert the module ‘module/1’ directive into an *note object/1: 9a.
     opening object directive, using the module name as the object name.
     For ‘module/2’ directives apply the same conversion and convert the
     list of exported predicates into *note public/1: 143. predicate
     directives.  Add a closing object directive, *note end_object/0:
     9b, at the end of the source code.

  2. Convert any ‘export/1’ directives into ‘public/1’ predicate
     directives.

  3. Convert any ‘use_module/1’ directives for modules that will not be
     converted to objects into ‘use_module/2’ directives (see next
     section), replacing the file spec in the first argument with the
     module name.

  4. Convert any ‘use_module/1-2’ directives referencing other modules
     also being converted to objects into Logtalk *note uses/2: 4b.
     directives.

  5. Convert each ‘reexport/1’ directive into a *note uses/2: 4b.
     directive and ‘public/1’ predicate directives (see next section).

  6. Convert any ‘meta_predicate/1’ directives into Logtalk *note
     meta_predicate/1: 152. directives by replacing the module
     meta-argument indicator, ‘:’, with the Logtalk meta-argument
     indicator ‘0’ for goal meta-arguments.  For closure meta-arguments,
     use an integer denoting the number of additional arguments that
     will be appended to construct a goal.  Arguments that are not
     meta-arguments are represented by the ‘*’ character.  Do not use
     argument mode indicators such as ‘?’, or ‘+’, or ‘-’ as Logtalk
     supports *note mode directives: 148.

  7. Convert any explicit qualified calls to module predicates to
     messages by replacing the ‘(:)/2’ operator with the *note (;;)/2:
     7e. message-sending operator when the referenced modules are also
     being converted into objects.  Calls in the pseudo-module ‘user’
     can be encapsulated using the *note {}/1: 191. Logtalk external
     call control construct.  You can also use instead a *note uses/2:
     4b. directive where the first argument would be the atom ‘user’ and
     the second argument a list of all external predicates.  This
     alternative has the advantages of not requiring changes to the code
     making the predicate calls and of better visibility for the
     documenting and diagramming tools.

  8. If your module uses the database built-in predicates to implement
     module-local mutable state using dynamic predicates, add both *note
     private/1: 145. and *note dynamic/1: 15a. directives for each
     dynamic predicate.

  9. If your module declares or defines clauses for multifile module
     predicates, replace the ‘(:)/2’ functor by ‘(::)/2’ in the
     ‘multifile/1’ directives and in the clause heads for all modules
     defining the multifile predicates that are also being converted
     into objects; if that is not the case, just keep the ‘multifile/1’
     directives and the clause heads as-is.

  10. Compile the resulting objects with the Logtalk *note
     unknown_predicates: 2c1, and *note portability: 1d1. flags set to
     ‘warning’ to help you locate possible issues and calls to
     proprietary Prolog built-in predicates and to predicates defined on
     other converted modules.  In order to improve code portability,
     check the Logtalk library for possible alternatives to the use of
     proprietary Prolog built-in predicates.

Before converting your modules to objects, you may try to compile them
first as objects (using the *note logtalk_compile/1: 29e. Logtalk
built-in predicates) to help identify any issues that must be dealt with
when doing the conversion to objects.  Note that Logtalk supports
compiling Prolog files as Logtalk source code without requiring changes
to the file name extensions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiling Prolog modules as objects,  Next: Dealing with proprietary Prolog directives and predicates,  Prev: Converting Prolog modules into objects,  Up: Prolog integration and migration

1.21.4 Compiling Prolog modules as objects
------------------------------------------

A possible alternative to porting Prolog code to Logtalk is to compile
the Prolog source files using the ‘logtalk_load/1-2’ and
‘logtalk_compile/1-2’ predicates.  The Logtalk compiler provides partial
support for compiling Prolog modules as Logtalk objects.  This support
may allow using modules from a backend Prolog system in a different
backend Prolog system, although its main purpose is to help in porting
existing Prolog code to Logtalk in order to benefit from its extended
language features and its developer tools.  Why partial support?
Although there is an ISO Prolog standard for modules, it is (rightfully)
ignored by most implementers and vendors (due to its flaws and deviation
from common practice).  In addition, there is no de facto standard for
module systems, despite otherwise frequent misleading claims.  Key
system differences include the set of implemented module directives, the
directive semantics, the handling of operators, the locality of flags,
and the integration of term-expansion mechanisms (when provided).
Another potential issue is that, when compiling modules as objects,
Logtalk assumes that any referenced module (e.g., using ‘use_module/1-2’
directives) is also being compiled as an object.  If that’s not the
case, the compiled module calls being compiled as message-sending goals
will still work for normal predicates but will not work for
meta-predicates called using implicit module qualification.  The reason
is that, unlike in Logtalk, calls to implicitly and explicitly qualified
module meta-predicates have different semantics.  Follows a discussion
of other limitations of this approach that you should be aware of.

* Menu:

* Supported module directives::
* Unsupported module directives::
* Modules using a term-expansion mechanism::
* File search paths::


File: TheLogtalkHandbook-3.96.0.info,  Node: Supported module directives,  Next: Unsupported module directives,  Up: Compiling Prolog modules as objects

1.21.4.1 Supported module directives
....................................

Currently, Logtalk supports the following module directives:

‘module/1’

     The module name becomes the object name.

‘module/2’

     The module name becomes the object name.  The exported predicates
     become public object predicates.  The exported grammar rule
     non-terminals become public grammar rule non-terminals.  The
     exported operators become public object operators but are not
     active elsewhere when loading the code.

‘use_module/2’

     This directive is compiled as a Logtalk *note uses/2: 4b. directive
     in order to ensure correct compilation of the module predicate
     clauses.  The first argument of this directive must be the module
     'name' (an atom), not a module file specification (the adapter
     files attempt to use the Prolog dialect level term-expansion
     mechanism to find the module name from the module file
     specification).  Note that the module is not automatically loaded
     by Logtalk (as it would be when compiling the directive using
     Prolog instead of Logtalk; the programmer may also want the
     specified module to be compiled as an object).  The second argument
     must be a predicate indicator (‘Name/Arity’), a grammar rule
     non-terminal indicator (‘Name//Arity’), a operator declaration, or
     a list of predicate indicators, grammar rule non-terminal
     indicators, and operator declarations.  Predicate aliases can be
     declared using the notation ‘Name/Arity as Alias/Arity’ or, in
     alternative, the notation ‘Name/Arity:Alias/Arity’.  Similar for
     non-terminal aliases.

‘export/1’

     Exported predicates are compiled as public object predicates.  The
     argument must be a predicate indicator (‘Name/Arity’), a grammar
     rule non-terminal indicator (‘Name//Arity’), an operator
     declaration, or a list of predicate indicators, grammar rule
     non-terminal indicators, and operator declarations.

‘reexport/2’

     Reexported predicates are compiled as public object predicates.
     The first argument is the module name.  The second argument must be
     a predicate indicator (‘Name/Arity’), a grammar rule non-terminal
     indicator (‘Name//Arity’), an operator declaration, or a list of
     predicate indicators, grammar rule non-terminal indicators, and
     operator declarations.  Predicate aliases can be declared using the
     notation ‘Name/Arity as Alias/Arity’ or, in alternative, the
     notation ‘Name/Arity:Alias/Arity’.  Similar for non-terminal
     aliases.

‘meta_predicate/1’

     Module meta-predicates become object meta-predicates.  All
     meta-predicates must be declared using the *note meta_predicate/1:
     152. directive using Logtalk syntax for normal arguments and
     meta-arguments.  Note that Prolog module meta-predicates and
     Logtalk meta-predicates don’t share the same explicit-qualification
     calling semantics: in Logtalk, meta-arguments are always called in
     the context of the *note sender: 399.  Moreover, Logtalk is not
     based on the predicate-prefixing mechanism common to most Prolog
     module systems.

A common issue when compiling modules as objects is the use of the atoms
‘dynamic’, ‘discontiguous’, and ‘multifile’ as operators in directives.
For better portability, avoid this usage.  For example, write:

     :- dynamic([foo/1, bar/2]).

instead of:

     :- dynamic foo/1, bar/2.

Another common issue is missing ‘meta_predicate/1’, ‘dynamic/1’,
‘discontiguous/1’, and ‘multifile/1’ predicate directives.  The Logtalk
compiler supports detection of missing directives (by setting its *note
missing_directives: 2c6. flag to ‘warning’).

When compiling modules as objects, you probably don’t need event support
turned on.  You may use the *note events: 89. compiler flag to ‘deny’ in
the Logtalk compiling and loading built-in methods for a small
performance gain for the compiled code.


File: TheLogtalkHandbook-3.96.0.info,  Node: Unsupported module directives,  Next: Modules using a term-expansion mechanism,  Prev: Supported module directives,  Up: Compiling Prolog modules as objects

1.21.4.2 Unsupported module directives
......................................

The ‘reexport/1’ and ‘use_module/1’ directives are not directly
supported by the Logtalk compiler.  But most Prolog adapter files
provide support for compiling these directives using Logtalk’s first
stage of its *note term-expansion mechanism: cb.  Nevertheless, these
directives can be converted, respectively, into a sequence of ‘:-
use_module/2’ and ‘export/1’ directives and ‘use_module/2’ directives by
finding which predicates exported by the specified modules are
reexported or imported into the module containing the directive.  For
‘use_module/1’ directives, finding the names of the imported predicates
that are actually used is easy.  First, comment out the directive and
compile the file (making sure that the *note unknown_predicates: 2c1.
compiler flag is set to ‘warning’).  Logtalk will print a warning with a
list of predicates that are called but never defined.  Second, use this
list to replace the ‘use_module/1’ directives by ‘use_module/2’
directives.  You should then be able to compile the modified Prolog
module as an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modules using a term-expansion mechanism,  Next: File search paths,  Prev: Unsupported module directives,  Up: Compiling Prolog modules as objects

1.21.4.3 Modules using a term-expansion mechanism
.................................................

Although Logtalk supports *note term and goal expansion mechanisms: cb,
the usage semantics are different from similar mechanisms found in some
Prolog compilers.  In particular, Logtalk does not support defining term
and goal expansions clauses in a source file for expanding the source
file itself.  Logtalk forces a clean separation between expansion
clauses and the source files that will be subject to source-to-source
expansions by using *note hook objects: 39e.  But hook objects also
provide a working solution here when the expansion code is separated
from the code to be expanded.  Logtalk supports using a module as a hook
object as long as its name doesn’t coincide with the name of an object
and that the module uses ‘term_expansion/2’ and ‘goal_expansion/2’
predicates.  Assuming that’s the case, before attempting to compile the
modules as objects, set the default hook object to the module containing
the expansion code.  For example, if the expansions are stored in a
‘system’ module:

     | ?- set_logtalk_flag(hook, system).
     ...

This, however, may not be enough, as expansions may be stored in
multiple modules.  A common example is to use a module named ‘prolog’
for system expansions and to store the user-defined expansions in
‘user’.  The Logtalk library provides a solution for these scenarios.
Using the ‘hook_flows’ library we can select multiple hook objects or
hook modules.  For example, assuming expansions stored on both ‘user’
and ‘system’ modules:

     | ?- logtalk_load(hook_flows(loader)).
     ...

     | ?- set_logtalk_flag(hook, hook_set([user, system])).
     ...

After these queries, we can try to compile the modules and look for
other porting or portability issues.  A well-know issue is Prolog module
term-expansions calling predicates such as ‘prolog_load_context/2’,
which will always fail when it’s the Logtalk compiler instead of the
Prolog compiler loading a source file.  In some of these cases, it may
be possible to rewrite the expansion rules to use the *note
logtalk_load_context/2: 317. predicate instead.


File: TheLogtalkHandbook-3.96.0.info,  Node: File search paths,  Prev: Modules using a term-expansion mechanism,  Up: Compiling Prolog modules as objects

1.21.4.4 File search paths
..........................

Some Prolog systems provide a mechanism for defining file search paths
(this mechanism works differently from Logtalk own support for defining
library path aliases).  When porting Prolog code that defines file
search paths, e.g.  for finding module libraries, it often helps to load
the pristine Prolog application before attempting to compile its source
files as Logtalk source files.  Depending on the Prolog backend, this
may allow the file search paths to be used when compiling modules as
objects that use file directives such as ‘use_module/2’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Dealing with proprietary Prolog directives and predicates,  Next: Calling Prolog module predicates<2>,  Prev: Compiling Prolog modules as objects,  Up: Prolog integration and migration

1.21.5 Dealing with proprietary Prolog directives and predicates
----------------------------------------------------------------

Most Prolog compilers define proprietary, non-standard directives and
predicates that may be used in both plain code and module code.
Non-standard Prolog built-in predicates are usually not problematic, as
Logtalk is usually able to identify and compile them correctly (but see
the notes on built-in meta-predicates for possible caveats).  However,
Logtalk will generate compilation errors on source files containing
proprietary directives unless you first specify how the directives
should be handled.  Several actions are possible on a per-directive
basis: ignoring the directive (i.e., do not copy the directive, although
a goal can be proved as a consequence), rewriting and copying the
directive to the generated Prolog files, or rewriting and recompiling
the resulting directive.  To specify these actions, the adapter files
contain clauses for the internal ‘'$lgt_prolog_term_expansion'/2’
predicate.  For example, assume that a given Prolog compiler defines a
‘comment/2’ directive for predicates using the format:

     :- comment(foo/2, "Brief description of the predicate").

We can rewrite this predicate into a Logtalk ‘info/2’ directive by
defining a suitable clause for the ‘'$lgt_prolog_term_expansion'/2’
predicate:

     '$lgt_prolog_term_expansion'(
             (:- comment(F/A, String)),
             (:- info(F/A, [comment is Atom]))
     ) :-
         atom_codes(Atom, String).

This Logtalk feature can be used to allow compilation of legacy Prolog
code without the need of changing the sources.  When used, it is
advisable to set the *note portability: 1d1. compiler flag to ‘warning’
in order to more easily identify source files that are likely
non-portable across Prolog compilers.

A second example, where a proprietary Prolog directive is discarded
after triggering a side effect:

     '$lgt_prolog_term_expansion'(
             (:- load_foreign_files(Files,Libs,InitRoutine)),
             []
     ) :-
         load_foreign_files(Files,Libs,InitRoutine).

In this case, although the directive is not copied to the generated
Prolog file, the foreign library files are loaded as a side effect of
the Logtalk compiler calling the ‘'$lgt_prolog_term_expansion'/2’ hook
predicate.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling Prolog module predicates<2>,  Next: Loading converted Prolog applications,  Prev: Dealing with proprietary Prolog directives and predicates,  Up: Prolog integration and migration

1.21.6 Calling Prolog module predicates
---------------------------------------

Prolog module predicates can be called from within objects or categories
by simply using explicit module qualification, i.e.  by writing
‘Module:Goal’ or ‘Goal@Module’ (depending on the module system).
Logtalk also supports the use of ‘use_module/2’ directives in objects
and categories (with the restriction that the first argument of the
directive must be the actual module name and not the module file name or
the module file path).  In this case, these directives are parsed in a
similar way to Logtalk *note uses/2: 4b. directives, with calls to the
specified module predicates being automatically translated to
‘Module:Goal’ calls.

As a general rule, the Prolog modules should be loaded (e.g., in the
auxiliary Logtalk loader files) 'before' compiling objects that make use
of module predicates.  Moreover, the Logtalk compiler does not generate
code for the automatic loading of modules referenced in ‘use_module/1-2’
directives.  This is a consequence of the lack of standardization of
these directives, whose first argument can be a module name, a straight
file name, or a file name using some kind of library notation, depending
on the *note backend Prolog compiler: 34.  Worse, modules are sometimes
defined in files with names different from the module names, requiring
finding, opening, and reading the file in order to find the actual
module name.

Logtalk allows you to send a message to a module in order to call one of
its predicates.  This is usually not advised as it implies a performance
penalty when compared to just using the ‘Module:Call’ notation.
Moreover, this works only if there is no object with the same name as
the module you are targeting.  This feature is necessary, however, in
order to properly support the compilation of modules containing
‘use_module/2’ directives as objects.  If the modules specified in the
‘use_module/2’ directives are not compiled as objects but are instead
loaded as-is by Prolog, the exported predicates would need to be called
using the ‘Module:Call’ notation but the converted module will be
calling them through message-sending.  Thus, this feature ensures that,
on a module compiled as an object, any predicate calling other module
predicates will work as expected, either these other modules are loaded
as-is or also compiled as objects.

For more details, see the *note Calling Prolog predicates: 3e. section.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading converted Prolog applications,  Prev: Calling Prolog module predicates<2>,  Up: Prolog integration and migration

1.21.7 Loading converted Prolog applications
--------------------------------------------

Logtalk strongly favors and advises users to provide a main *note loader
file: 2a4. for applications that explicitly load any required libraries
and the application source files.  In contrast, Prolog applications
often either scatter loading of source files from multiple files or use
implicit loading of source files via ‘use_module/1-2’ directives.  Due
to this frequent ad-hoc approach, it’s common to find Prolog
applications with duplicated loading directives, and where loading order
ignores the dependencies between source files.  These issues are easily
exposed by the Logtalk linter when compiling Prolog files as Logtalk
files.  Also common are Prolog files with multiple circular
dependencies.  While this should not affect the 'semantics' of the
ported code, it may cause some performance penalties as it prevents the
Logtalk compiler from optimizing the message sending goals using
static-binding.  It also makes the application architecture more
difficult to understand.  The definition of explicit loader files
provides a good opportunity for sorting out loading order and circular
dependencies, with the linter warnings providing hints for possible code
refactoring to eliminate these issues.  The *note diagrams: 2ed. tool
supports directory and file loading and dependency diagrams that are
also useful in understanding applications architecture.


File: TheLogtalkHandbook-3.96.0.info,  Node: Reference Manual,  Next: Tutorial,  Prev: User Manual,  Up: Top

2 Reference Manual
******************

* Menu:

* Grammar::
* Control constructs::
* Directives: Directives<2>.
* Built-in predicates::
* Built-in methods: Built-in methods<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Grammar,  Next: Control constructs,  Up: Reference Manual

2.1 Grammar
===========

The Logtalk grammar is here described using W3C-style Extended
Backus-Naur Form syntax.  Non-terminal symbols not defined here can be
found in the ISO Prolog Core standard.  Terminal symbols are represented
between double-quotes.

* Menu:

* Entities::
* Object definition::
* Category definition::
* Protocol definition::
* Entity relations::
* Entity identifiers::
* Source files: Source files<2>.
* Source file names::
* Terms::
* Directives::
* Clauses and goals::
* Lambda expressions: Lambda expressions<2>.
* Entity properties::
* Predicate properties: Predicate properties<2>.
* Compiler flags: Compiler flags<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Entities,  Next: Object definition,  Up: Grammar

2.1.1 Entities
--------------

     entity ::=
        object
        | category
        | protocol


File: TheLogtalkHandbook-3.96.0.info,  Node: Object definition,  Next: Category definition,  Prev: Entities,  Up: Grammar

2.1.2 Object definition
-----------------------

     object ::=
        begin_object_directive ( object_term )* end_object_directive

     begin_object_directive ::=
        ":- object(" object_identifier ( "," object_relations )? ")."

     end_object_directive ::=
        ":- end_object."

     object_relations ::=
        prototype_relations
        | non_prototype_relations

     prototype_relations ::=
        prototype_relation
        | prototype_relation "," prototype_relations

     prototype_relation ::=
        implements_protocols
        | imports_categories
        | extends_objects

     non_prototype_relations ::=
        non_prototype_relation
        | non_prototype_relation "," non_prototype_relations

     non_prototype_relation ::=
        implements_protocols
        | imports_categories
        | instantiates_classes
        | specializes_classes


File: TheLogtalkHandbook-3.96.0.info,  Node: Category definition,  Next: Protocol definition,  Prev: Object definition,  Up: Grammar

2.1.3 Category definition
-------------------------

     category ::=
        begin_category_directive  ( category_term )* end_category_directive

     begin_category_directive ::=
        ":- category(" category_identifier ( "," category_relations )? ")."

     end_category_directive ::=
        ":- end_category."

     category_relations ::=
        category_relation
        | category_relation "," category_relations

     category_relation ::=
        implements_protocols
        | extends_categories
        | complements_objects


File: TheLogtalkHandbook-3.96.0.info,  Node: Protocol definition,  Next: Entity relations,  Prev: Category definition,  Up: Grammar

2.1.4 Protocol definition
-------------------------

     protocol ::=
        begin_protocol_directive  ( protocol_directive )* end_protocol_directive

     begin_protocol_directive ::=
        ":- protocol(" protocol_identifier ( "," extends_protocols)? ")."

     end_protocol_directive ::=
        ":- end_protocol."


File: TheLogtalkHandbook-3.96.0.info,  Node: Entity relations,  Next: Entity identifiers,  Prev: Protocol definition,  Up: Grammar

2.1.5 Entity relations
----------------------

     extends_protocols ::=
        "extends(" extended_protocols ")"

     extends_objects ::=
        "extends(" extended_objects ")"

     extends_categories ::=
        "extends(" extended_categories ")"

     implements_protocols ::=
        "implements(" implemented_protocols ")"

     imports_categories ::=
        "imports(" imported_categories ")"

     instantiates_classes ::=
        "instantiates(" instantiated_objects ")"

     specializes_classes ::=
        "specializes(" specialized_objects ")"

     complements_objects ::=
        "complements(" complemented_objects ")"

* Menu:

* Implemented protocols::
* Extended protocols::
* Imported categories::
* Extended objects::
* Extended categories::
* Instantiated objects::
* Specialized objects::
* Complemented objects::
* Entity and predicate scope::


File: TheLogtalkHandbook-3.96.0.info,  Node: Implemented protocols,  Next: Extended protocols,  Up: Entity relations

2.1.5.1 Implemented protocols
.............................

     implemented_protocols ::=
        implemented_protocol
        | implemented_protocol_sequence
        | implemented_protocol_list

     implemented_protocol ::=
        protocol_identifier
        | scope "::" protocol_identifier

     implemented_protocol_sequence ::=
        implemented_protocol
        | implemented_protocol "," implemented_protocol_sequence

     implemented_protocol_list ::=
        "[" implemented_protocol_sequence "]"


File: TheLogtalkHandbook-3.96.0.info,  Node: Extended protocols,  Next: Imported categories,  Prev: Implemented protocols,  Up: Entity relations

2.1.5.2 Extended protocols
..........................

     extended_protocols ::=
        extended_protocol
        | extended_protocol_sequence
        | extended_protocol_list

     extended_protocol ::=
        protocol_identifier
        | scope "::" protocol_identifier

     extended_protocol_sequence ::=
        extended_protocol
        |extended_protocol "," extended_protocol_sequence

     extended_protocol_list ::=
        "[" extended_protocol_sequence "]"


File: TheLogtalkHandbook-3.96.0.info,  Node: Imported categories,  Next: Extended objects,  Prev: Extended protocols,  Up: Entity relations

2.1.5.3 Imported categories
...........................

     imported_categories ::=
        imported_category
        | imported_category_sequence
        | imported_category_list

     imported_category ::=
        category_identifier
        | scope "::" category_identifier

     imported_category_sequence ::=
        imported_category
        | imported_category "," imported_category_sequence

     imported_category_list ::=
        "[" imported_category_sequence "]"


File: TheLogtalkHandbook-3.96.0.info,  Node: Extended objects,  Next: Extended categories,  Prev: Imported categories,  Up: Entity relations

2.1.5.4 Extended objects
........................

     extended_objects ::=
        extended_object
        | extended_object_sequence
        | extended_object_list

     extended_object ::=
        object_identifier
        | scope "::" object_identifier

     extended_object_sequence ::=
        extended_object
        | extended_object "," extended_object_sequence

     extended_object_list ::=
        "[" extended_object_sequence "]"


File: TheLogtalkHandbook-3.96.0.info,  Node: Extended categories,  Next: Instantiated objects,  Prev: Extended objects,  Up: Entity relations

2.1.5.5 Extended categories
...........................

     extended_categories ::=
        extended_category
        | extended_category_sequence
        | extended_category_list

     extended_category ::=
        category_identifier
        | scope "::" category_identifier

     extended_category_sequence ::=
        extended_category
        | extended_category "," extended_category_sequence

     extended_category_list ::=
        "[" extended_category_sequence "]"


File: TheLogtalkHandbook-3.96.0.info,  Node: Instantiated objects,  Next: Specialized objects,  Prev: Extended categories,  Up: Entity relations

2.1.5.6 Instantiated objects
............................

     instantiated_objects ::=
        instantiated_object
        | instantiated_object_sequence
        | instantiated_object_list

     instantiated_object ::=
        object_identifier
        | scope "::" object_identifier

     instantiated_object_sequence ::=
        instantiated_object
        | instantiated_object "," instantiated_object_sequence

     instantiated_object_list ::=
        "[" instantiated_object_sequence "]"


File: TheLogtalkHandbook-3.96.0.info,  Node: Specialized objects,  Next: Complemented objects,  Prev: Instantiated objects,  Up: Entity relations

2.1.5.7 Specialized objects
...........................

     specialized_objects ::=
        specialized_object
        | specialized_object_sequence
        | specialized_object_list

     specialized_object ::=
        object_identifier
        | scope "::" object_identifier

     specialized_object_sequence ::=
        specialized_object
        | specialized_object "," specialized_object_sequence

     specialized_object_list ::=
        "[" specialized_object_sequence "]"


File: TheLogtalkHandbook-3.96.0.info,  Node: Complemented objects,  Next: Entity and predicate scope,  Prev: Specialized objects,  Up: Entity relations

2.1.5.8 Complemented objects
............................

     complemented_objects ::=
        object_identifier
        | complemented_object_sequence
        | complemented_object_list

     complemented_object_sequence ::=
        object_identifier
        | object_identifier "," complemented_object_sequence

     complemented_object_list ::=
        "[" complemented_object_sequence "]"


File: TheLogtalkHandbook-3.96.0.info,  Node: Entity and predicate scope,  Prev: Complemented objects,  Up: Entity relations

2.1.5.9 Entity and predicate scope
..................................

     scope ::=
        "public"
        | "protected"
        | "private"


File: TheLogtalkHandbook-3.96.0.info,  Node: Entity identifiers,  Next: Source files<2>,  Prev: Entity relations,  Up: Grammar

2.1.6 Entity identifiers
------------------------

     entity_identifier ::=
        object_identifier
        | protocol_identifier
        | category_identifier

* Menu:

* Object identifiers::
* Category identifiers::
* Protocol identifiers::
* Module identifiers::


File: TheLogtalkHandbook-3.96.0.info,  Node: Object identifiers,  Next: Category identifiers,  Up: Entity identifiers

2.1.6.1 Object identifiers
..........................

     object_identifier ::=
        atom
        | compound


File: TheLogtalkHandbook-3.96.0.info,  Node: Category identifiers,  Next: Protocol identifiers,  Prev: Object identifiers,  Up: Entity identifiers

2.1.6.2 Category identifiers
............................

     category_identifier ::=
        atom
        | compound


File: TheLogtalkHandbook-3.96.0.info,  Node: Protocol identifiers,  Next: Module identifiers,  Prev: Category identifiers,  Up: Entity identifiers

2.1.6.3 Protocol identifiers
............................

     protocol_identifier ::=
        atom


File: TheLogtalkHandbook-3.96.0.info,  Node: Module identifiers,  Prev: Protocol identifiers,  Up: Entity identifiers

2.1.6.4 Module identifiers
..........................

     module_identifier ::=
        atom


File: TheLogtalkHandbook-3.96.0.info,  Node: Source files<2>,  Next: Source file names,  Prev: Entity identifiers,  Up: Grammar

2.1.7 Source files
------------------

     source_file ::=
        ( source_file_content )*

     source_file_content ::=
        source_file_directive
        | clause
        | grammar_rule
        | entity


File: TheLogtalkHandbook-3.96.0.info,  Node: Source file names,  Next: Terms,  Prev: Source files<2>,  Up: Grammar

2.1.8 Source file names
-----------------------

     source_file_name ::=
        atom
        | library_source_file_name

     library_source_file_name ::=
        library_name "(" atom ")"

     library_name ::=
        atom


File: TheLogtalkHandbook-3.96.0.info,  Node: Terms,  Next: Directives,  Prev: Source file names,  Up: Grammar

2.1.9 Terms
-----------

* Menu:

* Object terms::
* Category terms::


File: TheLogtalkHandbook-3.96.0.info,  Node: Object terms,  Next: Category terms,  Up: Terms

2.1.9.1 Object terms
....................

     object_term ::=
        object_directive
        | clause
        | grammar_rule


File: TheLogtalkHandbook-3.96.0.info,  Node: Category terms,  Prev: Object terms,  Up: Terms

2.1.9.2 Category terms
......................

     category_term ::=
        category_directive
        | clause
        | grammar_rule


File: TheLogtalkHandbook-3.96.0.info,  Node: Directives,  Next: Clauses and goals,  Prev: Terms,  Up: Grammar

2.1.10 Directives
-----------------

* Menu:

* Source file directives::
* Conditional compilation directives::
* Object directives: Object directives<2>.
* Category directives: Category directives<2>.
* Protocol directives: Protocol directives<2>.
* Predicate directives::


File: TheLogtalkHandbook-3.96.0.info,  Node: Source file directives,  Next: Conditional compilation directives,  Up: Directives

2.1.10.1 Source file directives
...............................

     source_file_directive ::=
        ":- encoding(" atom ")."
        | ":- set_logtalk_flag(" atom "," nonvar ")."
        | ":- include(" source_file_name ")."
        | prolog_directive


File: TheLogtalkHandbook-3.96.0.info,  Node: Conditional compilation directives,  Next: Object directives<2>,  Prev: Source file directives,  Up: Directives

2.1.10.2 Conditional compilation directives
...........................................

     conditional_compilation_directive ::=
        ":- if(" callable ")."
        | ":- elif(" callable ")."
        | ":- else."
        | ":- endif."


File: TheLogtalkHandbook-3.96.0.info,  Node: Object directives<2>,  Next: Category directives<2>,  Prev: Conditional compilation directives,  Up: Directives

2.1.10.3 Object directives
..........................

     object_directive ::=
        ":- initialization(" callable ")."
        | ":- built_in."
        | ":- threaded."
        | ":- dynamic."
        | ":- info(" entity_info_list ")."
        | ":- set_logtalk_flag(" atom "," nonvar ")."
        | ":- include(" source_file_name ")."
        | ":- uses(" object_alias_list ")."
        | ":- use_module(" module_alias_list ")."
        | conditional_compilation_directive
        | predicate_directive


File: TheLogtalkHandbook-3.96.0.info,  Node: Category directives<2>,  Next: Protocol directives<2>,  Prev: Object directives<2>,  Up: Directives

2.1.10.4 Category directives
............................

     category_directive ::=
        ":- built_in."
        | ":- dynamic."
        | ":- info(" entity_info_list ")."
        | ":- set_logtalk_flag(" atom "," nonvar ")."
        | ":- include(" source_file_name ")."
        | ":- uses(" object_alias_list ")."
        | ":- use_module(" module_alias_list ")."
        | conditional_compilation_directive
        | predicate_directive


File: TheLogtalkHandbook-3.96.0.info,  Node: Protocol directives<2>,  Next: Predicate directives,  Prev: Category directives<2>,  Up: Directives

2.1.10.5 Protocol directives
............................

     protocol_directive ::=
        ":- built_in."
        | ":- dynamic."
        | ":- info(" entity_info_list ")."
        | ":- set_logtalk_flag(" atom "," nonvar ")."
        | ":- include(" source_file_name ")."
        | conditional_compilation_directive
        | predicate_directive


File: TheLogtalkHandbook-3.96.0.info,  Node: Predicate directives,  Prev: Protocol directives<2>,  Up: Directives

2.1.10.6 Predicate directives
.............................

     predicate_directive ::=
        alias_directive
        | synchronized_directive
        | uses_directive
        | use_module_directive
        | scope_directive
        | mode_directive
        | mode_non_terminal_directive
        | meta_predicate_directive
        | meta_non_terminal_directive
        | info_directive
        | dynamic_directive
        | discontiguous_directive
        | multifile_directive
        | coinductive_directive
        | operator_directive

     alias_directive ::=
        ":- alias(" entity_identifier "," alias_directive_resource_list ")."

     synchronized_directive ::=
        ":- synchronized(" synchronized_directive_resource_term ")."

     uses_directive ::=
        ":- uses(" ( object_identifier | parameter_variable ) "," uses_directive_resource_list ")."

     use_module_directive ::=
        ":- use_module(" ( module_identifier | parameter_variable ) "," use_module_directive_resource_list ")."

     scope_directive ::=
        ":- public(" scope_directive_resource_term ")."
        | ":- protected(" scope_directive_resource_term ")."
        | ":- private(" scope_directive_resource_term ")."

     mode_directive ::=
        ":- mode(" predicate_mode_term "," number_of_proofs ")."

     mode_non_terminal_directive ::=
        ":- mode_non_terminal(" non_terminal_mode_term "," number_of_proofs ")."

     meta_predicate_directive ::=
        ":- meta_predicate(" meta_predicate_template_term ")."

     meta_non_terminal_directive ::=
        ":- meta_non_terminal(" meta_non_terminal_template_term ")."

     info_directive ::=
        ":- info(" ( predicate_indicator | non_terminal_indicator ) "," predicate_info_list ")."

     dynamic_directive ::=
        ":- dynamic(" qualified_directive_resource_term ")."

     discontiguous_directive ::=
        ":- discontiguous(" qualified_directive_resource_term ")."

     multifile_directive ::=
        ":- multifile(" qualified_directive_resource_term ")."

     coinductive_directive ::=
        ":- coinductive(" ( predicate_indicator_term | coinductive_predicate_template_term ) ")."

     parameter_variable ::=
        _variable_

     scope_directive_resource_term ::=
        scope_directive_resource
        | scope_directive_resource_sequence
        | scope_directive_resource_list

     scope_directive_resource ::=
        predicate_indicator
        | non_terminal_indicator
        | operator

     scope_directive_resource_sequence ::=
        scope_directive_resource
        | scope_directive_resource "," scope_directive_resource_sequence

     scope_directive_resource_list ::=
        "[" scope_directive_resource_sequence "]"

     entity_resources_list ::=
        predicate_indicator_list
        | operator_list

     predicate_indicator_term ::=
        predicate_indicator
        | predicate_indicator_sequence
        | predicate_indicator_list

     predicate_indicator_sequence ::=
        predicate_indicator
        | predicate_indicator "," predicate_indicator_sequence

     predicate_indicator_list ::=
        "[" predicate_indicator_sequence "]"

     alias_directive_resource_list ::=
        "[" alias_directive_resource_sequence "]"

     alias_directive_resource_sequence ::=
        alias_directive_resource
        | alias_directive_resource "," alias_directive_resource_sequence

     alias_directive_resource ::=
        predicate_indicator_alias
        | non_terminal_indicator_alias

     synchronized_directive_resource_term ::=
        synchronized_directive_resource
        | synchronized_directive_resource_sequence
        | synchronized_directive_resource_list

     synchronized_directive_resource ::=
        predicate_indicator
        | non_terminal_indicator

     synchronized_directive_resource_sequence ::=
        synchronized_directive_resource
        | synchronized_directive_resource "," synchronized_directive_resource_sequence

     synchronized_directive_resource_list ::=
        "[" synchronized_directive_resource_sequence "]"

     uses_directive_resource_list ::=
        "[" uses_directive_resource_sequence "]"

     uses_directive_resource_sequence ::=
        uses_directive_resource
        | uses_directive_resource "," uses_directive_resource_sequence

     uses_directive_resource ::=
        predicate_indicator
        | non_terminal_indicator
        | predicate_template_alias
        | operator

     use_module_directive_resource_list ::=
        "[" use_module_directive_resource_sequence "]"

     use_module_directive_resource_sequence ::=
        use_module_directive_resource
        | use_module_directive_resource "," use_module_directive_resource_sequence

     use_module_directive_resource ::=
        predicate_indicator
        | non_terminal_indicator
        | predicate_template_alias
        | operator

     qualified_directive_resource_term ::=
        qualified_directive_resource
        | qualified_directive_resource_sequence
        | qualified_directive_resource_list

     qualified_directive_resource_sequence ::=
        qualified_directive_resource
        | qualified_directive_resource "," qualified_directive_resource_sequence

     qualified_directive_resource_list ::=
        "[" qualified_directive_resource_sequence "]"

     qualified_directive_resource ::=
        predicate_indicator
        | non_terminal_indicator
        | object_identifier "::" ( predicate_indicator | non_terminal_indicator)
        | category_identifier "::" ( predicate_indicator | non_terminal_indicator)
        | module_identifier ":" ( predicate_indicator | non_terminal_indicator)

     predicate_indicator_alias ::=
        predicate_indicator "as" predicate_indicator

     predicate_template_alias ::=
        callable "as" callable

     non_terminal_indicator ::=
        functor "//" arity

     non_terminal_indicator_alias ::=
        non_terminal_indicator "as" non_terminal_indicator

     operator_sequence ::=
        operator specification
        | operator specification "," operator_sequence

     operator_list ::=
        "[" operator_sequence "]"

     coinductive_predicate_template_term ::=
        coinductive_predicate_template
        | coinductive_predicate_template_sequence
        | coinductive_predicate_template_list

     coinductive_predicate_template_sequence ::=
        coinductive_predicate_template
        | coinductive_predicate_template "," coinductive_predicate_template_sequence

     coinductive_predicate_template_list ::=
        "[" coinductive_predicate_template_sequence "]"

     coinductive_predicate_template ::=
        atom "(" coinductive_mode_terms ")"

     coinductive_mode_terms ::=
        coinductive_mode_term
        | coinductive_mode_terms "," coinductive_mode_terms

     coinductive_mode_term ::=
        "+"
        | "-"

     predicate_mode_term ::=
        atom "(" mode_terms ")"

     non_terminal_mode_term ::=
        atom "(" mode_terms ")"

     mode_terms ::=
        mode_term
        |mode_term "," mode_terms

     mode_term ::=
        "@"  type?
        | "+" type?
        | "-" type?
        | "?" type?
        | "++" type?
        | "--" type?

     type ::=
        prolog_type | logtalk_type | user_defined_type

     prolog_type ::=
        "term"
        | "nonvar"
        | "var"
        | "compound"
        | "ground"
        | "callable"
        | "list"
        | "atomic"
        | "atom"
        | "number"
        | "integer"
        | "float"

     logtalk_type ::=
        "object"
        | "category"
        | "protocol"
        | "event"

     user_defined_type ::=
        atom
        | compound

     number_of_proofs ::=
        "zero"
        | "zero_or_one"
        | "zero_or_more"
        | "one"
        | "one_or_more"
        | "zero_or_error"
        | "one_or_error"
        | "zero_or_one_or_error"
        | "zero_or_more_or_error"
        | "one_or_more_or_error"
        | "error"

     meta_predicate_template_term ::=
        meta_predicate_template
        | meta_predicate_template_sequence
        | meta_predicate_template_list

     meta_predicate_template_sequence ::=
        meta_predicate_template
        | meta_predicate_template "," meta_predicate_template_sequence

     meta_predicate_template_list ::=
        "[" meta_predicate_template_sequence "]"

     meta_predicate_template ::=
        object_identifier "::" atom "(" meta_predicate_specifiers ")"
        | category_identifier "::" atom "(" meta_predicate_specifiers ")"
        | module_identifier ":" atom "(" meta_predicate_specifiers ")"
        | atom "(" meta_predicate_specifiers ")"

     meta_predicate_specifiers ::=
        meta_predicate_specifier
        | meta_predicate_specifier "," meta_predicate_specifiers

     meta_predicate_specifier ::=
        non_negative_integer
        | "::"
        | "^"
        | "*"

     meta_non_terminal_template_term ::=
        meta_predicate_template_term

     entity_info_list ::=
        "[" entity_info_sequence? "]"

     entity_info_sequence ::=
        entity_info_item "is" nonvar
        | entity_info_item "is" nonvar "," entity_info_sequence

     entity_info_item ::=
        "comment"
        | "remarks"
        | "author"
        | "version"
        | "date"
        | "copyright"
        | "license"
        | "parameters"
        | "parnames"
        | "see_also"
        | atom

     predicate_info_list ::=
        "[" predicate_info_sequence? "]"

     predicate_info_sequence ::=
        predicate_info_item "is" nonvar
        | predicate_info_item "is" nonvar "," predicate_info_sequence

     predicate_info_item ::=
        "comment"
        | "remarks"
        | "arguments"
        | "argnames"
        | "redefinition"
        | "allocation"
        | "examples"
        | "exceptions"
        | "see_also"
        | atom

     object_alias_list ::=
        "[" object_alias_sequence "]"

     object_alias_sequence ::=
        object_alias
        | object_alias "," object_alias_sequence

     object_alias ::=
        object_identifier "as" object_identifier

     module_alias_list ::=
        "[" module_alias_sequence "]"

     module_alias_sequence ::=
        module_alias
        | module_alias "," module_alias_sequence

     module_alias ::=
        module_identifier "as" module_identifier


File: TheLogtalkHandbook-3.96.0.info,  Node: Clauses and goals,  Next: Lambda expressions<2>,  Prev: Directives,  Up: Grammar

2.1.11 Clauses and goals
------------------------

     clause ::=
        object_identifier "::" head ":-" body
        | module_identifier ":" head ":-" body
        | head ":-" body
        | object_identifier "::" fact
        | module_identifier ":" fact
        | fact

     goal ::=
        message_sending
        | super_call
        | external_call
        | context_switching_call
        | callable

     message_sending ::=
        message_to_object
        | message_delegation
        | message_to_self

     message_to_object ::=
        receiver "::" messages

     message_delegation ::=
        "[" message_to_object "]"

     message_to_self ::=
        "::" messages

     super_call ::=
        "^^" message

     messages ::=
        message
        | "(" message "," messages ")"
        | "(" message ";" messages ")"
        | "(" message "->" messages ")"

     message ::=
        callable
        | variable

     receiver ::=
        "{" callable "}"
        | object_identifier
        | variable

     external_call ::=
        "{" callable "}"

     context_switching_call ::=
        object_identifier "<<" callable


File: TheLogtalkHandbook-3.96.0.info,  Node: Lambda expressions<2>,  Next: Entity properties,  Prev: Clauses and goals,  Up: Grammar

2.1.12 Lambda expressions
-------------------------

     lambda_expression ::=
        lambda_free_variables "/" lambda_parameters ">>" callable
        | lambda_free_variables "/" callable
        | lambda_parameters ">>" callable

     lambda_free_variables ::=
        "{" variables? "}"

     lambda_parameters ::=
        "[" terms? "]"

     variables ::=
        variable
        | variable "," variables

     terms ::=
        term
        | term "," terms


File: TheLogtalkHandbook-3.96.0.info,  Node: Entity properties,  Next: Predicate properties<2>,  Prev: Lambda expressions<2>,  Up: Grammar

2.1.13 Entity properties
------------------------

     category_property ::=
        "static"
        | "dynamic"
        | "built_in"
        | "file(" atom ")"
        | "file(" atom "," atom ")"
        | "lines(" integer "," integer ")"
        | "directive(" integer "," integer ")"
        | "events"
        | "source_data"
        | "public(" entity_resources_list ")"
        | "protected(" entity_resources_list ")"
        | "private(" entity_resources_list ")"
        | "declares(" predicate_indicator "," predicate_declaration_property_list ")"
        | "defines(" predicate_indicator "," predicate_definition_property_list ")"
        | "includes(" predicate_indicator "," ( object_identifier | category_identifier ) "," predicate_definition_property_list ")"
        | "provides(" predicate_indicator "," ( object_identifier | category_identifier ) "," predicate_definition_property_list ")"
        | "references(" reference "," reference_property_list ")"
        | "alias(" ( object_identifier | module_identifier ) "," entity_alias_property_list ")"
        | "alias(" predicate_indicator "," predicate_alias_property_list ")"
        | "calls(" predicate "," predicate_call_update_property_list ")"
        | "updates(" predicate "," predicate_call_update_property_list ")"
        | "number_of_clauses(" integer ")"
        | "number_of_rules(" integer ")"
        | "number_of_user_clauses(" integer ")"
        | "number_of_user_rules(" integer ")"
        | "debugging"

     object_property ::=
        "static"
        | "dynamic"
        | "built_in"
        | "threaded"
        | "file(" atom ")"
        | "file(" atom "," atom ")"
        | "lines(" integer "," integer ")"
        | "directive(" integer "," integer ")"
        | "context_switching_calls"
        | "dynamic_declarations"
        | "events"
        | "source_data"
        | "complements(" ( "allow" | "restrict" ) ")"
        | "complements"
        | "public(" entity_resources_list ")"
        | "protected(" entity_resources_list ")"
        | "private(" entity_resources_list ")"
        | "declares(" predicate_indicator "," predicate_declaration_property_list ")"
        | "defines(" predicate_indicator "," predicate_definition_property_list ")"
        | "includes(" predicate_indicator "," ( object_identifier | category_identifier ) "," predicate_definition_property_list ")"
        | "provides(" predicate_indicator "," ( object_identifier | category_identifier ) "," predicate_definition_property_list ")"
        | "references(" reference "," reference_property_list ")"
        | "alias(" ( object_identifier | module_identifier ) "," entity_alias_property_list ")"
        | "alias(" predicate_indicator "," predicate_alias_property_list ")"
        | "calls(" predicate "," predicate_call_update_property_list ")"
        | "updates(" predicate "," predicate_call_update_property_list ")"
        | "number_of_clauses(" integer ")"
        | "number_of_rules(" integer ")"
        | "number_of_user_clauses(" integer ")"
        | "number_of_user_rules(" integer ")"
        | "module"
        | "debugging"

     protocol_property ::=
        "static"
        | "dynamic"
        | "built_in"
        | "source_data"
        | "file(" atom ")"
        | "file(" atom "," atom ")"
        | "lines(" integer "," integer ")"
        | "directive(" integer "," integer ")"
        | "public(" entity_resources_list ")"
        | "protected(" entity_resources_list ")"
        | "private(" entity_resources_list ")"
        | "declares(" predicate_indicator "," predicate_declaration_property_list ")"
        | "alias(" predicate_indicator "," predicate_alias_property_list ")"
        | "debugging"

     predicate_declaration_property_list ::=
        "[" predicate_declaration_property_sequence "]"

     predicate_declaration_property_sequence ::=
        predicate_declaration_property
        | predicate_declaration_property "," predicate_declaration_property_sequence

     predicate_declaration_property ::=
        "static"
        | "dynamic"
        | "scope(" scope ")"
        | "private"
        | "protected"
        | "public"
        | "coinductive"
        | "multifile"
        | "synchronized"
        | "meta_predicate(" meta_predicate_template ")"
        | "coinductive(" coinductive_predicate_template ")"
        | "non_terminal(" non_terminal_indicator ")"
        | "include(" atom ")"
        | "lines(" integer  "," integer ")"
        | "line_count(" integer ")"
        | "mode(" predicate_mode_term "," number_of_proofs ")"
        | "info(" list ")"

     predicate_definition_property_list ::=
        "[" predicate_definition_property_sequence "]"

     predicate_definition_property_sequence ::=
        predicate_definition_property
        | predicate_definition_property "," predicate_definition_property_sequence

     predicate_definition_property ::=
        "inline"
        | "auxiliary"
        | "non_terminal(" non_terminal_indicator ")"
        | "include(" atom ")"
        | "lines(" integer  "," integer ")"
        | "line_count(" integer ")"
        | "number_of_clauses(" integer ")"
        | "number_of_rules(" integer ")"

     entity_alias_property_list ::=
        "[" entity_alias_property_sequence "]"

     entity_alias_property_sequence ::=
        entity_alias_property
        | entity_alias_property "," entity_alias_property_sequence

     entity_alias_property ::=
        "object"
        | "module"
        | "for(" ( object_identifier | module_identifier ) ")"
        | "include(" atom ")"
        | "lines(" integer  "," integer ")"
        | "line_count(" integer ")"

     predicate_alias_property_list ::=
        "[" predicate_alias_property_sequence "]"

     predicate_alias_property_sequence ::=
        predicate_alias_property
        | predicate_alias_property "," predicate_alias_property_sequence

     predicate_alias_property ::=
        "predicate"
        | "for(" predicate_indicator ")"
        | "from(" entity_identifier ")"
        | "non_terminal(" non_terminal_indicator ")"
        | "include(" atom ")"
        | "lines(" integer  "," integer ")"
        | "line_count(" integer ")"

     predicate ::=
        predicate_indicator
        | "^^" predicate_indicator
        | "::" predicate_indicator
        | ( variable | object_identifier ) "::" predicate_indicator
        | ( variable | module_identifier ) ":" predicate_indicator

     predicate_call_update_property_list ::=
        "[" predicate_call_update_property_sequence "]"

     predicate_call_update_property_sequence ::=
        predicate_call_update_property
        | predicate_call_update_property "," predicate_call_update_property_sequence

     predicate_call_update_property ::=
        "caller(" predicate_indicator ")"
        | "include(" atom ")"
        | "lines(" integer  "," integer ")"
        | "line_count(" integer ")"
        | "alias(" predicate_indicator ")"
        | "non_terminal(" non_terminal_indicator ")"

     reference ::=
        object_identifier | category_identifier
        | ( object_identifier | category_identifier ) "::" predicate_indicator

     reference_property_list ::=
        "in(" ( "multifile" | "dynamic" | "discontiguous" | "meta_predicate" | "meta_non_terminal" | "clause" ) ")"
        | "include(" atom ")"
        | "lines(" integer  "," integer ")"
        | "line_count(" integer ")"
        | "non_terminal(" non_terminal_indicator ")"


File: TheLogtalkHandbook-3.96.0.info,  Node: Predicate properties<2>,  Next: Compiler flags<2>,  Prev: Entity properties,  Up: Grammar

2.1.14 Predicate properties
---------------------------

     predicate_property ::=
        "static"
        | "dynamic"
        | "scope(" scope ")"
        | "private"
        | "protected"
        | "public"
        | "logtalk"
        | "prolog"
        | "foreign"
        | "coinductive(" coinductive_predicate_template ")"
        | "multifile"
        | "synchronized"
        | "built_in"
        | "inline"
        | "recursive"
        | "declared_in(" entity_identifier ")"
        | "defined_in(" ( object_identifier | category_identifier ) ")"
        | "redefined_from(" ( object_identifier | category_identifier ) ")"
        | "meta_predicate(" meta_predicate_template ")"
        | "alias_of(" callable ")"
        | "alias_declared_in(" entity_identifier ")"
        | "non_terminal(" non_terminal_indicator ")"
        | "mode(" predicate_mode_term "," number_of_proofs ")"
        | "info(" list ")"
        | "number_of_clauses(" integer ")"
        | "number_of_rules(" integer ")"
        | "declared_in(" entity_identifier "," line_count ")"
        | "defined_in(" ( object_identifier | category_identifier ) "," line_count ")"
        | "redefined_from(" ( object_identifier | category_identifier ) "," line_count ")"
        | "alias_declared_in(" entity_identifier "," line_count ")"

     line_count ::=
        integer


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiler flags<2>,  Prev: Predicate properties<2>,  Up: Grammar

2.1.15 Compiler flags
---------------------

     compiler_flag ::=
        flag "(" flag_value ")"


File: TheLogtalkHandbook-3.96.0.info,  Node: Control constructs,  Next: Directives<2>,  Prev: Grammar,  Up: Reference Manual

2.2 Control constructs
======================

* Menu:

* Message sending: Message sending<2>.
* Message delegation::
* Calling imported and inherited predicates: Calling imported and inherited predicates<2>.
* Calling predicates in this::
* Calling external predicates::
* Context switching calls::


File: TheLogtalkHandbook-3.96.0.info,  Node: Message sending<2>,  Next: Message delegation,  Up: Control constructs

2.2.1 Message sending
---------------------

'control construct'

* Menu:

* (;;)/2: /2.
* (;;)/1: /1.


File: TheLogtalkHandbook-3.96.0.info,  Node: /2,  Next: /1,  Up: Message sending<2>

2.2.1.1 ‘(::)/2’
................

* Menu:

* Description::
* Modes and number of proofs::
* Errors::
* Examples: Examples<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description,  Next: Modes and number of proofs,  Up: /2

2.2.1.2 Description
...................

     Object::Message
     {Proxy}::Message

Sends a message to an object.  The message argument must match a *note
public: 143. predicate of the receiver object.  When the message
corresponds to a *note protected: 144. or *note private: 145. predicate,
the call is only valid if the *note sender: 399. matches the *note
predicate scope container: 3f9.  When the predicate is declared but not
defined, the message simply fails (as per the *note closed-world
assumption: 6a.).

When the predicate used to answer the message is a *note meta-predicate:
52, the *note calling context: 150. for the predicate meta-arguments is
the object sending the message.

The ‘{Proxy}::Message’ syntax allows simplified access to *note
parametric object proxies: 3fa.  Its operational semantics is equivalent
to the conjunction ‘(call(Proxy), Proxy::Message)’.  I.e.  ‘Proxy’ is
proved within the context of the pseudo-object *note user: cf. and, if
successful, the ‘Proxy’ term is used as an object identifier.
Exceptions thrown when proving ‘Proxy’ are handled by the ‘(::)/2’
control construct.  This control construct supports backtracking over
the ‘{Proxy}’ goal.

The lookups for the message declaration and the corresponding method are
performed using a depth-first strategy.  Depending on the value of the
*note optimize: 8c. flag, these lookups are performed at compile-time
whenever sufficient information is available.  When the lookups are
performed at runtime, a caching mechanism is used to improve performance
for subsequent messages.  See the User Manual section on *note
performance: 38. for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs,  Next: Errors,  Prev: Description,  Up: /2

2.2.1.3 Modes and number of proofs
..................................

     +object_identifier::+callable - zero_or_more
     {+object_identifier}::+callable - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors,  Next: Examples<2>,  Prev: Modes and number of proofs,  Up: /2

2.2.1.4 Errors
..............

     Either ‘Object’ or ‘Message’ is a variable:
          ‘instantiation_error’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Message’ is neither a variable nor a callable term:
          ‘type_error(callable, Message)’
     ‘Message’, with predicate indicator ‘Name/Arity’, is declared private:
          ‘permission_error(access, private_predicate, Name/Arity)’
     ‘Message’, with predicate indicator ‘Name/Arity’, is declared protected:
          ‘permission_error(access, protected_predicate, Name/Arity)’
     ‘Message’, with predicate indicator ‘Name/Arity’, is not declared:
          ‘existence_error(predicate_declaration, Name/Arity)’
     ‘Object’ does not exist:
          ‘existence_error(object, Object)’
          
     ‘Proxy’ is a variable:
          ‘instantiation_error’
     ‘Proxy’ is neither a variable nor a callable term:
          ‘type_error(callable, Proxy)’
     ‘Proxy’, with predicate indicator ‘Name/Arity’, does not exist in the ‘user’ pseudo-object:
          ‘existence_error(procedure, Name/Arity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<2>,  Prev: Errors,  Up: /2

2.2.1.5 Examples
................

     | ?- list::member(X, [1, 2, 3]).

     X = 1 ;
     X = 2 ;
     X = 3
     yes

See also
........

*note (;;)/1: 5c, *note (^^)/1: 5d, *note []/1: 81.

'control construct'


File: TheLogtalkHandbook-3.96.0.info,  Node: /1,  Prev: /2,  Up: Message sending<2>

2.2.1.6 ‘(::)/1’
................

* Menu:

* Description: Description<2>.
* Modes and number of proofs: Modes and number of proofs<2>.
* Errors: Errors<2>.
* Examples: Examples<3>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<2>,  Next: Modes and number of proofs<2>,  Up: /1

2.2.1.7 Description
...................

     ::Message

Sends a message to *note self: 69.  Can only be used in the body of a
predicate definition.  The argument should match a *note public: 143. or
*note protected: 144. predicate of 'self'.  It may also match a *note
private: 145. predicate if the predicate is within the scope of the
object where the method making the call is defined, if imported from a
category, if used from within a category, or when using private
inheritance.  When the predicate is declared but not defined, the
message simply fails (as per the *note closed-world assumption: 6a.).

When the predicate used to answer the message is a *note meta-predicate:
52, the *note calling context: 150. for the predicate meta-arguments is
the object sending the message.

The lookups for the message declaration and the corresponding method are
performed using a depth-first strategy.  A message to 'self' necessarily
implies the use of *note dynamic binding: 36. but a caching mechanism is
used to improve performance in subsequent messages.  See the User Manual
section on *note performance: 38. for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<2>,  Next: Errors<2>,  Prev: Description<2>,  Up: /1

2.2.1.8 Modes and number of proofs
..................................

     ::+callable - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<2>,  Next: Examples<3>,  Prev: Modes and number of proofs<2>,  Up: /1

2.2.1.9 Errors
..............

     ‘Message’ is a variable:
          ‘instantiation_error’
     ‘Message’ is neither a variable nor a callable term:
          ‘type_error(callable, Message)’
     ‘Message’, with predicate indicator ‘Name/Arity’, is declared private:
          ‘permission_error(access, private_predicate, Name/Arity)’
     ‘Message’, with predicate indicator ‘Name/Arity’, is not declared:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<3>,  Prev: Errors<2>,  Up: /1

2.2.1.10 Examples
.................

     area(Area) :-
         ::width(Width),
         ::height(Height),
         Area is Width * Height.

See also
........

*note (;;)/2: 7e, *note (^^)/1: 5d, *note []/1: 81.


File: TheLogtalkHandbook-3.96.0.info,  Node: Message delegation,  Next: Calling imported and inherited predicates<2>,  Prev: Message sending<2>,  Up: Control constructs

2.2.2 Message delegation
------------------------

'control construct'

* Menu:

* []/1::


File: TheLogtalkHandbook-3.96.0.info,  Node: []/1,  Up: Message delegation

2.2.2.1 ‘[]/1’
..............

* Menu:

* Description: Description<3>.
* Modes and number of proofs: Modes and number of proofs<3>.
* Errors: Errors<3>.
* Examples: Examples<4>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<3>,  Next: Modes and number of proofs<3>,  Up: []/1

2.2.2.2 Description
...................

     [Object::Message]
     [{Proxy}::Message]

This control construct allows the programmer to send a message to an
object while preserving the original sender and meta-call context.  It
is mainly used in the definition of object handlers for unknown
messages.  This functionality is usually known as 'delegation' but be
aware that this is an overloaded word that can mean different things in
different object-oriented programming languages.

To prevent the use of this control construct to break object
encapsulation, an attempt to delegate a message to the original sender
results in an error.  The remaining error conditions are the same as the
*note (;;)/2: 7e. control construct.

Note that, despite the correct functor for this control construct being
(traditionally) ‘'.'/2’, we refer to it as ‘[]/1’ simply to emphasize
that the syntax is a list with a single element.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<3>,  Next: Errors<3>,  Prev: Description<3>,  Up: []/1

2.2.2.3 Modes and number of proofs
..................................

     [+object_identifier::+callable] - zero_or_more
     [{+object_identifier}::+callable] - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<3>,  Next: Examples<4>,  Prev: Modes and number of proofs<3>,  Up: []/1

2.2.2.4 Errors
..............

     ‘Object’ is a variable:
          ‘instantiation_error’
     Object is neither a variable nor an object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Object’ does not exist:
          ‘existence_error(object, Object)’
     ‘Object’ and the original 'sender' are the same object:
          ‘permission_error(access, object, Sender)’
          
     ‘Proxy’ is a variable:
          ‘instantiation_error’
     ‘Proxy’ is neither a variable nor an object identifier:
          ‘type_error(object_identifier, Proxy)’
     ‘Proxy’, with predicate indicator ‘Name/Arity’, does not exist in the ‘user’ pseudo-object:
          ‘existence_error(procedure, Name/Arity)’
          
     ‘Message’ is a variable:
          ‘instantiation_error’
     ‘Message’ is neither a variable nor a callable term:
          ‘type_error(callable, Message)’
     ‘Message’, with predicate indicator ‘Name/Arity’, is declared private:
          ‘permission_error(access, private_predicate, Name/Arity)’
     ‘Message’, with predicate indicator ‘Name/Arity’, is declared protected:
          ‘permission_error(access, protected_predicate, Name/Arity)’
     ‘Message’, with predicate indicator ‘Name/Arity’, is not declared:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<4>,  Prev: Errors<3>,  Up: []/1

2.2.2.5 Examples
................

     % delegate unknown messages to the "backup" object:
     forward(Message) :-
         [backup::Message].

See also
........

*note (;;)/2: 7e, *note (;;)/1: 5c, *note (^^)/1: 5d, *note forward/1:
105.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling imported and inherited predicates<2>,  Next: Calling predicates in this,  Prev: Message delegation,  Up: Control constructs

2.2.3 Calling imported and inherited predicates
-----------------------------------------------

'control construct'

* Menu:

* (^^)/1: ^^ /1.


File: TheLogtalkHandbook-3.96.0.info,  Node: ^^ /1,  Up: Calling imported and inherited predicates<2>

2.2.3.1 ‘(^^)/1’
................

* Menu:

* Description: Description<4>.
* Modes and number of proofs: Modes and number of proofs<4>.
* Errors: Errors<4>.
* Examples: Examples<5>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<4>,  Next: Modes and number of proofs<4>,  Up: ^^ /1

2.2.3.2 Description
...................

     ^^Predicate

Calls an imported or inherited predicate definition.  The call fails if
the predicate is declared but there is no imported or inherited
predicate definition (as per the *note closed-world assumption: 6a.).
This control construct may be used within objects or categories in the
body of a predicate definition.

This control construct preserves the implicit execution context *note
self: 69. and *note sender: 399. arguments (plus the meta-call context
and coinduction stack when applicable) when calling the inherited (or
imported) predicate definition.

The lookups for the predicate declaration and the predicate definition
are performed using a depth-first strategy.  Depending on the value of
the *note optimize: 8c. flag, these lookups are performed at
compile-time when the predicate is static and sufficient information is
available.  When the lookups are performed at runtime, a caching
mechanism is used to improve performance in subsequent calls.  See the
User Manual section on *note performance: 38. for details.

When the call is made from within an object, the lookup for the
predicate definition starts at the imported categories, if any.  If an
imported predicate definition is not found, the lookup proceeds to the
ancestor objects.  Calls from predicates defined in complementing
categories lookup inherited definitions as if the calls were made from
the complemented object, thus allowing more comprehensive object
patching.  For other categories, the predicate definition lookup is
restricted to the extended categories.

The called predicate should be declared *note public: 143. or *note
protected: 144.  It may also be declared *note private: 145. if within
the scope of the entity where the method making the call is defined.

This control construct is a generalization of the Smalltalk 'super'
keyword to take into account Logtalk support for prototypes and
categories besides classes.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<4>,  Next: Errors<4>,  Prev: Description<4>,  Up: ^^ /1

2.2.3.3 Modes and number of proofs
..................................

     ^^+callable - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<4>,  Next: Examples<5>,  Prev: Modes and number of proofs<4>,  Up: ^^ /1

2.2.3.4 Errors
..............

     ‘Predicate’ is a variable:
          ‘instantiation_error’
     ‘Predicate’ is neither a variable nor a callable term:
          ‘type_error(callable, Predicate)’
     ‘Predicate’, with predicate indicator ‘Name/Arity’, is declared private:
          ‘permission_error(access, private_predicate, Name/Arity)’
     ‘Predicate’, with predicate indicator ‘Name/Arity’, is not declared:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<5>,  Prev: Errors<4>,  Up: ^^ /1

2.2.3.5 Examples
................

     % specialize the inherited definition
     % of the init/0 predicate:
     init :-
         assertz(counter(0)),
         ^^init.

See also
........

*note (;;)/2: 7e, *note (;;)/1: 5c, *note []/1: 81.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling predicates in this,  Next: Calling external predicates,  Prev: Calling imported and inherited predicates<2>,  Up: Control constructs

2.2.4 Calling predicates in 'this'
----------------------------------

'control construct'

* Menu:

* (@)/1: @ /1.


File: TheLogtalkHandbook-3.96.0.info,  Node: @ /1,  Up: Calling predicates in this

2.2.4.1 ‘(@)/1’
...............

* Menu:

* Description: Description<5>.
* Modes and number of proofs: Modes and number of proofs<5>.
* Errors: Errors<5>.
* Examples: Examples<6>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<5>,  Next: Modes and number of proofs<5>,  Up: @ /1

2.2.4.2 Description
...................

     @Predicate

Calls a predicate definition in *note this: 114.  The argument must be a
callable term at compile-time.  The predicate must be declared (by a
scope directive).  This control construct provides access to predicate
definitions in 'this' from categories.  For example, it allows
overriding a predicate definition from a complementing category with a
new definition that calls goals before and after calling the overridden
definition (the overriding definition is sometimes described in other
programming languages as an 'around method').  When used within an
object, it’s the same as calling its argument.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<5>,  Next: Errors<5>,  Prev: Description<5>,  Up: @ /1

2.2.4.3 Modes and number of proofs
..................................

     @ +callable - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<5>,  Next: Examples<6>,  Prev: Modes and number of proofs<5>,  Up: @ /1

2.2.4.4 Errors
..............

     ‘Predicate’, with predicate indicator ‘Name/Arity’, is not declared:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<6>,  Prev: Errors<5>,  Up: @ /1

2.2.4.5 Examples
................

Assuming an object declaring a ‘make_sound/0’ predicate, define an
'around method' in a complementing category:

     make_sound :-
         write('Started making sound...'), nl,
         @make_sound,
         write('... finished making sound.'), nl.

See also
........

*note (;;)/2: 7e, *note (;;)/1: 5c, *note []/1: 81.


File: TheLogtalkHandbook-3.96.0.info,  Node: Calling external predicates,  Next: Context switching calls,  Prev: Calling predicates in this,  Up: Control constructs

2.2.5 Calling external predicates
---------------------------------

'control construct'

* Menu:

* {}/1::


File: TheLogtalkHandbook-3.96.0.info,  Node: {}/1,  Up: Calling external predicates

2.2.5.1 ‘{}/1’
..............

* Menu:

* Description: Description<6>.
* Modes and number of proofs: Modes and number of proofs<6>.
* Errors: Errors<6>.
* Examples: Examples<7>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<6>,  Next: Modes and number of proofs<6>,  Up: {}/1

2.2.5.2 Description
...................

     {Goal}
     {Closure}
     {Term}

This control construct allows the programmer to bypass the Logtalk
compiler (including its linter but not its optimizer) in multiple
contexts:

   - Calling a goal as-is (from within an object or category) in the
     context of the *note user: cf. pseudo-object.

   - Extending a closure as-is with the remaining arguments of a *note
     call/2-N: 181. call in order to construct a goal that will be
     called within the context of the ‘user’ pseudo-object.

   - Wrapping a source file term (either a clause or a directive) or a
     source file goal to bypass the *note term-expansion mechanism: cb.

   - Using it in place of an object identifier when sending a message.
     In this case, its argument is proved as a goal within the context
     of the ‘user’ pseudo-object with the resulting term being used as
     an object identifier in the message-sending goal.  This feature is
     mainly used with *note parametric objects: 425. when their
     identifiers correspond to predicates defined in ‘user’.

   - Using it as a message to an object.  This is mainly useful when the
     message is a *note conjunction of messages: 84. where some of goals
     are calls to Prolog built-in predicates.

     Note: This control construct is opaque to cuts when used to wrap a
     goal (thus ensuring the same semantics independently of the
     argument being bound at compile-time or at runtime).


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<6>,  Next: Errors<6>,  Prev: Description<6>,  Up: {}/1

2.2.5.3 Modes and number of proofs
..................................

     {+callable} - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<6>,  Next: Examples<7>,  Prev: Modes and number of proofs<6>,  Up: {}/1

2.2.5.4 Errors
..............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
          
     ‘Closure’ is a variable:
          ‘instantiation_error’
     ‘Closure’ is neither a variable nor a callable term:
          ‘type_error(callable, Closure)’
          
     ‘Term’ is a variable:
          ‘instantiation_error’
     ‘Term’ is neither a variable nor a callable term:
          ‘type_error(callable, Term)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<7>,  Prev: Errors<6>,  Up: {}/1

2.2.5.5 Examples
................

     % overload the standard (<)/2 operator by
     % calling its standard built-in definition:
     N1/D1 < N2/D2 :-
         {N1*D2 < N2*D1}.

     % call a closure in the context of "user":
     call_in_user(F, X, Y, Z) :-
         call({F}, X, Y, Z).

     % bypass the compiler for a proprietary backend directive:
     {:- load_foreign_resource(file)}.

     % use parametric object proxies:
     | ?- {circle(Id, Radius, Color)}::area(Area).
     ...

     % use Prolog built-in predicates as messages:
     | ?- logtalk::{write('hello world!'), nl}.
     hello world!
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Context switching calls,  Prev: Calling external predicates,  Up: Control constructs

2.2.6 Context switching calls
-----------------------------

'control construct'

* Menu:

* (<<)/2: << /2.


File: TheLogtalkHandbook-3.96.0.info,  Node: << /2,  Up: Context switching calls

2.2.6.1 ‘(<<)/2’
................

* Menu:

* Description: Description<7>.
* Modes and number of proofs: Modes and number of proofs<7>.
* Errors: Errors<7>.
* Examples: Examples<8>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<7>,  Next: Modes and number of proofs<7>,  Up: << /2

2.2.6.2 Description
...................

     Object<<Goal
     {Proxy}<<Goal

Debugging control construct.  Calls a goal within the context of the
specified object.  The goal is called with the following execution
context:

   - *note sender: 399, *note this: 114, and *note self: 69. values set
     to the object

   - empty meta-call context

   - empty coinduction stack

The goal may need to be written between parenthesis to avoid parsing
errors due to operator conflicts.  This control construct should only be
used for debugging or for writing unit tests.  This control construct
can only be used for objects compiled with the *note
context_switching_calls: 2d9. compiler flag set to ‘allow’.  Set this
compiler flag to ‘deny’ to disable this control construct and thus
prevent using it to break encapsulation when deploying applications.

The ‘{Proxy}<<Goal’ syntax allows simplified access to *note parametric
object proxies: 3fa.  Its operational semantics is equivalent to the
goal conjunction ‘(call(Proxy), Proxy<<Goal)’.  I.e.  ‘Proxy’ is proved
within the context of the pseudo-object *note user: cf. and, if
successful, the goal term is used as a parametric object identifier.
Exceptions thrown when proving ‘Proxy’ are handled by the ‘(<<)/2’
control construct.  This syntax construct supports backtracking over the
‘{Proxy}’ goal.

Caveat: although the goal argument is fully compiled before calling,
some necessary information for the second compiler pass may not be
available at runtime.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<7>,  Next: Errors<7>,  Prev: Description<7>,  Up: << /2

2.2.6.3 Modes and number of proofs
..................................

     +object_identifier<<+callable - zero_or_more
     {+object_identifier}<<+callable - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<7>,  Next: Examples<8>,  Prev: Modes and number of proofs<7>,  Up: << /2

2.2.6.4 Errors
..............

     ‘Object’ is a variable:
          ‘instantiation_error’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Object’ does not contain a local definition for the Goal predicate:
          ‘existence_error(procedure, Goal)’
     ‘Object’ does not exist:
          ‘existence_error(object, Object)’
     ‘Object’ was created/compiled with support for context-switching calls turned off:
          ‘permission_error(access, database, Goal)’
          
     ‘Proxy’ is a variable:
          ‘instantiation_error’
     ‘Proxy’ is neither a variable nor an object identifier:
          ‘type_error(object_identifier, Proxy)’
     The predicate ‘Proxy’ does not exist in the ‘user’ pseudo-object:
          ‘existence_error(procedure, ProxyFunctor/ProxyArity)’
          
     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<8>,  Prev: Errors<7>,  Up: << /2

2.2.6.5 Examples
................

     % call the member/2 predicate in the
     % context of the "list" object:
     test(member) :-
         list << member(1, [1]).


File: TheLogtalkHandbook-3.96.0.info,  Node: Directives<2>,  Next: Built-in predicates,  Prev: Control constructs,  Up: Reference Manual

2.3 Directives
==============

* Menu:

* Source file directives: Source file directives<2>.
* Conditional compilation directives: Conditional compilation directives<2>.
* Entity directives::
* Predicate directives: Predicate directives<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Source file directives<2>,  Next: Conditional compilation directives<2>,  Up: Directives<2>

2.3.1 Source file directives
----------------------------

'directive'

* Menu:

* encoding/1::
* include/1::
* initialization/1::
* op/3::
* set_logtalk_flag/2::


File: TheLogtalkHandbook-3.96.0.info,  Node: encoding/1,  Next: include/1,  Up: Source file directives<2>

2.3.1.1 ‘encoding/1’
....................

* Menu:

* Description: Description<8>.
* Template and modes::
* Examples: Examples<9>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<8>,  Next: Template and modes,  Up: encoding/1

2.3.1.2 Description
...................

     encoding(Encoding)

Declares the source file text encoding.  Requires a *note backend Prolog
compiler: 34. supporting the chosen encoding.  When used, this directive
must be the first term in the source file in the first line.  This
directive is also supported in files included in a main file or in a
dynamically created entity using *note include/1: b8. directives.

The encoding used in a source file (and, in the case of a Unicode
encoding, any BOM present) will be used for the intermediate Prolog file
generated by the compiler.  Logtalk uses the encoding names specified by
IANA(1). In those cases where a preferred MIME name alias is specified,
the alias is used instead.  Examples includes ‘'US-ASCII'’,
‘'ISO-8859-1'’, ‘'ISO-8859-2'’, ‘'ISO-8859-15'’, ‘'UCS-2'’, ‘'UCS-2LE'’,
‘'UCS-2BE'’, ‘'UTF-8'’, ‘'UTF-16'’, ‘'UTF-16LE'’, ‘'UTF-16BE'’,
‘'UTF-32'’, ‘'UTF-32LE'’, ‘'UTF-32BE'’, ‘'Shift_JIS'’, and ‘'EUC-JP'’.
When writing portable code that cannot be expressed using ASCII,
‘'UTF-8'’ is the most commonly supported Unicode encoding.

The backend Prolog compiler adapter files define a table that translates
between the Logtalk and Prolog specific atoms that represent each
supported encoding.  The *note encoding_directive: 299. read-only flag
can be used to find if a backend supports this directive and how.

   ---------- Footnotes ----------

   (1) 
http://www.iana.org/assignments/character-sets/character-sets.xhtml


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes,  Next: Examples<9>,  Prev: Description<8>,  Up: encoding/1

2.3.1.3 Template and modes
..........................

     encoding(+atom)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<9>,  Prev: Template and modes,  Up: encoding/1

2.3.1.4 Examples
................

     :- encoding('UTF-8').

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: include/1,  Next: initialization/1,  Prev: encoding/1,  Up: Source file directives<2>

2.3.1.5 ‘include/1’
...................

* Menu:

* Description: Description<9>.
* Template and modes: Template and modes<2>.
* Examples: Examples<10>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<9>,  Next: Template and modes<2>,  Up: include/1

2.3.1.6 Description
...................

     include(File)

Includes a file contents, which must be valid terms, at the place of
occurrence of the directive.  The file can be specified as a relative
path, an absolute path, or using *note library notation: 2a8. and is
expanded as a source file name.  Relative paths are interpreted as
relative to the path of the file containing the directive.  The file
extension is optional (the recognized Logtalk and Prolog file extensions
are defined in the *note backend adapter files: 154.).

When using the *note reflection API: 48, predicates from an included
file can be distinguished from predicates from the main file by looking
for the ‘include/1’ predicate declaration property or the ‘include/1’
predicate definition property.  For the included predicates, the
‘line_count/1’ property stores the term line number in the included
file.

This directive can be used as either a source file directive or an
entity directive.  As an entity directive, it can be used both in
entities defined in source files and with the entity creation built-in
predicates.  In the latter case, the file should be specified using an
absolute path or using library notation (which expands to a full path)
to avoid a fragile dependency on the current working directory.

Included files may contain an *note encoding/1: 298. directive, which
may specify the same encoding of the main file or a different encoding.

     Warning: When using this directive as an argument in calls to the
     *note create_object/4: 62, *note create_category/4: 11a, and *note
     create_protocol/3: e3. built-in predicates, the objects,
     categories, and protocols will not be recreated or redefined when
     the included file(s) are modified and the *note logtalk_make/0:
     29f. predicate or the *note logtalk_make/1: 2a0. (with target
     ‘all’) predicates are called.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<2>,  Next: Examples<10>,  Prev: Description<9>,  Up: include/1

2.3.1.7 Template and modes
..........................

     include(@source_file_name)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<10>,  Prev: Template and modes<2>,  Up: include/1

2.3.1.8 Examples
................

     % include the "raw_1.txt" text file found
     % on the "data" library directory:
     :- include(data('raw_1.txt')).

     % include a "factbase.pl" file in the same directory
     % of the source file containing the directive:
     :- include('factbase.pl').

     % include a file given its absolute path:
     :- include('/home/me/databases/countries.pl').

     % create a wrapper object for a Prolog file using
     % library notation to define the file path:
     | ?- create_object(cities, [], [public(city/4), include(geo('cities.pl'))], []).

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: initialization/1,  Next: op/3,  Prev: include/1,  Up: Source file directives<2>

2.3.1.9 ‘initialization/1’
..........................

* Menu:

* Description: Description<10>.
* Template and modes: Template and modes<3>.
* Examples: Examples<11>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<10>,  Next: Template and modes<3>,  Up: initialization/1

2.3.1.10 Description
....................

     initialization(Goal)

When used within an object, this directive defines a goal to be called
after the object has been successfully loaded into memory.  When used at
a global level within a source file, this directive defines a goal to be
called after the source file is successfully compiled and loaded into
memory.

The loading context can be accessed from this directive by calling the
*note logtalk_load_context/2: 317. predicate.  Note that the usable
loading context keys depend on the directive scope (file or object).

Multiple initialization directives can be used in a source file or in an
object.  Their goals will be called in the same order as the directives
at loading time.

     Note: Arbitrary goals cannot be used as directives in source files.
     Any goal that should be automatically called when a source file is
     loaded must be wrapped using this directive.

     Categories and protocols cannot contain ‘initialization/1’
     directives as the initialization goals would lack a complete *note
     execution context: 35e. that is only available for objects.

Although technically a global ‘initialization/1’ directive in a source
file is a Prolog directive, calls to Logtalk built-in predicates from it
are usually compiled to improve portability, improve performance, and
provide better support for embedded applications.

     Warning: Some backend Prolog compilers declare the atom
     ‘initialization’ as an operator for a lighter syntax.  But this
     makes the code non-portable and is therefore a practice best
     avoided.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<3>,  Next: Examples<11>,  Prev: Description<10>,  Up: initialization/1

2.3.1.11 Template and modes
...........................

     initialization(@callable)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<11>,  Prev: Template and modes<3>,  Up: initialization/1

2.3.1.12 Examples
.................

     % call the init/0 predicate after loading the
     % source file containing the directive

     :- initialization(init).

     % print a debug message after loading a
     % source file defining an object

     :- object(log).

         :- initialization(start_date).

         start_date :-
             os::date_time(Year, Month, Day, _, _, _, _),
             logtalk::print_message(debug, my_app, 'Starting date: ~d-~d-~d~n'+[Year,Month,Day]).

     :- end_object.

See also
........

*note logtalk_load_context/2: 317.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: op/3,  Next: set_logtalk_flag/2,  Prev: initialization/1,  Up: Source file directives<2>

2.3.1.13 ‘op/3’
...............

* Menu:

* Description: Description<11>.
* Template and modes: Template and modes<4>.
* Examples: Examples<12>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<11>,  Next: Template and modes<4>,  Up: op/3

2.3.1.14 Description
....................

     op(Precedence, Associativity, Operator)
     op(Precedence, Associativity, [Operator, ...])

Declares operators.  Global operators can be declared inside a source
file by writing the respective directives before the entity opening
directives.  Operators declared inside entities have local scope.  Calls
to the standard term input and output predicates take into account any
locally defined operators.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<4>,  Next: Examples<12>,  Prev: Description<11>,  Up: op/3

2.3.1.15 Template and modes
...........................

     op(+integer, +associativity, +atom_or_atom_list)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<12>,  Prev: Template and modes<4>,  Up: op/3

2.3.1.16 Examples
.................

Some of the predicate argument instantiation mode operators used by
Logtalk:

     :- op(200, fy, +).
     :- op(200, fy, ?).
     :- op(200, fy, @).
     :- op(200, fy, -).

An example of using entity local operators.  Consider the following
‘ops.lgt’ file:

     :- initialization((write(<=>(1,2)), nl)).

     :- object(ops).

         :- op(700, xfx, <=>).

         :- public(w/1).
         w(Term) :-
             write(Term), nl.

         :- public(r/1).
         r(Term) :-
             read(Term).

     :- end_object.

Loading the file automatically calls the initialization goal.  Compare
its output with the output of the ‘ops::w/1’ predicate.  Compare also
reading a term from within the ‘ops’ object versus reading from ‘user’.

     | ?- {ops}.
     <=>(1,2)
     true.

     | ?- ops::w(<=>(1,2)).
     1<=>2
     true.

     | ?- ops::r(T).
     |: 3<=>4.

     T = <=>(3, 4).

     | ?- read(T).
     |: 5<=>6.

     SYNTAX ERROR: operator expected

See also
........

*note current_op/3: 15e.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: set_logtalk_flag/2,  Prev: op/3,  Up: Source file directives<2>

2.3.1.17 ‘set_logtalk_flag/2’
.............................

* Menu:

* Description: Description<12>.
* Template and modes: Template and modes<5>.
* Errors: Errors<8>.
* Examples: Examples<13>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<12>,  Next: Template and modes<5>,  Up: set_logtalk_flag/2

2.3.1.18 Description
....................

     set_logtalk_flag(Flag, Value)

Sets local flag values.  The scope of this directive is the entity or
the source file containing it.  For global scope, use the corresponding
*note set_logtalk_flag/2: 51. built-in predicate called from an *note
initialization/1: 42. directive.  For a description of the predefined
compiler flags, consult the *note Compiler flags: 251. section in the
User Manual.  The directive affects the compilation of all terms that
follow it within the scope of the directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<5>,  Next: Errors<8>,  Prev: Description<12>,  Up: set_logtalk_flag/2

2.3.1.19 Template and modes
...........................

     set_logtalk_flag(+atom, +nonvar)


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<8>,  Next: Examples<13>,  Prev: Template and modes<5>,  Up: set_logtalk_flag/2

2.3.1.20 Errors
...............

     Flag is a variable:
          ‘instantiation_error’
     Value is a variable:
          ‘instantiation_error’
     Flag is not an atom:
          ‘type_error(atom, Flag)’
     Flag is neither a variable nor a valid flag:
          ‘domain_error(flag, Flag)’
     Value is not a valid value for flag Flag:
          ‘domain_error(flag_value, Flag + Value)’
     Flag is a read-only flag:
          ‘permission_error(modify, flag, Flag)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<13>,  Prev: Errors<8>,  Up: set_logtalk_flag/2

2.3.1.21 Examples
.................

     % turn off the compiler unknown entity warnings
     % during the compilation of this source file:
     :- set_logtalk_flag(unknown_entities, silent).


     :- object(...).

         % generate events for messages sent from this object:
         :- set_logtalk_flag(events, allow).
         ...

         % turn off suspicious call lint checks for the next predicate:
         :- set_logtalk_flag(suspicious_calls, silent).
         foo :-
             ...
         :- set_logtalk_flag(suspicious_calls, warning).
         ...


File: TheLogtalkHandbook-3.96.0.info,  Node: Conditional compilation directives<2>,  Next: Entity directives,  Prev: Source file directives<2>,  Up: Directives<2>

2.3.2 Conditional compilation directives
----------------------------------------

'directive'

* Menu:

* if/1::
* elif/1::
* else/0::
* endif/0::


File: TheLogtalkHandbook-3.96.0.info,  Node: if/1,  Next: elif/1,  Up: Conditional compilation directives<2>

2.3.2.1 ‘if/1’
..............

* Menu:

* Description: Description<13>.
* Template and modes: Template and modes<6>.
* Examples: Examples<14>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<13>,  Next: Template and modes<6>,  Up: if/1

2.3.2.2 Description
...................

     if(Goal)

Starts an 'if-then' branch when performing conditional compilation.  The
code following the directive is compiled iff ‘Goal’ is true.  If ‘Goal’
throws an error instead of either succeeding or failing, the error is
reported by the compiler and compilation of the enclosing source file or
entity is aborted.  The goal is *note expanded: cb. when the directive
occurs in a source file.  Conditional compilation directives can be
nested.

     Warning: Conditional compilation goals 'cannot' depend on predicate
     definitions contained in the same source file that contains the
     conditional compilation directives (as those predicates only become
     available after the file is successfully compiled and loaded).


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<6>,  Next: Examples<14>,  Prev: Description<13>,  Up: if/1

2.3.2.3 Template and modes
..........................

     if(@callable)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<14>,  Prev: Template and modes<6>,  Up: if/1

2.3.2.4 Examples
................

A common example is checking if a built-in predicate exists and
providing a definition when the predicate is absent:

     :- if(\+ predicate_property(length(_,_), built_in)).

         length(List, Length) :-
             ...

     :- endif.

Another common example is conditionally including code for a specific
backend Prolog compiler:

     :- if(current_logtalk_flag(prolog_dialect, swi)).

         % SWI-Prolog specific code
         :- set_prolog_flag(double_quotes, codes).

     :- endif.

If necessary, test goal errors can be converted into failures using the
standard ‘catch/3’ control construct.  For example:

     :- if(catch(\+ log(7,_), _, fail)).

        % define the legacy log/2 predicate
        log(X, Y) :- Y is log(X).

     :- endif.

See also
........

*note elif/1: 2f3, *note else/0: 2f4, *note endif/0: 2f5.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: elif/1,  Next: else/0,  Prev: if/1,  Up: Conditional compilation directives<2>

2.3.2.5 ‘elif/1’
................

* Menu:

* Description: Description<14>.
* Template and modes: Template and modes<7>.
* Examples: Examples<15>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<14>,  Next: Template and modes<7>,  Up: elif/1

2.3.2.6 Description
...................

     elif(Goal)

Supports embedded conditionals when performing conditional compilation.
The code following the directive is compiled iff ‘Goal’ is true.  If
‘Goal’ throws an error instead of either succeeding or failing, the
error is reported by the compiler and compilation of the enclosing
source file or entity is aborted.  The goal is *note expanded: cb. when
the directive occurs in a source file.

     Warning: Conditional compilation goals 'cannot' depend on predicate
     definitions contained in the same source file that contains the
     conditional compilation directives (as those predicates only become
     available after the file is successfully compiled and loaded).


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<7>,  Next: Examples<15>,  Prev: Description<14>,  Up: elif/1

2.3.2.7 Template and modes
..........................

     elif(@callable)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<15>,  Prev: Template and modes<7>,  Up: elif/1

2.3.2.8 Examples
................

     :- if(current_prolog_flag(double_quotes, codes)).

         ...

     :- elif(current_prolog_flag(double_quotes, chars)).

         ...

     :- elif(current_prolog_flag(double_quotes, atom)).

         ...

     :- endif.

See also
........

*note else/0: 2f4, *note endif/0: 2f5, *note if/1: 2f2.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: else/0,  Next: endif/0,  Prev: elif/1,  Up: Conditional compilation directives<2>

2.3.2.9 ‘else/0’
................

* Menu:

* Description: Description<15>.
* Template and modes: Template and modes<8>.
* Examples: Examples<16>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<15>,  Next: Template and modes<8>,  Up: else/0

2.3.2.10 Description
....................

     else

Starts an 'else' branch when performing conditional compilation.  The
code following this directive is compiled iff the goal in the matching
*note if/1: 2f2. or *note elif/1: 2f3. directive is false.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<8>,  Next: Examples<16>,  Prev: Description<15>,  Up: else/0

2.3.2.11 Template and modes
...........................

     else


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<16>,  Prev: Template and modes<8>,  Up: else/0

2.3.2.12 Examples
.................

An example where a hypothetical application would have some limitations
that the user should be made aware of when running on a backend Prolog
compiler with bounded arithmetic:

     :- if(current_prolog_flag(bounded, true)).

         :- initialization(
             logtalk::print_message(warning,app,bounded_arithmetic)
         ).

     :- else.

         :- initialization(
             logtalk::print_message(comment,app,unbounded_arithmetic)
         ).

     :- endif.

See also
........

*note elif/1: 2f3, *note endif/0: 2f5, *note if/1: 2f2.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: endif/0,  Prev: else/0,  Up: Conditional compilation directives<2>

2.3.2.13 ‘endif/0’
..................

* Menu:

* Description: Description<16>.
* Template and modes: Template and modes<9>.
* Examples: Examples<17>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<16>,  Next: Template and modes<9>,  Up: endif/0

2.3.2.14 Description
....................

     endif

Ends conditional compilation for the matching *note if/1: 2f2.
directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<9>,  Next: Examples<17>,  Prev: Description<16>,  Up: endif/0

2.3.2.15 Template and modes
...........................

     endif


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<17>,  Prev: Template and modes<9>,  Up: endif/0

2.3.2.16 Examples
.................

     :- if(date::today(_,5,25)).

         :- initialization(write('Happy Towel Day!\n')).

     :- endif.

See also
........

*note elif/1: 2f3, *note else/0: 2f4, *note if/1: 2f2.


File: TheLogtalkHandbook-3.96.0.info,  Node: Entity directives,  Next: Predicate directives<2>,  Prev: Conditional compilation directives<2>,  Up: Directives<2>

2.3.3 Entity directives
-----------------------

'directive'

* Menu:

* built_in/0::
* category/1-4::
* dynamic/0::
* end_category/0::
* end_object/0::
* end_protocol/0::
* info/1::
* object/1-5::
* protocol/1-2::
* threaded/0::
* uses/1::
* use_module/1::


File: TheLogtalkHandbook-3.96.0.info,  Node: built_in/0,  Next: category/1-4,  Up: Entity directives

2.3.3.1 ‘built_in/0’
....................

* Menu:

* Description: Description<17>.
* Template and modes: Template and modes<10>.
* Examples: Examples<18>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<17>,  Next: Template and modes<10>,  Up: built_in/0

2.3.3.2 Description
...................

     built_in

Declares an entity as built-in.  Built-in entities must be static and
cannot be redefined once loaded.  This directive is used in the
pre-defined protocols, categories, and objects that are automatically
loaded at startup.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<10>,  Next: Examples<18>,  Prev: Description<17>,  Up: built_in/0

2.3.3.3 Template and modes
..........................

     built_in


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<18>,  Prev: Template and modes<10>,  Up: built_in/0

2.3.3.4 Examples
................

     :- built_in.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: category/1-4,  Next: dynamic/0,  Prev: built_in/0,  Up: Entity directives

2.3.3.5 ‘category/1-4’
......................

* Menu:

* Description: Description<18>.
* Template and modes: Template and modes<11>.
* Examples: Examples<19>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<18>,  Next: Template and modes<11>,  Up: category/1-4

2.3.3.6 Description
...................

     category(Category)

     category(Category,
         implements(Protocols))

     category(Category,
         extends(Categories))

     category(Category,
         complements(Objects))

     category(Category,
         implements(Protocols),
         extends(Categories))

     category(Category,
         implements(Protocols),
         complements(Objects))

     category(Category,
         extends(Categories),
         complements(Objects))

     category(Category,
         implements(Protocols),
         extends(Categories),
         complements(Objects))

Starting category directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<11>,  Next: Examples<19>,  Prev: Description<18>,  Up: category/1-4

2.3.3.7 Template and modes
..........................

     category(+category_identifier)

     category(+category_identifier,
         implements(+implemented_protocols))

     category(+category_identifier,
         extends(+extended_categories))

     category(+category_identifier,
         complements(+complemented_objects))

     category(+category_identifier,
         implements(+implemented_protocols),
         extends(+extended_categories))

     category(+category_identifier,
         implements(+implemented_protocols),
         complements(+complemented_objects))

     category(+category_identifier,
         extends(+extended_categories),
         complements(+complemented_objects))

     category(+category_identifier,
         implements(+implemented_protocols),
         extends(+extended_categories),
         complements(+complemented_objects))


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<19>,  Prev: Template and modes<11>,  Up: category/1-4

2.3.3.8 Examples
................

     :- category(monitoring).

     :- category(monitoring,
         implements(monitoringp)).

     :- category(attributes,
         implements(protected::variables)).

     :- category(extended,
         extends(minimal)).

     :- category(logging,
         implements(monitoring),
         complements(employee)).

See also
........

*note end_category/0: 10f.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: dynamic/0,  Next: end_category/0,  Prev: category/1-4,  Up: Entity directives

2.3.3.9 ‘dynamic/0’
...................

* Menu:

* Description: Description<19>.
* Template and modes: Template and modes<12>.
* Examples: Examples<20>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<19>,  Next: Template and modes<12>,  Up: dynamic/0

2.3.3.10 Description
....................

     dynamic

Declares an entity and its contents as dynamic.  Dynamic entities can be
abolished at runtime.

As entities created at runtime (using the *note create_object/4: 62,
*note create_protocol/3: e3, and *note create_category/4: 11a. built-in
predicates) are always dynamic, this directive is only necessary in the
rare cases where we want to define dynamic entities in source files.

     Warning: Some backend Prolog compilers declare the atom ‘dynamic’
     as an operator for a lighter syntax, forcing writing this atom
     between parenthesis when using this directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<12>,  Next: Examples<20>,  Prev: Description<19>,  Up: dynamic/0

2.3.3.11 Template and modes
...........................

     dynamic


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<20>,  Prev: Template and modes<12>,  Up: dynamic/0

2.3.3.12 Examples
.................

     :- dynamic.

See also
........

*note dynamic/1: 15a, *note object_property/2: c6, *note
protocol_property/2: f4, *note category_property/2: 12c.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: end_category/0,  Next: end_object/0,  Prev: dynamic/0,  Up: Entity directives

2.3.3.13 ‘end_category/0’
.........................

* Menu:

* Description: Description<20>.
* Template and modes: Template and modes<13>.
* Examples: Examples<21>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<20>,  Next: Template and modes<13>,  Up: end_category/0

2.3.3.14 Description
....................

     end_category

Ending category directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<13>,  Next: Examples<21>,  Prev: Description<20>,  Up: end_category/0

2.3.3.15 Template and modes
...........................

     end_category


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<21>,  Prev: Template and modes<13>,  Up: end_category/0

2.3.3.16 Examples
.................

     :- end_category.

See also
........

*note category/1-4: 10e.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: end_object/0,  Next: end_protocol/0,  Prev: end_category/0,  Up: Entity directives

2.3.3.17 ‘end_object/0’
.......................

* Menu:

* Description: Description<21>.
* Template and modes: Template and modes<14>.
* Examples: Examples<22>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<21>,  Next: Template and modes<14>,  Up: end_object/0

2.3.3.18 Description
....................

     end_object

Ending object directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<14>,  Next: Examples<22>,  Prev: Description<21>,  Up: end_object/0

2.3.3.19 Template and modes
...........................

     end_object


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<22>,  Prev: Template and modes<14>,  Up: end_object/0

2.3.3.20 Examples
.................

     :- end_object.

See also
........

*note object/1-5: 9a.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: end_protocol/0,  Next: info/1,  Prev: end_object/0,  Up: Entity directives

2.3.3.21 ‘end_protocol/0’
.........................

* Menu:

* Description: Description<22>.
* Template and modes: Template and modes<15>.
* Examples: Examples<23>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<22>,  Next: Template and modes<15>,  Up: end_protocol/0

2.3.3.22 Description
....................

     end_protocol

Ending protocol directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<15>,  Next: Examples<23>,  Prev: Description<22>,  Up: end_protocol/0

2.3.3.23 Template and modes
...........................

     end_protocol


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<23>,  Prev: Template and modes<15>,  Up: end_protocol/0

2.3.3.24 Examples
.................

     :- end_protocol.

See also
........

*note protocol/1-2: dc.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: info/1,  Next: object/1-5,  Prev: end_protocol/0,  Up: Entity directives

2.3.3.25 ‘info/1’
.................

* Menu:

* Description: Description<23>.
* Template and modes: Template and modes<16>.
* Examples: Examples<24>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<23>,  Next: Template and modes<16>,  Up: info/1

2.3.3.26 Description
....................

     info([Key is Value, ...])

Documentation directive for objects, protocols, and categories.  The
directive argument is a list of pairs using the format 'Key is Value'.
See the *note Entity documenting directives: 323. section for a
description of the default keys.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<16>,  Next: Examples<24>,  Prev: Description<23>,  Up: info/1

2.3.3.27 Template and modes
...........................

     info(+entity_info_list)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<24>,  Prev: Template and modes<16>,  Up: info/1

2.3.3.28 Examples
.................

     :- info([
         version is 1:0:0,
         author is 'Paulo Moura',
         date is 2000-11-20,
         comment is 'List protocol.'
     ]).

See also
........

*note info/2: 168, *note object_property/2: c6, *note
protocol_property/2: f4, *note category_property/2: 12c.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: object/1-5,  Next: protocol/1-2,  Prev: info/1,  Up: Entity directives

2.3.3.29 ‘object/1-5’
.....................

* Menu:

* Description: Description<24>.
* Template and modes: Template and modes<17>.
* Examples: Examples<25>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<24>,  Next: Template and modes<17>,  Up: object/1-5

2.3.3.30 Description
....................

'Stand-alone objects (prototypes)'

     object(Object)

     object(Object,
         implements(Protocols))

     object(Object,
         imports(Categories))

     object(Object,
         implements(Protocols),
         imports(Categories))

'Prototype extensions'

     object(Object,
         extends(Objects))

     object(Object,
         implements(Protocols),
         extends(Objects))

     object(Object,
         imports(Categories),
         extends(Objects))

     object(Object,
         implements(Protocols),
         imports(Categories),
         extends(Objects))

'Class instances'

     object(Object,
         instantiates(Classes))

     object(Object,
         implements(Protocols),
         instantiates(Classes))

     object(Object,
         imports(Categories),
         instantiates(Classes))

     object(Object,
         implements(Protocols),
         imports(Categories),
         instantiates(Classes))

'Classes'

     object(Object,
         specializes(Classes))

     object(Object,
         implements(Protocols),
         specializes(Classes))

     object(Object,
         imports(Categories),
         specializes(Classes))

     object(Object,
         implements(Protocols),
         imports(Categories),
         specializes(Classes))

'Classes with metaclasses'

     object(Object,
         instantiates(Classes),
         specializes(Classes))

     object(Object,
         implements(Protocols),
         instantiates(Classes),
         specializes(Classes))

     object(Object,
         imports(Categories),
         instantiates(Classes),
         specializes(Classes))

     object(Object,
         implements(Protocols),
         imports(Categories),
         instantiates(Classes),
         specializes(Classes))

Starting object directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<17>,  Next: Examples<25>,  Prev: Description<24>,  Up: object/1-5

2.3.3.31 Template and modes
...........................

'Stand-alone objects (prototypes)'

     object(+object_identifier)

     object(+object_identifier,
         implements(+implemented_protocols))

     object(+object_identifier,
         imports(+imported_categories))

     object(+object_identifier,
         implements(+implemented_protocols),
         imports(+imported_categories))

'Prototype extensions'

     object(+object_identifier,
         extends(+extended_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         extends(+extended_objects))

     object(+object_identifier,
         imports(+imported_categories),
         extends(+extended_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         imports(+imported_categories),
         extends(+extended_objects))

'Class instances'

     object(+object_identifier,
         instantiates(+instantiated_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         instantiates(+instantiated_objects))

     object(+object_identifier,
         imports(+imported_categories),
         instantiates(+instantiated_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         imports(+imported_categories),
         instantiates(+instantiated_objects))

'Classes'

     object(+object_identifier,
         specializes(+specialized_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         specializes(+specialized_objects))

     object(+object_identifier,
         imports(+imported_categories),
         specializes(+specialized_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         imports(+imported_categories),
         specializes(+specialized_objects))

'Class with metaclasses'

     object(+object_identifier,
         instantiates(+instantiated_objects),
         specializes(+specialized_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         instantiates(+instantiated_objects),
         specializes(+specialized_objects))

     object(+object_identifier,
         imports(+imported_categories),
         instantiates(+instantiated_objects),
         specializes(+specialized_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         imports(+imported_categories),
         instantiates(+instantiated_objects),
         specializes(+specialized_objects))


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<25>,  Prev: Template and modes<17>,  Up: object/1-5

2.3.3.32 Examples
.................

     :- object(list).

     :- object(list,
         implements(listp)).

     :- object(list,
         extends(compound)).

     :- object(list,
         implements(listp),
         extends(compound)).

     :- object(object,
         imports(initialization),
         instantiates(class)).

     :- object(abstract_class,
         instantiates(class),
         specializes(object)).

     :- object(agent,
         imports(private::attributes)).

See also
........

*note end_object/0: 9b.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: protocol/1-2,  Next: threaded/0,  Prev: object/1-5,  Up: Entity directives

2.3.3.33 ‘protocol/1-2’
.......................

* Menu:

* Description: Description<25>.
* Template and modes: Template and modes<18>.
* Examples: Examples<26>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<25>,  Next: Template and modes<18>,  Up: protocol/1-2

2.3.3.34 Description
....................

     protocol(Protocol)

     protocol(Protocol,
         extends(Protocols))

Starting protocol directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<18>,  Next: Examples<26>,  Prev: Description<25>,  Up: protocol/1-2

2.3.3.35 Template and modes
...........................

     protocol(+protocol_identifier)

     protocol(+protocol_identifier,
         extends(+extended_protocols))


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<26>,  Prev: Template and modes<18>,  Up: protocol/1-2

2.3.3.36 Examples
.................

     :- protocol(listp).

     :- protocol(listp,
         extends(compoundp)).

     :- protocol(queuep,
         extends(protected::listp)).

See also
........

*note end_protocol/0: dd.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded/0,  Next: uses/1,  Prev: protocol/1-2,  Up: Entity directives

2.3.3.37 ‘threaded/0’
.....................

* Menu:

* Description: Description<26>.
* Template and modes: Template and modes<19>.
* Examples: Examples<27>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<26>,  Next: Template and modes<19>,  Up: threaded/0

2.3.3.38 Description
....................

     threaded

Declares that an object supports threaded engines, concurrent calls, and
asynchronous messages.  Any object containing calls to the built-in
multi-threading predicates (or importing a category that contains such
calls) must include this directive.

This directive results in the automatic creation and set up of an object
message queue when the object is loaded or created at runtime.  Object
message queues are used for exchanging thread notifications and for
storing concurrent goal solutions and replies to the multi-threading
calls made within the object.  The message queue for the *note user: cf.
pseudo-object is automatically created at Logtalk startup (provided that
multi-threading programming is supported and enabled for the chosen
*note backend Prolog compiler: 34.).

     Note: This directive requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<19>,  Next: Examples<27>,  Prev: Description<26>,  Up: threaded/0

2.3.3.39 Template and modes
...........................

     threaded


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<27>,  Prev: Template and modes<19>,  Up: threaded/0

2.3.3.40 Examples
.................

     :- threaded.

See also
........

*note synchronized/1: 74, *note object_property/2: c6.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: uses/1,  Next: use_module/1,  Prev: threaded/0,  Up: Entity directives

2.3.3.41 ‘uses/1’
.................

* Menu:

* Description: Description<27>.
* Template and modes: Template and modes<20>.
* Examples: Examples<28>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<27>,  Next: Template and modes<20>,  Up: uses/1

2.3.3.42 Description
....................

     uses([Object as Alias, ...])

Declares object aliases.  Typically used to shorten long object names,
to simplify and consistently send messages to parameterized objects, and
to simplify using or experimenting with different object implementations
of the same protocol when using explicit message-sending.  Object
aliases are local to the object (or category) where they are defined.

The objects being aliased can be *note parameter variables: a1. or
parametric objects where one or more parameters are parameter variables
when using the directive in a parametric object or a parametric category
defined in a source file (the common case).

Declaring multiple aliases for the same object is allowed.  But repeated
declarations of the same alias, declaring an alias for an object alias,
and redefining an alias to reference a different object are reported as
compilation errors.

To enable the use of *note static binding: 35, and thus optimal
message-sending performance, the objects should be loaded before
compiling the entities that call their predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<20>,  Next: Examples<28>,  Prev: Description<27>,  Up: uses/1

2.3.3.43 Template and modes
...........................

     uses(+object_alias_list)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<28>,  Prev: Template and modes<20>,  Up: uses/1

2.3.3.44 Examples
.................

     :- object(foo(_HeapType_, _OptionsObject_)).

         :- uses([
             fast_random as rnd,
             time(utc) as time,
             heap(_HeapType_) as heap,
             _OptionsObject_ as options
         ]).

         bar :-
             ...,
             % the same as fast_random::permutation(L, P)
             rnd::permutation(L, P),
             % the same as heap(_HeapType_)::as_heap(L, H)
             heap::as_heap(L, H),
             % the same as _OptionsObject_::get(foo, X)
             options::get(foo, X),
             % the same as time(utc)::now(T)
             time::now(T),
             ...

See also
........

*note uses/2: 4b, *note use_module/1: 4c, *note use_module/2: 4d.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: use_module/1,  Prev: uses/1,  Up: Entity directives

2.3.3.45 ‘use_module/1’
.......................

* Menu:

* Description: Description<28>.
* Template and modes: Template and modes<21>.
* Examples: Examples<29>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<28>,  Next: Template and modes<21>,  Up: use_module/1

2.3.3.46 Description
....................

     use_module([Module as Alias, ...])

Declares module aliases.  Typically used to shorten long module names
and to simplify using or experimenting with different module
implementations of the same predicates when using explicitly-qualified
calls.  Module aliases are local to the object (or category) where they
are defined.

The modules being aliased can be *note parameter variables: a1. when
using the directive in a parametric object or a parametric category
defined in a source file (the common case).

Declaring multiple aliases for the same module is allowed.  But repeated
declarations of the same alias, declaring an alias for a module alias,
and redefining an alias to reference a different module are reported as
compilation errors.

To enable the use of *note static binding: 35, and thus optimal
predicate call performance, the modules should be loaded before
compiling the entities that call their predicates.

Note that this directive semantics differs from the directive with the
same name found on some Prolog implementations where it is used to load
a module and import all its exported predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<21>,  Next: Examples<29>,  Prev: Description<28>,  Up: use_module/1

2.3.3.47 Template and modes
...........................

     use_module(+module_alias_list)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<29>,  Prev: Template and modes<21>,  Up: use_module/1

2.3.3.48 Examples
.................

     :- object(foo(_DataModule_)).

         :- use_module([
             data_noise_handler as cleaner,
             _DataModule_ as data
         ]).

         bar :-
             ...,
             % the same as _DataModule_:xy(X, Y)
             data:xy(X, Y),
             % the same as data_noise_handler:filter(X, Y)
             cleaner:filter(X, Y, Z),
             ...

See also
........

*note uses/1: 4a, *note uses/2: 4b, *note use_module/2: 4d.


File: TheLogtalkHandbook-3.96.0.info,  Node: Predicate directives<2>,  Prev: Entity directives,  Up: Directives<2>

2.3.4 Predicate directives
--------------------------

'directive'

* Menu:

* alias/2::
* coinductive/1::
* discontiguous/1::
* dynamic/1::
* info/2::
* meta_predicate/1::
* meta_non_terminal/1::
* mode/2::
* mode_non_terminal/2::
* multifile/1::
* private/1::
* protected/1::
* public/1::
* synchronized/1::
* uses/2::
* use_module/2::


File: TheLogtalkHandbook-3.96.0.info,  Node: alias/2,  Next: coinductive/1,  Up: Predicate directives<2>

2.3.4.1 ‘alias/2’
.................

* Menu:

* Description: Description<29>.
* Template and modes: Template and modes<22>.
* Examples: Examples<30>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<29>,  Next: Template and modes<22>,  Up: alias/2

2.3.4.2 Description
...................

     alias(Entity, [Name/Arity as Alias/Arity, ...])
     alias(Entity, [Name//Arity as Alias//Arity, ...])

Declares predicate and grammar rule non-terminal *note aliases: ca.  A
predicate (non-terminal) alias is an alternative name for a predicate
(non-terminal) declared or defined in an extended protocol, an
implemented protocol, an extended category, an imported category, an
extended prototype, an instantiated class, or a specialized class.
Predicate aliases may be used to solve conflicts between imported or
inherited predicates.  It may also be used to give a predicate
(non-terminal) a name more appropriate in its usage context.  This
directive may be used in objects, protocols, and categories.

Predicate (and non-terminal) aliases are specified using (preferably)
the notation ‘Name/Arity as Alias/Arity’ or, in alternative, the
notation ‘Name/Arity::Alias/Arity’.

It is also possible to declare predicate and grammar rule non-terminal
aliases in implicit qualification directives for sending messages to
objects and calling module predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<22>,  Next: Examples<30>,  Prev: Description<29>,  Up: alias/2

2.3.4.3 Template and modes
..........................

     alias(@entity_identifier, +list(predicate_indicator_alias))
     alias(@entity_identifier, +list(non_terminal_indicator_alias))


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<30>,  Prev: Template and modes<22>,  Up: alias/2

2.3.4.4 Examples
................

     % resolve a predicate name conflict:
     :- alias(list, [member/2 as list_member/2]).
     :- alias(set,  [member/2 as set_member/2]).

     % define an alternative name for a non-terminal:
     :- alias(words, [singular//0 as peculiar//0]).

See also
........

*note uses/2: 4b, *note use_module/2: 4d, *note uses/1: 4a.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: coinductive/1,  Next: discontiguous/1,  Prev: alias/2,  Up: Predicate directives<2>

2.3.4.5 ‘coinductive/1’
.......................

* Menu:

* Description: Description<30>.
* Template and modes: Template and modes<23>.
* Examples: Examples<31>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<30>,  Next: Template and modes<23>,  Up: coinductive/1

2.3.4.6 Description
...................

     coinductive(Name/Arity)
     coinductive((Name/Arity, ...))
     coinductive([Name/Arity, ...])

     coinductive(Name//Arity)
     coinductive((Name//Arity, ...))
     coinductive([Name//Arity, ...])

     coinductive(Template)
     coinductive((Template1, ...))
     coinductive([Template1, ...])

This is an 'experimental' directive, used for declaring *note
coinductive: 170. predicates.  Requires a *note backend Prolog compiler:
34. with minimal support for cyclic terms.  The current implementation
of coinduction allows the generation of only the 'basic cycles' but all
valid solutions should be recognized.  Use a predicate indicator or a
non-terminal indicator as argument when all the coinductive predicate
arguments are relevant for coinductive success.  Use a template when
only some coinductive predicate arguments (represented by a “‘+’”)
should be considered when testing for coinductive success (represent the
arguments that should be disregarded by a “‘-’“).  It’s possible to
define local *note coinductive_success_hook/1-2: 4b2. predicates that
are automatically called with the coinductive predicate term resulting
from a successful unification with an ancestor goal as first argument.
The second argument, when present, is the coinductive hypothesis (i.e.,
the ancestor goal) used.  These hook predicates can provide an
alternative to the use of tabling when defining some coinductive
predicates.  There is no overhead when these hook predicates are not
defined.

This directive must precede any calls to the declared coinductive
predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<23>,  Next: Examples<31>,  Prev: Description<30>,  Up: coinductive/1

2.3.4.7 Template and modes
..........................

     coinductive(+predicate_indicator_term)
     coinductive(+non_terminal_indicator_term)
     coinductive(+coinductive_predicate_template_term)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<31>,  Prev: Template and modes<23>,  Up: coinductive/1

2.3.4.8 Examples
................

     :- coinductive(comember/2).
     :- coinductive(ones_and_zeros//0).
     :- coinductive(controller(+,+,+,-,-)).

See also
........

*note coinductive_success_hook/1-2: 4b2, *note predicate_property/2:
142.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: discontiguous/1,  Next: dynamic/1,  Prev: coinductive/1,  Up: Predicate directives<2>

2.3.4.9 ‘discontiguous/1’
.........................

* Menu:

* Description: Description<31>.
* Template and modes: Template and modes<24>.
* Examples: Examples<32>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<31>,  Next: Template and modes<24>,  Up: discontiguous/1

2.3.4.10 Description
....................

     discontiguous(Name/Arity)
     discontiguous((Name/Arity, ...))
     discontiguous([Name/Arity, ...])

     discontiguous(Entity::Name/Arity)
     discontiguous((Entity::Name/Arity, ...))
     discontiguous([Entity::Name/Arity, ...])

     discontiguous(Module:Name/Arity)
     discontiguous((Module:Name/Arity, ...))
     discontiguous([Module:Name/Arity, ...])

     discontiguous(Name//Arity)
     discontiguous((Name//Arity, ...))
     discontiguous([Name//Arity, ...])

     discontiguous(Entity::Name//Arity)
     discontiguous((Entity::Name//Arity, ...))
     discontiguous([Entity::Name//Arity, ...])

     discontiguous(Module:Name//Arity)
     discontiguous((Module:Name//Arity, ...))
     discontiguous([Module:Name//Arity, ...])

Declares *note discontiguous: 4b8. predicates and discontiguous grammar
rule non-terminals.  The use of this directive should be avoided as not
all *note backend Prolog compilers: 34. support discontiguous
predicates.

     Warning: Some backend Prolog compilers declare the atom
     ‘discontiguous’ as an operator for a lighter syntax.  But this
     makes the code non-portable and is therefore a practice best
     avoided.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<24>,  Next: Examples<32>,  Prev: Description<31>,  Up: discontiguous/1

2.3.4.11 Template and modes
...........................

     discontiguous(+predicate_indicator_term)
     discontiguous(+non_terminal_indicator_term)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<32>,  Prev: Template and modes<24>,  Up: discontiguous/1

2.3.4.12 Examples
.................

     :- discontiguous(counter/1).

     :- discontiguous((lives/2, works/2)).

     :- discontiguous([db/4, key/2, file/3]).

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: dynamic/1,  Next: info/2,  Prev: discontiguous/1,  Up: Predicate directives<2>

2.3.4.13 ‘dynamic/1’
....................

* Menu:

* Description: Description<32>.
* Template and modes: Template and modes<25>.
* Examples: Examples<33>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<32>,  Next: Template and modes<25>,  Up: dynamic/1

2.3.4.14 Description
....................

     dynamic(Name/Arity)
     dynamic((Name/Arity, ...))
     dynamic([Name/Arity, ...])

     dynamic(Entity::Name/Arity)
     dynamic((Entity::Name/Arity, ...))
     dynamic([Entity::Name/Arity, ...])

     dynamic(Module:Name/Arity)
     dynamic((Module:Name/Arity, ...))
     dynamic([Module:Name/Arity, ...])

     dynamic(Name//Arity)
     dynamic((Name//Arity, ...))
     dynamic([Name//Arity, ...])

     dynamic(Entity::Name//Arity)
     dynamic((Entity::Name//Arity, ...))
     dynamic([Entity::Name//Arity, ...])

     dynamic(Module:Name//Arity)
     dynamic((Module:Name//Arity, ...))
     dynamic([Module:Name//Arity, ...])

Declares *note dynamic: 4be. predicates and dynamic grammar rule
non-terminals.  Note that an object can be static and have both static
and dynamic predicates/non-terminals.  When the dynamic predicates are
local to an object, declaring them also as *note private predicates:
145. allows the Logtalk compiler to generate optimized code for
asserting and retracting predicate clauses.  Categories can also contain
dynamic predicate directives but cannot contain clauses for dynamic
predicates.

The predicate indicators (or non-terminal indicators) can be explicitly
qualified with an object, category, or module identifier when the
predicates (or non-terminals) are also declared *note multifile: 16c.

Note that dynamic predicates cannot be declared synchronized (when
necessary, declare the predicates updating the dynamic predicates as
*note synchronized: 74.).

     Warning: Some backend Prolog compilers declare the atom ‘dynamic’
     as an operator for a lighter syntax.  But this makes the code
     non-portable and is therefore a practice best avoided.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<25>,  Next: Examples<33>,  Prev: Description<32>,  Up: dynamic/1

2.3.4.15 Template and modes
...........................

     dynamic(+qualified_predicate_indicator_term)
     dynamic(+qualified_non_terminal_indicator_term)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<33>,  Prev: Template and modes<25>,  Up: dynamic/1

2.3.4.16 Examples
.................

     :- dynamic(counter/1).

     :- dynamic((lives/2, works/2)).

     :- dynamic([db/4, key/2, file/3]).

See also
........

*note dynamic/0: b1, *note predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: info/2,  Next: meta_predicate/1,  Prev: dynamic/1,  Up: Predicate directives<2>

2.3.4.17 ‘info/2’
.................

* Menu:

* Description: Description<33>.
* Template and modes: Template and modes<26>.
* Examples: Examples<34>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<33>,  Next: Template and modes<26>,  Up: info/2

2.3.4.18 Description
....................

     info(Name/Arity, [Key is Value, ...])
     info(Name//Arity, [Key is Value, ...])

Documentation directive for predicates and grammar rule non-terminals.
The first argument is either a predicate indicator or a grammar rule
non-terminal indicator.  The second argument is a list of pairs using
the format 'Key is Value'.  See the *note Predicate documenting
directives: 325. section for a description of the default keys.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<26>,  Next: Examples<34>,  Prev: Description<33>,  Up: info/2

2.3.4.19 Template and modes
...........................

     info(+predicate_indicator, +predicate_info_list)
     info(+non_terminal_indicator, +predicate_info_list)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<34>,  Prev: Template and modes<26>,  Up: info/2

2.3.4.20 Examples
.................

     :- info(empty/1, [
         comment is 'True if the argument is an empty list.',
         argnames is ['List']
     ]).

     :- info(sentence//0, [
         comment is 'Rewrites a sentence into a noun phrase and a verb phrase.'
     ]).

See also
........

*note info/1: b4, *note mode/2: 149, *note predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: meta_predicate/1,  Next: meta_non_terminal/1,  Prev: info/2,  Up: Predicate directives<2>

2.3.4.21 ‘meta_predicate/1’
...........................

* Menu:

* Description: Description<34>.
* Template and modes: Template and modes<27>.
* Examples: Examples<35>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<34>,  Next: Template and modes<27>,  Up: meta_predicate/1

2.3.4.22 Description
....................

     meta_predicate(Template)
     meta_predicate((Template, ...))
     meta_predicate([Template, ...])

     meta_predicate(Entity::Template)
     meta_predicate((Entity::Template, ...))
     meta_predicate([Entity::Template, ...])

     meta_predicate(Module:Template)
     meta_predicate((Module:Template, ...))
     meta_predicate([Module:Template, ...])

Declares *note meta-predicates: 52, i.e., predicates that have arguments
interpreted as goals, arguments interpreted as *note closures: 14f. used
to construct goals, or arguments with sub-terms that will be interpreted
as goals or closures.  Meta-arguments are always called in the
meta-predicate *note calling context: 150, not in the meta-predicate
*note definition context: 151.

Meta-arguments which are goals are represented by the integer ‘0’.
Meta-arguments which are closures are represented by a positive integer,
‘N’, representing the number of additional arguments that will be
appended to the closure in order to construct the corresponding goal
(typically by calling the *note call/1-N: 181. built-in method).
Meta-arguments with sub-terms that will be interpreted as goals or
closures are represented by ‘::’.  Meta-arguments that will be called
using the ‘bagof/3’ or ‘setof/3’ predicates and that can thus be
existentially-qualified are represented by the atom ‘^’.  Normal
arguments are represented by the atom ‘*’.

Logtalk allows the use of this directive to override the original
meta-predicate directive.  This is sometimes necessary when calling
Prolog built-in meta-predicates or Prolog module meta-predicates due to
the lack of standardization of the syntax of the meta-predicate
templates.  Another case is when a meta-predicate directive is missing.
The compiler requires access to correct and non-ambiguous meta-predicate
templates to correctly compile calls to Prolog meta-predicates.

     Warning: Some backend Prolog compilers declare the atom
     ‘meta_predicate’ as an operator for a lighter syntax.  But this
     makes the code non-portable and is therefore a practice best
     avoided.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<27>,  Next: Examples<35>,  Prev: Description<34>,  Up: meta_predicate/1

2.3.4.23 Template and modes
...........................

     meta_predicate(+meta_predicate_template_term)

     meta_predicate(+object_identifier::+meta_predicate_template_term)
     meta_predicate(+category_identifier::+meta_predicate_template_term)

     meta_predicate(+module_identifier:+meta_predicate_template_term)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<35>,  Prev: Template and modes<27>,  Up: meta_predicate/1

2.3.4.24 Examples
.................

     % findall/3 second argument is interpreted as a goal:
     :- meta_predicate(findall(*, 0, *)).

     % both forall/2 arguments are interpreted as goals:
     :- meta_predicate(forall(0, 0)).

     % maplist/3 first argument is interpreted as a closure
     % that will be expanded to a goal by appending two
     % arguments:
     :- meta_predicate(maplist(2, *, *)).

See also
........

*note meta_non_terminal/1: 153, *note predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: meta_non_terminal/1,  Next: mode/2,  Prev: meta_predicate/1,  Up: Predicate directives<2>

2.3.4.25 ‘meta_non_terminal/1’
..............................

* Menu:

* Description: Description<35>.
* Template and modes: Template and modes<28>.
* Examples: Examples<36>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<35>,  Next: Template and modes<28>,  Up: meta_non_terminal/1

2.3.4.26 Description
....................

     meta_non_terminal(Template)
     meta_non_terminal((Template, ...))
     meta_non_terminal([Template, ...])

     meta_non_terminal(Entity::Template)
     meta_non_terminal((Entity::Template, ...))
     meta_non_terminal([Entity::Template, ...])

     meta_non_terminal(Module:Template)
     meta_non_terminal((Module:Template, ...))
     meta_non_terminal([Module:Template, ...])

Declares meta-non-terminals, i.e., non-terminals that have arguments
that will be called as non-terminals (or grammar rule bodies).  An
argument may also be a *note closure: 14f. instead of a goal if the
non-terminal uses the *note call//1-N: 1c9. built-in methods to
construct and call the actual non-terminal from the closure and the
additional arguments or the *note phrase//1: 1c8. built-in method.

Meta-arguments which are non-terminals are represented by the integer
‘0’.  Meta-arguments which are closures are represented by a positive
integer, ‘N’, representing the number of additional arguments that will
be appended to the closure in order to construct the corresponding
meta-call.  Normal arguments are represented by the atom ‘*’.
Meta-arguments are always called in the meta-non-terminal calling
context, not in the meta-non-terminal definition context.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<28>,  Next: Examples<36>,  Prev: Description<35>,  Up: meta_non_terminal/1

2.3.4.27 Template and modes
...........................

     meta_non_terminal(+meta_non_terminal_template_term)

     meta_non_terminal(+object_identifier::+meta_non_terminal_template_term)
     meta_non_terminal(+category_identifier::+meta_non_terminal_template_term)

     meta_non_terminal(+module_identifier:+meta_non_terminal_template_term)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<36>,  Prev: Template and modes<28>,  Up: meta_non_terminal/1

2.3.4.28 Examples
.................

     :- meta_non_terminal(phrase(1, *)).
     phrase(X, T) --> call(X, T).

See also
........

*note meta_predicate/1: 152, *note predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: mode/2,  Next: mode_non_terminal/2,  Prev: meta_non_terminal/1,  Up: Predicate directives<2>

2.3.4.29 ‘mode/2’
.................

* Menu:

* Description: Description<36>.
* Template and modes: Template and modes<29>.
* Examples: Examples<37>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<36>,  Next: Template and modes<29>,  Up: mode/2

2.3.4.30 Description
....................

     mode(Mode, NumberOfProofs)

Most predicates can be used with several instantiations modes.  This
directive enables the specification of each *note instantiation mode:
14b. and the corresponding *note number of proofs: 14d. (but not
necessarily distinct solutions).  The instantiation mode of each
argument can include type information.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<29>,  Next: Examples<37>,  Prev: Description<36>,  Up: mode/2

2.3.4.31 Template and modes
...........................

     mode(+predicate_mode_term, +number_of_proofs)
     mode(+non_terminal_mode_term, +number_of_proofs)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<37>,  Prev: Template and modes<29>,  Up: mode/2

2.3.4.32 Examples
.................

     :- mode(atom_concat(-atom, -atom, +atom), one_or_more).
     :- mode(atom_concat(+atom, +atom, -atom), one).

     :- mode(var(@term), zero_or_one).

     :- mode(solve(+callable, -list(atom)), zero_or_one).

See also
........

*note mode_non_terminal/2: 14a, *note info/2: 168, *note
predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: mode_non_terminal/2,  Next: multifile/1,  Prev: mode/2,  Up: Predicate directives<2>

2.3.4.33 ‘mode_non_terminal/2’
..............................

* Menu:

* Description: Description<37>.
* Template and modes: Template and modes<30>.
* Examples: Examples<38>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<37>,  Next: Template and modes<30>,  Up: mode_non_terminal/2

2.3.4.34 Description
....................

     mode_non_terminal(Mode, NumberOfProofs)

Most non-terminals can be used with several instantiations modes.  This
directive enables the specification of each *note instantiation mode:
14b. and the corresponding *note number of proofs: 14d. (but not
necessarily distinct solutions).  The instantiation mode of each
argument can include type information.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<30>,  Next: Examples<38>,  Prev: Description<37>,  Up: mode_non_terminal/2

2.3.4.35 Template and modes
...........................

     mode_non_terminal(+predicate_mode_term, +number_of_proofs)
     mode_non_terminal(+non_terminal_mode_term, +number_of_proofs)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<38>,  Prev: Template and modes<30>,  Up: mode_non_terminal/2

2.3.4.36 Examples
.................

     :- mode_non_terminal(zero_or_more(-list(atomic)), one).

See also
........

*note mode/2: 149, *note info/2: 168, *note predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: multifile/1,  Next: private/1,  Prev: mode_non_terminal/2,  Up: Predicate directives<2>

2.3.4.37 ‘multifile/1’
......................

* Menu:

* Description: Description<38>.
* Template and modes: Template and modes<31>.
* Examples: Examples<39>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<38>,  Next: Template and modes<31>,  Up: multifile/1

2.3.4.38 Description
....................

     multifile(Name/Arity)
     multifile((Name/Arity, ...))
     multifile([Name/Arity, ...])

     multifile(Entity::Name/Arity)
     multifile((Entity::Name/Arity, ...))
     multifile([Entity::Name/Arity, ...])

     multifile(Module:Name/Arity)
     multifile((Module:Name/Arity, ...))
     multifile([Module:Name/Arity, ...])

     multifile(Name//Arity)
     multifile((Name//Arity, ...))
     multifile([Name//Arity, ...])

     multifile(Entity::Name//Arity)
     multifile((Entity::Name//Arity, ...))
     multifile([Entity::Name//Arity, ...])

     multifile(Module:Name//Arity)
     multifile((Module:Name//Arity, ...))
     multifile([Module:Name//Arity, ...])

Declares *note multifile: 16b. predicates and multifile grammar rule
non-terminals.  In the case of object or category multifile predicates,
the predicate (or non-terminal) must also have a *note scope directive:
1e4. in the object or category holding its 'primary declaration' (i.e.,
the declaration without the ‘Entity::’ prefix).  Entities holding
multifile predicate primary declarations must be compiled and loaded
prior to any entities contributing with clauses for the multifile
predicates (to prevent using multifile predicates to break entity
encapsulation).

Protocols cannot declare or define multifile predicates as protocols
cannot contain predicate definitions.

     Warning: Some backend Prolog compilers declare the atom ‘multifile’
     as an operator for a lighter syntax.  But this makes the code
     non-portable and is therefore a practice best avoided.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<31>,  Next: Examples<39>,  Prev: Description<38>,  Up: multifile/1

2.3.4.39 Template and modes
...........................

     multifile(+qualified_predicate_indicator_term)
     multifile(+qualified_non_terminal_indicator_term)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<39>,  Prev: Template and modes<31>,  Up: multifile/1

2.3.4.40 Examples
.................

     :- multifile(table/3).
     :- multifile(user::hook/2).

See also
........

*note public/1: 143, *note protected/1: 144, *note private/1: 145, *note
predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: private/1,  Next: protected/1,  Prev: multifile/1,  Up: Predicate directives<2>

2.3.4.41 ‘private/1’
....................

* Menu:

* Description: Description<39>.
* Template and modes: Template and modes<32>.
* Examples: Examples<40>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<39>,  Next: Template and modes<32>,  Up: private/1

2.3.4.42 Description
....................

     private(Name/Arity)
     private((Name/Arity, ...))
     private([Name/Arity, ...])

     private(Name//Arity)
     private((Name//Arity, ...))
     private([Name//Arity, ...])


     private(op(Precedence,Associativity,Operator))
     private((op(Precedence,Associativity,Operator), ...))
     private([op(Precedence,Associativity,Operator), ...])

Declares *note private: 55. predicates, private grammar rule
non-terminals, and private operators.  A private predicate can only be
called from the object containing the private directive.  A private
non-terminal can only be used in a call of the *note phrase/2: 18e. and
*note phrase/3: 18f. methods from the object containing the private
directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<32>,  Next: Examples<40>,  Prev: Description<39>,  Up: private/1

2.3.4.43 Template and modes
...........................

     private(+predicate_indicator_term)
     private(+non_terminal_indicator_term)
     private(+operator_declaration)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<40>,  Prev: Template and modes<32>,  Up: private/1

2.3.4.44 Examples
.................

     :- private(counter/1).

     :- private((init/1, free/1)).

     :- private([data/3, key/1, keys/1]).

See also
........

*note protected/1: 144, *note public/1: 143, *note predicate_property/2:
142.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: protected/1,  Next: public/1,  Prev: private/1,  Up: Predicate directives<2>

2.3.4.45 ‘protected/1’
......................

* Menu:

* Description: Description<40>.
* Template and modes: Template and modes<33>.
* Examples: Examples<41>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<40>,  Next: Template and modes<33>,  Up: protected/1

2.3.4.46 Description
....................

     protected(Name/Arity)
     protected((Name/Arity, ...))
     protected([Name/Arity, ...])

     protected(Name//Arity)
     protected((Name//Arity, ...))
     protected([Name//Arity, ...])

     protected(op(Precedence,Associativity,Operator))
     protected((op(Precedence,Associativity,Operator), ...))
     protected([op(Precedence,Associativity,Operator), ...])

Declares *note protected: 54. predicates, protected grammar rule
non-terminals, and protected operators.  A protected predicate can only
be called from the object containing the directive or from an object
that inherits the directive.  A protected non-terminal can only be used
as an argument in a *note phrase/2: 18e. and *note phrase/3: 18f. calls
from the object containing the directive or from an object that inherits
the directive.

     Note: Protected operators are not inherited but declaring them
     provides a reusable specification for using them in descendant
     objects (or categories).


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<33>,  Next: Examples<41>,  Prev: Description<40>,  Up: protected/1

2.3.4.47 Template and modes
...........................

     protected(+predicate_indicator_term)
     protected(+non_terminal_indicator_term)
     protected(+operator_declaration)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<41>,  Prev: Template and modes<33>,  Up: protected/1

2.3.4.48 Examples
.................

     :- protected(init/1).

     :- protected((print/2, convert/4)).

     :- protected([load/1, save/3]).

See also
........

*note private/1: 145, *note public/1: 143, *note predicate_property/2:
142.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: public/1,  Next: synchronized/1,  Prev: protected/1,  Up: Predicate directives<2>

2.3.4.49 ‘public/1’
...................

* Menu:

* Description: Description<41>.
* Template and modes: Template and modes<34>.
* Examples: Examples<42>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<41>,  Next: Template and modes<34>,  Up: public/1

2.3.4.50 Description
....................

     public(Name/Arity)
     public((Name/Arity, ...))
     public([Name/Arity, ...])

     public(Name//Arity)
     public((Name//Arity, ...))
     public([Name//Arity, ...])

     public(op(Precedence,Associativity,Operator))
     public((op(Precedence,Associativity,Operator), ...))
     public([op(Precedence,Associativity,Operator), ...])

Declares *note public: 53. predicates, public grammar rule
non-terminals, and public operators.  A public predicate can be called
from any object.  A public non-terminal can be used as an argument in
*note phrase/2: 18e. and *note phrase/3: 18f. calls from any object.

     Note: Declaring a public operator does not make it global when the
     entity holding the scope directive is compiled and loaded.  But
     declaring public operators provides a reusable specification for
     using them in the entity clients (e.g., in *note uses/2: 4b.
     directives).


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<34>,  Next: Examples<42>,  Prev: Description<41>,  Up: public/1

2.3.4.51 Template and modes
...........................

     public(+predicate_indicator_term)
     public(+non_terminal_indicator_term)
     public(+operator_declaration)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<42>,  Prev: Template and modes<34>,  Up: public/1

2.3.4.52 Examples
.................

     :- public(ancestor/1).

     :- public((instance/1, instances/1)).

     :- public([leaf/1, leaves/1]).

See also
........

*note private/1: 145, *note protected/1: 144, *note
predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: synchronized/1,  Next: uses/2,  Prev: public/1,  Up: Predicate directives<2>

2.3.4.53 ‘synchronized/1’
.........................

* Menu:

* Description: Description<42>.
* Template and modes: Template and modes<35>.
* Examples: Examples<43>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<42>,  Next: Template and modes<35>,  Up: synchronized/1

2.3.4.54 Description
....................

     synchronized(Name/Arity)
     synchronized((Name/Arity, ...))
     synchronized([Name/Arity, ...])

     synchronized(Name//Arity)
     synchronized((Name//Arity, ...))
     synchronized([Name//Arity, ...])

Declares *note synchronized: 175. predicates and synchronized grammar
rule non-terminals.  The most common use is for predicates that have
side effects (e.g., asserting or retracting clauses for a dynamic
predicate) in multi-threaded applications.  A synchronized predicate (or
synchronized non-terminal) is protected by a mutex in order to allow for
thread synchronization when proving a call to the predicate (or
non-terminal).

All predicates (and non-terminals) declared in the same synchronized
directive share the same mutex.  In order to use a separate mutex for
each predicate (non-terminal) so that they are independently
synchronized, a per-predicate synchronized directive must be used.

     Warning: Declaring a predicate synchronized implicitly makes it
     'deterministic'.  When using a single-threaded *note backend Prolog
     compiler: 34, calls to synchronized predicates behave as wrapped by
     the standard *note once/1: 1bb. meta-predicate.

Note that synchronized predicates cannot be declared *note dynamic: 15a.
(when necessary, declare the predicates updating the dynamic predicates
as synchronized).


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<35>,  Next: Examples<43>,  Prev: Description<42>,  Up: synchronized/1

2.3.4.55 Template and modes
...........................

     synchronized(+predicate_indicator_term)
     synchronized(+non_terminal_indicator_term)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<43>,  Prev: Template and modes<35>,  Up: synchronized/1

2.3.4.56 Examples
.................

     :- synchronized(db_update/1).

     :- synchronized((write_stream/2, read_stream/2)).

     :- synchronized([add_to_queue/2, remove_from_queue/2]).

See also
........

*note predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: uses/2,  Next: use_module/2,  Prev: synchronized/1,  Up: Predicate directives<2>

2.3.4.57 ‘uses/2’
.................

* Menu:

* Description: Description<43>.
* Template and modes: Template and modes<36>.
* Examples: Examples<44>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<43>,  Next: Template and modes<36>,  Up: uses/2

2.3.4.58 Description
....................

     uses(Object, [Name/Arity, ...])
     uses(Object, [Name/Arity as Alias/Arity, ...])

     uses(Object, [Predicate as Alias, ...])

     uses(Object, [Name//Arity, ...])
     uses(Object, [Name//Arity as Alias//Arity, ...])

     uses(Object, [op(Precedence, Associativity, Operator), ...])

Declares that all calls made from predicates (or non-terminals) defined
in the category or object containing the directive to the specified
predicates (or non-terminals) are to be interpreted as messages to the
specified object.  Thus, this directive may be used to simplify writing
of predicate definitions by allowing the programmer to omit the
‘Object::’ prefix when using the predicates listed in the directive (as
long as the calls do not occur as arguments for non-standard Prolog
meta-predicates not declared in the adapter files).  It is also possible
to include operator declarations in the second argument.

This directive is also taken into account when compiling calls to the
*note database: 1af. and *note reflection: 1c4. built-in methods by
looking into these methods predicate arguments if bound at compile-time.

It is possible to specify a predicate alias using the notation
‘Name/Arity as Alias/Arity’ or, in alternative, the notation
‘Name/Arity::Alias/Arity’.  Aliases may be used to avoid conflicts
between predicates specified in ‘use_module/2’ and ‘uses/2’ directives,
for giving more meaningful names considering the calling context of the
predicates, and to change the order of the predicate arguments when
calling the predicate.  For predicates, it is also possible to define
alias shorthands using the notation ‘Predicate as Alias’ or, in
alternative, the notation ‘Predicate::Alias’, where ‘Predicate’ and
‘Alias’ are callable terms where some or all arguments may be
instantiated.

To enable the use of *note static binding: 35, and thus optimal
message-sending performance, the objects should be loaded before
compiling the entities that call their predicates.

The object identifier argument can also be a *note parameter variable:
a1. when using the directive in a parametric object or a parametric
category defined in a source file (the common case).  In this case,
*note dynamic binding: 36. will be used for all listed predicates (and
non-terminals).  The parameter variable must be instantiated at runtime
when the messages are sent.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<36>,  Next: Examples<44>,  Prev: Description<43>,  Up: uses/2

2.3.4.59 Template and modes
...........................

     uses(+object_identifier, +predicate_indicator_list)
     uses(+object_identifier, +predicate_indicator_alias_list)

     uses(+object_identifier, +predicate_template_alias_list)

     uses(+object_identifier, +non_terminal_indicator_list)
     uses(+object_identifier, +non_terminal_indicator_alias_list)

     uses(+object_identifier, +operator_list)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<44>,  Prev: Template and modes<36>,  Up: uses/2

2.3.4.60 Examples
.................

     :- uses(list,  [append/3, member/2]).
     :- uses(store, [data/2]).
     :- uses(user,  [table/4]).

     foo :-
         ...,
         % the same as findall(X, list::member(X, L), A)
         findall(X, member(X, L), A),
         % the same as list::append(A, B, C)
         append(A, B, C),
         % the same as store::assertz(data(X, C))
         assertz(data(X, C)),
         % call the table/4 predicate in "user"
         table(X, Y, Z, T),
         ...

Another example, using the extended notation that allows us to define
predicate aliases:

     :- uses(btrees, [new/1 as new_btree/1]).
     :- uses(queues, [new/1 as new_queue/1]).

     btree_to_queue :-
         ...,
         % the same as btrees::new(Tree)
         new_btree(Tree),
         % the same as queues::new(Queue)
         new_queue(Queue),
         ...

An example of defining a predicate alias that is also a shorthand:

     :- uses(logtalk, [
         print_message(debug, my_app, Message) as dbg(Message)
     ]).

Predicate aliases can also be used to change argument order:

     :- uses(meta, [
         fold_left(Closure,Accumulator,List,Result) as foldl(Closure,List,Accumulator,Result)
     ]).

An example of using a *note parameter variable: a1. in place of the
object identifier to allow using the same test set for checking multiple
implementations of the same protocol:

     :- object(tests(_HeapObject_),
         extends(lgtunit)).

         :- uses(_HeapObject_, [
             as_heap/2, as_list/2, valid/1, new/1,
             insert/4, insert_all/3, delete/4, merge/3,
             empty/1, size/2, top/3, top_next/5
         ]).

See also
........

*note uses/1: 4a, *note use_module/1: 4c, *note use_module/2: 4d, *note
alias/2: 165.

'directive'


File: TheLogtalkHandbook-3.96.0.info,  Node: use_module/2,  Prev: uses/2,  Up: Predicate directives<2>

2.3.4.61 ‘use_module/2’
.......................

* Menu:

* Description: Description<44>.
* Template and modes: Template and modes<37>.
* Examples: Examples<45>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<44>,  Next: Template and modes<37>,  Up: use_module/2

2.3.4.62 Description
....................

     use_module(Module, [Name/Arity, ...])
     use_module(Module, [Name/Arity as Alias/Arity, ...])

     use_module(Module, [Predicate as Alias, ...])

     use_module(Module, [Name//Arity, ...])
     use_module(Module, [Name//Arity as Alias//Arity, ...])

     use_module(Module, [op(Precedence,Associativity,Operator), ...])

This directive declares that all calls (made from predicates defined in
the category or object containing the directive) to the specified
predicates (or non-terminals) are to be interpreted as calls to
explicitly-qualified module predicates (or non-terminals).  Thus, this
directive may be used to simplify the writing of predicate definitions
by allowing the programmer to omit the ‘Module:’ prefix when using the
predicates listed in the directive (as long as the predicate calls do
not occur as arguments for non-standard Prolog meta-predicates not
declared on the adapter files).  It is also possible to include operator
declarations in the second argument.

This directive is also taken into account when compiling calls to the
*note database: 1af. and *note reflection: 1c4. built-in methods by
looking into these methods predicate arguments if bound at compile-time.

It is possible to specify a predicate alias using the notation
‘Name/Arity as Alias/Arity’ or, in alternative, the notation
‘Name/Arity:Alias/Arity’.  Aliases may be used either for avoiding
conflicts between predicates specified in ‘use_module/2’ and *note
uses/2: 4b. directives or for giving more meaningful names considering
the calling context of the predicates.  For predicates, it is also
possible to define alias shorthands using the notation ‘Predicate as
Alias’ or, in alternative, the notation ‘Predicate::Alias’, where
‘Predicate’ and ‘Alias’ are callable terms where some or all arguments
may be instantiated.

Note that this directive differs from the directive with the same name
found on some Prolog implementations by requiring the first argument to
be a module name (an atom) instead of a file specification.  In Logtalk,
there’s no mixing between 'loading' a resource and (declaring the)
'using' (of) a resource.  As a consequence, this directive doesn’t
automatically load the module.  Loading the module file is dependent on
the used *note backend Prolog compiler: 34. and must be done separately
(usually, using a source file directive such as ‘use_module/1’ or
‘use_module/2’ in the entity file or preferably in the application *note
loader file: 4f. file).  Also, note that the name of the module may
differ from the name of the module file.

     Warning: The modules 'must' be loaded prior to the compilation of
     entities that call the module predicates.  This is required in
     general to allow the compiler to check if the called module
     predicate is a meta-predicate and retrieve its meta-predicate
     template to ensure proper call compilation.

The module identifier argument can also be a *note parameter variable:
a1. when using the directive in a parametric object or a parametric
category defined in a source file (the common case).  In this case,
*note dynamic binding: 36. will be used for all listed predicates (and
non-terminals).  The parameter variable must be instantiated at runtime
when the calls are made.


File: TheLogtalkHandbook-3.96.0.info,  Node: Template and modes<37>,  Next: Examples<45>,  Prev: Description<44>,  Up: use_module/2

2.3.4.63 Template and modes
...........................

     use_module(+module_identifier, +predicate_indicator_list)
     use_module(+module_identifier, +module_predicate_indicator_alias_list)

     use_module(+module_identifier, +predicate_template_alias_list)

     use_module(+module_identifier, +non_terminal_indicator_list)
     use_module(+module_identifier, +module_non_terminal_indicator_alias_list)

     use_module(+module_identifier, +operator_list)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<45>,  Prev: Template and modes<37>,  Up: use_module/2

2.3.4.64 Examples
.................

     :- use_module(lists, [append/3, member/2]).
     :- use_module(store, [data/2]).
     :- use_module(user,  [foo/1 as bar/1]).

     foo :-
         ...,
         % same as findall(X, lists:member(X, L), A)
         findall(X, member(X, L), A),
         % same as lists:append(A, B, C)
         append(A, B, C),
         % same as assertz(store:data(X, C))
         assertz(data(X, C)),
         % same as retractall(user:foo(_))
         retractall(bar(_)),
         ...

Another example, using the extended notation that allows us to define
predicate aliases:

     :- use_module(ugraphs, [transpose_ugraph/2 as transpose/2]).

     convert_graph :-
         ...,
         % the same as ugraphs:transpose_ugraph(Graph0, Graph)
         transpose(Graph0, Graph),
         ...

An example of defining a predicate alias that is also a shorthand:

     :- use_module(pairs, [
         map_list_to_pairs(length, Lists, Pairs) as length_pairs(Lists, Pairs)
     ]).

An example of using a *note parameter variable: a1. in place of the
module identifier to delay to runtime the actual module to use:

     :- object(bar(_OptionsModule_)).

         :- use_module(_OptionsModule_, [
             set/2, get/2, reset/0
         ]).

See also
........

*note use_module/1: 4c, *note uses/2: 4b, *note uses/1: 4a, *note
alias/2: 165.


File: TheLogtalkHandbook-3.96.0.info,  Node: Built-in predicates,  Next: Built-in methods<2>,  Prev: Directives<2>,  Up: Reference Manual

2.4 Built-in predicates
=======================

* Menu:

* Enumerating objects, categories and protocols: Enumerating objects categories and protocols.
* Enumerating objects, categories and protocols properties: Enumerating objects categories and protocols properties.
* Creating new objects, categories and protocols: Creating new objects categories and protocols.
* Abolishing objects, categories and protocols: Abolishing objects categories and protocols.
* Objects, categories, and protocols relations: Objects categories and protocols relations.
* Event handling: Event handling<2>.
* Multi-threading::
* Multi-threading engines::
* Compiling and loading source files::
* Flags::
* Linter::


File: TheLogtalkHandbook-3.96.0.info,  Node: Enumerating objects categories and protocols,  Next: Enumerating objects categories and protocols properties,  Up: Built-in predicates

2.4.1 Enumerating objects, categories and protocols
---------------------------------------------------

'built-in predicate'

* Menu:

* current_category/1::
* current_object/1::
* current_protocol/1::


File: TheLogtalkHandbook-3.96.0.info,  Node: current_category/1,  Next: current_object/1,  Up: Enumerating objects categories and protocols

2.4.1.1 ‘current_category/1’
............................

* Menu:

* Description: Description<45>.
* Modes and number of proofs: Modes and number of proofs<8>.
* Errors: Errors<9>.
* Examples: Examples<46>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<45>,  Next: Modes and number of proofs<8>,  Up: current_category/1

2.4.1.2 Description
...................

     current_category(Category)

Enumerates, by backtracking, all currently defined categories.  All
categories are found, either static, dynamic, or built-in.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<8>,  Next: Errors<9>,  Prev: Description<45>,  Up: current_category/1

2.4.1.3 Modes and number of proofs
..................................

     current_category(?category_identifier) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<9>,  Next: Examples<46>,  Prev: Modes and number of proofs<8>,  Up: current_category/1

2.4.1.4 Errors
..............

     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Category)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<46>,  Prev: Errors<9>,  Up: current_category/1

2.4.1.5 Examples
................

     % enumerate the defined categories:
     | ?- current_category(Category).

     Category = core_messages ;
     ...

See also
........

*note abolish_category/1: f5, *note category_property/2: 12c, *note
create_category/4: 11a, *note complements_object/2: c3, *note
extends_category/2-3: 129, *note imports_category/2-3: c0.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: current_object/1,  Next: current_protocol/1,  Prev: current_category/1,  Up: Enumerating objects categories and protocols

2.4.1.6 ‘current_object/1’
..........................

* Menu:

* Description: Description<46>.
* Modes and number of proofs: Modes and number of proofs<9>.
* Errors: Errors<10>.
* Examples: Examples<47>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<46>,  Next: Modes and number of proofs<9>,  Up: current_object/1

2.4.1.7 Description
...................

     current_object(Object)

Enumerates, by backtracking, all currently defined objects.  All objects
are found, either static, dynamic or built-in.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<9>,  Next: Errors<10>,  Prev: Description<46>,  Up: current_object/1

2.4.1.8 Modes and number of proofs
..................................

     current_object(?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<10>,  Next: Examples<47>,  Prev: Modes and number of proofs<9>,  Up: current_object/1

2.4.1.9 Errors
..............

     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<47>,  Prev: Errors<10>,  Up: current_object/1

2.4.1.10 Examples
.................

     % enumerate the defined objects:
     | ?- current_object(Object).

     Object = user ;
     Object = logtalk ;
     ...

See also
........

*note abolish_object/1: 64, *note create_object/4: 62, *note
object_property/2: c6, *note extends_object/2-3: bf, *note
instantiates_class/2-3: bd, *note specializes_class/2-3: be, *note
complements_object/2: c3.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: current_protocol/1,  Prev: current_object/1,  Up: Enumerating objects categories and protocols

2.4.1.11 ‘current_protocol/1’
.............................

* Menu:

* Description: Description<47>.
* Modes and number of proofs: Modes and number of proofs<10>.
* Errors: Errors<11>.
* Examples: Examples<48>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<47>,  Next: Modes and number of proofs<10>,  Up: current_protocol/1

2.4.1.12 Description
....................

     current_protocol(Protocol)

Enumerates, by backtracking, all currently defined protocols.  All
protocols are found, either static, dynamic, or built-in.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<10>,  Next: Errors<11>,  Prev: Description<47>,  Up: current_protocol/1

2.4.1.13 Modes and number of proofs
...................................

     current_protocol(?protocol_identifier) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<11>,  Next: Examples<48>,  Prev: Modes and number of proofs<10>,  Up: current_protocol/1

2.4.1.14 Errors
...............

     ‘Protocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Protocol)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<48>,  Prev: Errors<11>,  Up: current_protocol/1

2.4.1.15 Examples
.................

     % enumerate the defined protocols:
     | ?- current_protocol(Protocol).

     Protocol = expanding ;
     Protocol = monitoring ;
     Protocol = forwarding ;
     ...

See also
........

*note abolish_protocol/1: e6, *note create_protocol/3: e3, *note
protocol_property/2: f4, *note conforms_to_protocol/2-3: c2, *note
extends_protocol/2-3: f0, *note implements_protocol/2-3: c1.


File: TheLogtalkHandbook-3.96.0.info,  Node: Enumerating objects categories and protocols properties,  Next: Creating new objects categories and protocols,  Prev: Enumerating objects categories and protocols,  Up: Built-in predicates

2.4.2 Enumerating objects, categories and protocols properties
--------------------------------------------------------------

'built-in predicate'

* Menu:

* category_property/2::
* object_property/2::
* protocol_property/2::


File: TheLogtalkHandbook-3.96.0.info,  Node: category_property/2,  Next: object_property/2,  Up: Enumerating objects categories and protocols properties

2.4.2.1 ‘category_property/2’
.............................

* Menu:

* Description: Description<48>.
* Modes and number of proofs: Modes and number of proofs<11>.
* Errors: Errors<12>.
* Examples: Examples<49>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<48>,  Next: Modes and number of proofs<11>,  Up: category_property/2

2.4.2.2 Description
...................

     category_property(Category, Property)

Enumerates, by backtracking, the properties associated with the defined
categories.  The valid properties are listed in the language grammar
section on *note entity properties: c8. and described in the User Manual
section on *note category properties: 12a.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<11>,  Next: Errors<12>,  Prev: Description<48>,  Up: category_property/2

2.4.2.3 Modes and number of proofs
..................................

     category_property(?category_identifier, ?category_property) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<12>,  Next: Examples<49>,  Prev: Modes and number of proofs<11>,  Up: category_property/2

2.4.2.4 Errors
..............

     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Category)’
          
     ‘Property’ is neither a variable nor a callable term:
          ‘type_error(callable, Property)’
     ‘Property’ is a callable term but not a valid category property:
          ‘domain_error(category_property, Property)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<49>,  Prev: Errors<12>,  Up: category_property/2

2.4.2.5 Examples
................

     % enumerate the properties of the core_messages built-in category:
     | ?- category_property(core_messages, Property).

     Property = source_data ;
     Property = static ;
     Property = built_in ;
     ...

See also
........

*note abolish_category/1: f5, *note create_category/4: 11a, *note
current_category/1: f1, *note complements_object/2: c3, *note
extends_category/2-3: 129, *note imports_category/2-3: c0.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: object_property/2,  Next: protocol_property/2,  Prev: category_property/2,  Up: Enumerating objects categories and protocols properties

2.4.2.6 ‘object_property/2’
...........................

* Menu:

* Description: Description<49>.
* Modes and number of proofs: Modes and number of proofs<12>.
* Errors: Errors<13>.
* Examples: Examples<50>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<49>,  Next: Modes and number of proofs<12>,  Up: object_property/2

2.4.2.7 Description
...................

     object_property(Object, Property)

Enumerates, by backtracking, the properties associated with the defined
objects.  The valid properties are listed in the language grammar
section on *note entity properties: c8. and described in the User Manual
section on *note object properties: c5.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<12>,  Next: Errors<13>,  Prev: Description<49>,  Up: object_property/2

2.4.2.8 Modes and number of proofs
..................................

     object_property(?object_identifier, ?object_property) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<13>,  Next: Examples<50>,  Prev: Modes and number of proofs<12>,  Up: object_property/2

2.4.2.9 Errors
..............

     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Property’ is neither a variable nor a callable term:
          ‘type_error(callable, Property)’
     ‘Property’ is a callable term but not a valid object property:
          ‘domain_error(object_property, Property)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<50>,  Prev: Errors<13>,  Up: object_property/2

2.4.2.10 Examples
.................

     % enumerate the properties of the logtalk built-in object:
     | ?- object_property(logtalk, Property).

     Property = context_switching_calls ;
     Property = source_data ;
     Property = threaded ;
     Property = static ;
     Property = built_in ;
     ...

See also
........

*note abolish_object/1: 64, *note create_object/4: 62, *note
current_object/1: a6, *note extends_object/2-3: bf, *note
instantiates_class/2-3: bd, *note specializes_class/2-3: be, *note
complements_object/2: c3.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: protocol_property/2,  Prev: object_property/2,  Up: Enumerating objects categories and protocols properties

2.4.2.11 ‘protocol_property/2’
..............................

* Menu:

* Description: Description<50>.
* Modes and number of proofs: Modes and number of proofs<13>.
* Errors: Errors<14>.
* Examples: Examples<51>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<50>,  Next: Modes and number of proofs<13>,  Up: protocol_property/2

2.4.2.12 Description
....................

     protocol_property(Protocol, Property)

Enumerates, by backtracking, the properties associated with the
currently defined protocols.  The valid properties are listed in the
language grammar section on *note entity properties: c8. and described
in the User Manual section on *note protocol properties: f3.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<13>,  Next: Errors<14>,  Prev: Description<50>,  Up: protocol_property/2

2.4.2.13 Modes and number of proofs
...................................

     protocol_property(?protocol_identifier, ?protocol_property) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<14>,  Next: Examples<51>,  Prev: Modes and number of proofs<13>,  Up: protocol_property/2

2.4.2.14 Errors
...............

     ‘Protocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Protocol)’
     ‘Property’ is neither a variable nor a callable term:
          ‘type_error(callable, Property)’
     ‘Property’ is a callable term but not a valid protocol property:
          ‘domain_error(protocol_property, Property)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<51>,  Prev: Errors<14>,  Up: protocol_property/2

2.4.2.15 Examples
.................

     % enumerate the properties of the monitoring built-in protocol:
     | ?- protocol_property(monitoring, Property).

     Property = source_data ;
     Property = static ;
     Property = built_in ;
     ...

See also
........

*note abolish_protocol/1: e6, *note create_protocol/3: e3, *note
current_protocol/1: e0, *note conforms_to_protocol/2-3: c2, *note
extends_protocol/2-3: f0, *note implements_protocol/2-3: c1.


File: TheLogtalkHandbook-3.96.0.info,  Node: Creating new objects categories and protocols,  Next: Abolishing objects categories and protocols,  Prev: Enumerating objects categories and protocols properties,  Up: Built-in predicates

2.4.3 Creating new objects, categories and protocols
----------------------------------------------------

'built-in predicate'

* Menu:

* create_category/4::
* create_object/4::
* create_protocol/3::


File: TheLogtalkHandbook-3.96.0.info,  Node: create_category/4,  Next: create_object/4,  Up: Creating new objects categories and protocols

2.4.3.1 ‘create_category/4’
...........................

* Menu:

* Description: Description<51>.
* Modes and number of proofs: Modes and number of proofs<14>.
* Errors: Errors<15>.
* Examples: Examples<52>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<51>,  Next: Modes and number of proofs<14>,  Up: create_category/4

2.4.3.2 Description
...................

     create_category(Identifier, Relations, Directives, Clauses)

Creates a new, dynamic category.  This predicate is often used as a
primitive to implement high-level category creation methods.

Note that, when opting for runtime generated category identifiers, it’s
possible to run out of identifiers when using a *note backend Prolog
compiler: 34. with bounded integer support.  The portable solution, when
creating a large number of dynamic categories in long-running
applications, is to recycle, whenever possible, the identifiers.

When creating a new dynamic parametric category, access to the object
parameters must use the *note parameter/2: a2. built-in execution
context method.

When using Logtalk multi-threading features, predicates calling this
built-in predicate may need to be declared synchronized in order to
avoid race conditions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<14>,  Next: Errors<15>,  Prev: Description<51>,  Up: create_category/4

2.4.3.3 Modes and number of proofs
..................................

     create_category(?category_identifier, @list(category_relation), @list(category_directive), @list(clause)) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<15>,  Next: Examples<52>,  Prev: Modes and number of proofs<14>,  Up: create_category/4

2.4.3.4 Errors
..............

     ‘Relations’, ‘Directives’, or ‘Clauses’ is a variable:
          ‘instantiation_error’
     ‘Identifier’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Identifier)’
     ‘Identifier’ is already in use:
          ‘permission_error(modify, category, Identifier)’
          ‘permission_error(modify, object, Identifier)’
          ‘permission_error(modify, protocol, Identifier)’
     ‘Relations’ is neither a variable nor a proper list:
          ‘type_error(list, Relations)’
     Repeated entity relation clause:
          ‘permission_error(repeat, entity_relation, implements/1)’
          ‘permission_error(repeat, entity_relation, extends/1)’
          ‘permission_error(repeat, entity_relation, complements/1)’
     ‘Directives’ is neither a variable nor a proper list:
          ‘type_error(list, Directives)’
     ‘Clauses’ is neither a variable nor a proper list:
          ‘type_error(list, Clauses)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<52>,  Prev: Errors<15>,  Up: create_category/4

2.4.3.5 Examples
................

     | ?- create_category(
             tolerances,
             [implements(comparing)],
             [],
             [epsilon(1e-15), (equal(X, Y) :- epsilon(E), abs(X-Y) =< E)]
          ).

See also
........

*note abolish_category/1: f5, *note category_property/2: 12c, *note
current_category/1: f1, *note complements_object/2: c3, *note
extends_category/2-3: 129, *note imports_category/2-3: c0.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: create_object/4,  Next: create_protocol/3,  Prev: create_category/4,  Up: Creating new objects categories and protocols

2.4.3.6 ‘create_object/4’
.........................

* Menu:

* Description: Description<52>.
* Modes and number of proofs: Modes and number of proofs<15>.
* Errors: Errors<16>.
* Examples: Examples<53>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<52>,  Next: Modes and number of proofs<15>,  Up: create_object/4

2.4.3.7 Description
...................

     create_object(Identifier, Relations, Directives, Clauses)

Creates a new, dynamic object.  The word *note object: 533. is used here
as a generic term.  This predicate can be used to create new prototypes,
instances, and classes.  This predicate is often used as a primitive to
implement high-level object creation methods.

Note that, when opting for runtime generated object identifiers, it’s
possible to run out of identifiers when using a *note backend Prolog
compiler: 34. with bounded integer support.  The portable solution, when
creating a large number of dynamic objects in long-running applications,
is to recycle, whenever possible, the identifiers.

When creating a new dynamic parametric object, access to the object
parameters must use the *note parameter/2: a2. built-in execution
context method.

Declared predicates (using scope clauses in the ‘Directives’ argument)
are implicitly declared also as dynamic.

When using Logtalk multi-threading features, predicates calling this
built-in predicate may need to be declared synchronized in order to
avoid race conditions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<15>,  Next: Errors<16>,  Prev: Description<52>,  Up: create_object/4

2.4.3.8 Modes and number of proofs
..................................

     create_object(?object_identifier, @list(object_relation), @list(object_directive), @list(clause)) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<16>,  Next: Examples<53>,  Prev: Modes and number of proofs<15>,  Up: create_object/4

2.4.3.9 Errors
..............

     ‘Relations’, ‘Directives’, or ‘Clauses’ is a variable:
          ‘instantiation_error’
     ‘Identifier’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Identifier)’
     ‘Identifier’ is already in use:
          ‘permission_error(modify, category, Identifier)’
          ‘permission_error(modify, object, Identifier)’
          ‘permission_error(modify, protocol, Identifier)’
     ‘Relations’ is neither a variable nor a proper list:
          ‘type_error(list, Relations)’
     Repeated entity relation clause:
          ‘permission_error(repeat, entity_relation, implements/1)’
          ‘permission_error(repeat, entity_relation, imports/1)’
          ‘permission_error(repeat, entity_relation, extends/1)’
          ‘permission_error(repeat, entity_relation, instantiates/1)’
          ‘permission_error(repeat, entity_relation, specializes/1)’
     ‘Directives’ is neither a variable nor a proper list:
          ‘type_error(list, Directives)’
     ‘Clauses’ is neither a variable nor a proper list:
          ‘type_error(list, Clauses)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<53>,  Prev: Errors<16>,  Up: create_object/4

2.4.3.10 Examples
.................

     % create a stand-alone object (a prototype):
     | ?- create_object(
              translator,
              [],
              [public(int/2)],
              [int(0, zero)]
          ).

     % create a prototype derived from a parent prototype:
     | ?- create_object(
              mickey,
              [extends(mouse)],
              [public(alias/1)],
              [alias(mortimer)]
          ).

     % create a class instance:
     | ?- create_object(
              p1,
              [instantiates(person)],
              [],
              [name('Paulo Moura'), age(42)]
          ).

     % create a subclass:
     | ?- create_object(
              hovercraft,
              [specializes(vehicle)],
              [public([propeller/2, fan/2])],
              []
          ).

     % create an object with an initialization goal:
     | ?- create_object(
              runner,
              [instantiates(runners)],
              [initialization(::start)],
              [length(22), time(60)]
          ).

     % create an object supporting dynamic predicate declarations:
     | ?- create_object(
              database,
              [],
              [set_logtalk_flag(dynamic_declarations, allow)],
              []
          ).

See also
........

*note abolish_object/1: 64, *note current_object/1: a6, *note
object_property/2: c6, *note extends_object/2-3: bf, *note
instantiates_class/2-3: bd, *note specializes_class/2-3: be, *note
complements_object/2: c3.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: create_protocol/3,  Prev: create_object/4,  Up: Creating new objects categories and protocols

2.4.3.11 ‘create_protocol/3’
............................

* Menu:

* Description: Description<53>.
* Modes and number of proofs: Modes and number of proofs<16>.
* Errors: Errors<17>.
* Examples: Examples<54>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<53>,  Next: Modes and number of proofs<16>,  Up: create_protocol/3

2.4.3.12 Description
....................

     create_protocol(Identifier, Relations, Directives)

Creates a new, dynamic, protocol.  This predicate is often used as a
primitive to implement high-level protocol creation methods.

Note that, when opting for runtime generated protocol identifiers, it’s
possible to run out of identifiers when using a *note backend Prolog
compiler: 34. with bounded integer support.  The portable solution, when
creating a large number of dynamic protocols in long-running
applications, is to recycle, whenever possible, the identifiers.

When using Logtalk multi-threading features, predicates calling this
built-in predicate may need to be declared synchronized in order to
avoid race conditions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<16>,  Next: Errors<17>,  Prev: Description<53>,  Up: create_protocol/3

2.4.3.13 Modes and number of proofs
...................................

     create_protocol(?protocol_identifier, @list(protocol_relation), @list(protocol_directive)) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<17>,  Next: Examples<54>,  Prev: Modes and number of proofs<16>,  Up: create_protocol/3

2.4.3.14 Errors
...............

     Either ‘Relations’ or ‘Directives’ is a variable:
          ‘instantiation_error’
     ‘Identifier’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Identifier)’
     ‘Identifier’ is already in use:
          ‘permission_error(modify, category, Identifier)’
          ‘permission_error(modify, object, Identifier)’
          ‘permission_error(modify, protocol, Identifier)’
     ‘Relations’ is neither a variable nor a proper list:
          ‘type_error(list, Relations)’
     Repeated entity relation clause:
          ‘permission_error(repeat, entity_relation, extends/1)’
     ‘Directives’ is neither a variable nor a proper list:
          ‘type_error(list, Directives)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<54>,  Prev: Errors<17>,  Up: create_protocol/3

2.4.3.15 Examples
.................

     | ?- create_protocol(
             logging,
             [extends(monitoring)],
             [public([log_file/1, log_on/0, log_off/0])]
          ).

See also
........

*note abolish_protocol/1: e6, *note current_protocol/1: e0, *note
protocol_property/2: f4, *note conforms_to_protocol/2-3: c2, *note
extends_protocol/2-3: f0, *note implements_protocol/2-3: c1.


File: TheLogtalkHandbook-3.96.0.info,  Node: Abolishing objects categories and protocols,  Next: Objects categories and protocols relations,  Prev: Creating new objects categories and protocols,  Up: Built-in predicates

2.4.4 Abolishing objects, categories and protocols
--------------------------------------------------

'built-in predicate'

* Menu:

* abolish_category/1::
* abolish_object/1::
* abolish_protocol/1::


File: TheLogtalkHandbook-3.96.0.info,  Node: abolish_category/1,  Next: abolish_object/1,  Up: Abolishing objects categories and protocols

2.4.4.1 ‘abolish_category/1’
............................

* Menu:

* Description: Description<54>.
* Modes and number of proofs: Modes and number of proofs<17>.
* Errors: Errors<18>.
* Examples: Examples<55>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<54>,  Next: Modes and number of proofs<17>,  Up: abolish_category/1

2.4.4.2 Description
...................

     abolish_category(Category)

Abolishes a dynamic category.  The category identifier can then be
reused when creating a new category.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<17>,  Next: Errors<18>,  Prev: Description<54>,  Up: abolish_category/1

2.4.4.3 Modes and number of proofs
..................................

     abolish_category(+category_identifier) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<18>,  Next: Examples<55>,  Prev: Modes and number of proofs<17>,  Up: abolish_category/1

2.4.4.4 Errors
..............

     ‘Category’ is a variable:
          ‘instantiation_error’
     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Category)’
     ‘Category’ is an identifier of a static category:
          ‘permission_error(modify, static_category, Category)’
     ‘Category’ does not exist:
          ‘existence_error(category, Category)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<55>,  Prev: Errors<18>,  Up: abolish_category/1

2.4.4.5 Examples
................

     | ?- abolish_category(monitoring).

See also
........

*note category_property/2: 12c, *note create_category/4: 11a, *note
current_category/1: f1. *note complements_object/2: c3, *note
extends_category/2-3: 129, *note imports_category/2-3: c0.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: abolish_object/1,  Next: abolish_protocol/1,  Prev: abolish_category/1,  Up: Abolishing objects categories and protocols

2.4.4.6 ‘abolish_object/1’
..........................

* Menu:

* Description: Description<55>.
* Modes and number of proofs: Modes and number of proofs<18>.
* Errors: Errors<19>.
* Examples: Examples<56>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<55>,  Next: Modes and number of proofs<18>,  Up: abolish_object/1

2.4.4.7 Description
...................

     abolish_object(Object)

Abolishes a dynamic object.  The object identifier can then be reused
when creating a new object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<18>,  Next: Errors<19>,  Prev: Description<55>,  Up: abolish_object/1

2.4.4.8 Modes and number of proofs
..................................

     abolish_object(+object_identifier) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<19>,  Next: Examples<56>,  Prev: Modes and number of proofs<18>,  Up: abolish_object/1

2.4.4.9 Errors
..............

     ‘Object’ is a variable:
          ‘instantiation_error’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Object’ is an identifier of a static object:
          ‘permission_error(modify, static_object, Object)’
     ‘Object’ does not exist:
          ‘existence_error(object, Object)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<56>,  Prev: Errors<19>,  Up: abolish_object/1

2.4.4.10 Examples
.................

     | ?- abolish_object(list).

See also
........

*note create_object/4: 62, *note current_object/1: a6, *note
object_property/2: c6, *note extends_object/2-3: bf, *note
instantiates_class/2-3: bd, *note specializes_class/2-3: be, *note
complements_object/2: c3.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: abolish_protocol/1,  Prev: abolish_object/1,  Up: Abolishing objects categories and protocols

2.4.4.11 ‘abolish_protocol/1’
.............................

* Menu:

* Description: Description<56>.
* Modes and number of proofs: Modes and number of proofs<19>.
* Errors: Errors<20>.
* Examples: Examples<57>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<56>,  Next: Modes and number of proofs<19>,  Up: abolish_protocol/1

2.4.4.12 Description
....................

     abolish_protocol(Protocol)

Abolishes a dynamic protocol.  The protocol identifier can then be
reused when creating a new protocol.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<19>,  Next: Errors<20>,  Prev: Description<56>,  Up: abolish_protocol/1

2.4.4.13 Modes and number of proofs
...................................

     abolish_protocol(@protocol_identifier) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<20>,  Next: Examples<57>,  Prev: Modes and number of proofs<19>,  Up: abolish_protocol/1

2.4.4.14 Errors
...............

     ‘Protocol’ is a variable:
          ‘instantiation_error’
     ‘Protocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Protocol)’
     ‘Protocol’ is an identifier of a static protocol:
          ‘permission_error(modify, static_protocol, Protocol)’
     ‘Protocol’ does not exist:
          ‘existence_error(protocol, Protocol)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<57>,  Prev: Errors<20>,  Up: abolish_protocol/1

2.4.4.15 Examples
.................

     | ?- abolish_protocol(listp).

See also
........

*note create_protocol/3: e3, *note current_protocol/1: e0, *note
protocol_property/2: f4, *note conforms_to_protocol/2-3: c2, *note
extends_protocol/2-3: f0, *note implements_protocol/2-3: c1.


File: TheLogtalkHandbook-3.96.0.info,  Node: Objects categories and protocols relations,  Next: Event handling<2>,  Prev: Abolishing objects categories and protocols,  Up: Built-in predicates

2.4.5 Objects, categories, and protocols relations
--------------------------------------------------

'built-in predicate'

* Menu:

* extends_object/2-3::
* extends_protocol/2-3::
* extends_category/2-3::
* implements_protocol/2-3::
* conforms_to_protocol/2-3::
* complements_object/2::
* imports_category/2-3::
* instantiates_class/2-3::
* specializes_class/2-3::


File: TheLogtalkHandbook-3.96.0.info,  Node: extends_object/2-3,  Next: extends_protocol/2-3,  Up: Objects categories and protocols relations

2.4.5.1 ‘extends_object/2-3’
............................

* Menu:

* Description: Description<57>.
* Modes and number of proofs: Modes and number of proofs<20>.
* Errors: Errors<21>.
* Examples: Examples<58>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<57>,  Next: Modes and number of proofs<20>,  Up: extends_object/2-3

2.4.5.2 Description
...................

     extends_object(Prototype, Parent)
     extends_object(Prototype, Parent, Scope)

Enumerates, by backtracking, all pairs of objects such that the first
one extends the second.  The relation scope is represented by the atoms
‘public’, ‘protected’, and ‘private’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<20>,  Next: Errors<21>,  Prev: Description<57>,  Up: extends_object/2-3

2.4.5.3 Modes and number of proofs
..................................

     extends_object(?object_identifier, ?object_identifier) - zero_or_more
     extends_object(?object_identifier, ?object_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<21>,  Next: Examples<58>,  Prev: Modes and number of proofs<20>,  Up: extends_object/2-3

2.4.5.4 Errors
..............

     ‘Prototype’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Prototype)’
     ‘Parent’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Parent)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<58>,  Prev: Errors<21>,  Up: extends_object/2-3

2.4.5.5 Examples
................

     % enumerate objects derived from the state_space prototype:
     | ?- extends_object(Object, state_space).

     % enumerate objects publicly derived from the list prototype:
     | ?- extends_object(Object, list, public).

See also
........

*note current_object/1: a6, *note instantiates_class/2-3: bd, *note
specializes_class/2-3: be.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: extends_protocol/2-3,  Next: extends_category/2-3,  Prev: extends_object/2-3,  Up: Objects categories and protocols relations

2.4.5.6 ‘extends_protocol/2-3’
..............................

* Menu:

* Description: Description<58>.
* Modes and number of proofs: Modes and number of proofs<21>.
* Errors: Errors<22>.
* Examples: Examples<59>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<58>,  Next: Modes and number of proofs<21>,  Up: extends_protocol/2-3

2.4.5.7 Description
...................

     extends_protocol(Protocol, ParentProtocol)
     extends_protocol(Protocol, ParentProtocol, Scope)

Enumerates, by backtracking, all pairs of protocols such that the first
one extends the second.  The relation scope is represented by the atoms
‘public’, ‘protected’, and ‘private’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<21>,  Next: Errors<22>,  Prev: Description<58>,  Up: extends_protocol/2-3

2.4.5.8 Modes and number of proofs
..................................

     extends_protocol(?protocol_identifier, ?protocol_identifier) - zero_or_more
     extends_protocol(?protocol_identifier, ?protocol_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<22>,  Next: Examples<59>,  Prev: Modes and number of proofs<21>,  Up: extends_protocol/2-3

2.4.5.9 Errors
..............

     ‘Protocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Protocol)’
     ‘ParentProtocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, ParentProtocol)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<59>,  Prev: Errors<22>,  Up: extends_protocol/2-3

2.4.5.10 Examples
.................

     % enumerate the protocols extended by the listp protocol:
     | ?- extends_protocol(listp, Protocol).

     % enumerate protocols that privately extend the termp protocol:
     | ?- extends_protocol(Protocol, termp, private).

See also
........

*note current_protocol/1: e0, *note implements_protocol/2-3: c1, *note
conforms_to_protocol/2-3: c2.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: extends_category/2-3,  Next: implements_protocol/2-3,  Prev: extends_protocol/2-3,  Up: Objects categories and protocols relations

2.4.5.11 ‘extends_category/2-3’
...............................

* Menu:

* Description: Description<59>.
* Modes and number of proofs: Modes and number of proofs<22>.
* Errors: Errors<23>.
* Examples: Examples<60>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<59>,  Next: Modes and number of proofs<22>,  Up: extends_category/2-3

2.4.5.12 Description
....................

     extends_category(Category, ParentCategory)
     extends_category(Category, ParentCategory, Scope)

Enumerates, by backtracking, all pairs of categories such that the first
one extends the second.  The relation scope is represented by the atoms
‘public’, ‘protected’, and ‘private’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<22>,  Next: Errors<23>,  Prev: Description<59>,  Up: extends_category/2-3

2.4.5.13 Modes and number of proofs
...................................

     extends_category(?category_identifier, ?category_identifier) - zero_or_more
     extends_category(?category_identifier, ?category_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<23>,  Next: Examples<60>,  Prev: Modes and number of proofs<22>,  Up: extends_category/2-3

2.4.5.14 Errors
...............

     ‘Category’ is neither a variable nor a valid protocol identifier:
          ‘type_error(category_identifier, Category)’
     ‘ParentCategory’ is neither a variable nor a valid protocol identifier:
          ‘type_error(category_identifier, ParentCategory)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<60>,  Prev: Errors<23>,  Up: extends_category/2-3

2.4.5.15 Examples
.................

     % enumerate the categories extended by the derailleur category:
     | ?- extends_category(derailleur, Category).

     % enumerate categories that privately extend the basics category:
     | ?- extends_category(Category, basics, private).

See also
........

*note current_category/1: f1, *note complements_object/2: c3, *note
imports_category/2-3: c0.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: implements_protocol/2-3,  Next: conforms_to_protocol/2-3,  Prev: extends_category/2-3,  Up: Objects categories and protocols relations

2.4.5.16 ‘implements_protocol/2-3’
..................................

* Menu:

* Description: Description<60>.
* Modes and number of proofs: Modes and number of proofs<23>.
* Errors: Errors<24>.
* Examples: Examples<61>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<60>,  Next: Modes and number of proofs<23>,  Up: implements_protocol/2-3

2.4.5.17 Description
....................

     implements_protocol(Object, Protocol)
     implements_protocol(Category, Protocol)

     implements_protocol(Object, Protocol, Scope)
     implements_protocol(Category, Protocol, Scope)

Enumerates, by backtracking, all pairs of entities such that an object
or a category implements a protocol.  The relation scope is represented
by the atoms ‘public’, ‘protected’, and ‘private’.  This predicate only
returns direct implementation relations.  For a transitive closure, see
the *note conforms_to_protocol/2-3: c2. predicate.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<23>,  Next: Errors<24>,  Prev: Description<60>,  Up: implements_protocol/2-3

2.4.5.18 Modes and number of proofs
...................................

     implements_protocol(?object_identifier, ?protocol_identifier) - zero_or_more
     implements_protocol(?category_identifier, ?protocol_identifier) - zero_or_more

     implements_protocol(?object_identifier, ?protocol_identifier, ?scope) - zero_or_more
     implements_protocol(?category_identifier, ?protocol_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<24>,  Next: Examples<61>,  Prev: Modes and number of proofs<23>,  Up: implements_protocol/2-3

2.4.5.19 Errors
...............

     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Category)’
     ‘Protocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Protocol)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<61>,  Prev: Errors<24>,  Up: implements_protocol/2-3

2.4.5.20 Examples
.................

     % check that the list object implements the listp protocol:
     | ?- implements_protocol(list, listp).

     % check that the list object publicly implements the listp protocol:
     | ?- implements_protocol(list, listp, public).

     % enumerate only objects that implement the listp protocol:
     | ?- current_object(Object), implements_protocol(Object, listp).

     % enumerate only categories that implement the serialization protocol:
     | ?- current_category(Category), implements_protocol(Category, serialization).

See also
........

*note current_object/1: a6, *note current_protocol/1: e0, *note
current_category/1: f1, *note conforms_to_protocol/2-3: c2.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: conforms_to_protocol/2-3,  Next: complements_object/2,  Prev: implements_protocol/2-3,  Up: Objects categories and protocols relations

2.4.5.21 ‘conforms_to_protocol/2-3’
...................................

* Menu:

* Description: Description<61>.
* Modes and number of proofs: Modes and number of proofs<24>.
* Errors: Errors<25>.
* Examples: Examples<62>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<61>,  Next: Modes and number of proofs<24>,  Up: conforms_to_protocol/2-3

2.4.5.22 Description
....................

     conforms_to_protocol(Object, Protocol)
     conforms_to_protocol(Category, Protocol)

     conforms_to_protocol(Object, Protocol, Scope)
     conforms_to_protocol(Category, Protocol, Scope)

Enumerates, by backtracking, all pairs of entities such that an object
or a category conforms to a protocol.  The relation scope is represented
by the atoms ‘public’, ‘protected’, and ‘private’.  This predicate
implements a transitive closure for the protocol implementation
relation.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<24>,  Next: Errors<25>,  Prev: Description<61>,  Up: conforms_to_protocol/2-3

2.4.5.23 Modes and number of proofs
...................................

     conforms_to_protocol(?object_identifier, ?protocol_identifier) - zero_or_more
     conforms_to_protocol(?category_identifier, ?protocol_identifier) - zero_or_more

     conforms_to_protocol(?object_identifier, ?protocol_identifier, ?scope) - zero_or_more
     conforms_to_protocol(?category_identifier, ?protocol_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<25>,  Next: Examples<62>,  Prev: Modes and number of proofs<24>,  Up: conforms_to_protocol/2-3

2.4.5.24 Errors
...............

     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Category)’
     ‘Protocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Protocol)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<62>,  Prev: Errors<25>,  Up: conforms_to_protocol/2-3

2.4.5.25 Examples
.................

     % enumerate objects and categories that conform to the listp protocol:
     | ?- conforms_to_protocol(Object, listp).

     % enumerate objects and categories that privately conform to the listp protocol:
     | ?- conforms_to_protocol(Object, listp, private).

     % enumerate only objects that conform to the listp protocol:
     | ?- current_object(Object), conforms_to_protocol(Object, listp).

     % enumerate only categories that conform to the serialization protocol:
     | ?- current_category(Category), conforms_to_protocol(Category, serialization).

See also
........

*note current_object/1: a6, *note current_protocol/1: e0, *note
current_category/1: f1, *note implements_protocol/2-3: c1.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: complements_object/2,  Next: imports_category/2-3,  Prev: conforms_to_protocol/2-3,  Up: Objects categories and protocols relations

2.4.5.26 ‘complements_object/2’
...............................

* Menu:

* Description: Description<62>.
* Modes and number of proofs: Modes and number of proofs<25>.
* Errors: Errors<26>.
* Examples: Examples<63>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<62>,  Next: Modes and number of proofs<25>,  Up: complements_object/2

2.4.5.27 Description
....................

     complements_object(Category, Object)

Enumerates, by backtracking, all category–object pairs such that the
category explicitly complements the object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<25>,  Next: Errors<26>,  Prev: Description<62>,  Up: complements_object/2

2.4.5.28 Modes and number of proofs
...................................

     complements_object(?category_identifier, ?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<26>,  Next: Examples<63>,  Prev: Modes and number of proofs<25>,  Up: complements_object/2

2.4.5.29 Errors
...............

     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Prototype)’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Parent)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<63>,  Prev: Errors<26>,  Up: complements_object/2

2.4.5.30 Examples
.................

     % check that the logging category complements the employee object:
     | ?- complements_object(logging, employee).

See also
........

*note current_category/1: f1, *note imports_category/2-3: c0.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: imports_category/2-3,  Next: instantiates_class/2-3,  Prev: complements_object/2,  Up: Objects categories and protocols relations

2.4.5.31 ‘imports_category/2-3’
...............................

* Menu:

* Description: Description<63>.
* Modes and number of proofs: Modes and number of proofs<26>.
* Errors: Errors<27>.
* Examples: Examples<64>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<63>,  Next: Modes and number of proofs<26>,  Up: imports_category/2-3

2.4.5.32 Description
....................

     imports_category(Object, Category)

     imports_category(Object, Category, Scope)

Enumerates, by backtracking, importation relations between objects and
categories.  The relation scope is represented by the atoms ‘public’,
‘protected’, and ‘private’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<26>,  Next: Errors<27>,  Prev: Description<63>,  Up: imports_category/2-3

2.4.5.33 Modes and number of proofs
...................................

     imports_category(?object_identifier, ?category_identifier) - zero_or_more
     imports_category(?object_identifier, ?category_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<27>,  Next: Examples<64>,  Prev: Modes and number of proofs<26>,  Up: imports_category/2-3

2.4.5.34 Errors
...............

     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Category)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<64>,  Prev: Errors<27>,  Up: imports_category/2-3

2.4.5.35 Examples
.................

     % check that the xref_diagram object imports the diagram category:
     | ?- imports_category(xref_diagram, diagram).

     % enumerate the objects that privately import the diagram category:
     | ?- imports_category(Object, diagram, private).

See also
........

*note current_category/1: f1, *note complements_object/2: c3.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: instantiates_class/2-3,  Next: specializes_class/2-3,  Prev: imports_category/2-3,  Up: Objects categories and protocols relations

2.4.5.36 ‘instantiates_class/2-3’
.................................

* Menu:

* Description: Description<64>.
* Modes and number of proofs: Modes and number of proofs<27>.
* Errors: Errors<28>.
* Examples: Examples<65>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<64>,  Next: Modes and number of proofs<27>,  Up: instantiates_class/2-3

2.4.5.37 Description
....................

     instantiates_class(Instance, Class)
     instantiates_class(Instance, Class, Scope)

Enumerates, by backtracking, all pairs of objects such that the first
one instantiates the second.  The relation scope is represented by the
atoms ‘public’, ‘protected’, and ‘private’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<27>,  Next: Errors<28>,  Prev: Description<64>,  Up: instantiates_class/2-3

2.4.5.38 Modes and number of proofs
...................................

     instantiates_class(?object_identifier, ?object_identifier) - zero_or_more
     instantiates_class(?object_identifier, ?object_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<28>,  Next: Examples<65>,  Prev: Modes and number of proofs<27>,  Up: instantiates_class/2-3

2.4.5.39 Errors
...............

     ‘Instance’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Instance)’
     ‘Class’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Class)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<65>,  Prev: Errors<28>,  Up: instantiates_class/2-3

2.4.5.40 Examples
.................

     % check that the water_jug is an instante of state_space:
     | ?- instantiates_class(water_jug, state_space).

     % enumerate the state_space instances where the
     % instantiation relation is public:
     | ?- instantiates_class(Space, state_space, public).

See also
........

*note current_object/1: a6, *note extends_object/2-3: bf, *note
specializes_class/2-3: be.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: specializes_class/2-3,  Prev: instantiates_class/2-3,  Up: Objects categories and protocols relations

2.4.5.41 ‘specializes_class/2-3’
................................

* Menu:

* Description: Description<65>.
* Modes and number of proofs: Modes and number of proofs<28>.
* Errors: Errors<29>.
* Examples: Examples<66>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<65>,  Next: Modes and number of proofs<28>,  Up: specializes_class/2-3

2.4.5.42 Description
....................

     specializes_class(Class, Superclass)
     specializes_class(Class, Superclass, Scope)

Enumerates, by backtracking, all pairs of objects such that the first
one specializes the second.  The relation scope is represented by the
atoms ‘public’, ‘protected’, and ‘private’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<28>,  Next: Errors<29>,  Prev: Description<65>,  Up: specializes_class/2-3

2.4.5.43 Modes and number of proofs
...................................

     specializes_class(?object_identifier, ?object_identifier) - zero_or_more
     specializes_class(?object_identifier, ?object_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<29>,  Next: Examples<66>,  Prev: Modes and number of proofs<28>,  Up: specializes_class/2-3

2.4.5.44 Errors
...............

     ‘Class’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Class)’
     ‘Superclass’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Superclass)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<66>,  Prev: Errors<29>,  Up: specializes_class/2-3

2.4.5.45 Examples
.................

     % enumerate the state_space subclasses:
     | ?- specializes_class(Subclass, state_space).

     % enumerate the state_space subclasses where the
     % specialization relation is public:
     | ?- specializes_class(Subclass, state_space, public).

See also
........

*note current_object/1: a6, *note extends_object/2-3: bf, *note
instantiates_class/2-3: bd.


File: TheLogtalkHandbook-3.96.0.info,  Node: Event handling<2>,  Next: Multi-threading,  Prev: Objects categories and protocols relations,  Up: Built-in predicates

2.4.6 Event handling
--------------------

'built-in predicate'

* Menu:

* abolish_events/5::
* current_event/5::
* define_events/5::


File: TheLogtalkHandbook-3.96.0.info,  Node: abolish_events/5,  Next: current_event/5,  Up: Event handling<2>

2.4.6.1 ‘abolish_events/5’
..........................

* Menu:

* Description: Description<66>.
* Modes and number of proofs: Modes and number of proofs<29>.
* Errors: Errors<30>.
* Examples: Examples<67>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<66>,  Next: Modes and number of proofs<29>,  Up: abolish_events/5

2.4.6.2 Description
...................

     abolish_events(Event, Object, Message, Sender, Monitor)

Abolishes all matching events.  The two types of events are represented
by the atoms ‘before’ and ‘after’.  When the predicate is called with
the first argument unbound, both types of events are abolished.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<29>,  Next: Errors<30>,  Prev: Description<66>,  Up: abolish_events/5

2.4.6.3 Modes and number of proofs
..................................

     abolish_events(@term, @term, @term, @term, @term) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<30>,  Next: Examples<67>,  Prev: Modes and number of proofs<29>,  Up: abolish_events/5

2.4.6.4 Errors
..............

     ‘Event’ is neither a variable nor a valid event identifier:
          ‘type_error(event, Event)’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Message’ is neither a variable nor a callable term:
          ‘type_error(callable, Message)’
     ‘Sender’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Sender)’
     ‘Monitor’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Monitor)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<67>,  Prev: Errors<30>,  Up: abolish_events/5

2.4.6.5 Examples
................

     % abolish all events for messages sent to the "list"
     % object being monitored by the "debugger" object:
     | ?- abolish_events(_, list, _, _, debugger).

See also
........

*note current_event/5: 21e, *note define_events/5: 218, *note before/3:
101, *note after/3: 102.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: current_event/5,  Next: define_events/5,  Prev: abolish_events/5,  Up: Event handling<2>

2.4.6.6 ‘current_event/5’
.........................

* Menu:

* Description: Description<67>.
* Modes and number of proofs: Modes and number of proofs<30>.
* Errors: Errors<31>.
* Examples: Examples<68>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<67>,  Next: Modes and number of proofs<30>,  Up: current_event/5

2.4.6.7 Description
...................

     current_event(Event, Object, Message, Sender, Monitor)

Enumerates, by backtracking, all defined events.  The two types of
events are represented by the atoms ‘before’ and ‘after’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<30>,  Next: Errors<31>,  Prev: Description<67>,  Up: current_event/5

2.4.6.8 Modes and number of proofs
..................................

     current_event(?event, ?term, ?term, ?term, ?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<31>,  Next: Examples<68>,  Prev: Modes and number of proofs<30>,  Up: current_event/5

2.4.6.9 Errors
..............

     ‘Event’ is neither a variable nor a valid event identifier:
          ‘type_error(event, Event)’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Message’ is neither a variable nor a callable term:
          ‘type_error(callable, Message)’
     ‘Sender’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Sender)’
     ‘Monitor’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Monitor)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<68>,  Prev: Errors<31>,  Up: current_event/5

2.4.6.10 Examples
.................

     % enumerate all events monitored by the "debugger" object:
     | ?- current_event(Event, Object, Message, Sender, debugger).

See also
........

*note abolish_events/5: 21b, *note define_events/5: 218, *note before/3:
101, *note after/3: 102.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: define_events/5,  Prev: current_event/5,  Up: Event handling<2>

2.4.6.11 ‘define_events/5’
..........................

* Menu:

* Description: Description<68>.
* Modes and number of proofs: Modes and number of proofs<31>.
* Errors: Errors<32>.
* Examples: Examples<69>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<68>,  Next: Modes and number of proofs<31>,  Up: define_events/5

2.4.6.12 Description
....................

     define_events(Event, Object, Message, Sender, Monitor)

Defines a new set of events.  The two types of events are represented by
the atoms ‘before’ and ‘after’.  When the predicate is called with the
first argument unbound, both types of events are defined.  The object
‘Monitor’ must define the event handler methods required by the ‘Event’
argument.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<31>,  Next: Errors<32>,  Prev: Description<68>,  Up: define_events/5

2.4.6.13 Modes and number of proofs
...................................

     define_events(@term, @term, @term, @term, +object_identifier) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<32>,  Next: Examples<69>,  Prev: Modes and number of proofs<31>,  Up: define_events/5

2.4.6.14 Errors
...............

     ‘Event’ is neither a variable nor a valid event identifier:
          ‘type_error(event, Event)’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Message’ is neither a variable nor a callable term:
          ‘type_error(callable, Message)’
     ‘Sender’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Sender)’
     ‘Monitor’ is a variable:
          ‘instantiation_error’
     ‘Monitor’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Monitor)’
     ‘Monitor’ does not define the required ‘before/3’ method:
          ‘existence_error(procedure, before/3)’
     ‘Monitor’ does not define the required ‘after/3’ method:
          ‘existence_error(procedure, after/3)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<69>,  Prev: Errors<32>,  Up: define_events/5

2.4.6.15 Examples
.................

     % define "debugger" as a monitor for member/2 messages
     % sent to the "list" object:
     | ?- define_events(_, list, member(_, _), _ , debugger).

See also
........

*note abolish_events/5: 21b, *note current_event/5: 21e, *note before/3:
101, *note after/3: 102.


File: TheLogtalkHandbook-3.96.0.info,  Node: Multi-threading,  Next: Multi-threading engines,  Prev: Event handling<2>,  Up: Built-in predicates

2.4.7 Multi-threading
---------------------

'built-in predicate'

* Menu:

* threaded/1::
* threaded_call/1-2::
* threaded_once/1-2::
* threaded_ignore/1::
* threaded_exit/1-2::
* threaded_peek/1-2::
* threaded_cancel/1::
* threaded_wait/1::
* threaded_notify/1::


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded/1,  Next: threaded_call/1-2,  Up: Multi-threading

2.4.7.1 ‘threaded/1’
....................

* Menu:

* Description: Description<69>.
* Meta-predicate template::
* Modes and number of proofs: Modes and number of proofs<32>.
* Errors: Errors<33>.
* Examples: Examples<70>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<69>,  Next: Meta-predicate template,  Up: threaded/1

2.4.7.2 Description
...................

     threaded(Conjunction)
     threaded(Disjunction)

Proves each goal in a conjunction or a disjunction of goals in its own
thread.  This meta-predicate is deterministic and opaque to cuts.  The
predicate argument is 'not' flattened.

When the argument is a conjunction of goals, a call to this predicate
blocks until either all goals succeed, one of the goals fail, or one of
the goals generate an exception; the failure of one of the goals or an
exception on the execution of one of the goals results in the
termination of the remaining threads.  The predicate call is true 'iff'
all goals are true.  The predicate call fails if all goals fail.  When
one of the goals throws an exception, the predicate call re-throws that
exception.

When the argument is a disjunction of goals, a call to this predicate
blocks until either one of the goals succeeds or all the goals fail or
throw exceptions; the success of one of the goals results in the
termination of the remaining threads.  The predicate call is true 'iff'
one of the goals is true.  The predicate call fails if all goals fails.
When no goal succeeds and one of the goals throws an exception, the
predicate call re-throws that exception.

When the predicate argument is neither a conjunction nor a disjunction
of goals, no threads are used.  In this case, the predicate call is
equivalent to a ‘once/1’ predicate call.

A dedicated message queue is used per call of this predicate to collect
the individual goal results.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template,  Next: Modes and number of proofs<32>,  Prev: Description<69>,  Up: threaded/1

2.4.7.3 Meta-predicate template
...............................

     threaded(0)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<32>,  Next: Errors<33>,  Prev: Meta-predicate template,  Up: threaded/1

2.4.7.4 Modes and number of proofs
..................................

     threaded(+callable) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<33>,  Next: Examples<70>,  Prev: Modes and number of proofs<32>,  Up: threaded/1

2.4.7.5 Errors
..............

     ‘Goals’ is a variable:
          ‘instantiation_error’
     A goal in ‘Goals’ is a variable:
          ‘instantiation_error’
     ‘Goals’ is neither a variable nor a callable term:
          ‘type_error(callable, Goals)’
     A goal ‘Goal’ in ‘Goals’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<70>,  Prev: Errors<33>,  Up: threaded/1

2.4.7.6 Examples
................

     Prove a conjunction of goals, each one in its own thread:
          ‘threaded((Goal, Goals))’
     Prove a disjunction of goals, each one in its own thread:
          ‘threaded((Goal; Goals))’

See also
........

*note threaded_call/1-2: 230, *note threaded_once/1-2: 232, *note
threaded_ignore/1: 237, *note synchronized/1: 74.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_call/1-2,  Next: threaded_once/1-2,  Prev: threaded/1,  Up: Multi-threading

2.4.7.7 ‘threaded_call/1-2’
...........................

* Menu:

* Description: Description<70>.
* Meta-predicate template: Meta-predicate template<2>.
* Modes and number of proofs: Modes and number of proofs<33>.
* Errors: Errors<34>.
* Examples: Examples<71>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<70>,  Next: Meta-predicate template<2>,  Up: threaded_call/1-2

2.4.7.8 Description
...................

     threaded_call(Goal)
     threaded_call(Goal, Tag)

Proves ‘Goal’ asynchronously using a new thread.  The argument can be a
message-sending goal.  Calls to this predicate always succeed and return
immediately.  The results (success, failure, or exception) are sent back
to the message queue of the object containing the call (*note this:
114.) and can be retrieved by calling the *note threaded_exit/1: 231.
predicate.

The ‘threaded_call/2’ variant returns a threaded call identifier tag
that can be used with the *note threaded_exit/2: 231. and *note
threaded_cancel/1: 234. predicates.  Tags shall be regarded as opaque
terms; users shall not rely on their type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<2>,  Next: Modes and number of proofs<33>,  Prev: Description<70>,  Up: threaded_call/1-2

2.4.7.9 Meta-predicate template
...............................

     threaded_call(0)
     threaded_call(0, *)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<33>,  Next: Errors<34>,  Prev: Meta-predicate template<2>,  Up: threaded_call/1-2

2.4.7.10 Modes and number of proofs
...................................

     threaded_call(@callable) - one
     threaded_call(@callable, --nonvar) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<34>,  Next: Examples<71>,  Prev: Modes and number of proofs<33>,  Up: threaded_call/1-2

2.4.7.11 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Tag’ is not a variable:
          ‘uninstantiation_error(Tag)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<71>,  Prev: Errors<34>,  Up: threaded_call/1-2

2.4.7.12 Examples
.................

     Prove ‘Goal’ asynchronously in a new thread:
          ‘threaded_call(Goal)’
     Prove ‘::Message’ asynchronously in a new thread:
          ‘threaded_call(::Message)’
     Prove ‘Object::Message’ asynchronously in a new thread:
          ‘threaded_call(Object::Message)’

See also
........

*note threaded_exit/1-2: 231, *note threaded_ignore/1: 237, *note
threaded_once/1-2: 232, *note threaded_peek/1-2: 233, *note
threaded_cancel/1: 234, *note threaded/1: 22b, *note synchronized/1: 74.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_once/1-2,  Next: threaded_ignore/1,  Prev: threaded_call/1-2,  Up: Multi-threading

2.4.7.13 ‘threaded_once/1-2’
............................

* Menu:

* Description: Description<71>.
* Meta-predicate template: Meta-predicate template<3>.
* Modes and number of proofs: Modes and number of proofs<34>.
* Errors: Errors<35>.
* Examples: Examples<72>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<71>,  Next: Meta-predicate template<3>,  Up: threaded_once/1-2

2.4.7.14 Description
....................

     threaded_once(Goal)
     threaded_once(Goal, Tag)

Proves ‘Goal’ asynchronously using a new thread.  Only the first goal
solution is found.  The argument can be a message-sending goal.  This
call always succeeds.  The result (success, failure, or exception) is
sent back to the message queue of the object containing the call (*note
this: 114.).

The ‘threaded_once/2’ variant returns a threaded call identifier tag
that can be used with the *note threaded_exit/2: 231. and *note
threaded_cancel/1: 234. predicates.  Tags shall be regarded as opaque
terms; users shall not rely on their type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<3>,  Next: Modes and number of proofs<34>,  Prev: Description<71>,  Up: threaded_once/1-2

2.4.7.15 Meta-predicate template
................................

     threaded_once(0)
     threaded_once(0, *)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<34>,  Next: Errors<35>,  Prev: Meta-predicate template<3>,  Up: threaded_once/1-2

2.4.7.16 Modes and number of proofs
...................................

     threaded_once(@callable) - one
     threaded_once(@callable, --nonvar) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<35>,  Next: Examples<72>,  Prev: Modes and number of proofs<34>,  Up: threaded_once/1-2

2.4.7.17 Errors
...............

     Goal is a variable:
          ‘instantiation_error’
     Goal is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     Tag is not a variable:
          ‘uninstantiation_error(Tag)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<72>,  Prev: Errors<35>,  Up: threaded_once/1-2

2.4.7.18 Examples
.................

     Prove ‘Goal’ asynchronously in a new thread:
          ‘threaded_once(Goal)’
     Prove ‘::Message’ asynchronously in a new thread:
          ‘threaded_once(::Message)’
     Prove ‘Object::Message’ asynchronously in a new thread:
          ‘threaded_once(Object::Message)’

See also
........

*note threaded_call/1-2: 230, *note threaded_exit/1-2: 231, *note
threaded_ignore/1: 237, *note threaded_peek/1-2: 233, *note
threaded_cancel/1: 234, *note threaded/1: 22b, *note synchronized/1: 74.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_ignore/1,  Next: threaded_exit/1-2,  Prev: threaded_once/1-2,  Up: Multi-threading

2.4.7.19 ‘threaded_ignore/1’
............................

* Menu:

* Description: Description<72>.
* Meta-predicate template: Meta-predicate template<4>.
* Modes and number of proofs: Modes and number of proofs<35>.
* Errors: Errors<36>.
* Examples: Examples<73>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<72>,  Next: Meta-predicate template<4>,  Up: threaded_ignore/1

2.4.7.20 Description
....................

     threaded_ignore(Goal)

Proves ‘Goal’ asynchronously using a new thread.  Only the first goal
solution is found.  The argument can be a message-sending goal.  This
call always succeeds, independently of the result (success, failure, or
exception), which is simply discarded instead of being sent back to the
message queue of the object containing the call (*note this: 114.).

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<4>,  Next: Modes and number of proofs<35>,  Prev: Description<72>,  Up: threaded_ignore/1

2.4.7.21 Meta-predicate template
................................

     threaded_ignore(0)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<35>,  Next: Errors<36>,  Prev: Meta-predicate template<4>,  Up: threaded_ignore/1

2.4.7.22 Modes and number of proofs
...................................

     threaded_ignore(@callable) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<36>,  Next: Examples<73>,  Prev: Modes and number of proofs<35>,  Up: threaded_ignore/1

2.4.7.23 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<73>,  Prev: Errors<36>,  Up: threaded_ignore/1

2.4.7.24 Examples
.................

     Prove ‘Goal’ asynchronously in a new thread:
          ‘threaded_ignore(Goal)’
     Prove ‘::Message’ asynchronously in a new thread:
          ‘threaded_ignore(::Message)’
     Prove ‘Object::Message’ asynchronously in a new thread:
          ‘threaded_ignore(Object::Message)’

See also
........

*note threaded_call/1-2: 230, *note threaded_exit/1-2: 231, *note
threaded_once/1-2: 232, *note threaded_peek/1-2: 233, *note threaded/1:
22b, *note synchronized/1: 74.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_exit/1-2,  Next: threaded_peek/1-2,  Prev: threaded_ignore/1,  Up: Multi-threading

2.4.7.25 ‘threaded_exit/1-2’
............................

* Menu:

* Description: Description<73>.
* Modes and number of proofs: Modes and number of proofs<36>.
* Errors: Errors<37>.
* Examples: Examples<74>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<73>,  Next: Modes and number of proofs<36>,  Up: threaded_exit/1-2

2.4.7.26 Description
....................

     threaded_exit(Goal)
     threaded_exit(Goal, Tag)

Retrieves the result of proving ‘Goal’ in a new thread.  This predicate
blocks execution until the reply is sent to the *note this: 114. message
queue by the thread executing the goal.  When there is no thread proving
the goal, the predicate generates an exception.  This predicate is
non-deterministic, providing access to any alternative solutions of its
argument.

The argument of this predicate should be a 'variant' of the argument of
the corresponding *note threaded_call/1: 230. or *note threaded_once/1:
232. call.  When the predicate argument is subsumed by the
‘threaded_call/1’ or ‘threaded_once/1’ call argument, the
‘threaded_exit/1’ call will succeed iff its argument is a solution of
the (more general) goal.

The ‘threaded_exit/2’ variant accepts a threaded call identifier tag
generated by the calls to the *note threaded_call/2: 230. and *note
threaded_once/2: 232. predicates.  Tags shall be regarded as an opaque
term; users shall not rely on their type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<36>,  Next: Errors<37>,  Prev: Description<73>,  Up: threaded_exit/1-2

2.4.7.27 Modes and number of proofs
...................................

     threaded_exit(+callable) - zero_or_more
     threaded_exit(+callable, +nonvar) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<37>,  Next: Examples<74>,  Prev: Modes and number of proofs<36>,  Up: threaded_exit/1-2

2.4.7.28 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     No thread is running for proving ‘Goal’ in the ‘Object’ calling context:
          ‘existence_error(thread, Object)’
     ‘Tag’ is a variable:
          ‘instantiation_error’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<74>,  Prev: Errors<37>,  Up: threaded_exit/1-2

2.4.7.29 Examples
.................

     To retrieve an asynchronous goal proof result:
          ‘threaded_exit(Goal)’
     To retrieve an asynchronous message to 'self' result:
          ‘threaded_exit(::Goal)’
     To retrieve an asynchronous message result:
          ‘threaded_exit(Object::Goal)’

See also
........

*note threaded_call/1-2: 230, *note threaded_ignore/1: 237, *note
threaded_once/1-2: 232, *note threaded_peek/1-2: 233, *note
threaded_cancel/1: 234, *note threaded/1: 22b.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_peek/1-2,  Next: threaded_cancel/1,  Prev: threaded_exit/1-2,  Up: Multi-threading

2.4.7.30 ‘threaded_peek/1-2’
............................

* Menu:

* Description: Description<74>.
* Modes and number of proofs: Modes and number of proofs<37>.
* Errors: Errors<38>.
* Examples: Examples<75>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<74>,  Next: Modes and number of proofs<37>,  Up: threaded_peek/1-2

2.4.7.31 Description
....................

     threaded_peek(Goal)
     threaded_peek(Goal, Tag)

Checks if the result of proving ‘Goal’ in a new thread is already
available.  This call succeeds or fails without blocking execution
waiting for a reply to be available.  When there is no thread proving
the goal, the predicate generates an exception.

The argument of this predicate should be a 'variant' of the argument of
the corresponding *note threaded_call/1: 230. or *note threaded_once/1:
232. call.  When the predicate argument is subsumed by the
‘threaded_call/1’ or ‘threaded_once/1’ call argument, the
‘threaded_peek/1’ call will succeed iff its argument unifies with an
already available solution of the (more general) goal.

The ‘threaded_peek/2’ variant accepts a threaded call identifier tag
generated by the calls to the *note threaded_call/2: 230. and *note
threaded_once/2: 232. predicates.  Tags shall be regarded as an opaque
term; users shall not rely on their type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<37>,  Next: Errors<38>,  Prev: Description<74>,  Up: threaded_peek/1-2

2.4.7.32 Modes and number of proofs
...................................

     threaded_peek(+callable) - zero_or_one
     threaded_peek(+callable, +nonvar) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<38>,  Next: Examples<75>,  Prev: Modes and number of proofs<37>,  Up: threaded_peek/1-2

2.4.7.33 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     No thread is running for proving ‘Goal’ in the ‘Object’ calling context:
          ‘existence_error(thread, Object)’
     ‘Tag’ is a variable:
          ‘instantiation_error’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<75>,  Prev: Errors<38>,  Up: threaded_peek/1-2

2.4.7.34 Examples
.................

     To check for an asynchronous goal proof result:
          ‘threaded_peek(Goal)’
     To check for an asynchronous message to 'self' result:
          ‘threaded_peek(::Goal)’
     To check for an asynchronous message result:
          ‘threaded_peek(Object::Goal)’

See also
........

*note threaded_call/1-2: 230, *note threaded_exit/1-2: 231, *note
threaded_ignore/1: 237, *note threaded_once/1-2: 232, *note
threaded_cancel/1: 234, *note threaded/1: 22b.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_cancel/1,  Next: threaded_wait/1,  Prev: threaded_peek/1-2,  Up: Multi-threading

2.4.7.35 ‘threaded_cancel/1’
............................

* Menu:

* Description: Description<75>.
* Modes and number of proofs: Modes and number of proofs<38>.
* Errors: Errors<39>.
* Examples: Examples<76>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<75>,  Next: Modes and number of proofs<38>,  Up: threaded_cancel/1

2.4.7.36 Description
....................

     threaded_cancel(Tag)

Cancels a tagged threaded call.  When there is no asynchronous call with
the given tag, calling this predicate succeeds assuming the asynchronous
call has already terminated or canceled.  The threaded call identifier
tag is generated by calls to the *note threaded_call/2: 230. and *note
threaded_once/2: 232. predicates.  Tags shall be regarded as an opaque
term; users shall not rely on their type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<38>,  Next: Errors<39>,  Prev: Description<75>,  Up: threaded_cancel/1

2.4.7.37 Modes and number of proofs
...................................

     threaded_cancel(+nonvar) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<39>,  Next: Examples<76>,  Prev: Modes and number of proofs<38>,  Up: threaded_cancel/1

2.4.7.38 Errors
...............

     ‘Tag’ is a variable:
          ‘instantiation_error’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<76>,  Prev: Errors<39>,  Up: threaded_cancel/1

2.4.7.39 Examples
.................

(none)

See also
........

*note threaded_call/1-2: 230, *note threaded_exit/1-2: 231, *note
threaded_ignore/1: 237, *note threaded_once/1-2: 232, *note threaded/1:
22b.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_wait/1,  Next: threaded_notify/1,  Prev: threaded_cancel/1,  Up: Multi-threading

2.4.7.40 ‘threaded_wait/1’
..........................

* Menu:

* Description: Description<76>.
* Modes and number of proofs: Modes and number of proofs<39>.
* Errors: Errors<40>.
* Examples: Examples<77>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<76>,  Next: Modes and number of proofs<39>,  Up: threaded_wait/1

2.4.7.41 Description
....................

     threaded_wait(Term)
     threaded_wait([Term| Terms])

Suspends the thread making the call until a notification is received
that unifies with ‘Term’.  The call must be made within the same object
(*note this: 114.) containing the calls to the *note threaded_notify/1:
23c. predicate that will eventually send the notification.  The argument
may also be a list of notifications, ‘[Term| Terms]’.  In this case, the
thread making the call will suspend until all notifications in the list
are received.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<39>,  Next: Errors<40>,  Prev: Description<76>,  Up: threaded_wait/1

2.4.7.42 Modes and number of proofs
...................................

     threaded_wait(?term) - one
     threaded_wait(+list(term)) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<40>,  Next: Examples<77>,  Prev: Modes and number of proofs<39>,  Up: threaded_wait/1

2.4.7.43 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<77>,  Prev: Errors<40>,  Up: threaded_wait/1

2.4.7.44 Examples
.................

     % wait until the "data_available" notification is received:
     ..., threaded_wait(data_available), ...

See also
........

*note threaded_notify/1: 23c.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_notify/1,  Prev: threaded_wait/1,  Up: Multi-threading

2.4.7.45 ‘threaded_notify/1’
............................

* Menu:

* Description: Description<77>.
* Modes and number of proofs: Modes and number of proofs<40>.
* Errors: Errors<41>.
* Examples: Examples<78>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<77>,  Next: Modes and number of proofs<40>,  Up: threaded_notify/1

2.4.7.46 Description
....................

     threaded_notify(Term)
     threaded_notify([Term| Terms])

Sends ‘Term’ as a notification to any thread suspended waiting for it in
order to proceed.  The call must be made within the same object (*note
this: 114.) containing the calls to the *note threaded_wait/1: 23b.
predicate waiting for the notification.  The argument may also be a list
of notifications, ‘[Term| Terms]’.  In this case, all notifications in
the list will be sent to any threads suspended waiting for them in order
to proceed.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<40>,  Next: Errors<41>,  Prev: Description<77>,  Up: threaded_notify/1

2.4.7.47 Modes and number of proofs
...................................

     threaded_notify(@term) - one
     threaded_notify(@list(term)) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<41>,  Next: Examples<78>,  Prev: Modes and number of proofs<40>,  Up: threaded_notify/1

2.4.7.48 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<78>,  Prev: Errors<41>,  Up: threaded_notify/1

2.4.7.49 Examples
.................

     % send a "data_available" notification:
     ..., threaded_notify(data_available), ...

See also
........

*note threaded_wait/1: 23b.


File: TheLogtalkHandbook-3.96.0.info,  Node: Multi-threading engines,  Next: Compiling and loading source files,  Prev: Multi-threading,  Up: Built-in predicates

2.4.8 Multi-threading engines
-----------------------------

'built-in predicate'

* Menu:

* threaded_engine_create/3::
* threaded_engine_destroy/1::
* threaded_engine/1::
* threaded_engine_self/1::
* threaded_engine_next/2::
* threaded_engine_next_reified/2::
* threaded_engine_yield/1::
* threaded_engine_post/2::
* threaded_engine_fetch/1::


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_engine_create/3,  Next: threaded_engine_destroy/1,  Up: Multi-threading engines

2.4.8.1 ‘threaded_engine_create/3’
..................................

* Menu:

* Description: Description<78>.
* Meta-predicate template: Meta-predicate template<5>.
* Modes and number of proofs: Modes and number of proofs<41>.
* Errors: Errors<42>.
* Examples: Examples<79>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<78>,  Next: Meta-predicate template<5>,  Up: threaded_engine_create/3

2.4.8.2 Description
...................

     threaded_engine_create(AnswerTemplate, Goal, Engine)

Creates a new engine for proving the given goal and defines an answer
template for retrieving the goal solution bindings.  A message queue for
passing arbitrary terms to the engine is also created.  If the name for
the engine is not given, a unique name is generated and returned.
Engine names shall be regarded as opaque terms; users shall not rely on
its type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2b9. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<5>,  Next: Modes and number of proofs<41>,  Prev: Description<78>,  Up: threaded_engine_create/3

2.4.8.3 Meta-predicate template
...............................

     threaded_engine_create(*, 0, *)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<41>,  Next: Errors<42>,  Prev: Meta-predicate template<5>,  Up: threaded_engine_create/3

2.4.8.4 Modes and number of proofs
..................................

     threaded_engine_create(@term, @callable, @nonvar) - one
     threaded_engine_create(@term, @callable, --nonvar) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<42>,  Next: Examples<79>,  Prev: Modes and number of proofs<41>,  Up: threaded_engine_create/3

2.4.8.5 Errors
..............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Engine’ is the name of an existing engine:
          ‘permission_error(create, engine, Engine)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<79>,  Prev: Errors<42>,  Up: threaded_engine_create/3

2.4.8.6 Examples
................

     % create a new engine to enumerate list elements:
     | ?- threaded_engine_create(X, member(X, [1,2,3]), worker_1).

See also
........

*note threaded_engine_destroy/1: 242, *note threaded_engine_self/1: 5e5,
*note threaded_engine/1: 5e6, *note threaded_engine_next/2: 240, *note
threaded_engine_next_reified/2: 241.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_engine_destroy/1,  Next: threaded_engine/1,  Prev: threaded_engine_create/3,  Up: Multi-threading engines

2.4.8.7 ‘threaded_engine_destroy/1’
...................................

* Menu:

* Description: Description<79>.
* Modes and number of proofs: Modes and number of proofs<42>.
* Errors: Errors<43>.
* Examples: Examples<80>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<79>,  Next: Modes and number of proofs<42>,  Up: threaded_engine_destroy/1

2.4.8.8 Description
...................

     threaded_engine_destroy(Engine)

Stops and destroys an engine.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2b9. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<42>,  Next: Errors<43>,  Prev: Description<79>,  Up: threaded_engine_destroy/1

2.4.8.9 Modes and number of proofs
..................................

     threaded_engine_destroy(@nonvar) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<43>,  Next: Examples<80>,  Prev: Modes and number of proofs<42>,  Up: threaded_engine_destroy/1

2.4.8.10 Errors
...............

     ‘Engine’ is a variable:
          ‘instantiation_error’
     ‘Engine’ is neither a variable nor the name of an existing engine:
          ‘existence_error(engine, Engine)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<80>,  Prev: Errors<43>,  Up: threaded_engine_destroy/1

2.4.8.11 Examples
.................

     % stop the worker_1 engine:
     | ?- threaded_engine_destroy(worker_1).

     % stop all engines:
     | ?- forall(
              threaded_engine(Engine),
              threaded_engine_destroy(Engine)
          ).

See also
........

*note threaded_engine_create/3: 23f, *note threaded_engine_self/1: 5e5,
*note threaded_engine/1: 5e6.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_engine/1,  Next: threaded_engine_self/1,  Prev: threaded_engine_destroy/1,  Up: Multi-threading engines

2.4.8.12 ‘threaded_engine/1’
............................

* Menu:

* Description: Description<80>.
* Modes and number of proofs: Modes and number of proofs<43>.
* Errors: Errors<44>.
* Examples: Examples<81>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<80>,  Next: Modes and number of proofs<43>,  Up: threaded_engine/1

2.4.8.13 Description
....................

     threaded_engine(Engine)

Enumerates, by backtracking, all existing engines.  Engine names shall
be regarded as opaque terms; users shall not rely on their type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2b9. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<43>,  Next: Errors<44>,  Prev: Description<80>,  Up: threaded_engine/1

2.4.8.14 Modes and number of proofs
...................................

     threaded_engine(?nonvar) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<44>,  Next: Examples<81>,  Prev: Modes and number of proofs<43>,  Up: threaded_engine/1

2.4.8.15 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<81>,  Prev: Errors<44>,  Up: threaded_engine/1

2.4.8.16 Examples
.................

     % check that the worker_1 engine exists:
     | ?- threaded_engine(worker_1).

     % write the names of all existing engines:
     | ?- forall(
              threaded_engine(Engine),
              (writeq(Engine), nl)
          ).

See also
........

*note threaded_engine_create/3: 23f, *note threaded_engine_self/1: 5e5,
*note threaded_engine_destroy/1: 242.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_engine_self/1,  Next: threaded_engine_next/2,  Prev: threaded_engine/1,  Up: Multi-threading engines

2.4.8.17 ‘threaded_engine_self/1’
.................................

* Menu:

* Description: Description<81>.
* Modes and number of proofs: Modes and number of proofs<44>.
* Errors: Errors<45>.
* Examples: Examples<82>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<81>,  Next: Modes and number of proofs<44>,  Up: threaded_engine_self/1

2.4.8.18 Description
....................

     threaded_engine_self(Engine)

Queries the name of engine calling the predicate.  Fails if not called
from within an engine or if the argument doesn’t unify with the engine
name.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2b9. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<44>,  Next: Errors<45>,  Prev: Description<81>,  Up: threaded_engine_self/1

2.4.8.19 Modes and number of proofs
...................................

     threaded_engine_self(?nonvar) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<45>,  Next: Examples<82>,  Prev: Modes and number of proofs<44>,  Up: threaded_engine_self/1

2.4.8.20 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<82>,  Prev: Errors<45>,  Up: threaded_engine_self/1

2.4.8.21 Examples
.................

     % find the name of the engine making the query:
     ..., threaded_engine_self(Engine), ...

     % check if the the engine making the query is worker_1:
     ..., threaded_engine_self(worker_1), ...

See also
........

*note threaded_engine_create/3: 23f, *note threaded_engine_destroy/1:
242, *note threaded_engine/1: 5e6.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_engine_next/2,  Next: threaded_engine_next_reified/2,  Prev: threaded_engine_self/1,  Up: Multi-threading engines

2.4.8.22 ‘threaded_engine_next/2’
.................................

* Menu:

* Description: Description<82>.
* Modes and number of proofs: Modes and number of proofs<45>.
* Errors: Errors<46>.
* Examples: Examples<83>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<82>,  Next: Modes and number of proofs<45>,  Up: threaded_engine_next/2

2.4.8.23 Description
....................

     threaded_engine_next(Engine, Answer)

Retrieves an answer from an engine and signals it to start computing the
next answer.  This predicate blocks until an answer becomes available.
The predicate fails when there are no more solutions to the engine goal.
If the engine goal throws an exception, calling this predicate will
re-throw the exception and subsequent calls will fail.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2b9. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<45>,  Next: Errors<46>,  Prev: Description<82>,  Up: threaded_engine_next/2

2.4.8.24 Modes and number of proofs
...................................

     threaded_engine_next(@nonvar, ?term) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<46>,  Next: Examples<83>,  Prev: Modes and number of proofs<45>,  Up: threaded_engine_next/2

2.4.8.25 Errors
...............

     ‘Engine’ is a variable:
          ‘instantiation_error’
     ‘Engine’ is neither a variable nor the name of an existing engine:
          ‘existence_error(engine, Engine)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<83>,  Prev: Errors<46>,  Up: threaded_engine_next/2

2.4.8.26 Examples
.................

     % get the next answer from the worker_1 engine:
     | ?- threaded_engine_next(worker_1, Answer).

See also
........

*note threaded_engine_create/3: 23f, *note
threaded_engine_next_reified/2: 241, *note threaded_engine_yield/1: 245.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_engine_next_reified/2,  Next: threaded_engine_yield/1,  Prev: threaded_engine_next/2,  Up: Multi-threading engines

2.4.8.27 ‘threaded_engine_next_reified/2’
.........................................

* Menu:

* Description: Description<83>.
* Modes and number of proofs: Modes and number of proofs<46>.
* Errors: Errors<47>.
* Examples: Examples<84>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<83>,  Next: Modes and number of proofs<46>,  Up: threaded_engine_next_reified/2

2.4.8.28 Description
....................

     threaded_engine_next_reified(Engine, Answer)

Retrieves an answer from an engine and signals it to start computing the
next answer.  This predicate always succeeds and blocks until an answer
becomes available.  Answers are returned using the terms ‘the(Answer)’,
‘no’, and ‘exception(Error)’.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2b9. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<46>,  Next: Errors<47>,  Prev: Description<83>,  Up: threaded_engine_next_reified/2

2.4.8.29 Modes and number of proofs
...................................

     threaded_engine_next_reified(@nonvar, ?nonvar) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<47>,  Next: Examples<84>,  Prev: Modes and number of proofs<46>,  Up: threaded_engine_next_reified/2

2.4.8.30 Errors
...............

     ‘Engine’ is a variable:
          ‘instantiation_error’
     ‘Engine’ is neither a variable nor the name of an existing engine:
          ‘existence_error(engine, Engine)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<84>,  Prev: Errors<47>,  Up: threaded_engine_next_reified/2

2.4.8.31 Examples
.................

     % get the next reified answer from the worker_1 engine:
     | ?- threaded_engine_next_reified(worker_1, Answer).

See also
........

*note threaded_engine_create/3: 23f, *note threaded_engine_next/2: 240,
*note threaded_engine_yield/1: 245.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_engine_yield/1,  Next: threaded_engine_post/2,  Prev: threaded_engine_next_reified/2,  Up: Multi-threading engines

2.4.8.32 ‘threaded_engine_yield/1’
..................................

* Menu:

* Description: Description<84>.
* Modes and number of proofs: Modes and number of proofs<47>.
* Errors: Errors<48>.
* Examples: Examples<85>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<84>,  Next: Modes and number of proofs<47>,  Up: threaded_engine_yield/1

2.4.8.33 Description
....................

     threaded_engine_yield(Answer)

Returns an answer independent of the solutions of the engine goal.
Fails if not called from within an engine.  This predicate is usually
used when the engine goal is a call to a recursive predicate processing
terms from the engine term queue.

This predicate blocks until the returned answer is consumed.

Note that this predicate should not be called as the last element of a
conjunction resulting in an engine goal solution as, in this case, an
answer will always be returned.  For example, instead of
‘(threaded_engine_yield(ready); member(X,[1,2,3]))’ use ‘(X=ready;
member(X,[1,2,3]))’.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2b9. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<47>,  Next: Errors<48>,  Prev: Description<84>,  Up: threaded_engine_yield/1

2.4.8.34 Modes and number of proofs
...................................

     threaded_engine_yield(@term) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<48>,  Next: Examples<85>,  Prev: Modes and number of proofs<47>,  Up: threaded_engine_yield/1

2.4.8.35 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<85>,  Prev: Errors<48>,  Up: threaded_engine_yield/1

2.4.8.36 Examples
.................

     % returns the atom "ready" as an engine answer:
     ..., threaded_engine_yield(ready), ...

See also
........

*note threaded_engine_create/3: 23f, *note threaded_engine_next/2: 240,
*note threaded_engine_next_reified/2: 241.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_engine_post/2,  Next: threaded_engine_fetch/1,  Prev: threaded_engine_yield/1,  Up: Multi-threading engines

2.4.8.37 ‘threaded_engine_post/2’
.................................

* Menu:

* Description: Description<85>.
* Modes and number of proofs: Modes and number of proofs<48>.
* Errors: Errors<49>.
* Examples: Examples<86>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<85>,  Next: Modes and number of proofs<48>,  Up: threaded_engine_post/2

2.4.8.38 Description
....................

     threaded_engine_post(Engine, Term)

Posts a term to the engine term queue.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2b9. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<48>,  Next: Errors<49>,  Prev: Description<85>,  Up: threaded_engine_post/2

2.4.8.39 Modes and number of proofs
...................................

     threaded_engine_post(@nonvar, @term) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<49>,  Next: Examples<86>,  Prev: Modes and number of proofs<48>,  Up: threaded_engine_post/2

2.4.8.40 Errors
...............

     ‘Engine’ is a variable:
          ‘instantiation_error’
     ‘Engine’ is neither a variable nor the name of an existing engine:
          ‘existence_error(engine, Engine)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<86>,  Prev: Errors<49>,  Up: threaded_engine_post/2

2.4.8.41 Examples
.................

     % post the atom "ready" to the worker_1 engine queue:
     | ?- threaded_engine_post(worker_1, ready).

See also
........

*note threaded_engine_fetch/1: 243.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: threaded_engine_fetch/1,  Prev: threaded_engine_post/2,  Up: Multi-threading engines

2.4.8.42 ‘threaded_engine_fetch/1’
..................................

* Menu:

* Description: Description<86>.
* Modes and number of proofs: Modes and number of proofs<49>.
* Errors: Errors<50>.
* Examples: Examples<87>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<86>,  Next: Modes and number of proofs<49>,  Up: threaded_engine_fetch/1

2.4.8.43 Description
....................

     threaded_engine_fetch(Term)

Fetches a term from the engine term queue.  Blocks until a term is
available.  Fails if not called from within an engine.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2b9. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<49>,  Next: Errors<50>,  Prev: Description<86>,  Up: threaded_engine_fetch/1

2.4.8.44 Modes and number of proofs
...................................

     threaded_engine_fetch(?term) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<50>,  Next: Examples<87>,  Prev: Modes and number of proofs<49>,  Up: threaded_engine_fetch/1

2.4.8.45 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<87>,  Prev: Errors<50>,  Up: threaded_engine_fetch/1

2.4.8.46 Examples
.................

     % fetch a term from the engine term queue:
     ..., threaded_engine_fetch(Term), ...

See also
........

*note threaded_engine_post/2: 244.


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiling and loading source files,  Next: Flags,  Prev: Multi-threading engines,  Up: Built-in predicates

2.4.9 Compiling and loading source files
----------------------------------------

'built-in predicate'

* Menu:

* logtalk_compile/1::
* logtalk_compile/2::
* logtalk_load/1::
* logtalk_load/2::
* logtalk_make/0::
* logtalk_make/1::
* logtalk_make_target_action/1::
* logtalk_library_path/2::
* logtalk_load_context/2::


File: TheLogtalkHandbook-3.96.0.info,  Node: logtalk_compile/1,  Next: logtalk_compile/2,  Up: Compiling and loading source files

2.4.9.1 ‘logtalk_compile/1’
...........................

* Menu:

* Description: Description<87>.
* Modes and number of proofs: Modes and number of proofs<50>.
* Errors: Errors<51>.
* Examples: Examples<88>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<87>,  Next: Modes and number of proofs<50>,  Up: logtalk_compile/1

2.4.9.2 Description
...................

     logtalk_compile(File)
     logtalk_compile(Files)

Compiles to disk a *note source file: 61c. or a list of source files
using the default compiler flag values.  The Logtalk source file name
extension (by default, ‘.lgt’) can be omitted.  Source file paths can be
absolute, relative to the current directory, or use *note library
notation: 2a8.  This predicate can also be used to compile Prolog source
files as Logtalk source code.  When no recognized Logtalk or Prolog
extension is specified, the compiler tries first to append a Logtalk
source file extension and then a Prolog source file extension.  If that
fails, the compiler tries to use the file name as-is.  The recognized
Logtalk and Prolog file extensions are defined in the *note backend
adapter files: 154.

     Note: This predicate does not load into memory the compiled source
     file.  If you want to both compile and load a source file, use
     instead the *note logtalk_load/1: 46. built-in predicate.

When this predicate is called from the top-level interpreter, relative
source file paths are resolved using the current working directory.
When the calls are made from a source file, relative source file paths
are resolved using the source file directory.

Note that only the errors related to problems in the predicate argument
are listed below.  This predicate fails on the first error found during
compilation of a source file.  In this case, no file with the compiled
code is written to disk.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<50>,  Next: Errors<51>,  Prev: Description<87>,  Up: logtalk_compile/1

2.4.9.3 Modes and number of proofs
..................................

     logtalk_compile(@source_file_name) - zero_or_one
     logtalk_compile(@list(source_file_name)) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<51>,  Next: Examples<88>,  Prev: Modes and number of proofs<50>,  Up: logtalk_compile/1

2.4.9.4 Errors
..............

     ‘File’ is a variable:
          ‘instantiation_error’
     ‘Files’ is a variable or a list with an element which is a variable:
          ‘instantiation_error’
     ‘File’, or an element ‘File’ of the ‘Files’ list, is neither a variable nor a source file name:
          ‘type_error(source_file_name, File)’
     ‘File’, or an element ‘File’ of the ‘Files’ list, uses library notation but the library does not exist:
          ‘existence_error(library, Library)’
     ‘File’ or an element ‘File’ of the ‘Files’ list does not exist:
          ‘existence_error(file, File)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<88>,  Prev: Errors<51>,  Up: logtalk_compile/1

2.4.9.5 Examples
................

     % compile to disk the "set" source file in the
     % current directory:
     | ?- logtalk_compile(set).

     % compile to disk the "tree" source file in the
     % "types" library directory:
     | ?- logtalk_load(types(tree)).

     % compile to disk the "listp" and "list" source
     % files in the current directory:
     | ?- logtalk_compile([listp, list]).

See also
........

*note logtalk_compile/2: 2b2, *note logtalk_load/1: 46, *note
logtalk_load/2: 4e, *note logtalk_make/0: 29f, *note logtalk_make/1:
2a0, *note logtalk_library_path/2: 2a7.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: logtalk_compile/2,  Next: logtalk_load/1,  Prev: logtalk_compile/1,  Up: Compiling and loading source files

2.4.9.6 ‘logtalk_compile/2’
...........................

* Menu:

* Description: Description<88>.
* Modes and number of proofs: Modes and number of proofs<51>.
* Errors: Errors<52>.
* Examples: Examples<89>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<88>,  Next: Modes and number of proofs<51>,  Up: logtalk_compile/2

2.4.9.7 Description
...................

     logtalk_compile(File, Flags)
     logtalk_compile(Files, Flags)

Compiles to disk a *note source file: 61c. or a list of source files
using a list of compiler flags.  The Logtalk source file name extension
(by default, ‘.lgt’) can be omitted.  Source file paths can be absolute,
relative to the current directory, or use *note library notation: 2a8.
This predicate can also be used to compile Prolog source files as
Logtalk source code.  When no recognized Logtalk or Prolog extension is
specified, the compiler tries first to append a Logtalk source file
extension and then a Prolog source file extension.  If that fails, the
compiler tries to use the file name as-is.  Compiler flags are
represented as 'flag(value)'.  For a description of the available
compiler flags, please see the *note Compiler flags: 251. section in the
User Manual.  The recognized Logtalk and Prolog file extensions are
defined in the *note backend adapter files: 154.

     Note: This predicate does not load into memory the compiled source
     file.  If you want to both compile and load a source file, use
     instead the *note logtalk_load/2: 4e. built-in predicate.

When this predicate is called from the top-level interpreter, relative
source file paths are resolved using the current working directory.
When the calls are made from a source file, relative source file paths
are resolved by default using the source file directory (unless a *note
relative_to: 2e4. flag is passed).

Note that only the errors related to problems in the predicate argument
are listed below.  This predicate fails on the first error found during
compilation of a source file.  In this case, no file with the compiled
code is written to disk.

     Warning: The compiler flags specified in the second argument only
     apply to the files listed in the first argument.  Notably, if you
     are compiling a *note loader file: 4f, the flags only apply to the
     loader file itself.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<51>,  Next: Errors<52>,  Prev: Description<88>,  Up: logtalk_compile/2

2.4.9.8 Modes and number of proofs
..................................

     logtalk_compile(@source_file_name, @list(compiler_flag)) - zero_or_one
     logtalk_compile(@list(source_file_name), @list(compiler_flag)) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<52>,  Next: Examples<89>,  Prev: Modes and number of proofs<51>,  Up: logtalk_compile/2

2.4.9.9 Errors
..............

     ‘File’ is a variable:
          ‘instantiation_error’
     ‘Files’ is a variable or a list with an element which is a variable:
          ‘instantiation_error’
     ‘File’, or an element ‘File’ of the ‘Files’ list, is neither a variable nor a source file name:
          ‘type_error(source_file_name, File)’
     ‘File’, or an element ‘File’ of the ‘Files’ list, uses library notation but the library does not exist:
          ‘existence_error(library, Library)’
     ‘File’ or an element ‘File’ of the ‘Files’ list, does not exist:
          ‘existence_error(file, File)’
          
     ‘Flags’ is a variable or a list with an element which is a variable:
          ‘instantiation_error’
     ‘Flags’ is neither a variable nor a proper list:
          ‘type_error(list, Flags)’
     An element ‘Flag’ of the ‘Flags’ list is not a valid compiler flag:
          ‘type_error(compiler_flag, Flag)’
     An element ‘Flag’ of the ‘Flags’ list defines a value for a read-only compiler flag:
          ‘permission_error(modify, flag, Flag)’
     An element ‘Flag’ of the ‘Flags’ list defines an invalid value for a flag:
          ‘domain_error(flag_value, Flag+Value)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<89>,  Prev: Errors<52>,  Up: logtalk_compile/2

2.4.9.10 Examples
.................

     % compile to disk the "list" source file in the
     % current directory using default compiler flags:
     | ?- logtalk_compile(list, []).

     % compile to disk the "tree" source file in the "types"
     % library directory with the source_data flag turned on:
     | ?- logtalk_compile(types(tree), [source_data(on)]).

     % compile to disk the "file_system" source file in the
     % current directory with portability warnings suppressed:
     | ?- logtalk_compile(file_system, [portability(silent)]).

See also
........

*note logtalk_compile/1: 29e, *note logtalk_load/1: 46, *note
logtalk_load/2: 4e, *note logtalk_make/0: 29f, *note logtalk_make/1:
2a0, *note logtalk_library_path/2: 2a7.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: logtalk_load/1,  Next: logtalk_load/2,  Prev: logtalk_compile/2,  Up: Compiling and loading source files

2.4.9.11 ‘logtalk_load/1’
.........................

* Menu:

* Description: Description<89>.
* Modes and number of proofs: Modes and number of proofs<52>.
* Errors: Errors<53>.
* Examples: Examples<90>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<89>,  Next: Modes and number of proofs<52>,  Up: logtalk_load/1

2.4.9.12 Description
....................

     logtalk_load(File)
     logtalk_load(Files)

Compiles to disk and then loads to memory a *note source file: 61c. or a
list of source files using the default compiler flag values.  The
Logtalk source file name extension (by default, ‘.lgt’) can be omitted.
Source file paths can be absolute, relative to the current directory, or
use *note library notation: 2a8.  This predicate can also be used to
compile Prolog source files as Logtalk source code.  When no recognized
Logtalk or Prolog extension is specified, the compiler tries first to
append a Logtalk source file extension and then a Prolog source file
extension.  If that fails, the compiler tries to use the file name
as-is.  The recognized Logtalk and Prolog file extensions are defined in
the *note backend adapter files: 154.

When this predicate is called from the top-level interpreter, relative
source file paths are resolved using the current working directory.
When the calls are made from a source file, relative source file paths
are resolved using the source file directory.

Note that only the errors related to problems in the predicate argument
are listed below.  This predicate fails on the first error found during
compilation of a source file.  In this case, the source file contents is
not loaded.

Depending on the *note backend Prolog compiler: 34, the shortcuts
‘{File}’ or ‘{File1, File2, ...}’ may be used as an alternative.  Check
the adapter files for the availability of these shortcuts as they are
not part of the language (and thus should only be used at the top-level
interpreter).


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<52>,  Next: Errors<53>,  Prev: Description<89>,  Up: logtalk_load/1

2.4.9.13 Modes and number of proofs
...................................

     logtalk_load(@source_file_name) - zero_or_one
     logtalk_load(@list(source_file_name)) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<53>,  Next: Examples<90>,  Prev: Modes and number of proofs<52>,  Up: logtalk_load/1

2.4.9.14 Errors
...............

     ‘File’ is a variable:
          ‘instantiation_error’
     ‘Files’ is a variable or a list with an element which is a variable:
          ‘instantiation_error’
     ‘File’, or an element ‘File’ of the ‘Files’ list, is neither a variable nor a source file name:
          ‘type_error(source_file_name, File)’
     ‘File’, or an element ‘File’ of the ‘Files’ list, uses library notation but the library does not exist:
          ‘existence_error(library, Library)’
     ‘File’ or an element ‘File’ of the ‘Files’ list, does not exist:
          ‘existence_error(file, File)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<90>,  Prev: Errors<53>,  Up: logtalk_load/1

2.4.9.15 Examples
.................

     % compile and load the "set" source file in the
     % current directory:
     | ?- logtalk_load(set).

     % compile and load the "tree" source file in the
     % "types" library directory:
     | ?- logtalk_load(types(tree)).

     % compile and load the "listp" and "list" source
     % files in the current directory:
     | ?- logtalk_load([listp, list]).

See also
........

*note logtalk_compile/1: 29e, *note logtalk_compile/2: 2b2, *note
logtalk_load/2: 4e, *note logtalk_make/0: 29f, *note logtalk_make/1:
2a0, *note logtalk_library_path/2: 2a7.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: logtalk_load/2,  Next: logtalk_make/0,  Prev: logtalk_load/1,  Up: Compiling and loading source files

2.4.9.16 ‘logtalk_load/2’
.........................

* Menu:

* Description: Description<90>.
* Modes and number of proofs: Modes and number of proofs<53>.
* Errors: Errors<54>.
* Examples: Examples<91>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<90>,  Next: Modes and number of proofs<53>,  Up: logtalk_load/2

2.4.9.17 Description
....................

     logtalk_load(File, Flags)
     logtalk_load(Files, Flags)

Compiles to disk and then loads to memory a *note source file: 61c. or a
list of source files using a list of compiler flags.  The Logtalk source
file name extension (by default, ‘.lgt’) can be omitted.  Source file
paths can be absolute, relative to the current directory, or use *note
library notation: 2a8.  Compiler flags are represented as 'flag(value)'.
This predicate can also be used to compile Prolog source files as
Logtalk source code.  When no recognized Logtalk or Prolog extension is
specified, the compiler tries first to append a Logtalk source file
extension and then a Prolog source file extension.  If that fails, the
compiler tries to use the file name as-is.  For a description of the
available compiler flags, please see the *note Compiler flags: 251.
section in the User Manual.  The recognized Logtalk and Prolog file
extensions are defined in the *note backend adapter files: 154.  The
recognized Logtalk and Prolog file extensions are defined in the *note
backend adapter files: 154.

When this predicate is called from the top-level interpreter, relative
source file paths are resolved using the current working directory.
When the calls are made from a source file, relative source file paths
are resolved by default using the source file directory (unless a *note
relative_to: 2e4. flag is passed).

Note that only the errors related to problems in the predicate argument
are listed below.  This predicate fails on the first error found during
compilation of a source file.  In this case, the source file contents is
not loaded.

     Warning: The compiler flags specified in the second argument only
     apply to the files listed in the first argument and not to any
     files that those files may load or compile.  Notably, if you are
     loading a *note loader file: 4f, the flags only apply to the loader
     file itself and not to the files loaded by it.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<53>,  Next: Errors<54>,  Prev: Description<90>,  Up: logtalk_load/2

2.4.9.18 Modes and number of proofs
...................................

     logtalk_load(@source_file_name, @list(compiler_flag)) - zero_or_one
     logtalk_load(@list(source_file_name), @list(compiler_flag)) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<54>,  Next: Examples<91>,  Prev: Modes and number of proofs<53>,  Up: logtalk_load/2

2.4.9.19 Errors
...............

     ‘File’ is a variable:
          ‘instantiation_error’
     ‘Files’ is a variable or a list with an element which is a variable:
          ‘instantiation_error’
     ‘File’, or an element ‘File’ of the ‘Files’ list, is neither a variable nor a source file name:
          ‘type_error(source_file_name, File)’
     ‘File’, or an element ‘File’ of the ‘Files’ list, uses library notation but the library does not exist:
          ‘existence_error(library, Library)’
     ‘File’ or an element ‘File’ of the ‘Files’ list, does not exist:
          ‘existence_error(file, File)’
     ‘Flags’ is a variable or a list with an element which is a variable:
          ‘instantiation_error’
     ‘Flags’ is neither a variable nor a proper list:
          ‘type_error(list, Flags)’
     An element ‘Flag’ of the ‘Flags’ list is not a valid compiler flag:
          ‘type_error(compiler_flag, Flag)’
     An element ‘Flag’ of the ‘Flags’ list defines a value for a read-only compiler flag:
          ‘permission_error(modify, flag, Flag)’
     An element ‘Flag’ of the ‘Flags’ list defines an invalid value for a flag:
          ‘domain_error(flag_value, Flag+Value)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<91>,  Prev: Errors<54>,  Up: logtalk_load/2

2.4.9.20 Examples
.................

     % compile and load the "list" source file in the
     % current directory using default compiler flags:
     | ?- logtalk_load(list, []).

     % compile and load the "tree" source file in the "types"
     % library directory with the source_data flag turned on:
     | ?- logtalk_load(types(tree)).

     % compile and load the "file_system" source file in the
     % current directory with portability warnings suppressed:
     | ?- logtalk_load(file_system, [portability(silent)]).

See also
........

*note logtalk_compile/1: 29e, *note logtalk_compile/2: 2b2, *note
logtalk_load/1: 46, *note logtalk_make/0: 29f, *note logtalk_make/1:
2a0, *note logtalk_library_path/2: 2a7.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: logtalk_make/0,  Next: logtalk_make/1,  Prev: logtalk_load/2,  Up: Compiling and loading source files

2.4.9.21 ‘logtalk_make/0’
.........................

* Menu:

* Description: Description<91>.
* Modes and number of proofs: Modes and number of proofs<54>.
* Errors: Errors<55>.
* Examples: Examples<92>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<91>,  Next: Modes and number of proofs<54>,  Up: logtalk_make/0

2.4.9.22 Description
....................

     logtalk_make

Reloads all Logtalk source files that have been modified since the time
they were last loaded.  Only source files loaded using the *note
logtalk_load/1: 46. and *note logtalk_load/2: 4e. predicates are
reloaded.  Non-modified files will also be reloaded when a previous
attempt to load them failed or when there is a change to the compilation
mode (i.e., when the files were loaded without explicit *note debug:
2e2. or *note optimize: 8c. flags and the default values of these flags
changed after loading; no check is made, however, for other implicit
compiler flags that may have changed since loading).  When an included
file is modified, this predicate reloads its main file (i.e., the file
that contains the *note include/1: b8. directive).

Depending on the *note backend Prolog compiler: 34, the shortcut ‘{*}’
may be used as an alternative.  Check the *note adapter files: 154. for
the availability of the shortcut as it is not part of the language.

     Warning: Only use the ‘{*}’ shortcut at the top-level interpreter
     and never in source files.

This predicate can be extended by the user by defining clauses for the
*note logtalk_make_target_action/1: 635. multifile and dynamic hook
predicate using the argument ‘all’.  The additional user defined actions
are run after the default one.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<54>,  Next: Errors<55>,  Prev: Description<91>,  Up: logtalk_make/0

2.4.9.23 Modes and number of proofs
...................................

     logtalk_make - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<55>,  Next: Examples<92>,  Prev: Modes and number of proofs<54>,  Up: logtalk_make/0

2.4.9.24 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<92>,  Prev: Errors<55>,  Up: logtalk_make/0

2.4.9.25 Examples
.................

     % reload all files modified since last loaded:
     | ?- logtalk_make.

See also
........

*note logtalk_compile/1: 29e, *note logtalk_compile/2: 2b2, *note
logtalk_load/1: 46, *note logtalk_load/2: 4e, *note logtalk_make/1: 2a0,
*note logtalk_make_target_action/1: 635.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: logtalk_make/1,  Next: logtalk_make_target_action/1,  Prev: logtalk_make/0,  Up: Compiling and loading source files

2.4.9.26 ‘logtalk_make/1’
.........................

* Menu:

* Description: Description<92>.
* Modes and number of proofs: Modes and number of proofs<55>.
* Errors: Errors<56>.
* Examples: Examples<93>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<92>,  Next: Modes and number of proofs<55>,  Up: logtalk_make/1

2.4.9.27 Description
....................

     logtalk_make(Target)

Runs a make target.  Prints a warning message and fails when the target
is not valid.

Allows reloading all Logtalk source files that have been modified since
last loaded when called with the target ‘all’, deleting all intermediate
files generated by the compilation of Logtalk source files when called
with the target ‘clean’, checking for code issues when called with the
target ‘check’, listing of circular dependencies between pairs or trios
of objects when called with the target ‘circular’, generating
documentation when called with the target ‘documentation’, and deleting
the *note dynamic binding: 36. caches with the target ‘caches’.

There are also three variants of the ‘all’ target: ‘debug’, ‘normal’,
and ‘optimal’.  These targets change the compilation mode (by changing
the default value of the *note debug: 2e2. and *note optimize: 8c.
flags) and reload all affected files (i.e., all files loaded without an
explicit ‘debug/1’ or ‘optimize/1’ compiler option).

When using the ‘all’ target, only source files loaded using the *note
logtalk_load/1: 46. and *note logtalk_load/2: 4e. predicates are
reloaded.  Non-modified files will also be reloaded when a previous
attempt to load them failed or when there is a change to the compilation
mode (i.e., when the files were loaded without explicit *note debug:
2e2. or *note optimize: 8c. flags and the default values of these flags
changed after loading; no check is made, however, for other implicit
compiler flags that may have changed since loading).  When an included
file is modified, this target reloads its main file (i.e., the file that
contains the *note include/1: b8. directive).

When using the ‘check’ or ‘circular’ targets, be sure to compile your
source files with the *note source_data: cc. flag turned on for complete
and detailed reports.

The ‘check’ target scans for missing entities (objects, protocols,
categories, and modules), missing entity predicates, and duplicated
library aliases.  Predicates for messages sent to objects that implement
the forwarding(1) built-in protocol are not reported.  While this
usually avoids only false positives, it may also result in failure to
report true missing predicates in some cases.

When using the ‘circular’ target, be prepared for a lengthy computation
time for applications with a large combined number of objects and
message calls.  Only mutual and triangular dependencies are checked due
to the computational cost.  Circular dependencies occur when an object
sends a message to a second object that, in turn, sends a message to the
first object.  These circular dependencies are often a consequence of
lack of separation of concerns.  But, when they cannot be fixed, the
only practical consequence is a small performance cost as some of the
messages would be forced to use dynamic binding.

The ‘documentation’ target requires the ‘doclet’ tool and a single *note
doclet object: 63c. to be loaded.  See the ‘doclet’ tool documentation
for more details.

Depending on the *note backend Prolog compiler: 34, the following
top-level shortcuts are usually defined:

   * ‘{*}’ - ‘logtalk_make(all)’

   * ‘{!}’ - ‘logtalk_make(clean)’

   * ‘{?}’ - ‘logtalk_make(check)’

   * ‘{@}’ - ‘logtalk_make(circular)’

   * ‘{#}’ - ‘logtalk_make(documentation)’

   * ‘{$}’ - ‘logtalk_make(caches)’

   * ‘{+d}’ - ‘logtalk_make(debug)’

   * ‘{+n}’ - ‘logtalk_make(normal)’

   * ‘{+o}’ - ‘logtalk_make(optimal)’

Check the *note adapter files: 154. for the availability of these
shortcuts as they are not part of the language.

     Warning: Only use the shortcuts at the top-level interpreter and
     never in source files.

The target actions can be extended by defining clauses for the multifile
and dynamic hook predicate *note logtalk_make_target_action(Target):
635. where ‘Target’ is one of the targets listed above.  The additional
user-defined actions are run after the default ones.

   ---------- Footnotes ----------

   (1) ../../../apis/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<55>,  Next: Errors<56>,  Prev: Description<92>,  Up: logtalk_make/1

2.4.9.28 Modes and number of proofs
...................................

     logtalk_make(+atom) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<56>,  Next: Examples<93>,  Prev: Modes and number of proofs<55>,  Up: logtalk_make/1

2.4.9.29 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<93>,  Prev: Errors<56>,  Up: logtalk_make/1

2.4.9.30 Examples
.................

     % reload loaded source files in debug mode:
     | ?- logtalk_make(debug).

     % check for code issues in the loaded source files:
     | ?- logtalk_make(check).

     % delete all intermediate files generated by
     % the compilation of Logtalk source files:
     | ?- logtalk_make(clean).

See also
........

*note logtalk_compile/1: 29e, *note logtalk_compile/2: 2b2, *note
logtalk_load/1: 46, *note logtalk_load/2: 4e, *note logtalk_make/0: 29f,
*note logtalk_make_target_action/1: 635.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: logtalk_make_target_action/1,  Next: logtalk_library_path/2,  Prev: logtalk_make/1,  Up: Compiling and loading source files

2.4.9.31 ‘logtalk_make_target_action/1’
.......................................

* Menu:

* Description: Description<93>.
* Modes and number of proofs: Modes and number of proofs<56>.
* Errors: Errors<57>.
* Examples: Examples<94>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<93>,  Next: Modes and number of proofs<56>,  Up: logtalk_make_target_action/1

2.4.9.32 Description
....................

     logtalk_make_target_action(Target)

Multifile and dynamic hook predicate that allows defining user actions
for the *note logtalk_make/1: 2a0. targets.  The user defined actions
are run after the default ones using a failure driven loop.  This loop
does not catch any exceptions thrown when calling the user-defined
actions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<56>,  Next: Errors<57>,  Prev: Description<93>,  Up: logtalk_make_target_action/1

2.4.9.33 Modes and number of proofs
...................................

     logtalk_make_target_action(+atom) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<57>,  Next: Examples<94>,  Prev: Modes and number of proofs<56>,  Up: logtalk_make_target_action/1

2.4.9.34 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<94>,  Prev: Errors<57>,  Up: logtalk_make_target_action/1

2.4.9.35 Examples
.................

     % integrate the dead_code_scanner tool with logtalk_make/1

     :- multifile(logtalk_make_target_action/1).
     :- dynamic(logtalk_make_target_action/1).

     logtalk_make_target_action(check) :-
         dead_code_scanner::all.

See also
........

*note logtalk_make/1: 2a0, *note logtalk_make/0: 29f.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: logtalk_library_path/2,  Next: logtalk_load_context/2,  Prev: logtalk_make_target_action/1,  Up: Compiling and loading source files

2.4.9.36 ‘logtalk_library_path/2’
.................................

* Menu:

* Description: Description<94>.
* Modes and number of proofs: Modes and number of proofs<57>.
* Errors: Errors<58>.
* Examples: Examples<95>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<94>,  Next: Modes and number of proofs<57>,  Up: logtalk_library_path/2

2.4.9.37 Description
....................

     logtalk_library_path(Library, Path)

Dynamic and multifile user-defined predicate, allowing the declaration
of aliases to *note library: 6e. paths.  Library aliases may also be
used in the second argument (using the notation 'alias(path)').  Paths
must always end with the path directory separator character (‘'/'’).

     Warning: Library aliases should be unique.  The *note
     logtalk_make/1: 2a0. built-in predicate can be used to detect and
     report duplicated library aliases using the ‘check’ target.

Clauses for this predicate should preferably be facts.  Defining rules
to dynamically compute at runtime both library alias names and their
paths, although sometimes handy, can inadvertently result in endless
loops when those rules also attempt to expand library paths.  When
asserting facts for this predicate, use preferably ‘asserta/1’ instead
of ‘assertz/1’ to help ensure the facts will be used before any rules.

Relative paths (e.g., ‘'../'’ or ‘'./'’) should only be used within the
'alias(path)') notation so that library paths can always be expanded to
absolute paths independently of the (usually unpredictable) current
directory at the time the ‘logtalk_library_path/2’ predicate is called.

When working with a relocatable application, the actual application
installation directory can be retrieved by calling the *note
logtalk_load_context/2: 317. predicate with the ‘directory’ key and
using the returned value to define the ‘logtalk_library_path/2’
predicate.  On a *note settings file: 49. file or a *note loader file:
4f. file, simply use an *note initialization/1: 42. directive to wrap
the call to the ‘logtalk_load_context/2’ predicate and the assert of the
‘logtalk_library_path/2’ fact.

This predicate may be used to override the default *note scratch
directory: 293. by defining the library alias ‘scratch_directory’ in a
backend Prolog initialization file (assumed to be loaded prior to
Logtalk loading).  This allows e.g.  Logtalk to be installed in a
read-only directory by setting this alias to the operating-system
directory for temporary files.  It also allows several Logtalk instances
to run concurrently without conflict by using a unique scratch directory
per instance (e.g., using a process ID or a UUID generator).

This predicate may be used to override the default location used by the
*note packs: 649. tool to store registries and packs by defining the
‘logtalk_packs’ library alias in settings file or in a backend Prolog
initialization file (assumed to be loaded prior to Logtalk loading).

The *note logtalk: d1. built-in object provides an
expand_library_path/2(1) predicate that can be used to expand library
aliases and files expressed using library notation.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0-expand-library-path-2


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<57>,  Next: Errors<58>,  Prev: Description<94>,  Up: logtalk_library_path/2

2.4.9.38 Modes and number of proofs
...................................

     logtalk_library_path(?atom, -atom) - zero_or_more
     logtalk_library_path(?atom, -compound) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<58>,  Next: Examples<95>,  Prev: Modes and number of proofs<57>,  Up: logtalk_library_path/2

2.4.9.39 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<95>,  Prev: Errors<58>,  Up: logtalk_library_path/2

2.4.9.40 Examples
.................

     :- initialization((
        logtalk_load_context(directory, Directory),
        asserta(logtalk_library_path(my_application_root, Directory))
     )).

     | ?- logtalk_library_path(viewpoints, Path).

     Path = examples('viewpoints/')
     yes

     | ?- logtalk_library_path(Library, Path).

     Library = home,
     Path = '$HOME/' ;

     Library = logtalk_home,
     Path = '$LOGTALKHOME/' ;

     Library = logtalk_user
     Path = '$LOGTALKUSER/' ;

     Library = examples
     Path = logtalk_user('examples/') ;

     Library = library
     Path = logtalk_user('library/') ;

     Library = viewpoints
     Path = examples('viewpoints/')
     yes

     | ?- logtalk::expand_library_path(viewpoints, Path).

     Path = '/Users/pmoura/logtalk/examples/viewpoints/'.
     yes

     | ?- logtalk::expand_library_path(viewpoints('loader.lgt'), Path).

     Path = '/Users/pmoura/logtalk/examples/viewpoints/loader.lgt'.
     yes

See also
........

*note logtalk_compile/1: 29e, *note logtalk_compile/2: 2b2, *note
logtalk_load/1: 46, *note logtalk_load/2: 4e.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: logtalk_load_context/2,  Prev: logtalk_library_path/2,  Up: Compiling and loading source files

2.4.9.41 ‘logtalk_load_context/2’
.................................

* Menu:

* Description: Description<95>.
* Modes and number of proofs: Modes and number of proofs<58>.
* Errors: Errors<59>.
* Examples: Examples<96>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<95>,  Next: Modes and number of proofs<58>,  Up: logtalk_load_context/2

2.4.9.42 Description
....................

     logtalk_load_context(Key, Value)

Provides access to the Logtalk compilation/loading context.  The
following keys are currently supported:

   * ‘entity_identifier’ - identifier of the entity being compiled if
     any

   * ‘entity_prefix’ - internal prefix for the entity compiled code

   * ‘entity_type’ - returns the value ‘module’ when compiling a module
     as an object

   * ‘entity_relation’ - returns the entity relations as declared in the
     entity opening directive

   * ‘source’ - full path of the source file being compiled

   * ‘file’ - the actual file being compiled, different from ‘source’
     only when processing an ‘include/1’ directive

   * ‘basename’ - source file basename

   * ‘directory’ - source file directory

   * ‘stream’ - input stream being used to read source file terms

   * ‘target’ - the full path of the intermediate Prolog file

   * ‘flags’ - the list of the explicit flags used for the compilation
     of the source file

   * ‘term’ - the source file term being compiled

   * ‘term_position’ - the position of the term being compiled
     (‘StartLine-EndLine’)

   * ‘variables’ - the variables of the term being compiled
     (‘[Variable1, ...]’)

   * ‘variable_names’ - the variable names of the term being compiled
     (‘[Name1=Variable1, ...]’)

   * ‘variable_names(Term)’ - the variable names of the term being
     compiled (‘[Name1=Variable1, ...]’)

   * ‘singletons’ - the singleton variables of the term being compiled
     (‘[Name1=Variable1, ...]’)

   * ‘singletons(Term)’ - the singleton variables of the term being
     compiled (‘[Name1=Variable1, ...]’)

   * ‘parameter_variables’ - list of parameter variable names and
     positions (‘[Name1-Position1, ...]’)

For the ‘entity_relation’ key, the possible values are:

   * ‘extends_protocol(Protocol, ParentProtocol, Scope)’

   * ‘implements_protocol(ObjectOrCategory, Protocol, Scope)’

   * ‘extends_category(Category, ParentCategory, Scope)’

   * ‘imports_category(Object, Category, Scope)’

   * ‘extends_object(Prototype, Parent, Scope)’

   * ‘instantiates_class(Instance, Class, Scope)’

   * ‘specializes_class(Class, Superclass, Scope)’

   * ‘complements_object(Category, Object)’

Calling this predicate with the ‘parameter_variables’ key only succeeds
when compiling a parametric entity containing parameter variables.

This predicate is usually called by the *note term_expansion/2: fc. and
*note goal_expansion/2: fd. methods.  It can also be called directly
from *note initialization/1: 42. directives in a source file.  Note that
the entity keys are only available when compiling an entity term or from
an object ‘initialization/1’ directive.

     Warning: The ‘term_position’ key is only supported in *note backend
     Prolog compilers: 34. that provide access to the start and end
     lines of a read term.  When such support is not available, the
     value ‘-1’ is returned for both the start and the end lines.

     Variables in the values of the ‘term’, ‘variables’,
     ‘variable_names’, and ‘singletons’ keys are not shared with,
     respectively, the term and goal arguments of the ‘term_expansion/2’
     and ‘goal_expansion/2’ methods.  Use instead the
     ‘variable_names(Term)’ and ‘singletons(Term)’ keys when possible.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<58>,  Next: Errors<59>,  Prev: Description<95>,  Up: logtalk_load_context/2

2.4.9.43 Modes and number of proofs
...................................

     logtalk_load_context(?callable, -nonvar) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<59>,  Next: Examples<96>,  Prev: Modes and number of proofs<58>,  Up: logtalk_load_context/2

2.4.9.44 Errors
...............

     ‘Key’ is neither a variable nor a callable term:
          ‘type_error(callable, Key)’
     ‘Key’ is a callable term but not a valid key:
          ‘domain_error(logtalk_load_context_key, Key)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<96>,  Prev: Errors<59>,  Up: logtalk_load_context/2

2.4.9.45 Examples
.................

     % expand source file terms only if they are entity terms
     term_expansion(Term, ExpandedTerms) :-
         logtalk_load_context(entity_identifier, _),
         ....

     % expand source file term while accessing its variable names
     term_expansion(Term, ExpandedTerms) :-
         logtalk_load_context(variable_names(Term), VariableNames),
         ....

     % define a library alias based on the source directory
     :- initialization((
         logtalk_load_context(directory, Directory),
         assertz(logtalk_library_path(my_app, Directory))
     )).

See also
........

*note term_expansion/2: fc, *note goal_expansion/2: fd, *note
initialization/1: 42.


File: TheLogtalkHandbook-3.96.0.info,  Node: Flags,  Next: Linter,  Prev: Compiling and loading source files,  Up: Built-in predicates

2.4.10 Flags
------------

'built-in predicate'

* Menu:

* current_logtalk_flag/2::
* set_logtalk_flag/2: set_logtalk_flag/2<2>.
* create_logtalk_flag/3::


File: TheLogtalkHandbook-3.96.0.info,  Node: current_logtalk_flag/2,  Next: set_logtalk_flag/2<2>,  Up: Flags

2.4.10.1 ‘current_logtalk_flag/2’
.................................

* Menu:

* Description: Description<96>.
* Modes and number of proofs: Modes and number of proofs<59>.
* Errors: Errors<60>.
* Examples: Examples<97>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<96>,  Next: Modes and number of proofs<59>,  Up: current_logtalk_flag/2

2.4.10.2 Description
....................

     current_logtalk_flag(Flag, Value)

Enumerates, by backtracking, the current Logtalk flag values.  For a
description of the predefined compiler flags, please see the *note
Compiler flags: 251. section in the User Manual.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<59>,  Next: Errors<60>,  Prev: Description<96>,  Up: current_logtalk_flag/2

2.4.10.3 Modes and number of proofs
...................................

     current_logtalk_flag(?atom, ?atom) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<60>,  Next: Examples<97>,  Prev: Modes and number of proofs<59>,  Up: current_logtalk_flag/2

2.4.10.4 Errors
...............

     ‘Flag’ is neither a variable nor an atom:
          ‘type_error(atom, Flag)’
     ‘Flag’ is an atom but an invalid flag:
          ‘domain_error(flag, Value)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<97>,  Prev: Errors<60>,  Up: current_logtalk_flag/2

2.4.10.5 Examples
.................

     % get the current value of the source_data flag:
     | ?- current_logtalk_flag(source_data, Value).

See also
........

*note create_logtalk_flag/3: 2e6, *note set_logtalk_flag/2: 51.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: set_logtalk_flag/2<2>,  Next: create_logtalk_flag/3,  Prev: current_logtalk_flag/2,  Up: Flags

2.4.10.6 ‘set_logtalk_flag/2’
.............................

* Menu:

* Description: Description<97>.
* Modes and number of proofs: Modes and number of proofs<60>.
* Errors: Errors<61>.
* Examples: Examples<98>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<97>,  Next: Modes and number of proofs<60>,  Up: set_logtalk_flag/2<2>

2.4.10.7 Description
....................

     set_logtalk_flag(Flag, Value)

Sets global, default, flag values.  For local flag scope, use the
corresponding *note set_logtalk_flag/2: 50. directive.  To set a global
flag value when compiling and loading a source file, wrap the calls to
this built-in predicate with an *note initialization/1: 42. directive.
For a description of the predefined compiler flags, please see the *note
Compiler flags: 251. section in the User Manual.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<60>,  Next: Errors<61>,  Prev: Description<97>,  Up: set_logtalk_flag/2<2>

2.4.10.8 Modes and number of proofs
...................................

     set_logtalk_flag(+atom, +nonvar) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<61>,  Next: Examples<98>,  Prev: Modes and number of proofs<60>,  Up: set_logtalk_flag/2<2>

2.4.10.9 Errors
...............

     ‘Flag’ is a variable:
          ‘instantiation_error’
     ‘Value’ is a variable:
          ‘instantiation_error’
     ‘Flag’ is neither a variable nor an atom:
          ‘type_error(atom, Flag)’
     ‘Flag’ is an atom but an invalid flag:
          ‘domain_error(flag, Flag)’
     ‘Value’ is not a valid value for flag ‘Flag’:
          ‘domain_error(flag_value, Flag + Value)’
     ‘Flag’ is a read-only flag:
          ‘permission_error(modify, flag, Flag)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<98>,  Prev: Errors<61>,  Up: set_logtalk_flag/2<2>

2.4.10.10 Examples
..................

     % turn off globally and by default the compiler
     % unknown entities warnings:
     | ?- set_logtalk_flag(unknown_entities, silent).

See also
........

*note create_logtalk_flag/3: 2e6, *note current_logtalk_flag/2: 2b3.

'built-in predicate'


File: TheLogtalkHandbook-3.96.0.info,  Node: create_logtalk_flag/3,  Prev: set_logtalk_flag/2<2>,  Up: Flags

2.4.10.11 ‘create_logtalk_flag/3’
.................................

* Menu:

* Description: Description<98>.
* Modes and number of proofs: Modes and number of proofs<61>.
* Errors: Errors<62>.
* Examples: Examples<99>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<98>,  Next: Modes and number of proofs<61>,  Up: create_logtalk_flag/3

2.4.10.12 Description
.....................

     create_logtalk_flag(Flag, Value, Options)

Creates a new Logtalk flag and sets its default value.  User-defined
flags can be queried and set in the same way as predefined flags by
using, respectively, the *note current_logtalk_flag/2: 2b3. and *note
set_logtalk_flag/2: 51. built-in predicates.  For a description of the
predefined compiler flags, please see the *note Compiler flags: 251.
section in the User Manual.

This predicate is based on the specification of the SWI-Prolog
‘create_prolog_flag/3’ built-in predicate and supports the same options:
‘access(Access)’, where ‘Access’ can be either ‘read_write’ (the
default) or ‘read_only’; ‘keep(Keep)’, where ‘Keep’ can be either
‘false’ (the default) or ‘true’, for deciding if an existing definition
of the flag should be kept or replaced by the new one; and ‘type(Type)’
for specifying the type of the flag, which can be ‘boolean’, ‘atom’,
‘integer’, ‘float’, or ‘term’ (which only restricts the flag value to
ground terms).  When the ‘type/1’ option is not specified, the type of
the flag is inferred from its initial value.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<61>,  Next: Errors<62>,  Prev: Description<98>,  Up: create_logtalk_flag/3

2.4.10.13 Modes and number of proofs
....................................

     create_logtalk_flag(+atom, +ground, +list(ground)) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<62>,  Next: Examples<99>,  Prev: Modes and number of proofs<61>,  Up: create_logtalk_flag/3

2.4.10.14 Errors
................

     ‘Flag’ is a variable:
          ‘instantiation_error’
     ‘Value’ is not a ground term:
          ‘instantiation_error’
     ‘Options’ is not a ground term:
          ‘instantiation_error’
     ‘Flag’ is neither a variable nor an atom:
          ‘type_error(atom, Flag)’
     ‘Options’ is neither a variable nor a list:
          ‘type_error(atom, Flag)’
     ‘Value’ is not a valid value for flag Flag:
          ‘domain_error(flag_value, Flag + Value)’
     ‘Flag’ is a system-defined flag:
          ‘permission_error(modify, flag, Flag)’
     An element ‘Option’ of the list ‘Options’ is not a valid option
          domain_error(flag_option,Option)
     The list ‘Options’ contains a ‘type(Type)’ option and ‘Value’ is not of type ‘Type’
          type_error(Type, Value)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<99>,  Prev: Errors<62>,  Up: create_logtalk_flag/3

2.4.10.15 Examples
..................

     % create a new boolean flag with default value set to false:
     | ?- create_logtalk_flag(pretty_print_blobs, false, []).

See also
........

*note current_logtalk_flag/2: 2b3, *note set_logtalk_flag/2: 51.


File: TheLogtalkHandbook-3.96.0.info,  Node: Linter,  Prev: Flags,  Up: Built-in predicates

2.4.11 Linter
-------------

'built-in predicate'

* Menu:

* logtalk_linter_hook/7::


File: TheLogtalkHandbook-3.96.0.info,  Node: logtalk_linter_hook/7,  Up: Linter

2.4.11.1 ‘logtalk_linter_hook/7’
................................

* Menu:

* Description: Description<99>.
* Modes and number of proofs: Modes and number of proofs<62>.
* Errors: Errors<63>.
* Examples: Examples<100>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<99>,  Next: Modes and number of proofs<62>,  Up: logtalk_linter_hook/7

2.4.11.2 Description
....................

     logtalk_linter_hook(Goal, Flag, File, Lines, Type, Entity, Warning)

Multifile user-defined predicate, supporting the definition of custom
linter warnings.  Experimental.  The ‘Goal’ argument can be a
message-sending goal, ‘Object::Message’, a call to a Prolog built-in
predicate, or a call to a module predicate, ‘Module:Predicate’.  The
‘Flag’ argument must be a supported linter flag.  The ‘Warning’ argument
must be a valid ‘core’ message term.  For a given ‘Goal’, only the first
successful call to this predicate is considered.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<62>,  Next: Errors<63>,  Prev: Description<99>,  Up: logtalk_linter_hook/7

2.4.11.3 Modes and number of proofs
...................................

     logtalk_linter_hook(@callable, +atom, +atom, +pair(integer), +atom, @object_identifier, --callable) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<63>,  Next: Examples<100>,  Prev: Modes and number of proofs<62>,  Up: logtalk_linter_hook/7

2.4.11.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<100>,  Prev: Errors<63>,  Up: logtalk_linter_hook/7

2.4.11.5 Examples
.................

     :- multifile(user::logtalk_linter_hook/7).
     % warn about using list::append/3 to construct a list from an head and a tail
     user::logtalk_linter_hook(
         list::append(L1,L2,L), suspicious_calls,
         File, Lines, Type, Entity,
         suspicious_call(File, Lines, Type, Entity, list::append(L1,L2,L), [L=[Head|L2]])
     ) :-
         nonvar(L1),
         L1 = [Head].


File: TheLogtalkHandbook-3.96.0.info,  Node: Built-in methods<2>,  Prev: Built-in predicates,  Up: Reference Manual

2.5 Built-in methods
====================

* Menu:

* Logic and control::
* Execution context::
* Reflection: Reflection<2>.
* Database::
* Meta-calls::
* Error handling: Error handling<2>.
* All solutions::
* Event handling: Event handling<3>.
* Message forwarding::
* Definite clause grammar rules: Definite clause grammar rules<2>.
* Term and goal expansion: Term and goal expansion<2>.
* Coinduction hooks::
* Message printing::
* Question asking::


File: TheLogtalkHandbook-3.96.0.info,  Node: Logic and control,  Next: Execution context,  Up: Built-in methods<2>

2.5.1 Logic and control
-----------------------

'built-in method'

* Menu:

* !/0::
* true/0::
* fail/0::
* false/0::
* repeat/0::


File: TheLogtalkHandbook-3.96.0.info,  Node: !/0,  Next: true/0,  Up: Logic and control

2.5.1.1 ‘!/0’
.............

* Menu:

* Description: Description<100>.
* Modes and number of proofs: Modes and number of proofs<63>.
* Errors: Errors<64>.
* Examples: Examples<101>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<100>,  Next: Modes and number of proofs<63>,  Up: !/0

2.5.1.2 Description
...................

     !

Always succeeds with the side-effect of discarding choice-points.  See
also the ISO Prolog standard definition.  This built-in method is
declared as a public method and can be used as a message to an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<63>,  Next: Errors<64>,  Prev: Description<100>,  Up: !/0

2.5.1.3 Modes and number of proofs
..................................

     ! - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<64>,  Next: Examples<101>,  Prev: Modes and number of proofs<63>,  Up: !/0

2.5.1.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<101>,  Prev: Errors<64>,  Up: !/0

2.5.1.5 Examples
................

(none)

See also
........

*note true/0: 197, *note fail/0: 198, *note false/0: 199, *note
repeat/0: 19a.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: true/0,  Next: fail/0,  Prev: !/0,  Up: Logic and control

2.5.1.6 ‘true/0’
................

* Menu:

* Description: Description<101>.
* Modes and number of proofs: Modes and number of proofs<64>.
* Errors: Errors<65>.
* Examples: Examples<102>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<101>,  Next: Modes and number of proofs<64>,  Up: true/0

2.5.1.7 Description
...................

     true

Always succeeds.  See also the ISO Prolog standard definition.  This
built-in method is declared as a public method and can be used as a
message to an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<64>,  Next: Errors<65>,  Prev: Description<101>,  Up: true/0

2.5.1.8 Modes and number of proofs
..................................

     true - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<65>,  Next: Examples<102>,  Prev: Modes and number of proofs<64>,  Up: true/0

2.5.1.9 Errors
..............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<102>,  Prev: Errors<65>,  Up: true/0

2.5.1.10 Examples
.................

(none)

See also
........

*note !/0: 196, *note fail/0: 198, *note false/0: 199, *note repeat/0:
19a.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: fail/0,  Next: false/0,  Prev: true/0,  Up: Logic and control

2.5.1.11 ‘fail/0’
.................

* Menu:

* Description: Description<102>.
* Modes and number of proofs: Modes and number of proofs<65>.
* Errors: Errors<66>.
* Examples: Examples<103>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<102>,  Next: Modes and number of proofs<65>,  Up: fail/0

2.5.1.12 Description
....................

     fail

Always fails.  See also the ISO Prolog standard definition.  This
built-in method is declared as a public method and can be used as a
message to an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<65>,  Next: Errors<66>,  Prev: Description<102>,  Up: fail/0

2.5.1.13 Modes and number of proofs
...................................

     fail - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<66>,  Next: Examples<103>,  Prev: Modes and number of proofs<65>,  Up: fail/0

2.5.1.14 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<103>,  Prev: Errors<66>,  Up: fail/0

2.5.1.15 Examples
.................

(none)

See also
........

*note !/0: 196, *note true/0: 197, *note false/0: 199, *note repeat/0:
19a.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: false/0,  Next: repeat/0,  Prev: fail/0,  Up: Logic and control

2.5.1.16 ‘false/0’
..................

* Menu:

* Description: Description<103>.
* Modes and number of proofs: Modes and number of proofs<66>.
* Errors: Errors<67>.
* Examples: Examples<104>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<103>,  Next: Modes and number of proofs<66>,  Up: false/0

2.5.1.17 Description
....................

     false

Always fails.  See also the ISO Prolog standard definition.  This
built-in method is declared as a public method and can be used as a
message to an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<66>,  Next: Errors<67>,  Prev: Description<103>,  Up: false/0

2.5.1.18 Modes and number of proofs
...................................

     false - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<67>,  Next: Examples<104>,  Prev: Modes and number of proofs<66>,  Up: false/0

2.5.1.19 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<104>,  Prev: Errors<67>,  Up: false/0

2.5.1.20 Examples
.................

(none)

See also
........

*note !/0: 196, *note true/0: 197, *note fail/0: 198, *note repeat/0:
19a.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: repeat/0,  Prev: false/0,  Up: Logic and control

2.5.1.21 ‘repeat/0’
...................

* Menu:

* Description: Description<104>.
* Modes and number of proofs: Modes and number of proofs<67>.
* Errors: Errors<68>.
* Examples: Examples<105>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<104>,  Next: Modes and number of proofs<67>,  Up: repeat/0

2.5.1.22 Description
....................

     repeat

Always succeeds when called and when backtracking into its call with an
infinite number of choice-points.  See also the ISO Prolog standard
definition.  This built-in method is declared as a public method and can
be used as a message to an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<67>,  Next: Errors<68>,  Prev: Description<104>,  Up: repeat/0

2.5.1.23 Modes and number of proofs
...................................

     repeat - one_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<68>,  Next: Examples<105>,  Prev: Modes and number of proofs<67>,  Up: repeat/0

2.5.1.24 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<105>,  Prev: Errors<68>,  Up: repeat/0

2.5.1.25 Examples
.................

(none)

See also
........

*note !/0: 196, *note true/0: 197, *note fail/0: 198, *note false/0:
199.


File: TheLogtalkHandbook-3.96.0.info,  Node: Execution context,  Next: Reflection<2>,  Prev: Logic and control,  Up: Built-in methods<2>

2.5.2 Execution context
-----------------------

'built-in method'

* Menu:

* context/1::
* parameter/2::
* self/1::
* sender/1::
* this/1::


File: TheLogtalkHandbook-3.96.0.info,  Node: context/1,  Next: parameter/2,  Up: Execution context

2.5.2.1 ‘context/1’
...................

* Menu:

* Description: Description<105>.
* Modes and number of proofs: Modes and number of proofs<68>.
* Errors: Errors<69>.
* Examples: Examples<106>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<105>,  Next: Modes and number of proofs<68>,  Up: context/1

2.5.2.2 Description
...................

     context(Context)

Returns the execution context for a predicate clause using the term
‘logtalk(Head,ExecutionContext)’ where ‘Head’ is the head of the clause
containing the call.  This private predicate is mainly used for
providing an error context when type-checking predicate arguments.  The
‘ExecutionContext’ term should be regarded as an opaque term, which can
be decoded using the logtalk::execution_context/7(1) predicate.  Calls
to this predicate are inlined at compilation time.

     Warning: As the execution context term includes the clause head,
     the head of the clause calling the ‘context(Context)’ method cannot
     contain the ‘Context’ variable as that would result in the creation
     of a cyclic term.  The compiler detects and reports any offending
     clauses by throwing a ‘representation_error(acyclic_term)’ error.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0-execution-context-7


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<68>,  Next: Errors<69>,  Prev: Description<105>,  Up: context/1

2.5.2.3 Modes and number of proofs
..................................

     context(--callable) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<69>,  Next: Examples<106>,  Prev: Modes and number of proofs<68>,  Up: context/1

2.5.2.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<106>,  Prev: Errors<69>,  Up: context/1

2.5.2.5 Examples
................

     foo(A, N) :-
         % type-check arguments
         context(Context),
         type::check(atom, A, Context),
         type::check(integer, N, Context),
         % arguments are fine; go ahead
         ... .

See also
........

*note parameter/2: a2, *note self/1: 67, *note sender/1: 19d, *note
this/1: 68.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: parameter/2,  Next: self/1,  Prev: context/1,  Up: Execution context

2.5.2.6 ‘parameter/2’
.....................

* Menu:

* Description: Description<106>.
* Modes and number of proofs: Modes and number of proofs<69>.
* Errors: Errors<70>.
* Examples: Examples<107>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<106>,  Next: Modes and number of proofs<69>,  Up: parameter/2

2.5.2.7 Description
...................

     parameter(Number, Term)

Used in *note parametric objects: 6a0. (and parametric categories), this
private method provides runtime access to the parameter values of the
entity that contains the predicate clause whose body is being executed
by using the argument number in the entity identifier.  This predicate
is implemented as a unification between its second argument and the
corresponding implicit execution-context argument in the predicate
clause making the call.  This unification occurs at the clause head when
the second argument is not instantiated (the most common case).  When
the second argument is instantiated, the unification must be delayed to
runtime and thus occurs at the clause body.

Entity parameters can also be accessed using 'parameter variables',
which use the syntax ‘_VariableName_’.  The compiler recognizes
occurrences of these variables in directives and clauses.  Parameter
variables allow us to abstract parameter positions, thus simplifying
code maintenance.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<69>,  Next: Errors<70>,  Prev: Description<106>,  Up: parameter/2

2.5.2.8 Modes and number of proofs
..................................

     parameter(+integer, ?term) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<70>,  Next: Examples<107>,  Prev: Modes and number of proofs<69>,  Up: parameter/2

2.5.2.9 Errors
..............

     ‘Number’ is a variable:
          ‘instantiation_error’
     ‘Number’ is neither a variable nor an integer value:
          ‘type_error(integer, Number)’
     ‘Number’ is smaller than one or greater than the parametric entity identifier arity:
          ‘domain_error(out_of_range, Number)’
     ‘Entity’ identifier is not a compound term:
          ‘type_error(compound, Entity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<107>,  Prev: Errors<70>,  Up: parameter/2

2.5.2.10 Examples
.................

     :- object(box(_Color, _Weight)).

         ...

         % this clause is translated into
         % a fact upon compilation
         color(Color) :-
             parameter(1, Color).

         % upon compilation, the >/2 call will be
         % the single goal in the clause body
         heavy :-
             parameter(2, Weight),
             Weight > 10.
         ...

The same example using 'parameter variables':

     :- object(box(_Color_, _Weight_)).

         ...

         color(_Color_).

         heavy :-
             _Weight_ > 10.

         ...

See also
........

*note context/1: 19e, *note self/1: 67, *note sender/1: 19d, *note
this/1: 68.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: self/1,  Next: sender/1,  Prev: parameter/2,  Up: Execution context

2.5.2.11 ‘self/1’
.................

* Menu:

* Description: Description<107>.
* Modes and number of proofs: Modes and number of proofs<70>.
* Errors: Errors<71>.
* Examples: Examples<108>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<107>,  Next: Modes and number of proofs<70>,  Up: self/1

2.5.2.12 Description
....................

     self(Self)

Unifies its argument with the object that received the message under
processing.

This private method is compiled into a unification between its argument
and the corresponding implicit context argument in the predicate clause
making the call.  This unification occurs at the clause head when the
argument is not bound at compile-time (the most common case).


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<70>,  Next: Errors<71>,  Prev: Description<107>,  Up: self/1

2.5.2.13 Modes and number of proofs
...................................

     self(?object_identifier) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<71>,  Next: Examples<108>,  Prev: Modes and number of proofs<70>,  Up: self/1

2.5.2.14 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<108>,  Prev: Errors<71>,  Up: self/1

2.5.2.15 Examples
.................

     % upon compilation, the write/1 call will be
     % the first goal in the clause body
     test :-
         self(Self),
         write('executing a method in behalf of '),
         writeq(Self), nl.

See also
........

*note context/1: 19e, *note parameter/2: a2, *note sender/1: 19d, *note
this/1: 68.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: sender/1,  Next: this/1,  Prev: self/1,  Up: Execution context

2.5.2.16 ‘sender/1’
...................

* Menu:

* Description: Description<108>.
* Modes and number of proofs: Modes and number of proofs<71>.
* Errors: Errors<72>.
* Examples: Examples<109>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<108>,  Next: Modes and number of proofs<71>,  Up: sender/1

2.5.2.17 Description
....................

     sender(Sender)

Unifies its argument with the object that sent the message under
processing.

This private method is translated into a unification between its
argument and the corresponding implicit context argument in the
predicate clause making the call.  This unification occurs at the clause
head when the argument is not bound at compile-time (the most common
case).


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<71>,  Next: Errors<72>,  Prev: Description<108>,  Up: sender/1

2.5.2.18 Modes and number of proofs
...................................

     sender(?object_identifier) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<72>,  Next: Examples<109>,  Prev: Modes and number of proofs<71>,  Up: sender/1

2.5.2.19 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<109>,  Prev: Errors<72>,  Up: sender/1

2.5.2.20 Examples
.................

     % after compilation, the write/1 call will
     % be the first goal in the clause body
     test :-
         sender(Sender),
         write('executing a method to answer a message sent by '),
         writeq(Sender), nl.

See also
........

*note context/1: 19e, *note parameter/2: a2, *note self/1: 67, *note
this/1: 68.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: this/1,  Prev: sender/1,  Up: Execution context

2.5.2.21 ‘this/1’
.................

* Menu:

* Description: Description<109>.
* Modes and number of proofs: Modes and number of proofs<72>.
* Errors: Errors<73>.
* Examples: Examples<110>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<109>,  Next: Modes and number of proofs<72>,  Up: this/1

2.5.2.22 Description
....................

     this(This)

Unifies its argument with the identifier of the object calling this
method.  When this method is called from a category, the argument is
unified with the object importing the category on whose behalf the
clause containing the call is being used to prove the current goal.

This private method is implemented as a unification between its argument
and the corresponding implicit execution-context argument in the
predicate clause making the call.  This unification occurs at the clause
head when the argument is not bound at compile-time (the most common
case).

This method is useful for avoiding hard-coding references to an object
identifier or for retrieving all object parameters with a single call
when using parametric objects.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<72>,  Next: Errors<73>,  Prev: Description<109>,  Up: this/1

2.5.2.23 Modes and number of proofs
...................................

     this(?object_identifier) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<73>,  Next: Examples<110>,  Prev: Modes and number of proofs<72>,  Up: this/1

2.5.2.24 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<110>,  Prev: Errors<73>,  Up: this/1

2.5.2.25 Examples
.................

     % after compilation, the write/1 call will
     % be the first goal in the clause body
     test :-
         this(This),
         write('Using a predicate clause contained in '),
         writeq(This), nl.

See also
........

*note context/1: 19e, *note parameter/2: a2, *note self/1: 67, *note
sender/1: 19d.


File: TheLogtalkHandbook-3.96.0.info,  Node: Reflection<2>,  Next: Database,  Prev: Execution context,  Up: Built-in methods<2>

2.5.3 Reflection
----------------

'built-in method'

* Menu:

* current_op/3::
* current_predicate/1::
* predicate_property/2::


File: TheLogtalkHandbook-3.96.0.info,  Node: current_op/3,  Next: current_predicate/1,  Up: Reflection<2>

2.5.3.1 ‘current_op/3’
......................

* Menu:

* Description: Description<110>.
* Modes and number of proofs: Modes and number of proofs<73>.
* Errors: Errors<74>.
* Examples: Examples<111>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<110>,  Next: Modes and number of proofs<73>,  Up: current_op/3

2.5.3.2 Description
...................

     current_op(Priority, Specifier, Operator)

Enumerates, by backtracking, the visible operators declared for an
object.  Operators not declared using a scope directive are not
enumerated.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<73>,  Next: Errors<74>,  Prev: Description<110>,  Up: current_op/3

2.5.3.3 Modes and number of proofs
..................................

     current_op(?operator_priority, ?operator_specifier, ?atom) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<74>,  Next: Examples<111>,  Prev: Modes and number of proofs<73>,  Up: current_op/3

2.5.3.4 Errors
..............

     ‘Priority’ is neither a variable nor an integer:
          ‘type_error(integer, Priority)’
     ‘Priority’ is an integer but not a valid operator priority:
          ‘domain_error(operator_priority, Priority)’
     ‘Specifier’ is neither a variable nor an atom:
          ‘type_error(atom, Specifier)’
     ‘Specifier’ is an atom but not a valid operator specifier:
          ‘domain_error(operator_specifier, Specifier)’
     ‘Operator’ is neither a variable nor an atom:
          ‘type_error(atom, Operator)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<111>,  Prev: Errors<74>,  Up: current_op/3

2.5.3.5 Examples
................

     To enumerate, by backtracking, the local operators or the operators visible in *note this: 114.:
          ‘current_op(Priority, Specifier, Operator)’
     To enumerate, by backtracking, the public and protected operators visible in *note self: 69.:
          ‘::current_op(Priority, Specifier, Operator)’
     To enumerate, by backtracking, the public operators visible for an explicit object:
          ‘Object::current_op(Priority, Specifier, Operator)’

See also
........

*note current_predicate/1: 141, *note predicate_property/2: 142, *note
op/3: 15d.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: current_predicate/1,  Next: predicate_property/2,  Prev: current_op/3,  Up: Reflection<2>

2.5.3.6 ‘current_predicate/1’
.............................

* Menu:

* Description: Description<111>.
* Modes and number of proofs: Modes and number of proofs<74>.
* Errors: Errors<75>.
* Examples: Examples<112>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<111>,  Next: Modes and number of proofs<74>,  Up: current_predicate/1

2.5.3.7 Description
...................

     current_predicate(Predicate)

Enumerates, by backtracking, visible, user-defined, object predicates.
Built-in predicates and predicates not declared using a scope directive
are not enumerated.

This predicate also succeeds for any predicates listed in *note uses/2:
4b. and *note use_module/2: 4d. directives.

When ‘Predicate’ is bound at compile-time to a ‘(:)/2’ term, this
predicate enumerates module predicates (assuming that the *note backend
Prolog compiler: 34. supports modules).


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<74>,  Next: Errors<75>,  Prev: Description<111>,  Up: current_predicate/1

2.5.3.8 Modes and number of proofs
..................................

     current_predicate(?predicate_indicator) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<75>,  Next: Examples<112>,  Prev: Modes and number of proofs<74>,  Up: current_predicate/1

2.5.3.9 Errors
..............

     ‘Predicate’ is neither a variable nor a valid predicate indicator:
          ‘type_error(predicate_indicator, Predicate)’
     ‘Predicate’ is a ‘Name/Arity’ term but ‘Functor’ is neither a variable nor an atom:
          ‘type_error(atom, Name)’
     ‘Predicate’ is a ‘Name/Arity’ term but ‘Arity’ is neither a variable nor an integer:
          ‘type_error(integer, Arity)’
     ‘Predicate’ is a ‘Name/Arity’ term but ‘Arity’ is a negative integer:
          ‘domain_error(not_less_than_zero, Arity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<112>,  Prev: Errors<75>,  Up: current_predicate/1

2.5.3.10 Examples
.................

     To enumerate, by backtracking, the locally visible user predicates or the user predicates visible in *note this: 114.:
          ‘current_predicate(Predicate)’
     To enumerate, by backtracking, the public and protected user predicates visible in *note self: 69.:
          ‘::current_predicate(Predicate)’
     To enumerate, by backtracking, the public user predicates visible for an explicit object:
          ‘Object::current_predicate(Predicate)’

An example of enumerating locally visible object predicates.  These
include predicates listed using *note uses/2: 4b. and *note
use_module/2: 4d. directives:

     :- object(foo).

         :- uses(bar, [
             baz/1, quux/2
         ]).

         :- public(pred/1).
         pred(X) :-
            current_predicate(X).

     :- end_object.

     | ?- foo::pred(X).
     X = pred/1 ;
     X = baz/1 ;
     X = quux/2 ;
     no

See also
........

*note current_op/3: 15e, *note predicate_property/2: 142, *note uses/2:
4b, *note use_module/2: 4d.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: predicate_property/2,  Prev: current_predicate/1,  Up: Reflection<2>

2.5.3.11 ‘predicate_property/2’
...............................

* Menu:

* Description: Description<112>.
* Modes and number of proofs: Modes and number of proofs<75>.
* Errors: Errors<76>.
* Examples: Examples<113>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<112>,  Next: Modes and number of proofs<75>,  Up: predicate_property/2

2.5.3.12 Description
....................

     predicate_property(Predicate, Property)

Enumerates, by backtracking, the properties of a visible object
predicate.  Properties for predicates not declared using a scope
directive are not enumerated.  The valid predicate properties are listed
in the language grammar section on *note predicate properties: 3ee. and
described in the User Manual section on *note predicate properties: 1cc.

When ‘Predicate’ is listed in a *note uses/2: 4b. or *note use_module/2:
4d. directive, properties are enumerated for the referenced object or
module predicate.

When ‘Predicate’ is bound at compile-time to a ‘(:)/2’ term, this
predicate enumerates properties for module predicates (assuming that the
*note backend Prolog compiler: 34. supports modules).


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<75>,  Next: Errors<76>,  Prev: Description<112>,  Up: predicate_property/2

2.5.3.13 Modes and number of proofs
...................................

     predicate_property(+callable, ?predicate_property) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<76>,  Next: Examples<113>,  Prev: Modes and number of proofs<75>,  Up: predicate_property/2

2.5.3.14 Errors
...............

     ‘Predicate’ is a variable:
          ‘instantiation_error’
     ‘Predicate’ is neither a variable nor a callable term:
          ‘type_error(callable, Predicate)’
     ‘Property’ is neither a variable nor a valid predicate property:
          ‘domain_error(predicate_property, Property)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<113>,  Prev: Errors<76>,  Up: predicate_property/2

2.5.3.15 Examples
.................

     To enumerate, by backtracking, the properties of a locally visible user predicate or a user predicate visible in *note this: 114.:
          ‘predicate_property(Predicate, Property)’
     To enumerate, by backtracking, the properties of a public or protected predicate visible in *note self: 69.:
          ‘::predicate_property(Predicate, Property)’
     To enumerate, by backtracking, the properties of a public predicate visible in an explicit object:
          ‘Object::predicate_property(Predicate, Property)’

An example of enumerating properties for locally visible object
predicates.  These include predicates listed using *note uses/2: 4b. and
*note use_module/2: 4d. directives:

     :- object(foo).

         :- uses(bar, [
             baz/1, quux/2
         ]).

         :- public(pred/1).
         pred_prop(Pred, Prop) :-
            predicate_property(Pred, Prop).

     :- end_object.

     | ?- foo::pred(baz(_), Prop).
     Prop = logtalk ;
     Prop = scope(public) ;
     Prop = public ;
     Prop = declared_in(bar) ;
     ...

See also
........

*note current_op/3: 15e, *note current_predicate/1: 141, *note uses/2:
4b, *note use_module/2: 4d.


File: TheLogtalkHandbook-3.96.0.info,  Node: Database,  Next: Meta-calls,  Prev: Reflection<2>,  Up: Built-in methods<2>

2.5.4 Database
--------------

'built-in method'

* Menu:

* abolish/1::
* asserta/1::
* assertz/1::
* clause/2::
* retract/1::
* retractall/1::


File: TheLogtalkHandbook-3.96.0.info,  Node: abolish/1,  Next: asserta/1,  Up: Database

2.5.4.1 ‘abolish/1’
...................

* Menu:

* Description: Description<113>.
* Modes and number of proofs: Modes and number of proofs<76>.
* Errors: Errors<77>.
* Examples: Examples<114>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<113>,  Next: Modes and number of proofs<76>,  Up: abolish/1

2.5.4.2 Description
...................

     abolish(Predicate)

Abolishes a runtime declared object dynamic predicate or an object local
dynamic predicate.  Only predicates that are dynamically declared at
runtime (using a call to the *note asserta/1: 1b2. or *note assertz/1:
1b3. built-in methods) can be abolished.

When the predicate indicator is declared in a *note uses/2: 4b. or *note
use_module/2: 4d. directive, the predicate is abolished in the
referenced object or module.  When the backend Prolog compiler supports
a module system, the predicate argument can also be module qualified.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<76>,  Next: Errors<77>,  Prev: Description<113>,  Up: abolish/1

2.5.4.3 Modes and number of proofs
..................................

     abolish(@predicate_indicator) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<77>,  Next: Examples<114>,  Prev: Modes and number of proofs<76>,  Up: abolish/1

2.5.4.4 Errors
..............

     ‘Predicate’ is a variable:
          ‘instantiation_error’
     ‘Functor’ is a variable:
          ‘instantiation_error’
     ‘Arity’ is a variable:
          ‘instantiation_error’
     ‘Predicate’ is neither a variable nor a valid predicate indicator:
          ‘type_error(predicate_indicator, Predicate)’
     ‘Functor’ is neither a variable nor an atom:
          ‘type_error(atom, Functor)’
     ‘Arity’ is neither a variable nor an integer:
          ‘type_error(integer, Arity)’
     ‘Predicate’ is statically declared:
          ‘permission_error(modify, predicate_declaration, Name/Arity)’
     ‘Predicate’ is a private predicate:
          ‘permission_error(modify, private_predicate, Name/Arity)’
     ‘Predicate’ is a protected predicate:
          ‘permission_error(modify, protected_predicate, Name/Arity)’
     ‘Predicate’ is a static predicate:
          ‘permission_error(modify, static_predicate, Name/Arity)’
     ‘Predicate’ is not declared for the object receiving the message:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<114>,  Prev: Errors<77>,  Up: abolish/1

2.5.4.5 Examples
................

     To abolish a local dynamic predicate or a dynamic predicate in *note this: 114.:
          ‘abolish(Predicate)’
     To abolish a public or protected dynamic predicate in *note self: 69.:
          ‘::abolish(Predicate)’
     To abolish a public dynamic predicate in an explicit object:
          ‘Object::abolish(Predicate)’

See also
........

*note asserta/1: 1b2, *note assertz/1: 1b3, *note clause/2: 1b4, *note
retract/1: 1b5, *note retractall/1: 1b6. *note dynamic/0: b1, *note
dynamic/1: 15a, *note uses/2: 4b, *note use_module/2: 4d.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: asserta/1,  Next: assertz/1,  Prev: abolish/1,  Up: Database

2.5.4.6 ‘asserta/1’
...................

* Menu:

* Description: Description<114>.
* Modes and number of proofs: Modes and number of proofs<77>.
* Errors: Errors<78>.
* Examples: Examples<115>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<114>,  Next: Modes and number of proofs<77>,  Up: asserta/1

2.5.4.7 Description
...................

     asserta(Head)
     asserta((Head:-Body))

Asserts a clause as the first one for an object dynamic predicate.

When the predicate was not previously declared (using a scope
directive), a dynamic predicate declaration is added to the object.  In
this case, the predicate scope depends on how this method is called:

‘asserta(Clause)’

     The predicate is dynamically declared as *note private: 55.

‘::asserta(Clause)’

     The predicate is dynamically declared as *note protected: 54.

‘Object::asserta(Clause)’

     The predicate is dynamically declared as *note public: 53.

Note, however, that dynamically declaring a new predicate requires
either a local assert or the *note dynamic_declarations: 2d8. compiler
flag set to ‘allow’ when the object was created or compiled.

When the predicate indicator for ‘Head’ is declared in a *note uses/2:
4b. or *note use_module/2: 4d. directive, the clause is asserted in the
referenced object or module.  When the backend Prolog compiler supports
a module system, the predicate argument can also be module qualified.

This method may be used to assert clauses for predicates that are not
declared dynamic for dynamic objects provided that the predicates are
declared in *note this: 114.  This allows easy initialization of
dynamically created objects when writing constructors.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<77>,  Next: Errors<78>,  Prev: Description<114>,  Up: asserta/1

2.5.4.8 Modes and number of proofs
..................................

     asserta(+clause) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<78>,  Next: Examples<115>,  Prev: Modes and number of proofs<77>,  Up: asserta/1

2.5.4.9 Errors
..............

     ‘Head’ is a variable:
          ‘instantiation_error’
     ‘Head’ is neither a variable nor a callable term:
          ‘type_error(callable, Head)’
     ‘Body’ cannot be converted to a goal:
          ‘type_error(callable, Body)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a private predicate:
          ‘permission_error(modify, private_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a protected predicate:
          ‘permission_error(modify, protected_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a static predicate:
          ‘permission_error(modify, static_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, does not match a declared predicate and the target object was created or compiled with support for dynamic declaration of predicates turned off:
          ‘permission_error(create, predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<115>,  Prev: Errors<78>,  Up: asserta/1

2.5.4.10 Examples
.................

     To assert a clause as the first one for a local dynamic predicate or a dynamic predicate in *note this: 114.:
          ‘asserta(Clause)’
     To assert a clause as the first one for any public or protected dynamic predicate in *note self: 69.:
          ‘::asserta(Clause)’
     To assert a clause as the first one for any public dynamic predicate in an explicit object:
          ‘Object::asserta(Clause)’

An example of asserting clauses in *note this: 114. and in *note self:
69. from a category:

     :- category(attributes,
         implements(attributes_protocol)).

         :- private(attr_/1).
         :- dynamic(attr_/1).

         set_in_this(A, X) :-
            asserta(attr_(A, X)).

         set_in_self(A, X) :-
            ::asserta(attr_(A, X)).

         ...

An example of asserting clauses into another object with the predicates
listed using a *note uses/2: 4b. directive (similar when using a *note
use_module/2: 4d. directive):

     :- object(reasoner(_KnowledgeBase_)).

         :- uses(_KnowledgeBase_, [
             foo/1, bar/1
         ]).

         baz(X) :-
            % compiled as _KnowledgeBase_::assertz(foo(X))
            asserta(foo(X)).

        foobar(Name, Argument) :-
           Clause =.. [Name, Argument],
           % runtime resolved to _KnowledgeBase_::assertz(Clause)
           % when Name is either foo or bar
           asserta(Clause).

         ...

See also
........

*note abolish/1: 1b1, *note assertz/1: 1b3, *note clause/2: 1b4, *note
retract/1: 1b5, *note retractall/1: 1b6. *note dynamic/0: b1, *note
dynamic/1: 15a, *note uses/2: 4b, *note use_module/2: 4d.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: assertz/1,  Next: clause/2,  Prev: asserta/1,  Up: Database

2.5.4.11 ‘assertz/1’
....................

* Menu:

* Description: Description<115>.
* Modes and number of proofs: Modes and number of proofs<78>.
* Errors: Errors<79>.
* Examples: Examples<116>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<115>,  Next: Modes and number of proofs<78>,  Up: assertz/1

2.5.4.12 Description
....................

     assertz(Head)
     assertz((Head:-Body))

Asserts a clause as the last one for a dynamic predicate.

When the predicate was not previously declared (using a scope
directive), a dynamic predicate declaration is added to the object.  In
this case, the predicate scope depends on how this method is called:

‘assertz(Clause)’

     The predicate is dynamically declared as *note private: 55.

‘::assertz(Clause)’

     The predicate is dynamically declared as *note protected: 54.

‘Object::assertz(Clause)’

     The predicate is dynamically declared as *note public: 53.

Note, however, that dynamically declaring a new predicate requires
either a local assert or the *note dynamic_declarations: 2d8. compiler
flag set to ‘allow’ when the object was created or compiled.

When the predicate indicator for ‘Head’ is declared in a *note uses/2:
4b. or *note use_module/2: 4d. directive, the clause is asserted in the
referenced object or module.  When the backend Prolog compiler supports
a module system, the predicate argument can also be module qualified.

This method may be used to assert clauses for predicates that are not
declared dynamic for dynamic objects provided that the predicates are
declared in *note this: 114.  This allows easy initialization of
dynamically created objects when writing constructors.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<78>,  Next: Errors<79>,  Prev: Description<115>,  Up: assertz/1

2.5.4.13 Modes and number of proofs
...................................

     assertz(+clause) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<79>,  Next: Examples<116>,  Prev: Modes and number of proofs<78>,  Up: assertz/1

2.5.4.14 Errors
...............

     ‘Head’ is a variable:
          ‘instantiation_error’
     ‘Head’ is neither a variable nor a callable term:
          ‘type_error(callable, Head)’
     ‘Body’ cannot be converted to a goal:
          ‘type_error(callable, Body)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a private predicate:
          ‘permission_error(modify, private_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a protected predicate:
          ‘permission_error(modify, protected_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a static predicate:
          ‘permission_error(modify, static_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, does not match a declared predicate and the target object was created/compiled with support for dynamic declaration of predicates turned off:
          ‘permission_error(create, predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<116>,  Prev: Errors<79>,  Up: assertz/1

2.5.4.15 Examples
.................

     To assert a clause as the last one for a local dynamic predicate or a dynamic predicate in *note this: 114.:
          ‘assertz(Clause)’
     To assert a clause as the last one for any public or protected dynamic predicate in *note self: 69.:
          ‘::assertz(Clause)’
     To assert a clause as the last one for any public dynamic predicate in an explicit object:
          ‘Object::assertz(Clause)’

An example of asserting clauses in *note this: 114. and in *note self:
69. from a category:

     :- category(attributes,
         implements(attributes_protocol)).

         :- private(attr_/1).
         :- dynamic(attr_/1).

         set_in_this(A, X) :-
            assertz(attr_(A, X)).

         set_in_self(A, X) :-
            ::assertz(attr_(A, X)).

         ...

An example of asserting clauses into another object with the predicates
listed using a *note uses/2: 4b. directive (similar when using a *note
use_module/2: 4d. directive):

     :- object(reasoner(_KnowledgeBase_)).

         :- uses(_KnowledgeBase_, [
             foo/1, bar/1
         ]).

         baz(X) :-
            % compiled as _KnowledgeBase_::assertz(foo(X))
            assertz(foo(X)).

        foobar(Name, Argument) :-
           Clause =.. [Name, Argument],
           % runtime resolved to _KnowledgeBase_::assertz(Clause)
           % when Name is either foo or bar
           assertz(Clause).

         ...

See also
........

*note abolish/1: 1b1, *note asserta/1: 1b2, *note clause/2: 1b4, *note
retract/1: 1b5, *note retractall/1: 1b6. *note dynamic/0: b1, *note
dynamic/1: 15a, *note uses/2: 4b, *note use_module/2: 4d.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: clause/2,  Next: retract/1,  Prev: assertz/1,  Up: Database

2.5.4.16 ‘clause/2’
...................

* Menu:

* Description: Description<116>.
* Modes and number of proofs: Modes and number of proofs<79>.
* Errors: Errors<80>.
* Examples: Examples<117>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<116>,  Next: Modes and number of proofs<79>,  Up: clause/2

2.5.4.17 Description
....................

     clause(Head, Body)

Enumerates, by backtracking, the clauses of a dynamic predicate.

When the predicate indicator for ‘Head’ is declared in a *note uses/2:
4b. or *note use_module/2: 4d. directive, the predicate enumerates the
clauses in the referenced object or module.  When the backend Prolog
compiler supports a module system, the head argument can also be module
qualified.

This method may be used to enumerate clauses for predicates that are not
declared dynamic for dynamic objects provided that the predicates are
declared in *note this: 114.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<79>,  Next: Errors<80>,  Prev: Description<116>,  Up: clause/2

2.5.4.18 Modes and number of proofs
...................................

     clause(+callable, ?body) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<80>,  Next: Examples<117>,  Prev: Modes and number of proofs<79>,  Up: clause/2

2.5.4.19 Errors
...............

     ‘Head’ is a variable:
          ‘instantiation_error’
     ‘Head’ is neither a variable nor a callable term:
          ‘type_error(callable, Head)’
     ‘Body’ is neither a variable nor a callable term:
          ‘type_error(callable, Body)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a private predicate:
          ‘permission_error(access, private_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a protected predicate:
          ‘permission_error(access, protected_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a static predicate:
          ‘permission_error(access, static_predicate, Name/Arity)’
     ‘Head’ is not a declared predicate:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<117>,  Prev: Errors<80>,  Up: clause/2

2.5.4.20 Examples
.................

     To retrieve a matching clause of a local dynamic predicate or a dynamic predicate in *note this: 114.:
          ‘clause(Head, Body)’
     To retrieve a matching clause of a public or protected dynamic predicate in *note self: 69.:
          ‘::clause(Head, Body)’
     To retrieve a matching clause of a public dynamic predicate in an explicit object:
          ‘Object::clause(Head, Body)’

See also
........

*note abolish/1: 1b1, *note asserta/1: 1b2, *note assertz/1: 1b3, *note
retract/1: 1b5, *note retractall/1: 1b6. *note dynamic/0: b1, *note
dynamic/1: 15a, *note uses/2: 4b, *note use_module/2: 4d.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: retract/1,  Next: retractall/1,  Prev: clause/2,  Up: Database

2.5.4.21 ‘retract/1’
....................

* Menu:

* Description: Description<117>.
* Modes and number of proofs: Modes and number of proofs<80>.
* Errors: Errors<81>.
* Examples: Examples<118>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<117>,  Next: Modes and number of proofs<80>,  Up: retract/1

2.5.4.22 Description
....................

     retract(Head)
     retract((Head:-Body))

Retracts a clause for an object dynamic predicate.  On backtracking, the
predicate retracts the next matching clause.

When the predicate indicator for ‘Head’ is declared in a *note uses/2:
4b. or *note use_module/2: 4d. directive, the clause is retracted in the
referenced object or module.  When the backend Prolog compiler supports
a module system, the predicate argument can also be module qualified.

This method may be used to retract clauses for predicates that are not
declared dynamic for dynamic objects provided that the predicates are
declared in *note this: 114.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<80>,  Next: Errors<81>,  Prev: Description<117>,  Up: retract/1

2.5.4.23 Modes and number of proofs
...................................

     retract(+clause) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<81>,  Next: Examples<118>,  Prev: Modes and number of proofs<80>,  Up: retract/1

2.5.4.24 Errors
...............

     ‘Head’ is a variable:
          ‘instantiation_error’
     ‘Head’ is neither a variable nor a callable term:
          ‘type_error(callable, Head)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a private predicate:
          ‘permission_error(modify, private_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a protected predicate:
          ‘permission_error(modify, protected_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a static predicate:
          ‘permission_error(modify, static_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is not declared:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<118>,  Prev: Errors<81>,  Up: retract/1

2.5.4.25 Examples
.................

     To retract a matching clause of a dynamic predicate in *note this: 114.:
          ‘retract(Clause)’
     To retract a matching clause of a public or protected dynamic predicate in *note self: 69.:
          ‘::retract(Clause)’
     To retract a matching clause of a public dynamic predicate in an explicit object:
          ‘Object::retract(Clause)’

See also
........

*note abolish/1: 1b1, *note asserta/1: 1b2, *note assertz/1: 1b3, *note
clause/2: 1b4, *note retractall/1: 1b6, *note dynamic/0: b1, *note
dynamic/1: 15a, *note uses/2: 4b, *note use_module/2: 4d.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: retractall/1,  Prev: retract/1,  Up: Database

2.5.4.26 ‘retractall/1’
.......................

* Menu:

* Description: Description<118>.
* Modes and number of proofs: Modes and number of proofs<81>.
* Errors: Errors<82>.
* Examples: Examples<119>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<118>,  Next: Modes and number of proofs<81>,  Up: retractall/1

2.5.4.27 Description
....................

     retractall(Head)

Retracts all clauses with a matching head for an object dynamic
predicate.

When the predicate indicator for ‘Head’ is declared in a *note uses/2:
4b. or *note use_module/2: 4d. directive, the clauses are retracted in
the referenced object or module.  When the backend Prolog compiler
supports a module system, the predicate argument can also be module
qualified.

This method may be used to retract clauses for predicates that are not
declared dynamic for dynamic objects provided that the predicates are
declared in *note this: 114.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<81>,  Next: Errors<82>,  Prev: Description<118>,  Up: retractall/1

2.5.4.28 Modes and number of proofs
...................................

     retractall(@callable) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<82>,  Next: Examples<119>,  Prev: Modes and number of proofs<81>,  Up: retractall/1

2.5.4.29 Errors
...............

     ‘Head’ is a variable:
          ‘instantiation_error’
     ‘Head’ is neither a variable nor a callable term:
          ‘type_error(callable, Head)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a private predicate:
          ‘permission_error(modify, private_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a protected predicate:
          ‘permission_error(modify, protected_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a static predicate:
          ‘permission_error(modify, static_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is not declared:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<119>,  Prev: Errors<82>,  Up: retractall/1

2.5.4.30 Examples
.................

     To retract all clauses with a matching head of a dynamic predicate in *note this: 114.:
          ‘retractall(Head)’
     To retract all clauses with a matching head of a public or protected dynamic predicate in *note self: 69.:
          ‘::retractall(Head)’
     To retract all clauses with a matching head of a public dynamic predicate in an explicit object:
          ‘Object::retractall(Head)’

See also
........

*note abolish/1: 1b1, *note asserta/1: 1b2, *note assertz/1: 1b3, *note
clause/2: 1b4, *note retract/1: 1b5, *note dynamic/0: b1, *note
dynamic/1: 15a, *note uses/2: 4b, *note use_module/2: 4d.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-calls,  Next: Error handling<2>,  Prev: Database,  Up: Built-in methods<2>

2.5.5 Meta-calls
----------------

'built-in method'

* Menu:

* call/1-N::
* ignore/1::
* once/1::
* (\+)/1: \+ /1.


File: TheLogtalkHandbook-3.96.0.info,  Node: call/1-N,  Next: ignore/1,  Up: Meta-calls

2.5.5.1 ‘call/1-N’
..................

* Menu:

* Description: Description<119>.
* Meta-predicate template: Meta-predicate template<6>.
* Modes and number of proofs: Modes and number of proofs<82>.
* Errors: Errors<83>.
* Examples: Examples<120>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<119>,  Next: Meta-predicate template<6>,  Up: call/1-N

2.5.5.2 Description
...................

     call(Goal)
     call(Closure, Arg1, ...)

Calls a goal constructed by appending additional arguments to a *note
closure: 14f.  The upper limit for ‘N’ depends on the upper limit for
the arity of a compound term of the *note backend Prolog compiler: 34.
This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.  The ‘Closure’ argument can
also be a lambda expression or a Logtalk control construct.  When using
a backend Prolog compiler supporting a module system, calls in the
format ‘call(Module:Closure, Arg1, ...)’ may also be used.

This meta-predicate is opaque to cuts in its arguments.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<6>,  Next: Modes and number of proofs<82>,  Prev: Description<119>,  Up: call/1-N

2.5.5.3 Meta-predicate template
...............................

     call(0)
     call(1, *)
     call(2, *, *)
     ...


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<82>,  Next: Errors<83>,  Prev: Meta-predicate template<6>,  Up: call/1-N

2.5.5.4 Modes and number of proofs
..................................

     call(+callable) - zero_or_more
     call(+callable, ?term) - zero_or_more
     call(+callable, ?term, ?term) - zero_or_more
     ...


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<83>,  Next: Examples<120>,  Prev: Modes and number of proofs<82>,  Up: call/1-N

2.5.5.5 Errors
..............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Closure’ is a variable:
          ‘instantiation_error’
     ‘Closure’ is neither a variable nor a callable term:
          ‘type_error(callable, Closure)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<120>,  Prev: Errors<83>,  Up: call/1-N

2.5.5.6 Examples
................

     Call a goal, constructed by appending additional arguments to a closure, in the context of the object or category containing the call:
          ‘call(Closure, Arg1, Arg2, ...)’
     To send a goal, constructed by appending additional arguments to a closure, as a message to *note self: 69.:
          ‘call(::Closure, Arg1, Arg2, ...)’
     To send a goal, constructed by appending additional arguments to a closure, as a message to an explicit object:
          ‘call(Object::Closure, Arg1, Arg2, ...)’

See also
........

*note ignore/1: 180, *note once/1: 1bb, *note (\+)/1: 1bc.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: ignore/1,  Next: once/1,  Prev: call/1-N,  Up: Meta-calls

2.5.5.7 ‘ignore/1’
..................

* Menu:

* Description: Description<120>.
* Meta-predicate template: Meta-predicate template<7>.
* Modes and number of proofs: Modes and number of proofs<83>.
* Errors: Errors<84>.
* Examples: Examples<121>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<120>,  Next: Meta-predicate template<7>,  Up: ignore/1

2.5.5.8 Description
...................

     ignore(Goal)

This predicate succeeds whether its argument succeeds or fails and it is
not re-executable.  This built-in meta-predicate is declared as a
private method and thus cannot be used as a message to an object.

This meta-predicate is opaque to cuts in its argument.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<7>,  Next: Modes and number of proofs<83>,  Prev: Description<120>,  Up: ignore/1

2.5.5.9 Meta-predicate template
...............................

     ignore(0)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<83>,  Next: Errors<84>,  Prev: Meta-predicate template<7>,  Up: ignore/1

2.5.5.10 Modes and number of proofs
...................................

     ignore(+callable) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<84>,  Next: Examples<121>,  Prev: Modes and number of proofs<83>,  Up: ignore/1

2.5.5.11 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<121>,  Prev: Errors<84>,  Up: ignore/1

2.5.5.12 Examples
.................

     Call a goal and succeeding even if it fails:
          ‘ignore(Goal)’
     To send a message succeeding even if it fails to *note self: 69.:
          ‘ignore(::Goal)’
     To send a message succeeding even if it fails to an explicit object:
          ‘ignore(Object::Goal)’

See also
........

*note call/1-N: 181, *note once/1: 1bb, *note (\+)/1: 1bc.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: once/1,  Next: \+ /1,  Prev: ignore/1,  Up: Meta-calls

2.5.5.13 ‘once/1’
.................

* Menu:

* Description: Description<121>.
* Meta-predicate template: Meta-predicate template<8>.
* Modes and number of proofs: Modes and number of proofs<84>.
* Errors: Errors<85>.
* Examples: Examples<122>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<121>,  Next: Meta-predicate template<8>,  Up: once/1

2.5.5.14 Description
....................

     once(Goal)

This predicate behaves as ‘call(Goal)’ but it is not re-executable.
This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.

This meta-predicate is opaque to cuts in its argument.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<8>,  Next: Modes and number of proofs<84>,  Prev: Description<121>,  Up: once/1

2.5.5.15 Meta-predicate template
................................

     once(0)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<84>,  Next: Errors<85>,  Prev: Meta-predicate template<8>,  Up: once/1

2.5.5.16 Modes and number of proofs
...................................

     once(+callable) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<85>,  Next: Examples<122>,  Prev: Modes and number of proofs<84>,  Up: once/1

2.5.5.17 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<122>,  Prev: Errors<85>,  Up: once/1

2.5.5.18 Examples
.................

     Call a goal deterministically in the context of the object or category containing the call:
          ‘once(Goal)’
     To send a goal as a non-backtracable message to *note self: 69.:
          ‘once(::Goal)’
     To send a goal as a non-backtracable message to an explicit object:
          ‘once(Object::Goal)’

See also
........

*note call/1-N: 181, *note ignore/1: 180, *note (\+)/1: 1bc.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: \+ /1,  Prev: once/1,  Up: Meta-calls

2.5.5.19 ‘(\+)/1’
.................

* Menu:

* Description: Description<122>.
* Meta-predicate template: Meta-predicate template<9>.
* Modes and number of proofs: Modes and number of proofs<85>.
* Errors: Errors<86>.
* Examples: Examples<123>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<122>,  Next: Meta-predicate template<9>,  Up: \+ /1

2.5.5.20 Description
....................

     \+ Goal

Not-provable meta-predicate.  True iff ‘call(Goal)’ is false.  This
built-in meta-predicate is declared as a private method and thus cannot
be used as a message to an object.

     Warning: The argument is always compiled (for improved
     performance).  As a consequence, when the argument is a control
     construct (e.g., a conjunction), any meta-variables will be wrapped
     with the equivalent to the ‘call/1’ control construct.  Note that
     these semantics differ from the ISO Prolog Core standard
     specification for the ‘(\+)/1’ built-in predicate.  For example,
     assuming a conforming system:

          | ?- X = !, \+ (member(Y,[1,2,3]), X, write(Y), fail).
          1

          X = !

     But in Logtalk ‘X’ is compiled into a meta-call, which is not
     cut-transparent:

          yes
          | ?- logtalk << (X = !, \+ (member(Y,[1,2,3]), X, write(Y), fail)).
          123

          X = !

     Note that the ISO Prolog Core standard doesn’t specify a
     cut-transparent alternative to the ‘call/1’ control construct.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<9>,  Next: Modes and number of proofs<85>,  Prev: Description<122>,  Up: \+ /1

2.5.5.21 Meta-predicate template
................................

     \+ 0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<85>,  Next: Errors<86>,  Prev: Meta-predicate template<9>,  Up: \+ /1

2.5.5.22 Modes and number of proofs
...................................

     \+ +callable - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<86>,  Next: Examples<123>,  Prev: Modes and number of proofs<85>,  Up: \+ /1

2.5.5.23 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<123>,  Prev: Errors<86>,  Up: \+ /1

2.5.5.24 Examples
.................

     Not-provable goal in the context of the object or category containing the call:
          ‘\+ Goal’
     Not-provable goal sent as a message to *note self: 69.:
          ‘\+ ::Goal’
     Not-provable goal sent as a message to an explicit object:
          ‘\+ Object::Goal’

See also
........

*note call/1-N: 181, *note ignore/1: 180, *note once/1: 1bb.


File: TheLogtalkHandbook-3.96.0.info,  Node: Error handling<2>,  Next: All solutions,  Prev: Meta-calls,  Up: Built-in methods<2>

2.5.6 Error handling
--------------------

'built-in method'

* Menu:

* catch/3::
* throw/1::
* instantiation_error/0::
* uninstantiation_error/1::
* type_error/2::
* domain_error/2::
* consistency_error/3::
* existence_error/2::
* permission_error/3::
* representation_error/1::
* evaluation_error/1::
* resource_error/1::
* syntax_error/1::
* system_error/0::


File: TheLogtalkHandbook-3.96.0.info,  Node: catch/3,  Next: throw/1,  Up: Error handling<2>

2.5.6.1 ‘catch/3’
.................

* Menu:

* Description: Description<123>.
* Modes and number of proofs: Modes and number of proofs<86>.
* Errors: Errors<87>.
* Examples: Examples<124>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<123>,  Next: Modes and number of proofs<86>,  Up: catch/3

2.5.6.2 Description
...................

     catch(Goal, Catcher, Recovery)

Catches exceptions thrown by a goal.  See also the ISO Prolog standard
definition.  This built-in meta-predicate is declared as a private
method and thus cannot be used as a message to an object.

This method can also be used in grammar rules.  In this case, the
meta-arguments are interpreted as grammar rule bodies.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<86>,  Next: Errors<87>,  Prev: Description<123>,  Up: catch/3

2.5.6.3 Modes and number of proofs
..................................

     catch(?callable, ?term, ?callable) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<87>,  Next: Examples<124>,  Prev: Modes and number of proofs<86>,  Up: catch/3

2.5.6.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<124>,  Prev: Errors<87>,  Up: catch/3

2.5.6.5 Examples
................

(none)

See also
........

*note throw/1: 1a2, *note context/1: 19e, *note instantiation_error/0:
1a3, *note uninstantiation_error/1: 1a4, *note type_error/2: 1a5, *note
domain_error/2: 1a6, *note consistency_error/3: 718, *note
existence_error/2: 1a7, *note permission_error/3: 1a8, *note
evaluation_error/1: 1aa, *note representation_error/1: 1a9. *note
resource_error/1: 1ab, *note syntax_error/1: 1ac, *note system_error/0:
1ad.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: throw/1,  Next: instantiation_error/0,  Prev: catch/3,  Up: Error handling<2>

2.5.6.6 ‘throw/1’
.................

* Menu:

* Description: Description<124>.
* Modes and number of proofs: Modes and number of proofs<87>.
* Errors: Errors<88>.
* Examples: Examples<125>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<124>,  Next: Modes and number of proofs<87>,  Up: throw/1

2.5.6.7 Description
...................

     throw(Exception)

Throws an exception.  See also the ISO Prolog standard definition.  This
built-in method is declared private and thus cannot be used as a message
to an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<87>,  Next: Errors<88>,  Prev: Description<124>,  Up: throw/1

2.5.6.8 Modes and number of proofs
..................................

     throw(+nonvar) - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<88>,  Next: Examples<125>,  Prev: Modes and number of proofs<87>,  Up: throw/1

2.5.6.9 Errors
..............

     ‘Exception’ is a variable:
          ‘instantiation_error’
     ‘Exception’ does not unify with the second argument of any call of *note catch/3: 1a1.:
          ‘system_error’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<125>,  Prev: Errors<88>,  Up: throw/1

2.5.6.10 Examples
.................

(none)

See also
........

*note catch/3: 1a1, *note context/1: 19e, *note instantiation_error/0:
1a3, *note uninstantiation_error/1: 1a4, *note type_error/2: 1a5, *note
domain_error/2: 1a6, *note consistency_error/3: 718, *note
existence_error/2: 1a7, *note permission_error/3: 1a8, *note
evaluation_error/1: 1aa, *note representation_error/1: 1a9. *note
resource_error/1: 1ab, *note syntax_error/1: 1ac, *note system_error/0:
1ad.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: instantiation_error/0,  Next: uninstantiation_error/1,  Prev: throw/1,  Up: Error handling<2>

2.5.6.11 ‘instantiation_error/0’
................................

* Menu:

* Description: Description<125>.
* Modes and number of proofs: Modes and number of proofs<88>.
* Errors: Errors<89>.
* Examples: Examples<126>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<125>,  Next: Modes and number of proofs<88>,  Up: instantiation_error/0

2.5.6.12 Description
....................

     instantiation_error

Throws an instantiation error.  Used when an argument or one of its
sub-arguments is a variable but a non-variable term is required.  For
example, trying to open a file with a variable for the input/output
mode.

This built-in method is declared private and thus cannot be used as a
message to an object.  Calling this predicate is equivalent to the
following sequence of calls:

     ...,
     context(Context),
     throw(error(instantiation_error, Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<88>,  Next: Errors<89>,  Prev: Description<125>,  Up: instantiation_error/0

2.5.6.13 Modes and number of proofs
...................................

     instantiation_error - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<89>,  Next: Examples<126>,  Prev: Modes and number of proofs<88>,  Up: instantiation_error/0

2.5.6.14 Errors
...............

     When called:
          ‘instantiation_error’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<126>,  Prev: Errors<89>,  Up: instantiation_error/0

2.5.6.15 Examples
.................

     ...,
     var(Handler),
     instantiation_error.

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
uninstantiation_error/1: 1a4, *note type_error/2: 1a5, *note
domain_error/2: 1a6, *note consistency_error/3: 718, *note
existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note evaluation_error/1: 1aa, *note
resource_error/1: 1ab, *note syntax_error/1: 1ac, *note system_error/0:
1ad.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: uninstantiation_error/1,  Next: type_error/2,  Prev: instantiation_error/0,  Up: Error handling<2>

2.5.6.16 ‘uninstantiation_error/1’
..................................

* Menu:

* Description: Description<126>.
* Modes and number of proofs: Modes and number of proofs<89>.
* Errors: Errors<90>.
* Examples: Examples<127>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<126>,  Next: Modes and number of proofs<89>,  Up: uninstantiation_error/1

2.5.6.17 Description
....................

     uninstantiation_error(Culprit)

Throws an uninstantiation error.  Used when an argument or one of its
sub-arguments is bound but a variable is required.  For example, trying
to open a file with a stream argument bound.

This built-in method is declared private and thus cannot be used as a
message to an object.  Calling this predicate is equivalent to the
following sequence of calls:

     ...,
     context(Context),
     throw(error(uninstantiation_error(Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<89>,  Next: Errors<90>,  Prev: Description<126>,  Up: uninstantiation_error/1

2.5.6.18 Modes and number of proofs
...................................

     uninstantiation_error(@nonvar) - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<90>,  Next: Examples<127>,  Prev: Modes and number of proofs<89>,  Up: uninstantiation_error/1

2.5.6.19 Errors
...............

     When called:
          ‘uninstantiation_error(Culprit)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<127>,  Prev: Errors<90>,  Up: uninstantiation_error/1

2.5.6.20 Examples
.................

     ...,
     var(Handler),
     uninstantiation_error(my_stream).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note type_error/2: 1a5, *note
domain_error/2: 1a6, *note consistency_error/3: 718, *note
existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note evaluation_error/1: 1aa, *note
resource_error/1: 1ab, *note syntax_error/1: 1ac, *note system_error/0:
1ad.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: type_error/2,  Next: domain_error/2,  Prev: uninstantiation_error/1,  Up: Error handling<2>

2.5.6.21 ‘type_error/2’
.......................

* Menu:

* Description: Description<127>.
* Modes and number of proofs: Modes and number of proofs<90>.
* Errors: Errors<91>.
* Examples: Examples<128>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<127>,  Next: Modes and number of proofs<90>,  Up: type_error/2

2.5.6.22 Description
....................

     type_error(Type, Culprit)

Throws a type error.  Used when the type of an argument is incorrect.
For example, trying to use a non-callable term as a message.  This
built-in method is declared private and thus cannot be used as a message
to an object.  Calling this predicate is equivalent to the following
sequence of goals:

     ...,
     context(Context),
     throw(error(type_error(Type,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Type’ include all the types defined by the ‘type’
library object and by other libraries such as ‘os’, ‘expecteds’, and
‘optionals’.  The value of ‘Culprit’ is the argument or one of its
sub-terms that caused the error.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<90>,  Next: Errors<91>,  Prev: Description<127>,  Up: type_error/2

2.5.6.23 Modes and number of proofs
...................................

     type_error(@nonvar, @term) - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<91>,  Next: Examples<128>,  Prev: Modes and number of proofs<90>,  Up: type_error/2

2.5.6.24 Errors
...............

     When called:
          ‘type_error(Type, Culprit)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<128>,  Prev: Errors<91>,  Up: type_error/2

2.5.6.25 Examples
.................

     ...,
     \+ atom(Name),
     type_error(atom, Name).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
domain_error/2: 1a6, *note consistency_error/3: 718, *note
existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9. *note evaluation_error/1: 1aa, *note
resource_error/1: 1ab, *note syntax_error/1: 1ac, *note system_error/0:
1ad,

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: domain_error/2,  Next: consistency_error/3,  Prev: type_error/2,  Up: Error handling<2>

2.5.6.26 ‘domain_error/2’
.........................

* Menu:

* Description: Description<128>.
* Modes and number of proofs: Modes and number of proofs<91>.
* Errors: Errors<92>.
* Examples: Examples<129>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<128>,  Next: Modes and number of proofs<91>,  Up: domain_error/2

2.5.6.27 Description
....................

     domain_error(Domain, Culprit)

Throws a domain error.  Used when an argument is of the correct type but
outside the valid domain.  For example, trying to use an atom as an
operator specifier that is not a valid specifier.  This built-in method
is declared private and thus cannot be used as a message to an object.
Calling this predicate is equivalent to the following sequence of goals:

     ...,
     context(Context),
     throw(error(domain_error(Domain,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Domain’ include:

   - ‘character_code_list’

   - ‘close_option’

   - ‘flag_option’

   - ‘flag_value’

   - ‘compiler_flag’

   - ‘flag’

   - ‘prolog_flag’

   - ‘io_mode’

   - ‘non_empty_list’

   - ‘not_less_than_zero’

   - ‘operator_priority’

   - ‘operator_specifier’

   - ‘read_option’

   - ‘source_sink’

   - ‘stream’

   - ‘stream_option’

   - ‘stream_or_alias’

   - ‘stream_position’

   - ‘stream_property’

   - ‘write_option’

   - ‘character_code_list’

   - ‘text_encoding’

   - ‘directive’

   - ‘object_directive’

   - ‘protocol_directive’

   - ‘category_directive’

   - ‘object_relation’

   - ‘protocol_relation’

   - ‘category_relation’

   - ‘object_property’

   - ‘protocol_property’

   - ‘category_property’

   - ‘predicate_property’

   - ‘meta_argument_specifier’

   - ‘meta_directive_template’

   - ‘closure’

   - ‘allocation’

   - ‘redefinition’

   - ‘message_sending_goal’

   - ‘class’

   - ‘prototype’

   - ‘scope’

   - ‘boolean’

The value of ‘Culprit’ is the argument or one of its sub-terms that
caused the error.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<91>,  Next: Errors<92>,  Prev: Description<128>,  Up: domain_error/2

2.5.6.28 Modes and number of proofs
...................................

     domain_error(+atom, @nonvar) - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<92>,  Next: Examples<129>,  Prev: Modes and number of proofs<91>,  Up: domain_error/2

2.5.6.29 Errors
...............

     When called:
          ‘domain_error(Domain, Culprit)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<129>,  Prev: Errors<92>,  Up: domain_error/2

2.5.6.30 Examples
.................

     ...,
     atom(Color),
     \+ color(Color),
     domain_error(color, Color).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note consistency_error/3: 718, *note
existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note evaluation_error/1: 1aa, *note
resource_error/1: 1ab, *note syntax_error/1: 1ac, *note system_error/0:
1ad.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: consistency_error/3,  Next: existence_error/2,  Prev: domain_error/2,  Up: Error handling<2>

2.5.6.31 ‘consistency_error/3’
..............................

* Menu:

* Description: Description<129>.
* Modes and number of proofs: Modes and number of proofs<92>.
* Errors: Errors<93>.
* Examples: Examples<130>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<129>,  Next: Modes and number of proofs<92>,  Up: consistency_error/3

2.5.6.32 Description
....................

     consistency_error(Consistency, Argument1, Argument2)

Throws a consistency error.  Used when two directives or predicate
arguments are individually correct but together are not consistent.  For
example, a predicate and its alias having different arity in a ‘uses/2’
directive.  This built-in method is declared private and thus cannot be
used as a message to an object.  Calling this predicate is equivalent to
the following sequence of goals:

     ...,
     context(Context),
     throw(error(consistency_error(Consistency,Argument1,Argument2), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values representing ‘Consistency’ checks include:

   - ‘same_arity’

   - ‘same_number_of_parameters’

   - ‘same_number_of_arguments’

   - ‘same_closure_specification’


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<92>,  Next: Errors<93>,  Prev: Description<129>,  Up: consistency_error/3

2.5.6.33 Modes and number of proofs
...................................

     consistency_error(+atom, @nonvar, @nonvar) - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<93>,  Next: Examples<130>,  Prev: Modes and number of proofs<92>,  Up: consistency_error/3

2.5.6.34 Errors
...............

     When called:
          ‘consistency_error(Consistency, Argument1, Argument2)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<130>,  Prev: Errors<93>,  Up: consistency_error/3

2.5.6.35 Examples
.................

     % code that will trigger consistency errors when compiled:

     % predicates (and non-terminals) aliases must have the same
     % arity as the original predicates (and non-terminals)
     :- uses(list, [
         member/2 as in/1
     ]).

     % meta-predicate templates should be consistent with how closures
     % are used regarding the number of additional arguments
     :- public(p/2).
     :- meta_predicate(p(1, *)).

     p(G, A) :-
         call(G, A, 2).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note existence_error/2:
1a7, *note permission_error/3: 1a8, *note representation_error/1: 1a9,
*note evaluation_error/1: 1aa, *note resource_error/1: 1ab, *note
syntax_error/1: 1ac, *note system_error/0: 1ad.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: existence_error/2,  Next: permission_error/3,  Prev: consistency_error/3,  Up: Error handling<2>

2.5.6.36 ‘existence_error/2’
............................

* Menu:

* Description: Description<130>.
* Modes and number of proofs: Modes and number of proofs<93>.
* Errors: Errors<94>.
* Examples: Examples<131>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<130>,  Next: Modes and number of proofs<93>,  Up: existence_error/2

2.5.6.37 Description
....................

     existence_error(Thing, Culprit)

Throws an existence error.  Used when the subject of an operation does
not exist.  This built-in method is declared private and thus cannot be
used as a message to an object.  Calling this predicate is equivalent to
the following sequence of goals:

     ...,
     context(Context),
     throw(error(existence_error(Thing,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Thing’ include:

   - ‘predicate’

   - ‘non_terminal’

   - ‘predicate_declaration’

   - ‘procedure’

   - ‘source_sink’

   - ‘stream’

   - ‘object’

   - ‘protocol’

   - ‘category’

   - ‘module’

   - ‘ancestor’

   - ‘library’

   - ‘file’

   - ‘directive’

   - ‘engine’

   - ‘thread’

   - ‘goal_thread’

The value of ‘Culprit’ is the argument or one of its sub-terms that
caused the error.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<93>,  Next: Errors<94>,  Prev: Description<130>,  Up: existence_error/2

2.5.6.38 Modes and number of proofs
...................................

     existence_error(@nonvar, @nonvar) - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<94>,  Next: Examples<131>,  Prev: Modes and number of proofs<93>,  Up: existence_error/2

2.5.6.39 Errors
...............

     When called:
          ‘existence_error(Thing, Culprit)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<131>,  Prev: Errors<94>,  Up: existence_error/2

2.5.6.40 Examples
.................

     ...,
     \+ current_object(payroll),
     existence_error(object, payroll).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
718, *note evaluation_error/1: 1aa, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note resource_error/1: 1ab, *note
syntax_error/1: 1ac, *note system_error/0: 1ad.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: permission_error/3,  Next: representation_error/1,  Prev: existence_error/2,  Up: Error handling<2>

2.5.6.41 ‘permission_error/3’
.............................

* Menu:

* Description: Description<131>.
* Modes and number of proofs: Modes and number of proofs<94>.
* Errors: Errors<95>.
* Examples: Examples<132>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<131>,  Next: Modes and number of proofs<94>,  Up: permission_error/3

2.5.6.42 Description
....................

     permission_error(Operation, PermissionType, Culprit)

Throws a permission error.  Used when an operation is not allowed.  For
example, sending a message for a predicate that is not within the scope
of the sender.  This built-in method is declared private and thus cannot
be used as a message to an object.  Calling this predicate is equivalent
to the following sequence of goals:

     ...,
     context(Context),
     throw(error(permission_error(Operation,PermissionType,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Operation’ include:

   - ‘access’

   - ‘create’

   - ‘declare’

   - ‘define’

   - ‘modify’

   - ‘open’

   - ‘input’

   - ‘output’

   - ‘reposition’

   - ‘repeat’

Possible values for ‘PermissionType’ include:

   - ‘predicate_declaration’

   - ‘protected_predicate’

   - ‘private_predicate’

   - ‘static_predicate’

   - ‘dynamic_predicate’

   - ‘predicate’

   - ‘non_terminal’

   - ‘database’

   - ‘object’

   - ‘static_object’

   - ‘static_protocol’

   - ‘static_category’

   - ‘entity_relation’

   - ‘operator’

   - ‘flag’

   - ‘engine’

   - ‘binary_stream’

   - ‘text_stream’

   - ‘source_sink’

   - ‘stream’

   - ‘past_end_of_stream’

The value of ‘Culprit’ is the argument or one of its sub-terms that
caused the error.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<94>,  Next: Errors<95>,  Prev: Description<131>,  Up: permission_error/3

2.5.6.43 Modes and number of proofs
...................................

     permission_error(@nonvar, @nonvar, @nonvar) - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<95>,  Next: Examples<132>,  Prev: Modes and number of proofs<94>,  Up: permission_error/3

2.5.6.44 Errors
...............

     When called:
          ‘permission_error(Operation, PermissionType, Culprit)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<132>,  Prev: Errors<95>,  Up: permission_error/3

2.5.6.45 Examples
.................

     ...,
     \+ writable(File),
     permission_error(modify, file, File).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
718, *note existence_error/2: 1a7, *note representation_error/1: 1a9,
*note evaluation_error/1: 1aa, *note resource_error/1: 1ab, *note
syntax_error/1: 1ac, *note system_error/0: 1ad.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: representation_error/1,  Next: evaluation_error/1,  Prev: permission_error/3,  Up: Error handling<2>

2.5.6.46 ‘representation_error/1’
.................................

* Menu:

* Description: Description<132>.
* Modes and number of proofs: Modes and number of proofs<95>.
* Errors: Errors<96>.
* Examples: Examples<133>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<132>,  Next: Modes and number of proofs<95>,  Up: representation_error/1

2.5.6.47 Description
....................

     representation_error(Flag)

Throws a representation error.  Used when some representation limit is
exceeded.  For example, trying to construct a compound term that exceeds
the maximum arity supported by the backend Prolog system.  This built-in
method is declared private and thus cannot be used as a message to an
object.  Calling this predicate is equivalent to the following sequence
of goals:

     ...,
     context(Context),
     throw(error(representation_error(Flag), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Flag’ include:

   - ‘character’

   - ‘character_code’

   - ‘in_character_code’

   - ‘max_arity’

   - ‘max_integer’

   - ‘min_integer’

   - ‘acyclic_term’

   - ‘lambda_parameters’

   - ‘entity_prefix’


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<95>,  Next: Errors<96>,  Prev: Description<132>,  Up: representation_error/1

2.5.6.48 Modes and number of proofs
...................................

     representation_error(+atom) - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<96>,  Next: Examples<133>,  Prev: Modes and number of proofs<95>,  Up: representation_error/1

2.5.6.49 Errors
...............

     When called:
          ‘representation_error(Flag)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<133>,  Prev: Errors<96>,  Up: representation_error/1

2.5.6.50 Examples
.................

     ...,
     Code > 127,
     representation_error(character_code).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
718, *note existence_error/2: 1a7, *note permission_error/3: 1a8, *note
evaluation_error/1: 1aa, *note resource_error/1: 1ab, *note
syntax_error/1: 1ac, *note system_error/0: 1ad.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: evaluation_error/1,  Next: resource_error/1,  Prev: representation_error/1,  Up: Error handling<2>

2.5.6.51 ‘evaluation_error/1’
.............................

* Menu:

* Description: Description<133>.
* Modes and number of proofs: Modes and number of proofs<96>.
* Errors: Errors<97>.
* Examples: Examples<134>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<133>,  Next: Modes and number of proofs<96>,  Up: evaluation_error/1

2.5.6.52 Description
....................

     evaluation_error(Error)

Throws an evaluation error.  Used when evaluating an arithmetic
expression generates an exception.  This built-in method is declared
private and thus cannot be used as a message to an object.  Calling this
predicate is equivalent to the following sequence of goals:

     ...,
     context(Context),
     throw(error(evaluation_error(Error), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Error’ include:

   - ‘float_overflow’

   - ‘int_overflow’

   - ‘undefined’

   - ‘underflow’

   - ‘zero_divisor’


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<96>,  Next: Errors<97>,  Prev: Description<133>,  Up: evaluation_error/1

2.5.6.53 Modes and number of proofs
...................................

     evaluation_error(@nonvar) - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<97>,  Next: Examples<134>,  Prev: Modes and number of proofs<96>,  Up: evaluation_error/1

2.5.6.54 Errors
...............

     When called:
          ‘evaluation_error(Exception)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<134>,  Prev: Errors<97>,  Up: evaluation_error/1

2.5.6.55 Examples
.................

     ...,
     Divisor =:= 0,
     evaluation_error(zero_divisor).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
718, *note existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note resource_error/1: 1ab, *note
syntax_error/1: 1ac, *note system_error/0: 1ad.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: resource_error/1,  Next: syntax_error/1,  Prev: evaluation_error/1,  Up: Error handling<2>

2.5.6.56 ‘resource_error/1’
...........................

* Menu:

* Description: Description<134>.
* Modes and number of proofs: Modes and number of proofs<97>.
* Errors: Errors<98>.
* Examples: Examples<135>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<134>,  Next: Modes and number of proofs<97>,  Up: resource_error/1

2.5.6.57 Description
....................

     resource_error(Resource)

Throws a resource error.  Used when a required resource (e.g., memory or
disk space) to complete execution is not available.  This built-in
method is declared private and thus cannot be used as a message to an
object.  Calling this predicate is equivalent to the following sequence
of goals:

     ...,
     context(Context),
     throw(error(resource_error(Resource), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Resource’ include:

   - ‘engines’

   - ‘threads’

   - ‘coinduction’

   - ‘soft_cut_support’

   - ‘text_encoding_support’


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<97>,  Next: Errors<98>,  Prev: Description<134>,  Up: resource_error/1

2.5.6.58 Modes and number of proofs
...................................

     resource_error(@nonvar) - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<98>,  Next: Examples<135>,  Prev: Modes and number of proofs<97>,  Up: resource_error/1

2.5.6.59 Errors
...............

     When called:
          ‘resource_error(Resource)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<135>,  Prev: Errors<98>,  Up: resource_error/1

2.5.6.60 Examples
.................

     ...,
     empty(Tank),
     resource_error(gas).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
718, *note existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note syntax_error/1: 1ac, *note
system_error/0: 1ad.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: syntax_error/1,  Next: system_error/0,  Prev: resource_error/1,  Up: Error handling<2>

2.5.6.61 ‘syntax_error/1’
.........................

* Menu:

* Description: Description<135>.
* Modes and number of proofs: Modes and number of proofs<98>.
* Errors: Errors<99>.
* Examples: Examples<136>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<135>,  Next: Modes and number of proofs<98>,  Up: syntax_error/1

2.5.6.62 Description
....................

     syntax_error(Description)

Throws a syntax error.  Used when the sequence of characters being read
are not syntactically valid.  This built-in method is declared private
and thus cannot be used as a message to an object.  Calling this
predicate is equivalent to the following sequence of goals:

     ...,
     context(Context),
     throw(error(syntax_error(Description), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<98>,  Next: Errors<99>,  Prev: Description<135>,  Up: syntax_error/1

2.5.6.63 Modes and number of proofs
...................................

     syntax_error(@nonvar) - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<99>,  Next: Examples<136>,  Prev: Modes and number of proofs<98>,  Up: syntax_error/1

2.5.6.64 Errors
...............

     When called:
          ‘syntax_error(Description)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<136>,  Prev: Errors<99>,  Up: syntax_error/1

2.5.6.65 Examples
.................

(none)

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
718, *note existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note system_error/0: 1ad. *note
resource_error/1: 1ab.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: system_error/0,  Prev: syntax_error/1,  Up: Error handling<2>

2.5.6.66 ‘system_error/0’
.........................

* Menu:

* Description: Description<136>.
* Modes and number of proofs: Modes and number of proofs<99>.
* Errors: Errors<100>.
* Examples: Examples<137>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<136>,  Next: Modes and number of proofs<99>,  Up: system_error/0

2.5.6.67 Description
....................

     system_error

Throws a system error.  Used when runtime execution can no longer
proceed.  For example, an exception is thrown without an active catcher.
This built-in method is declared private and thus cannot be used as a
message to an object.  Calling this predicate is equivalent to the
following sequence of goals:

     ...,
     context(Context),
     throw(error(system_error, Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<99>,  Next: Errors<100>,  Prev: Description<136>,  Up: system_error/0

2.5.6.68 Modes and number of proofs
...................................

     system_error - error


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<100>,  Next: Examples<137>,  Prev: Modes and number of proofs<99>,  Up: system_error/0

2.5.6.69 Errors
...............

     When called:
          ‘system_error’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<137>,  Prev: Errors<100>,  Up: system_error/0

2.5.6.70 Examples
.................

(none)

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
718, *note existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9. *note evaluation_error/1: 1aa, *note
resource_error/1: 1ab, *note syntax_error/1: 1ac,


File: TheLogtalkHandbook-3.96.0.info,  Node: All solutions,  Next: Event handling<3>,  Prev: Error handling<2>,  Up: Built-in methods<2>

2.5.7 All solutions
-------------------

'built-in method'

* Menu:

* bagof/3::
* findall/3::
* findall/4::
* forall/2::
* setof/3::


File: TheLogtalkHandbook-3.96.0.info,  Node: bagof/3,  Next: findall/3,  Up: All solutions

2.5.7.1 ‘bagof/3’
.................

* Menu:

* Description: Description<137>.
* Meta-predicate template: Meta-predicate template<10>.
* Modes and number of proofs: Modes and number of proofs<100>.
* Errors: Errors<101>.
* Examples: Examples<138>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<137>,  Next: Meta-predicate template<10>,  Up: bagof/3

2.5.7.2 Description
...................

     bagof(Template, Goal, List)

Collects a bag of solutions for the goal for each set of instantiations
of the free variables in the goal.  The order of the elements in the bag
follows the order of the goal solutions.  The free variables in the goal
are the variables that occur in the goal but not in the template.  Free
variables can be ignored, however, by using the ‘^/2’ existential
qualifier.  For example, if ‘T’ is term containing all the free
variables that we want to ignore, we can write ‘T^Goal’.  Note that the
term ‘T’ can be written as ‘V1^V2^...’.

When there are free variables, this method is re-executable on
backtracking.  This method fails when there are no solutions, never
returning an empty list.

This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<10>,  Next: Modes and number of proofs<100>,  Prev: Description<137>,  Up: bagof/3

2.5.7.3 Meta-predicate template
...............................

     bagof(*, ^, *)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<100>,  Next: Errors<101>,  Prev: Meta-predicate template<10>,  Up: bagof/3

2.5.7.4 Modes and number of proofs
..................................

     bagof(@term, +callable, -list) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<101>,  Next: Examples<138>,  Prev: Modes and number of proofs<100>,  Up: bagof/3

2.5.7.5 Errors
..............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Goal’ is a call to a non-existing predicate:
          ‘existence_error(procedure, Predicate)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<138>,  Prev: Errors<101>,  Up: bagof/3

2.5.7.6 Examples
................

     To find a bag of solutions in the context of the object or category containing the call:
          ‘bagof(Template, Goal, List)’
     To find a bag of solutions of sending a message to *note self: 69.:
          ‘bagof(Template, ::Message, List)’
     To find a bag of solutions of sending a message to an explicit object:
          ‘bagof(Template, Object::Message, List)’

See also
........

*note findall/3: 1c0, *note findall/4: 1c1, *note forall/2: 1c3, *note
setof/3: 1c2.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: findall/3,  Next: findall/4,  Prev: bagof/3,  Up: All solutions

2.5.7.7 ‘findall/3’
...................

* Menu:

* Description: Description<138>.
* Meta-predicate template: Meta-predicate template<11>.
* Modes and number of proofs: Modes and number of proofs<101>.
* Errors: Errors<102>.
* Examples: Examples<139>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<138>,  Next: Meta-predicate template<11>,  Up: findall/3

2.5.7.8 Description
...................

     findall(Template, Goal, List)

Collects a list of solutions for the goal.  The order of the elements in
the list follows the order of the goal solutions.  It succeeds returning
an empty list when the goal has no solutions.

This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<11>,  Next: Modes and number of proofs<101>,  Prev: Description<138>,  Up: findall/3

2.5.7.9 Meta-predicate template
...............................

     findall(*, 0, *)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<101>,  Next: Errors<102>,  Prev: Meta-predicate template<11>,  Up: findall/3

2.5.7.10 Modes and number of proofs
...................................

     findall(?term, +callable, ?list) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<102>,  Next: Examples<139>,  Prev: Modes and number of proofs<101>,  Up: findall/3

2.5.7.11 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Goal’ is a call to a non-existing predicate:
          ‘existence_error(procedure, Predicate)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<139>,  Prev: Errors<102>,  Up: findall/3

2.5.7.12 Examples
.................

     To find all solutions in the context of the object or category containing the call:
          ‘findall(Template, Goal, List)’
     To find all solutions of sending a message to *note self: 69.:
          ‘findall(Template, ::Message, List)’
     To find all solutions of sending a message to an explicit object:
          ‘findall(Template, Object::Message, List)’

See also
........

*note bagof/3: 1bf, *note findall/4: 1c1, *note forall/2: 1c3, *note
setof/3: 1c2.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: findall/4,  Next: forall/2,  Prev: findall/3,  Up: All solutions

2.5.7.13 ‘findall/4’
....................

* Menu:

* Description: Description<139>.
* Meta-predicate template: Meta-predicate template<12>.
* Modes and number of proofs: Modes and number of proofs<102>.
* Errors: Errors<103>.
* Examples: Examples<140>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<139>,  Next: Meta-predicate template<12>,  Up: findall/4

2.5.7.14 Description
....................

     findall(Template, Goal, List, Tail)

Variant of the *note findall/3: 1c0. method that allows passing the tail
of the results list.  It succeeds returning the tail argument when the
goal has no solutions.

This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<12>,  Next: Modes and number of proofs<102>,  Prev: Description<139>,  Up: findall/4

2.5.7.15 Meta-predicate template
................................

     findall(*, 0, *, *)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<102>,  Next: Errors<103>,  Prev: Meta-predicate template<12>,  Up: findall/4

2.5.7.16 Modes and number of proofs
...................................

     findall(?term, +callable, ?list, ?term) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<103>,  Next: Examples<140>,  Prev: Modes and number of proofs<102>,  Up: findall/4

2.5.7.17 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Goal’ is a call to a non-existing predicate:
          ‘existence_error(procedure, Predicate)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<140>,  Prev: Errors<103>,  Up: findall/4

2.5.7.18 Examples
.................

     To find all solutions in the context of the object or category containing the call:
          ‘findall(Template, Goal, List, Tail)’
     To find all solutions of sending a message to *note self: 69.:
          ‘findall(Template, ::Message, List, Tail)’
     To find all solutions of sending a message to an explicit object:
          ‘findall(Template, Object::Message, List, Tail)’

See also
........

*note bagof/3: 1bf, *note findall/3: 1c0, *note forall/2: 1c3, *note
setof/3: 1c2.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: forall/2,  Next: setof/3,  Prev: findall/4,  Up: All solutions

2.5.7.19 ‘forall/2’
...................

* Menu:

* Description: Description<140>.
* Meta-predicate template: Meta-predicate template<13>.
* Modes and number of proofs: Modes and number of proofs<103>.
* Errors: Errors<104>.
* Examples: Examples<141>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<140>,  Next: Meta-predicate template<13>,  Up: forall/2

2.5.7.20 Description
....................

     forall(Generator, Test)

For all solutions of ‘Generator’, ‘Test’ is true.  This meta-predicate
implements a 'generate-and-test' loop using a definition equivalent to
‘\+ (Generator, \+ Test)’.  As a consequence, no variables in the
arguments are bound by a call to this predicate.  This predicate often
provides a better alternative to a 'failure-driven loop' as an
unexpected ‘Test’ failure will not be ignored as it will make the
‘forall/2’ call fail.

This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<13>,  Next: Modes and number of proofs<103>,  Prev: Description<140>,  Up: forall/2

2.5.7.21 Meta-predicate template
................................

     forall(0, 0)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<103>,  Next: Errors<104>,  Prev: Meta-predicate template<13>,  Up: forall/2

2.5.7.22 Modes and number of proofs
...................................

     forall(@callable, @callable) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<104>,  Next: Examples<141>,  Prev: Modes and number of proofs<103>,  Up: forall/2

2.5.7.23 Errors
...............

     Either ‘Generator’ or ‘Test’ is a variable:
          ‘instantiation_error’
     ‘Generator’ is neither a variable nor a callable term:
          ‘type_error(callable, Generator)’
     ‘Test’ is neither a variable nor a callable term:
          ‘type_error(callable, Test)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<141>,  Prev: Errors<104>,  Up: forall/2

2.5.7.24 Examples
.................

     To call both goals in the context of the object or category containing the call:
          ‘forall(Generator, Test)’
     To send both goals as messages to *note self: 69.:
          ‘forall(::Generator, ::Test)’
     To send both goals as messages to explicit objects:
          ‘forall(Object1::Generator, Object2::Test)’

See also
........

*note bagof/3: 1bf, *note findall/3: 1c0, *note findall/4: 1c1, *note
setof/3: 1c2.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: setof/3,  Prev: forall/2,  Up: All solutions

2.5.7.25 ‘setof/3’
..................

* Menu:

* Description: Description<141>.
* Meta-predicate template: Meta-predicate template<14>.
* Modes and number of proofs: Modes and number of proofs<104>.
* Errors: Errors<105>.
* Examples: Examples<142>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<141>,  Next: Meta-predicate template<14>,  Up: setof/3

2.5.7.26 Description
....................

     setof(Template, Goal, List)

Collects a set of solutions for the goal for each set of instantiations
of the free variables in the goal.  The solutions are sorted using
standard term order.  The free variables in the goal are the variables
that occur in the goal but not in the template.  Free variables can be
ignored, however, by using the ‘^/2’ existential qualifier.  For
example, if ‘T’ is term containing all the free variables that we want
to ignore, we can write ‘T^Goal’.  Note that the term ‘T’ can be written
as ‘V1^V2^...’.

When there are free variables, this method is re-executable on
backtracking.  This method fails when there are no solutions, never
returning an empty list.

This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<14>,  Next: Modes and number of proofs<104>,  Prev: Description<141>,  Up: setof/3

2.5.7.27 Meta-predicate template
................................

     setof(*, ^, *)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<104>,  Next: Errors<105>,  Prev: Meta-predicate template<14>,  Up: setof/3

2.5.7.28 Modes and number of proofs
...................................

     setof(@term, +callable, -list) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<105>,  Next: Examples<142>,  Prev: Modes and number of proofs<104>,  Up: setof/3

2.5.7.29 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Goal’ is a call to a non-existing predicate:
          ‘existence_error(procedure, Predicate)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<142>,  Prev: Errors<105>,  Up: setof/3

2.5.7.30 Examples
.................

     To find a set of solutions in the context of the object or category containing the call:
          ‘setof(Template, Goal, List)’
     To find a set of solutions of sending a message to *note self: 69.:
          ‘setof(Template, ::Message, List)’
     To find a set of solutions of sending a message to an explicit object:
          ‘setof(Template, Object::Message, List)’

See also
........

*note bagof/3: 1bf, *note findall/3: 1c0, *note findall/4: 1c1, *note
forall/2: 1c3.


File: TheLogtalkHandbook-3.96.0.info,  Node: Event handling<3>,  Next: Message forwarding,  Prev: All solutions,  Up: Built-in methods<2>

2.5.8 Event handling
--------------------

'built-in method'

* Menu:

* before/3::
* after/3::


File: TheLogtalkHandbook-3.96.0.info,  Node: before/3,  Next: after/3,  Up: Event handling<3>

2.5.8.1 ‘before/3’
..................

* Menu:

* Description: Description<142>.
* Modes and number of proofs: Modes and number of proofs<105>.
* Errors: Errors<106>.
* Examples: Examples<143>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<142>,  Next: Modes and number of proofs<105>,  Up: before/3

2.5.8.2 Description
...................

     before(Object, Message, Sender)

User-defined method for handling *note before events: 205.  This method
is declared in the monitoring(1) built-in protocol as a public predicate
and is automatically called by the runtime for messages sent using the
*note (;;)/2: 7e. control construct from within objects compiled with
the *note events: 89. flag set to ‘allow’.

Note that you can make this predicate scope protected or private by
using, respectively, *note protected or private implementation: 9e. of
the ‘monitoring’ protocol.

   ---------- Footnotes ----------

   (1) ../../../apis/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<105>,  Next: Errors<106>,  Prev: Description<142>,  Up: before/3

2.5.8.3 Modes and number of proofs
..................................

     before(?object_identifier, ?callable, ?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<106>,  Next: Examples<143>,  Prev: Modes and number of proofs<105>,  Up: before/3

2.5.8.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<143>,  Prev: Errors<106>,  Up: before/3

2.5.8.5 Examples
................

     :- object(...,
         implements(monitoring),
         ...).

         % write a log message when a message is sent:
         before(Object, Message, Sender) :-
             writeq(Object), write('::'), writeq(Message),
             write(' from '), writeq(Sender), nl.

See also
........

*note after/3: 102, *note abolish_events/5: 21b, *note current_event/5:
21e, *note define_events/5: 218.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: after/3,  Prev: before/3,  Up: Event handling<3>

2.5.8.6 ‘after/3’
.................

* Menu:

* Description: Description<143>.
* Modes and number of proofs: Modes and number of proofs<106>.
* Errors: Errors<107>.
* Examples: Examples<144>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<143>,  Next: Modes and number of proofs<106>,  Up: after/3

2.5.8.7 Description
...................

     after(Object, Message, Sender)

User-defined method for handling *note after events: 205.  This method
is declared in the monitoring(1) built-in protocol as a public predicate
and is automatically called by the runtime for messages sent using the
*note (;;)/2: 7e. control construct from within objects compiled with
the *note events: 89. flag set to ‘allow’.

Note that you can make this predicate scope protected or private by
using, respectively, *note protected or private implementation: 9e. of
the ‘monitoring’ protocol.

   ---------- Footnotes ----------

   (1) ../../../apis/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<106>,  Next: Errors<107>,  Prev: Description<143>,  Up: after/3

2.5.8.8 Modes and number of proofs
..................................

     after(?object_identifier, ?callable, ?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<107>,  Next: Examples<144>,  Prev: Modes and number of proofs<106>,  Up: after/3

2.5.8.9 Errors
..............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<144>,  Prev: Errors<107>,  Up: after/3

2.5.8.10 Examples
.................

     :- object(...,
         implements(monitoring),
         ...).

         % write a log message when a message is successful:
         after(Object, Message, Sender) :-
             writeq(Object), write('::'), writeq(Message),
             write(' from '), writeq(Sender), nl.

See also
........

*note before/3: 101, *note abolish_events/5: 21b, *note current_event/5:
21e, *note define_events/5: 218.


File: TheLogtalkHandbook-3.96.0.info,  Node: Message forwarding,  Next: Definite clause grammar rules<2>,  Prev: Event handling<3>,  Up: Built-in methods<2>

2.5.9 Message forwarding
------------------------

'built-in method'

* Menu:

* forward/1::


File: TheLogtalkHandbook-3.96.0.info,  Node: forward/1,  Up: Message forwarding

2.5.9.1 ‘forward/1’
...................

* Menu:

* Description: Description<144>.
* Modes and number of proofs: Modes and number of proofs<107>.
* Errors: Errors<108>.
* Examples: Examples<145>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<144>,  Next: Modes and number of proofs<107>,  Up: forward/1

2.5.9.2 Description
...................

     forward(Message)

User-defined method for forwarding unknown messages sent to an object
(using the *note (;;)/2: 7e. control construct), automatically called by
the runtime when defined.  This method is declared in the forwarding(1)
built-in protocol as a *note public: 143. predicate.  Note that you can
make its scope protected or private by using, respectively, *note
protected or private implementation: 9e. of the ‘forwarding’ protocol.

   ---------- Footnotes ----------

   (1) ../../../apis/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<107>,  Next: Errors<108>,  Prev: Description<144>,  Up: forward/1

2.5.9.3 Modes and number of proofs
..................................

     forward(+callable) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<108>,  Next: Examples<145>,  Prev: Modes and number of proofs<107>,  Up: forward/1

2.5.9.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<145>,  Prev: Errors<108>,  Up: forward/1

2.5.9.5 Examples
................

     :- object(proxy,
         implements(forwarding),
         ...).

         forward(Message) :-
             % delegate unknown messages to the "real" object
             [real::Message].

See also
........

*note []/1: 81.


File: TheLogtalkHandbook-3.96.0.info,  Node: Definite clause grammar rules<2>,  Next: Term and goal expansion<2>,  Prev: Message forwarding,  Up: Built-in methods<2>

2.5.10 Definite clause grammar rules
------------------------------------

'built-in method'

* Menu:

* call//1-N::
* eos//0::
* phrase//1::
* phrase/2::
* phrase/3::


File: TheLogtalkHandbook-3.96.0.info,  Node: call//1-N,  Next: eos//0,  Up: Definite clause grammar rules<2>

2.5.10.1 ‘call//1-N’
....................

* Menu:

* Description: Description<145>.
* Meta-non-terminal template::
* Modes and number of proofs: Modes and number of proofs<108>.
* Errors: Errors<109>.
* Examples: Examples<146>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<145>,  Next: Meta-non-terminal template,  Up: call//1-N

2.5.10.2 Description
....................

     call(Closure)
     call(Closure, Arg1, ...)
     call(Object::Closure, Arg1, ...)
     call(::Closure, Arg1, ...)
     call(^^Closure, Arg1, ...)
     ...

This non-terminal takes a *note closure: 14f. and is processed by
appending the two implicit grammar rule arguments to the arguments of
the closure.  This built-in non-terminal is interpreted as a private
non-terminal and thus cannot be used as a message to an object.

Using this non-terminal is recommended when calling a predicate whose
last two arguments are the two implicit grammar rule arguments to avoid
hard-coding assumptions about how grammar rules are compiled into
clauses.  Note that the compiler ensures zero overhead when using this
non-terminal with a bound argument at compile-time.  To call a predicate
with a different argument order, use a *note lambda expression: 182. or
define a *note predicate alias: ca.  For example:

     square -->
         call([Number, Double]>>(Double is Number*Number)).

When using a *note backend Prolog compiler: 34. supporting a module
system, calls in the format ‘call(Module:Closure)’ may also be used.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-non-terminal template,  Next: Modes and number of proofs<108>,  Prev: Description<145>,  Up: call//1-N

2.5.10.3 Meta-non-terminal template
...................................

     call(0)
     call(1, *)
     call(2, *, *)
     ...


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<108>,  Next: Errors<109>,  Prev: Meta-non-terminal template,  Up: call//1-N

2.5.10.4 Modes and number of proofs
...................................

     call(+callable) - zero_or_more
     call(+callable, ?term) - zero_or_more
     call(+callable, ?term, ?term) - zero_or_more
     ...


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<109>,  Next: Examples<146>,  Prev: Modes and number of proofs<108>,  Up: call//1-N

2.5.10.5 Errors
...............

     ‘Closure’ is a variable:
          ‘instantiation_error’
     ‘Closure’ is neither a variable nor a callable term:
          ‘type_error(callable, Closure)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<146>,  Prev: Errors<109>,  Up: call//1-N

2.5.10.6 Examples
.................

     Calls a goal, constructed by appending the two implicit grammar rule arguments to the closure, in in the context of the object or category containing the call:
          ‘call(Closure)’
     To make a 'super' call, constructed by appending the two implicit grammar rule arguments to the closure:
          ‘call(^^Closure)’
     To send a goal, constructed by appending the two implicit grammar rule arguments to the closure, as a message to *note self: 69.:
          ‘call(::Closure)’
     To send a goal, constructed by appending the two implicit grammar rule arguments to the closure, as a message to an explicit object:
          ‘call(Object::Closure)’

See also
........

*note eos//0: 1ca, *note phrase//1: 1c8, *note phrase/2: 18e, *note
phrase/3: 18f.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: eos//0,  Next: phrase//1,  Prev: call//1-N,  Up: Definite clause grammar rules<2>

2.5.10.7 ‘eos//0’
.................

* Menu:

* Description: Description<146>.
* Modes and number of proofs: Modes and number of proofs<109>.
* Errors: Errors<110>.
* Examples: Examples<147>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<146>,  Next: Modes and number of proofs<109>,  Up: eos//0

2.5.10.8 Description
....................

     eos

This non-terminal matches the end-of-input.  It is implemented by
checking that the implicit difference list unifies with ‘[]-[]’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<109>,  Next: Errors<110>,  Prev: Description<146>,  Up: eos//0

2.5.10.9 Modes and number of proofs
...................................

     eos - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<110>,  Next: Examples<147>,  Prev: Modes and number of proofs<109>,  Up: eos//0

2.5.10.10 Errors
................

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<147>,  Prev: Errors<110>,  Up: eos//0

2.5.10.11 Examples
..................

     abc --> a, b, c, eos.

See also
........

*note call//1-N: 1c9, *note phrase//1: 1c8, *note phrase/2: 18e, *note
phrase/3: 18f.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: phrase//1,  Next: phrase/2,  Prev: eos//0,  Up: Definite clause grammar rules<2>

2.5.10.12 ‘phrase//1’
.....................

* Menu:

* Description: Description<147>.
* Meta-non-terminal template: Meta-non-terminal template<2>.
* Modes and number of proofs: Modes and number of proofs<110>.
* Errors: Errors<111>.
* Examples: Examples<148>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<147>,  Next: Meta-non-terminal template<2>,  Up: phrase//1

2.5.10.13 Description
.....................

     phrase(GrammarRuleBody)

This non-terminal takes a grammar rule body and parses it using the two
implicit grammar rule arguments.  A common use is to wrap what otherwise
would be a *note naked meta-variable: 7b8. in a grammar rule body when
defining a meta non-terminal.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-non-terminal template<2>,  Next: Modes and number of proofs<110>,  Prev: Description<147>,  Up: phrase//1

2.5.10.14 Meta-non-terminal template
....................................

     phrase(0)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<110>,  Next: Errors<111>,  Prev: Meta-non-terminal template<2>,  Up: phrase//1

2.5.10.15 Modes and number of proofs
....................................

     phrase(+callable) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<111>,  Next: Examples<148>,  Prev: Modes and number of proofs<110>,  Up: phrase//1

2.5.10.16 Errors
................

     ‘GrammarRuleBody’ is a variable:
          ‘instantiation_error’
     ‘GrammarRuleBody’ is neither a variable nor a callable term:
          ‘type_error(callable, GrammarRuleBody)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<148>,  Prev: Errors<111>,  Up: phrase//1

2.5.10.17 Examples
..................

     (none)

See also
........

*note call//1-N: 1c9, *note phrase/2: 18e, *note phrase/3: 18f.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: phrase/2,  Next: phrase/3,  Prev: phrase//1,  Up: Definite clause grammar rules<2>

2.5.10.18 ‘phrase/2’
....................

* Menu:

* Description: Description<148>.
* Meta-predicate template: Meta-predicate template<15>.
* Modes and number of proofs: Modes and number of proofs<111>.
* Errors: Errors<112>.
* Examples: Examples<149>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<148>,  Next: Meta-predicate template<15>,  Up: phrase/2

2.5.10.19 Description
.....................

     phrase(GrammarRuleBody, Input)
     phrase(::GrammarRuleBody, Input)
     phrase(Object::GrammarRuleBody, Input)

True when the ‘GrammarRuleBody’ grammar rule body can be applied to the
‘Input’ list of tokens.  In the most common case, ‘GrammarRuleBody’ is a
non-terminal defined by a grammar rule.  This built-in method is
declared private and thus cannot be used as a message to an object.
When using a *note backend Prolog compiler: 34. supporting a module
system, calls in the format ‘phrase(Module:GrammarRuleBody, Input)’ may
also be used.

This method is opaque to cuts in the first argument.  When the first
argument is sufficiently instantiated at compile-time, the method call
is compiled in order to eliminate the implicit overheads of converting
the grammar rule body into a goal and meta-calling it.  For performance
reasons, the second argument is only type-checked at compile-time.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<15>,  Next: Modes and number of proofs<111>,  Prev: Description<148>,  Up: phrase/2

2.5.10.20 Meta-predicate template
.................................

     phrase(2, *)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<111>,  Next: Errors<112>,  Prev: Meta-predicate template<15>,  Up: phrase/2

2.5.10.21 Modes and number of proofs
....................................

     phrase(+callable, ?list) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<112>,  Next: Examples<149>,  Prev: Modes and number of proofs<111>,  Up: phrase/2

2.5.10.22 Errors
................

     ‘GrammarRuleBody’ is a variable:
          ‘instantiation_error’
     ‘GrammarRuleBody’ is neither a variable nor a callable term:
          ‘type_error(callable, GrammarRuleBody)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<149>,  Prev: Errors<112>,  Up: phrase/2

2.5.10.23 Examples
..................

     To parse a list of tokens using a local non-terminal:
          ‘phrase(NonTerminal, Input)’
     To parse a list of tokens using a non-terminal within the scope of *note self: 69.:
          ‘phrase(::NonTerminal, Input)’
     To parse a list of tokens using a public non-terminal of an explicit object:
          ‘phrase(Object::NonTerminal, Input)’

See also
........

*note call//1-N: 1c9, *note phrase//1: 1c8, *note phrase/3: 18f.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: phrase/3,  Prev: phrase/2,  Up: Definite clause grammar rules<2>

2.5.10.24 ‘phrase/3’
....................

* Menu:

* Description: Description<149>.
* Meta-predicate template: Meta-predicate template<16>.
* Modes and number of proofs: Modes and number of proofs<112>.
* Errors: Errors<113>.
* Examples: Examples<150>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<149>,  Next: Meta-predicate template<16>,  Up: phrase/3

2.5.10.25 Description
.....................

     phrase(GrammarRuleBody, Input, Rest)
     phrase(::GrammarRuleBody, Input, Rest)
     phrase(Object::GrammarRuleBody, Input, Rest)

True when the ‘GrammarRuleBody’ grammar rule body can be applied to the
‘Input-Rest’ difference list of tokens.  In the most common case,
‘GrammarRuleBody’ is a non-terminal defined by a grammar rule.  This
built-in method is declared private and thus cannot be used as a message
to an object.  When using a *note backend Prolog compiler: 34.
supporting a module system, calls in the format
‘phrase(Module:GrammarRuleBody, Input, Rest)’ may also be used.

This method is opaque to cuts in the first argument.  When the first
argument is sufficiently instantiated at compile-time, the method call
is compiled in order to eliminate the implicit overheads of converting
the grammar rule body into a goal and meta-calling it.  For performance
reasons, the second and third arguments are only type-checked at compile
time.


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<16>,  Next: Modes and number of proofs<112>,  Prev: Description<149>,  Up: phrase/3

2.5.10.26 Meta-predicate template
.................................

     phrase(2, *, *)


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<112>,  Next: Errors<113>,  Prev: Meta-predicate template<16>,  Up: phrase/3

2.5.10.27 Modes and number of proofs
....................................

     phrase(+callable, ?list, ?list) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<113>,  Next: Examples<150>,  Prev: Modes and number of proofs<112>,  Up: phrase/3

2.5.10.28 Errors
................

     ‘GrammarRuleBody’ is a variable:
          ‘instantiation_error’
     ‘GrammarRuleBody’ is neither a variable nor a callable term:
          ‘type_error(callable, GrammarRuleBody)’


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<150>,  Prev: Errors<113>,  Up: phrase/3

2.5.10.29 Examples
..................

     To parse a list of tokens using a local non-terminal:
          ‘phrase(NonTerminal, Input, Rest)’
     To parse a list of tokens using a non-terminal within the scope of *note self: 69.:
          ‘phrase(::NonTerminal, Input, Rest)’
     To parse a list of tokens using a public non-terminal of an explicit object:
          ‘phrase(Object::NonTerminal, Input, Rest)’

See also
........

*note call//1-N: 1c9, *note phrase/2: 18e, *note phrase/3: 18f.


File: TheLogtalkHandbook-3.96.0.info,  Node: Term and goal expansion<2>,  Next: Coinduction hooks,  Prev: Definite clause grammar rules<2>,  Up: Built-in methods<2>

2.5.11 Term and goal expansion
------------------------------

'built-in method'

* Menu:

* expand_term/2::
* term_expansion/2::
* expand_goal/2::
* goal_expansion/2::


File: TheLogtalkHandbook-3.96.0.info,  Node: expand_term/2,  Next: term_expansion/2,  Up: Term and goal expansion<2>

2.5.11.1 ‘expand_term/2’
........................

* Menu:

* Description: Description<150>.
* Modes and number of proofs: Modes and number of proofs<113>.
* Errors: Errors<114>.
* Examples: Examples<151>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<150>,  Next: Modes and number of proofs<113>,  Up: expand_term/2

2.5.11.2 Description
....................

     expand_term(Term, Expansion)

Expands a term.  The most common use is to expand a grammar rule into a
clause.  Users may override the default Logtalk grammar rule translator
by defining clauses for the *note term_expansion/2: fc. hook predicate.

The expansion works as follows: if the first argument is a variable,
then it is unified with the second argument; if the first argument is
not a variable and there are local or inherited clauses for the
‘term_expansion/2’ hook predicate within scope, then this predicate is
called to provide an expansion that is then unified with the second
argument; if the ‘term_expansion/2’ predicate is not used and the first
argument is a compound term with functor ‘(-->)/2’ then the default
Logtalk grammar rule translator is used, with the resulting clause being
unified with the second argument; when the translator is not used, the
two arguments are unified.  The ‘expand_term/2’ predicate may return a
single term or a list of terms.

This built-in method may be used to expand a grammar rule into a clause
for use with the built-in database methods.

Automatic term expansion is only performed at compile-time (to expand
terms read from a source file) when using a *note hook object: 39e.
This predicate can be used by the user to manually perform term
expansion at runtime (for example, to convert a grammar rule into a
clause).


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<113>,  Next: Errors<114>,  Prev: Description<150>,  Up: expand_term/2

2.5.11.3 Modes and number of proofs
...................................

     expand_term(?term, ?term) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<114>,  Next: Examples<151>,  Prev: Modes and number of proofs<113>,  Up: expand_term/2

2.5.11.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<151>,  Prev: Errors<114>,  Up: expand_term/2

2.5.11.5 Examples
.................

(none)

See also
........

*note expand_goal/2: 312, *note goal_expansion/2: fd, *note
term_expansion/2: fc.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: term_expansion/2,  Next: expand_goal/2,  Prev: expand_term/2,  Up: Term and goal expansion<2>

2.5.11.6 ‘term_expansion/2’
...........................

* Menu:

* Description: Description<151>.
* Modes and number of proofs: Modes and number of proofs<114>.
* Errors: Errors<115>.
* Examples: Examples<152>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<151>,  Next: Modes and number of proofs<114>,  Up: term_expansion/2

2.5.11.7 Description
....................

     term_expansion(Term, Expansion)

Defines an expansion for a term.  This predicate, when defined and
within scope, is automatically called by the *note expand_term/2: 1b7.
method.  When that is not the case, the ‘expand_term/2’ method only uses
the default expansions.  Use of this predicate by the ‘expand_term/2’
method may be restricted by changing its default public scope.

The ‘term_expansion/2’ predicate may return a list of terms.  Returning
an empty list effectively suppresses the term.

Term expansion may also be applied when compiling source files by
defining the object providing access to the ‘term_expansion/2’ clauses
as a *note hook object: 39e.  Clauses for the ‘term_expansion/2’
predicate defined within an object or a category are 'never' used in the
compilation of the object or the category itself.  Moreover, in this
context, terms wrapped using the *note {}/1: 191. compiler bypass
control construct are not expanded and any expanded term wrapped in this
control construct will not be further expanded.

Objects and categories implementing this predicate should declare that
they implement the expanding(1) protocol if no ancestor already declares
it.  This protocol implementation relation can be declared as either
*note protected or private: 9e. to restrict the scope of this predicate.

   ---------- Footnotes ----------

   (1) ../../../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<114>,  Next: Errors<115>,  Prev: Description<151>,  Up: term_expansion/2

2.5.11.8 Modes and number of proofs
...................................

     term_expansion(+nonvar, -nonvar) - zero_or_one
     term_expansion(+nonvar, -list(nonvar)) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<115>,  Next: Examples<152>,  Prev: Modes and number of proofs<114>,  Up: term_expansion/2

2.5.11.9 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<152>,  Prev: Errors<115>,  Up: term_expansion/2

2.5.11.10 Examples
..................

     term_expansion((:- license(default)), (:- license(gplv3))).
     term_expansion(data(Millimeters), data(Meters)) :- Meters is Millimeters / 1000.

See also
........

*note expand_goal/2: 312, *note expand_term/2: 1b7, *note
goal_expansion/2: fd, *note logtalk_load_context/2: 317.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: expand_goal/2,  Next: goal_expansion/2,  Prev: term_expansion/2,  Up: Term and goal expansion<2>

2.5.11.11 ‘expand_goal/2’
.........................

* Menu:

* Description: Description<152>.
* Modes and number of proofs: Modes and number of proofs<115>.
* Errors: Errors<116>.
* Examples: Examples<153>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<152>,  Next: Modes and number of proofs<115>,  Up: expand_goal/2

2.5.11.12 Description
.....................

     expand_goal(Goal, ExpandedGoal)

Expands a goal.  The expansion works as follows: if the first argument
is a variable, then it is unified with the second argument; if the first
argument is not a variable and there are local or inherited clauses for
the ‘goal_expansion/2’ hook predicate within scope, then this predicate
is recursively called until a fixed-point is reached to provide an
expansion that is then unified with the second argument; if the
‘goal_expansion/2’ predicate is not within scope, the two arguments are
unified.

Automatic goal expansion is only performed at compile-time (to expand
the body of clauses and meta-directives read from a source file) when
using *note hook objects: 39e.  This predicate can be used by the user
to manually perform goal expansion at runtime (for example, before
asserting a clause).


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<115>,  Next: Errors<116>,  Prev: Description<152>,  Up: expand_goal/2

2.5.11.13 Modes and number of proofs
....................................

     expand_goal(?term, ?term) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<116>,  Next: Examples<153>,  Prev: Modes and number of proofs<115>,  Up: expand_goal/2

2.5.11.14 Errors
................

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<153>,  Prev: Errors<116>,  Up: expand_goal/2

2.5.11.15 Examples
..................

(none)

See also
........

*note expand_term/2: 1b7, *note goal_expansion/2: fd, *note
term_expansion/2: fc.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: goal_expansion/2,  Prev: expand_goal/2,  Up: Term and goal expansion<2>

2.5.11.16 ‘goal_expansion/2’
............................

* Menu:

* Description: Description<153>.
* Modes and number of proofs: Modes and number of proofs<116>.
* Errors: Errors<117>.
* Examples: Examples<154>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<153>,  Next: Modes and number of proofs<116>,  Up: goal_expansion/2

2.5.11.17 Description
.....................

     goal_expansion(Goal, ExpandedGoal)

Defines an expansion for a goal.  The first argument is the goal to be
expanded.  The expanded goal is returned in the second argument.  This
predicate is called recursively on the expanded goal until a fixed point
is reached.  Thus, care must be taken to avoid compilation loops.  This
predicate, when defined and within scope, is automatically called by the
*note expand_goal/2: 312. method.  Use of this predicate by the
‘expand_goal/2’ method may be restricted by changing its default public
scope.

Goal expansion may also be applied when compiling source files by
defining the object providing access to the ‘goal_expansion/2’ clauses
as a *note hook object: 39e.  Clauses for the ‘goal_expansion/2’
predicate defined within an object or a category are 'never' used in the
compilation of the object or the category itself.  Moreover, in this
context, goals wrapped using the *note {}/1: 191. compiler bypass
control construct are not expanded and any expanded goal wrapped in this
control construct will not be further expanded.

Objects and categories implementing this predicate should declare that
they implement the expanding(1) built-in protocol if no ancestor already
declares it.  This protocol implementation relation can be declared as
either *note protected or private: 9e. to restrict the scope of this
predicate.

   ---------- Footnotes ----------

   (1) ../../../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<116>,  Next: Errors<117>,  Prev: Description<153>,  Up: goal_expansion/2

2.5.11.18 Modes and number of proofs
....................................

     goal_expansion(+callable, -callable) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<117>,  Next: Examples<154>,  Prev: Modes and number of proofs<116>,  Up: goal_expansion/2

2.5.11.19 Errors
................

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<154>,  Prev: Errors<117>,  Up: goal_expansion/2

2.5.11.20 Examples
..................

     goal_expansion(write(Term), (write_term(Term, []), nl)).
     goal_expansion(read(Term), (write('Input: '), {read(Term)})).

See also
........

*note expand_goal/2: 312, *note expand_term/2: 1b7, *note
term_expansion/2: fc, *note logtalk_load_context/2: 317.


File: TheLogtalkHandbook-3.96.0.info,  Node: Coinduction hooks,  Next: Message printing,  Prev: Term and goal expansion<2>,  Up: Built-in methods<2>

2.5.12 Coinduction hooks
------------------------

'built-in method'

* Menu:

* coinductive_success_hook/1-2::


File: TheLogtalkHandbook-3.96.0.info,  Node: coinductive_success_hook/1-2,  Up: Coinduction hooks

2.5.12.1 ‘coinductive_success_hook/1-2’
.......................................

* Menu:

* Description: Description<154>.
* Modes and number of proofs: Modes and number of proofs<117>.
* Errors: Errors<118>.
* Examples: Examples<155>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<154>,  Next: Modes and number of proofs<117>,  Up: coinductive_success_hook/1-2

2.5.12.2 Description
....................

     coinductive_success_hook(Head, Hypothesis)
     coinductive_success_hook(Head)

User-defined hook predicates that are automatically called in case of
coinductive success when proving a query for a coinductive predicates.
The hook predicates are called with the head of the coinductive
predicate on coinductive success and, optionally, with the hypothesis
that has used to reach coinductive success.

When both hook predicates are defined, the ‘coinductive_success_hook/1’
clauses are only used if no ‘coinductive_success_hook/2’ clause applies.
The compiler ensures zero performance penalties when defining
coinductive predicates without a corresponding definition for the
coinductive success hook predicates.

The compiler assumes that these hook predicates are defined as static
predicates in order to optimize their use.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<117>,  Next: Errors<118>,  Prev: Description<154>,  Up: coinductive_success_hook/1-2

2.5.12.3 Modes and number of proofs
...................................

     coinductive_success_hook(+callable, +callable) - zero_or_one
     coinductive_success_hook(+callable) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<118>,  Next: Examples<155>,  Prev: Modes and number of proofs<117>,  Up: coinductive_success_hook/1-2

2.5.12.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<155>,  Prev: Errors<118>,  Up: coinductive_success_hook/1-2

2.5.12.5 Examples
.................

     % Are there "occurrences" of arg1 in arg2?
     :- public(member/2).
     :- coinductive(member/2).

     member(X, [X| _]).
     member(X, [_| T]) :-
         member(X, T).

     % Are there infinitely many "occurrences" of arg1 in arg2?
     :- public(comember/2).
     :- coinductive(comember/2).
     comember(X, [_| T]) :-
         comember(X, T).

     coinductive_success_hook(member(_, _)) :-
         fail.
     coinductive_success_hook(comember(X, L)) :-
         member(X, L).

See also
........

*note coinductive/1: 171.


File: TheLogtalkHandbook-3.96.0.info,  Node: Message printing,  Next: Question asking,  Prev: Coinduction hooks,  Up: Built-in methods<2>

2.5.13 Message printing
-----------------------

'built-in method'

* Menu:

* print_message/3::
* message_tokens//2::
* message_hook/4::
* message_prefix_stream/4::
* message_prefix_file/6::
* print_message_tokens/3::
* print_message_token/4::


File: TheLogtalkHandbook-3.96.0.info,  Node: print_message/3,  Next: message_tokens//2,  Up: Message printing

2.5.13.1 ‘print_message/3’
..........................

* Menu:

* Description: Description<155>.
* Modes and number of proofs: Modes and number of proofs<118>.
* Errors: Errors<119>.
* Examples: Examples<156>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<155>,  Next: Modes and number of proofs<118>,  Up: print_message/3

2.5.13.2 Description
....................

     print_message(Kind, Component, Term)

Built-in method for printing a message represented by a term, which is
converted to the message text using the *note
logtalk;;message_tokens(Term, Component): 300. hook non-terminal.  This
method is declared in the logtalk(1) built-in object as a public
predicate.  The line prefix and the output stream used for each
‘Kind-Component’ pair can be found using the *note
logtalk;;message_prefix_stream(Kind, Component, Prefix, Stream): 304.
hook predicate.

This predicate starts by converting the message term to a list of tokens
and by calling the *note logtalk;;message_hook(Message, Kind, Component,
Tokens): 306. hook predicate.  If this predicate succeeds, the
‘print_message/3’ predicate assumes that the message has been
successfully printed.

By default: messages of kind ‘debug’ or ‘debug(_)’ are only printed when
the ‘debug’ flag is turned on; messages of kind ‘banner’, ‘comment’, or
‘comment(_)’ are only printed when the ‘report’ flag is set to ‘on’;
messages of kind ‘warning’ and ‘warning(_)’ are not printed when the
‘report’ flag is set to ‘off’; messages of kind ‘silent’ and ‘silent()’
are not printed (but can be intercepted).

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<118>,  Next: Errors<119>,  Prev: Description<155>,  Up: print_message/3

2.5.13.3 Modes and number of proofs
...................................

     print_message(+nonvar, +nonvar, +nonvar) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<119>,  Next: Examples<156>,  Prev: Modes and number of proofs<118>,  Up: print_message/3

2.5.13.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<156>,  Prev: Errors<119>,  Up: print_message/3

2.5.13.5 Examples
.................

     ..., logtalk::print_message(information, core, redefining_entity(object, foo)), ...

See also
........

*note message_hook/4: 306, *note message_prefix_stream/4: 304, *note
message_tokens//2: 300, *note print_message_tokens/3: 7f8, *note
print_message_token/4: 7f9, *note ask_question/5: 30b, *note
question_hook/6: 30d, *note question_prompt_stream/4: 7fa.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: message_tokens//2,  Next: message_hook/4,  Prev: print_message/3,  Up: Message printing

2.5.13.6 ‘message_tokens//2’
............................

* Menu:

* Description: Description<156>.
* Modes and number of proofs: Modes and number of proofs<119>.
* Errors: Errors<120>.
* Examples: Examples<157>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<156>,  Next: Modes and number of proofs<119>,  Up: message_tokens//2

2.5.13.7 Description
....................

     message_tokens(Message, Component)

User-defined non-terminal hook used to rewrite a message term into a
list of tokens and declared in the logtalk(1) built-in object as a
public, multifile, and dynamic non-terminal.  The list of tokens can be
printed by calling the *note print_message_tokens/3: 7f8. method.  This
non-terminal hook is automatically called by the *note print_message/3:
2fe. method.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<119>,  Next: Errors<120>,  Prev: Description<156>,  Up: message_tokens//2

2.5.13.8 Modes and number of proofs
...................................

     message_tokens(+nonvar, +nonvar) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<120>,  Next: Examples<157>,  Prev: Modes and number of proofs<119>,  Up: message_tokens//2

2.5.13.9 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<157>,  Prev: Errors<120>,  Up: message_tokens//2

2.5.13.10 Examples
..................

     :- multifile(logtalk::message_tokens//2).
     :- dynamic(logtalk::message_tokens//2).

     logtalk::message_tokens(redefining_entity(Type, Entity), core) -->
         ['Redefining ~w ~q'-[Type, Entity], nl].

See also
........

*note message_hook/4: 306, *note message_prefix_stream/4: 304, *note
print_message/3: 2fe, *note print_message_tokens/3: 7f8, *note
print_message_token/4: 7f9, *note ask_question/5: 30b, *note
question_hook/6: 30d, *note question_prompt_stream/4: 7fa.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: message_hook/4,  Next: message_prefix_stream/4,  Prev: message_tokens//2,  Up: Message printing

2.5.13.11 ‘message_hook/4’
..........................

* Menu:

* Description: Description<157>.
* Modes and number of proofs: Modes and number of proofs<120>.
* Errors: Errors<121>.
* Examples: Examples<158>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<157>,  Next: Modes and number of proofs<120>,  Up: message_hook/4

2.5.13.12 Description
.....................

     message_hook(Message, Kind, Component, Tokens)

User-defined hook method for intercepting printing of a message,
declared in the logtalk(1) built-in object as a public, multifile, and
dynamic predicate.  This hook method is automatically called by the
*note print_message/3: 2fe. method.  When the call succeeds, the
‘print_message/3’ method assumes that the message has been successfully
printed.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<120>,  Next: Errors<121>,  Prev: Description<157>,  Up: message_hook/4

2.5.13.13 Modes and number of proofs
....................................

     message_hook(@nonvar, @nonvar, @nonvar, @list(nonvar)) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<121>,  Next: Examples<158>,  Prev: Modes and number of proofs<120>,  Up: message_hook/4

2.5.13.14 Errors
................

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<158>,  Prev: Errors<121>,  Up: message_hook/4

2.5.13.15 Examples
..................

     :- multifile(logtalk::message_hook/4).
     :- dynamic(logtalk::message_hook/4).

     % print silent messages instead of discarding them as default
     logtalk::message_hook(_, silent, core, Tokens) :-
         logtalk::message_prefix_stream(silent, core, Prefix, Stream),
         logtalk::print_message_tokens(Stream, Prefix, Tokens).

See also
........

*note message_prefix_stream/4: 304, *note message_tokens//2: 300, *note
print_message/3: 2fe, *note print_message_tokens/3: 7f8, *note
print_message_token/4: 7f9, *note ask_question/5: 30b, *note
question_hook/6: 30d, *note question_prompt_stream/4: 7fa.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: message_prefix_stream/4,  Next: message_prefix_file/6,  Prev: message_hook/4,  Up: Message printing

2.5.13.16 ‘message_prefix_stream/4’
...................................

* Menu:

* Description: Description<158>.
* Modes and number of proofs: Modes and number of proofs<121>.
* Errors: Errors<122>.
* Examples: Examples<159>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<158>,  Next: Modes and number of proofs<121>,  Up: message_prefix_stream/4

2.5.13.17 Description
.....................

     message_prefix_stream(Kind, Component, Prefix, Stream)

User-defined hook method for specifying the default prefix and stream
for printing a message for a given kind and *note component: 353.  This
method is declared in the logtalk(1) built-in object as a public,
multifile, and dynamic predicate.

The prefix is printed for each line in the list of tokens generated by
the message tokenization (new lines are specified using the ‘nl’ token;
see the documentation of the logtalk(2) built-in object for details).

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0

   (2) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<121>,  Next: Errors<122>,  Prev: Description<158>,  Up: message_prefix_stream/4

2.5.13.18 Modes and number of proofs
....................................

     message_prefix_stream(?nonvar, ?nonvar, ?atom, ?stream_or_alias) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<122>,  Next: Examples<159>,  Prev: Modes and number of proofs<121>,  Up: message_prefix_stream/4

2.5.13.19 Errors
................

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<159>,  Prev: Errors<122>,  Up: message_prefix_stream/4

2.5.13.20 Examples
..................

     :- multifile(logtalk::message_prefix_stream/4).
     :- dynamic(logtalk::message_prefix_stream/4).

     logtalk::message_prefix_stream(information, core, '% ', user_output).

See also
........

*note message_prefix_file/6: 307, *note message_hook/4: 306, *note
message_tokens//2: 300, *note print_message/3: 2fe, *note
print_message_tokens/3: 7f8, *note print_message_token/4: 7f9, *note
ask_question/5: 30b, *note question_hook/6: 30d, *note
question_prompt_stream/4: 7fa.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: message_prefix_file/6,  Next: print_message_tokens/3,  Prev: message_prefix_stream/4,  Up: Message printing

2.5.13.21 ‘message_prefix_file/6’
.................................

* Menu:

* Description: Description<159>.
* Modes and number of proofs: Modes and number of proofs<122>.
* Errors: Errors<123>.
* Examples: Examples<160>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<159>,  Next: Modes and number of proofs<122>,  Up: message_prefix_file/6

2.5.13.22 Description
.....................

     message_prefix_file(Kind, Component, Prefix, File, Mode, Options)

Experimental user-defined hook method for specifying the prefix and file
for copying messages for a given kind and *note component: 353.  This
method is declared in the logtalk(1) built-in object as a public,
multifile, and dynamic predicate.  The valid values for ‘Mode’ are
‘write’ and ‘append’.  The valid options are the same as the standard
‘open/4’ predicate.

The prefix is printed for each line in the list of tokens generated by
the message tokenization (new lines are specified using the ‘nl’ token;
see the documentation of the logtalk(2) built-in object for details).

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0

   (2) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<122>,  Next: Errors<123>,  Prev: Description<159>,  Up: message_prefix_file/6

2.5.13.23 Modes and number of proofs
....................................

     message_prefix_file(?nonvar, ?nonvar, ?atom, ?atom, ?atom, ?list(compound)) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<123>,  Next: Examples<160>,  Prev: Modes and number of proofs<122>,  Up: message_prefix_file/6

2.5.13.24 Errors
................

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<160>,  Prev: Errors<123>,  Up: message_prefix_file/6

2.5.13.25 Examples
..................

     :- multifile(logtalk::message_prefix_file/6).
     :- dynamic(logtalk::message_prefix_file/6).

     logtalk::message_prefix_file(comment, app, '% ', 'comments.txt', append, []).

See also
........

*note message_prefix_stream/4: 304, *note message_hook/4: 306, *note
message_tokens//2: 300, *note print_message/3: 2fe, *note
print_message_tokens/3: 7f8, *note print_message_token/4: 7f9, *note
ask_question/5: 30b, *note question_hook/6: 30d, *note
question_prompt_stream/4: 7fa.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: print_message_tokens/3,  Next: print_message_token/4,  Prev: message_prefix_file/6,  Up: Message printing

2.5.13.26 ‘print_message_tokens/3’
..................................

* Menu:

* Description: Description<160>.
* Modes and number of proofs: Modes and number of proofs<123>.
* Errors: Errors<124>.
* Examples: Examples<161>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<160>,  Next: Modes and number of proofs<123>,  Up: print_message_tokens/3

2.5.13.27 Description
.....................

     print_message_tokens(Stream, Prefix, Tokens)

Built-in method for printing a list of message tokens, declared in the
logtalk(1) built-in object as a public predicate.  This method is
automatically called by the *note print_message/3: 2fe. method (assuming
that the message was not intercepted by a *note message_hook/4: 306.
definition) and calls the user-defined hook predicate *note
print_message_token/4: 7f9. for each token.  When a call to this hook
predicate succeeds, the ‘print_message_tokens/3’ predicate assumes that
the token has been printed.  When the call fails, the
‘print_message_tokens/3’ predicate uses a default printing procedure for
the token.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<123>,  Next: Errors<124>,  Prev: Description<160>,  Up: print_message_tokens/3

2.5.13.28 Modes and number of proofs
....................................

     print_message_tokens(@stream_or_alias, +atom, @list(nonvar)) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<124>,  Next: Examples<161>,  Prev: Modes and number of proofs<123>,  Up: print_message_tokens/3

2.5.13.29 Errors
................

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<161>,  Prev: Errors<124>,  Up: print_message_tokens/3

2.5.13.30 Examples
..................

     ...,
     logtalk::print_message_tokens(user_error, '% ', ['Redefining ~w ~q'-[object,foo], nl]),
     ...

See also
........

*note message_hook/4: 306, *note message_prefix_stream/4: 304, *note
message_tokens//2: 300, *note print_message/3: 2fe, *note
print_message_token/4: 7f9, *note ask_question/5: 30b, *note
question_hook/6: 30d, *note question_prompt_stream/4: 7fa.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: print_message_token/4,  Prev: print_message_tokens/3,  Up: Message printing

2.5.13.31 ‘print_message_token/4’
.................................

* Menu:

* Description: Description<161>.
* Modes and number of proofs: Modes and number of proofs<124>.
* Errors: Errors<125>.
* Examples: Examples<162>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<161>,  Next: Modes and number of proofs<124>,  Up: print_message_token/4

2.5.13.32 Description
.....................

     print_message_token(Stream, Prefix, Token, Tokens)

User-defined hook method for printing a message token, declared in the
logtalk(1) built-in object as a public, multifile, and dynamic
predicate.  It allows the user to intercept the printing of a message
token.  This hook method is automatically called by the *note
print_message_tokens/3: 7f8. built-in method for each token.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<124>,  Next: Errors<125>,  Prev: Description<161>,  Up: print_message_token/4

2.5.13.33 Modes and number of proofs
....................................

     print_message_token(@stream_or_alias, @atom, @nonvar, @list(nonvar)) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<125>,  Next: Examples<162>,  Prev: Modes and number of proofs<124>,  Up: print_message_token/4

2.5.13.34 Errors
................

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<162>,  Prev: Errors<125>,  Up: print_message_token/4

2.5.13.35 Examples
..................

     :- multifile(logtalk::print_message_token/4).
     :- dynamic(logtalk::print_message_token/4).

     % ignore all flush tokens
     logtalk::print_message_token(_Stream, _Prefix, flush, _Tokens).

See also
........

*note message_hook/4: 306, *note message_prefix_stream/4: 304, *note
message_tokens//2: 300, *note print_message/3: 2fe, *note
print_message_tokens/3: 7f8, *note ask_question/5: 30b, *note
question_hook/6: 30d, *note question_prompt_stream/4: 7fa.


File: TheLogtalkHandbook-3.96.0.info,  Node: Question asking,  Prev: Message printing,  Up: Built-in methods<2>

2.5.14 Question asking
----------------------

'built-in method'

* Menu:

* ask_question/5::
* question_hook/6::
* question_prompt_stream/4::


File: TheLogtalkHandbook-3.96.0.info,  Node: ask_question/5,  Next: question_hook/6,  Up: Question asking

2.5.14.1 ‘ask_question/5’
.........................

* Menu:

* Description: Description<162>.
* Modes and number of proofs: Modes and number of proofs<125>.
* Meta-predicate template: Meta-predicate template<17>.
* Errors: Errors<126>.
* Examples: Examples<163>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<162>,  Next: Modes and number of proofs<125>,  Up: ask_question/5

2.5.14.2 Description
....................

     ask_question(Kind, Component, Question, Check, Answer)

Built-in method for asking a question represented by a term, ‘Question’,
which is converted to the question text using the *note
logtalk;;message_tokens(Question, Component): 300. hook predicate.  This
method is declared in the ‘logtalk’ built-in object as a public
predicate.  The default question prompt and the input stream used for
each ‘Kind-Component’ pair can be found using the *note
logtalk;;question_prompt_stream(Kind, Component, Prompt, Stream): 7fa.
hook predicate.  The ‘Check’ argument is a *note closure: 14f. that is
converted into a checking goal by extending it with the user supplied
answer.  This predicate implements a read-loop that terminates when the
check goal succeeds.

This predicate starts by calling the *note
logtalk;;question_hook(Question, Kind, Component, Tokens, Check,
Answer): 30d. hook predicate.  If this predicate succeeds, the
‘ask_question/5’ predicate assumes that the question have been
successfully asked and replied.


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<125>,  Next: Meta-predicate template<17>,  Prev: Description<162>,  Up: ask_question/5

2.5.14.3 Modes and number of proofs
...................................

     ask_question(+nonvar, +nonvar, +nonvar, +callable, -term) - one


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<17>,  Next: Errors<126>,  Prev: Modes and number of proofs<125>,  Up: ask_question/5

2.5.14.4 Meta-predicate template
................................

     ask_question(*, *, *, 1, *)


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<126>,  Next: Examples<163>,  Prev: Meta-predicate template<17>,  Up: ask_question/5

2.5.14.5 Errors
...............

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<163>,  Prev: Errors<126>,  Up: ask_question/5

2.5.14.6 Examples
.................

     ...,
     logtalk::ask_question(enter_age, question, my_app, integer, Age),
     ...

See also
........

*note question_hook/6: 30d, *note question_prompt_stream/4: 7fa, *note
message_hook/4: 306, *note message_prefix_stream/4: 304, *note
message_tokens//2: 300, *note print_message/3: 2fe, *note
print_message_tokens/3: 7f8, *note print_message_token/4: 7f9.

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: question_hook/6,  Next: question_prompt_stream/4,  Prev: ask_question/5,  Up: Question asking

2.5.14.7 ‘question_hook/6’
..........................

* Menu:

* Description: Description<163>.
* Modes and number of proofs: Modes and number of proofs<126>.
* Meta-predicate template: Meta-predicate template<18>.
* Errors: Errors<127>.
* Examples: Examples<164>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<163>,  Next: Modes and number of proofs<126>,  Up: question_hook/6

2.5.14.8 Description
....................

     question_hook(Question, Kind, Component, Tokens, Check, Answer)

User-defined hook method for intercepting asking a question, declared in
the logtalk(1) built-in object as a public, multifile, and dynamic
predicate.  This hook method is automatically called by the *note
ask_question/5: 30b. method.  When the call succeeds, the
‘ask_question/5’ method assumes that the question have been successfully
asked and replied.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<126>,  Next: Meta-predicate template<18>,  Prev: Description<163>,  Up: question_hook/6

2.5.14.9 Modes and number of proofs
...................................

     question_hook(+nonvar, +nonvar, +nonvar, +list(nonvar), +callable, -term) - zero_or_one


File: TheLogtalkHandbook-3.96.0.info,  Node: Meta-predicate template<18>,  Next: Errors<127>,  Prev: Modes and number of proofs<126>,  Up: question_hook/6

2.5.14.10 Meta-predicate template
.................................

     question_hook(*, *, *, *, 1, *)


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<127>,  Next: Examples<164>,  Prev: Meta-predicate template<18>,  Up: question_hook/6

2.5.14.11 Errors
................

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<164>,  Prev: Errors<127>,  Up: question_hook/6

2.5.14.12 Examples
..................

     :- multifile(logtalk::question_hook/6).
     :- dynamic(logtalk::question_hook/6).

     % use a pre-defined answer instead of asking the user
     logtalk::question_hook(upper_limit, question, my_app, _, _, 3.7).

See also
........

*note ask_question/5: 30b, *note question_prompt_stream/4: 7fa. *note
message_hook/4: 306, *note message_prefix_stream/4: 304, *note
message_tokens//2: 300, *note print_message/3: 2fe, *note
print_message_tokens/3: 7f8, *note print_message_token/4: 7f9,

'built-in method'


File: TheLogtalkHandbook-3.96.0.info,  Node: question_prompt_stream/4,  Prev: question_hook/6,  Up: Question asking

2.5.14.13 ‘question_prompt_stream/4’
....................................

* Menu:

* Description: Description<164>.
* Modes and number of proofs: Modes and number of proofs<127>.
* Errors: Errors<128>.
* Examples: Examples<165>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<164>,  Next: Modes and number of proofs<127>,  Up: question_prompt_stream/4

2.5.14.14 Description
.....................

     question_prompt_stream(Kind, Component, Prompt, Stream)

User-defined hook method for specifying the default prompt and input
stream for asking a question for a given kind and *note component: 353.
This method is declared in the logtalk(1) built-in object as a public,
multifile, and dynamic predicate.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Modes and number of proofs<127>,  Next: Errors<128>,  Prev: Description<164>,  Up: question_prompt_stream/4

2.5.14.15 Modes and number of proofs
....................................

     question_prompt_stream(?nonvar, ?nonvar, ?atom, ?stream_or_alias) - zero_or_more


File: TheLogtalkHandbook-3.96.0.info,  Node: Errors<128>,  Next: Examples<165>,  Prev: Modes and number of proofs<127>,  Up: question_prompt_stream/4

2.5.14.16 Errors
................

(none)


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<165>,  Prev: Errors<128>,  Up: question_prompt_stream/4

2.5.14.17 Examples
..................

     :- multifile(logtalk::question_prompt_stream/4).
     :- dynamic(logtalk::question_prompt_stream/4).

     logtalk::question_prompt_stream(question, debugger, '    > ', user_input).

See also
........

*note ask_question/5: 30b, *note question_hook/6: 30d, *note
message_hook/4: 306, *note message_prefix_stream/4: 304, *note
message_tokens//2: 300, *note print_message/3: 2fe, *note
print_message_tokens/3: 7f8, *note print_message_token/4: 7f9.


File: TheLogtalkHandbook-3.96.0.info,  Node: Tutorial,  Next: FAQ,  Prev: Reference Manual,  Up: Top

3 Tutorial
**********

* Menu:

* List predicates::
* Dynamic object attributes::
* A reflective class-based system::
* Profiling programs::


File: TheLogtalkHandbook-3.96.0.info,  Node: List predicates,  Next: Dynamic object attributes,  Up: Tutorial

3.1 List predicates
===================

In this example, we will illustrate the use of:

   - objects

   - protocols

by using common list utility predicates.

* Menu:

* Defining a list object::
* Defining a list protocol::
* Summary::


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining a list object,  Next: Defining a list protocol,  Up: List predicates

3.1.1 Defining a list object
----------------------------

We will start by defining an object, ‘list’, containing predicate
definitions for some common list predicates like ‘append/3’, ‘length/2’,
and ‘member/2’:

     :- object(list).

         :- public([
             append/3, length/2, member/2
         ]).

         append([], List, List).
         append([Head| Tail], List, [Head| Tail2]) :-
             append(Tail, List, Tail2).

         length(List, Length) :-
             length(List, 0, Length).

         length([], Length, Length).
         length([_| Tail], Acc, Length) :-
             Acc2 is Acc + 1,
             length(Tail, Acc2, Length).

         member(Element, [Element| _]).
         member(Element, [_| List]) :-
             member(Element, List).

     :- end_object.

What is different here from a regular Prolog program?  The definitions
of the list predicates are the usual ones.  We have two new directives,
*note object/1-5: 9a. and *note end_object/0: 9b, that encapsulate the
object’s code.  In Logtalk, by default, all object predicates are
private; therefore, we have to explicitly declare all predicates that we
want to be public, that is, that we want to call from outside the
object.  This is done using the *note public/1: 143. scope directive.

After we copy the object code to a text file and saved it under the name
‘list.lgt’, we need to change the Prolog working directory to the one
used to save our file (consult your Prolog compiler reference manual).
Then, after starting Logtalk (see the *note Installing and running
Logtalk: 370. section on the User Manual), we can compile and load the
object using the *note logtalk_load/1: 46. Logtalk built-in predicate:

     | ?- logtalk_load(list).

     object list loaded
     yes

We can now try goals like:

     | ?- list::member(X, [1, 2, 3]).

     X = 1;
     X = 2;
     X = 3;
     no

or:

     | ?- list::length([1, 2, 3], L).

     L = 3
     yes

The infix operator *note (;;)/2: 7e. is used in Logtalk to send a
message to an object.  The message must match a public object predicate.
If we try to call a non-public predicate such as the ‘length/3’
auxiliary predicate an exception will be generated:

     | ?- list::length([1, 2, 3], 0, L).

     uncaught exception:
         error(
             existence_error(predicate_declaration, length/3),
             logtalk(list::length([1,2,3],0,_), ...)
         )

The exception term describes the type of error and the context where the
error occurred.


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining a list protocol,  Next: Summary,  Prev: Defining a list object,  Up: List predicates

3.1.2 Defining a list protocol
------------------------------

As we saw in the above example, a Logtalk object may contain predicate
directives and predicate definitions (clauses).  The set of predicate
directives defines what we call the object’s 'protocol' or interface.
An interface may have several implementations.  For instance, we may
want to define a new object that implements the list predicates using
difference lists.  However, we do not want to repeat the predicate
directives in the new object.  Therefore, what we need is to split the
object’s protocol from the object’s implementation by defining a new
Logtalk entity known as a protocol.  Logtalk protocols are compilation
units, at the same level as objects and categories.  That said, let us
define a ‘listp’ protocol:

     :- protocol(listp).

         :- public([
             append/3, length/2, member/2
         ]).

     :- end_protocol.

Similar to what we have done for objects, we use the *note protocol/1-2:
dc. and *note end_protocol/0: dd. directives to encapsulate the
predicate directives.  We can improve this protocol by documenting the
call/return modes and the number of proofs of each predicate using the
*note mode/2: 149. directive:

     :- protocol(listp).

         :- public(append/3).
         :- mode(append(?list, ?list, ?list), zero_or_more).

         :- public(length/2).
         :- mode(length(?list, ?integer), zero_or_more).

         :- public(member/2).
         :- mode(member(?term, ?list), zero_or_more).

     :- end_protocol.

We now need to change our definition of the ‘list’ object by removing
the predicate directives and by declaring that the object implements the
‘listp’ protocol:

     :- object(list,
         implements(listp)).

         append([], List, List).
         append([Head| Tail], List, [Head| Tail2]) :-
             append(Tail, List, Tail2).
         ...

     :- end_object.

The protocol declared in ‘listp’ may now be alternatively implemented
using difference lists by defining a new object, ‘difflist’:

     :- object(difflist,
         implements(listp).

         append(L1-X, X-L2, L1-L2).
         ...

     :- end_object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Summary,  Prev: Defining a list protocol,  Up: List predicates

3.1.3 Summary
-------------

   * It is easy to define a simple object: just write your Prolog code
     inside starting and ending object directives and add the necessary
     scope directives.  The object will be self-defining and ready to
     use.

   * Define a protocol when you may want to provide or enable several
     alternative definitions to a given set of predicates.  This way we
     avoid needless repetition of predicate directives.


File: TheLogtalkHandbook-3.96.0.info,  Node: Dynamic object attributes,  Next: A reflective class-based system,  Prev: List predicates,  Up: Tutorial

3.2 Dynamic object attributes
=============================

In this example, we will illustrate the use of:

   - categories

   - category predicates

   - dynamic predicates

by defining a category that implements a set of predicates for handling
dynamic object attributes.

* Menu:

* Defining a category::
* Importing the category::
* Summary: Summary<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining a category,  Next: Importing the category,  Up: Dynamic object attributes

3.2.1 Defining a category
-------------------------

We want to define a set of predicates to handle dynamic object
attributes.  We need public predicates to set, get, and delete
attributes, and a private dynamic predicate to store the attribute
values.  Let us name these predicates ‘set_attribute/2’ and
‘get_attribute/2’, for getting and setting an attribute value,
‘del_attribute/2’ and ‘del_attributes/2’, for deleting attributes, and
‘attribute_/2’, for storing the attributes values.

But we do not want to encapsulate these predicates in an object.  Why?
Because they are a set of useful, closely related, predicates that may
be used by several, unrelated, objects.  If defined at an object level,
we would be constrained to use inheritance in order to have the
predicates available to other objects.  Furthermore, this could force us
to use multi-inheritance or to have some kind of generic root object
containing all kinds of possible useful predicates.

For this kind of situation, Logtalk enables the programmer to
encapsulate the predicates in a 'category', so that they can be used in
any object.  A category is a Logtalk entity, at the same level as
objects and protocols.  It can contain predicate directives and
predicate definitions.  Category predicates can be imported by any
object, without code duplication and without resorting to inheritance.

When defining category predicates, we need to remember that a category
can be imported by more than one object.  Thus, calls to the built-in
methods that handle the private dynamic predicate (such as *note
assertz/1: 1b3. or *note retract/1: 1b5.) must be made either in the
context of 'self', using the 'message to self' control structure, *note
(;;)/1: 5c, or in the context of 'this' (i.e., in the context of the
object importing the category).  This way, we ensure that when we call
one of the attribute predicates on an object, the intended object own
definition of ‘attribute_/2’ will be used.  The predicate definitions
are straightforward.  For example, if opting to store the attributes in
'self':

     :- category(attributes).

         :- public(set_attribute/2).
         :- mode(set_attribute(+nonvar, +nonvar), one).

         :- public(get_attribute/2).
         :- mode(get_attribute(?nonvar, ?nonvar), zero_or_more).

         :- public(del_attribute/2).
         :- mode(del_attribute(?nonvar, ?nonvar), zero_or_more).

         :- public(del_attributes/2).
         :- mode(del_attributes(@term, @term), one).

         :- private(attribute_/2).
         :- mode(attribute_(?nonvar, ?nonvar), zero_or_more).
         :- dynamic(attribute_/2).

         set_attribute(Attribute, Value):-
             ::retractall(attribute_(Attribute, _)),
             ::assertz(attribute_(Attribute, Value)).

         get_attribute(Attribute, Value):-
             ::attribute_(Attribute, Value).

         del_attribute(Attribute, Value):-
             ::retract(attribute_(Attribute, Value)).

         del_attributes(Attribute, Value):-
             ::retractall(attribute_(Attribute, Value)).

     :- end_category.

The alternative, opting to store the attributes on 'this', is similar:
just delete the ‘(::)/1’ operator from the code above.

We have two new directives, *note category/1-4: 10e. and *note
end_category/0: 10f, that encapsulate the category code.  If needed, we
can put the predicate directives inside a protocol that will be
implemented by the category:

     :- category(attributes,
         implements(attributes_protocol)).

         ...

     :- end_category.

Any protocol can be implemented by either an object, a category, or
both.


File: TheLogtalkHandbook-3.96.0.info,  Node: Importing the category,  Next: Summary<2>,  Prev: Defining a category,  Up: Dynamic object attributes

3.2.2 Importing the category
----------------------------

We reuse a category’s predicates by importing them into an object:

     :- object(person,
         imports(attributes)).

         ...

     :- end_object.

After compiling and loading this object and our category, we can now try
queries like:

     | ?- person::set_attribute(name, paulo).

     yes

     | ?- person::set_attribute(gender, male).

     yes

     | ?- person::get_attribute(Attribute, Value).

     Attribute = name, Value = paulo ;
     Attribute = gender, Value = male ;
     no


File: TheLogtalkHandbook-3.96.0.info,  Node: Summary<2>,  Prev: Importing the category,  Up: Dynamic object attributes

3.2.3 Summary
-------------

   - Categories are similar to objects: we just write our predicate
     directives and definitions bracketed by opening and ending category
     directives.

   - An object reuses a category by importing it.  The imported
     predicates behave as if they have been defined in the object
     itself.

   - When do we use a category instead of an object?  Whenever we have a
     set of closely related predicates that we want to reuse in several,
     unrelated, objects without being constrained by inheritance
     relations.  Thus, categories can be interpreted as object building
     components.


File: TheLogtalkHandbook-3.96.0.info,  Node: A reflective class-based system,  Next: Profiling programs,  Prev: Dynamic object attributes,  Up: Tutorial

3.3 A reflective class-based system
===================================

When compiling an object, Logtalk distinguishes prototypes from
instances or classes by examining the object relations.  If an object
instantiates and/or specializes another object, then it is compiled as
an instance or class, otherwise it is compiled as a prototype.  A
consequence of this is that, in order to work with instance or classes,
we always have to define root objects for the instantiation and
specialization hierarchies (however, we are not restricted to a single
hierarchy).  The best solution is often to define a reflective
class-based system *note [Maes87]: 14, where every class is also an
object and, as such, an instance of some class.

In this example, we are going to define the basis for a reflective
class-based system, based on an extension of the ideas presented in
*note [Cointe87]: 9c.  This extension provides, along with root objects
for the instantiation and specialization hierarchies, explicit support
for abstract classes *note [Moura94]: 9d.

* Menu:

* Defining the base classes::
* Summary: Summary<3>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining the base classes,  Next: Summary<3>,  Up: A reflective class-based system

3.3.1 Defining the base classes
-------------------------------

We will start by defining three classes: ‘object’, ‘abstract_class’, and
‘class’.  The class ‘object’ will contain all predicates common to all
objects.  It will be the root of the inheritance graph:

     :- object(object,
         instantiates(class)).

         % predicates common to all objects

     :- end_object.

The class ‘abstract_class’ specializes ‘object’ by adding predicates
common to all classes.  It will be the default meta-class for abstract
classes:

     :- object(abstract_class,
         instantiates(class),
         specializes(object)).

         % predicates common to all classes

     :- end_object.

The class ‘class’ specializes ‘abstract_class’ by adding predicates
common to all instantiable classes.  It will be the root of the
instantiation graph and the default meta-class for instantiable classes:

     :- object(class,
         instantiates(class),
         specializes(abstract_class)).

         % predicates common to all instantiable classes

     :- end_object.

Note that all three objects are instances of class ‘class’.  The
instantiation and specialization relationships are chosen so that each
object may use the predicates defined in itself and in the other two
objects, with no danger of *note message lookup: 37. endless loops.


File: TheLogtalkHandbook-3.96.0.info,  Node: Summary<3>,  Prev: Defining the base classes,  Up: A reflective class-based system

3.3.2 Summary
-------------

   - An object that does not instantiate or specialize other objects is
     always compiled as a prototype.

   - An instance must instantiate at least one object (its class).
     Similarly, a class must at least specialize or instantiate other
     object.

   - The distinction between abstract classes and instantiable classes
     is an operational one, depending on the class inherited methods.  A
     class is instantiable if inherits methods for creating instances.
     Conversely, a class is abstract if does not inherit any instance
     creation method.


File: TheLogtalkHandbook-3.96.0.info,  Node: Profiling programs,  Prev: A reflective class-based system,  Up: Tutorial

3.4 Profiling programs
======================

In this example, we will illustrate the use of:

   - events

   - monitors

by defining a simple profiler that prints the starting and ending time
for processing a message sent to an object.

* Menu:

* Messages as events::
* Profilers as monitors::
* Summary: Summary<4>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Messages as events,  Next: Profilers as monitors,  Up: Profiling programs

3.4.1 Messages as events
------------------------

In a pure object-oriented system, all computations start by sending
messages to objects.  We can thus define an 'event' as the sending of a
message to an object.  An event can then be specified by the tuple
‘(Object, Message, Sender)’.  This definition can be refined by
interpreting the sending of a message and the return of the control to
the object that has sent the message as two distinct events.  We call
these events respectively ‘before’ and ‘after’.  Therefore, we end up by
representing an event by the tuple ‘(Event, Object, Message, Sender)’.
For instance, if we send the message:

     | ?- foo::bar(X).

     X = 1
     yes

the two corresponding events will be:

     (before, foo, bar(X), user)
     (after, foo, bar(1), user)

Note that the second event is only generated if the message succeeds.
If the message as a goal has multiple solutions, then an ‘after’ event
will be generated for each solution.

Events are automatically generated by the message-sending mechanisms for
each public message sent using the *note (;;)/2: 7e. operator.


File: TheLogtalkHandbook-3.96.0.info,  Node: Profilers as monitors,  Next: Summary<4>,  Prev: Messages as events,  Up: Profiling programs

3.4.2 Profilers as monitors
---------------------------

A monitor is an object that reacts whenever a spied event occurs.  The
monitor actions are defined by two event handlers: *note before/3: 101.
for ‘before’ events and *note after/3: 102. for ‘after’ events.  These
predicates are automatically called by the message-sending mechanisms
when an event registered for the monitor occurs.  These event handlers
are declared as public predicates in the ‘monitoring’ built-in protocol.

In our example, we need a way to get the current time before and after
we process a message.  We will assume that we have a ‘time’ object
implementing a ‘cpu_time/1’ predicate that returns the current CPU time
for the Prolog session:

     :- object(time).

         :- public(cpu_time/1).
         :- mode(cpu_time(-number), one).
         ...

     :- end_object.

Our profiler will be named ‘stop_watch’.  It must define event handlers
for the ‘before’ and ‘after’ events that will print the event
description (object, message, and sender) and the current time:

     :- object(stop_watch,
         % event handler predicates protocol
         implements(monitoring)).

         :- uses(time, [cpu_time/1]).

         before(Object, Message, Sender) :-
             write(Object), write(' <-- '), writeq(Message),
             write(' from '), write(Sender), nl, write('STARTING at '),
             cpu_time(Seconds), write(Seconds), write(' seconds'), nl.

         after(Object, Message, Sender) :-
             write(Object), write(' <-- '), writeq(Message),
             write(' from '), write(Sender), nl, write('ENDING at '),
             cpu_time(Seconds), write(Seconds), write(' seconds'), nl.

     :- end_object.

After compiling and loading the ‘stop_watch’ object (and the objects
that we want to profile), we can use the *note define_events/5: 218.
built-in predicate to set up our profiler.  For example, to profile all
messages that are sent to the object ‘foo’, we need to call the goal:

     | ?- define_events(_, foo, _, _, stop_watch).

     yes

This call will register ‘stop_watch’ as a monitor to all messages sent
to object ‘foo’, for both ‘before’ and ‘after’ events.  Note that we say
“as a monitor”, not “the monitor”: we can have any number of monitors
over the same events.

From now on, every time we sent a message to ‘foo’, the ‘stop_watch’
monitor will print the starting and ending times for the message
execution.  For instance:

     | ?- foo::bar(X).

     foo <-- bar(X) from user
     STARTING at 12.87415 seconds
     foo <-- bar(1) from user
     ENDING at 12.87419 seconds

     X = 1
     yes

To stop profiling the messages sent to ‘foo’ we use the *note
abolish_events/5: 21b. built-in predicate:

     | ?- abolish_events(_, foo, _, _, stop_watch).

     yes

This call will abolish all events defined over the object ‘foo’ assigned
to the ‘stop_watch’ monitor.


File: TheLogtalkHandbook-3.96.0.info,  Node: Summary<4>,  Prev: Profilers as monitors,  Up: Profiling programs

3.4.3 Summary
-------------

   - An event is defined as the sending of a (public) message to an
     object.

   - There are two kinds of events: ‘before’ events, generated before a
     message is processed, and ‘after’ events, generated after the
     message processing has completed successfully.

   - Any object can be declared as a monitor to any event.  A monitor
     shall reference the ‘monitoring’ built-in protocol in the object
     opening directive.

   - A monitor defines event handlers, the predicates *note before/3:
     101. and *note after/3: 102, that are automatically called by the
     runtime engine when a spied event occurs.

   - Three built-in predicates, *note define_events/5: 218, *note
     current_event/5: 21e, and *note abolish_events/5: 21b, enables us
     to define, query, and abolish both events and monitors.


File: TheLogtalkHandbook-3.96.0.info,  Node: FAQ,  Next: Developer Tools,  Prev: Tutorial,  Up: Top

4 FAQ
*****

* Menu:

* General::
* Compatibility::
* Installation::
* Portability::
* Programming::
* Troubleshooting::
* Usability::
* Deployment::
* Performance: Performance<3>.
* Licensing::
* Support::


File: TheLogtalkHandbook-3.96.0.info,  Node: General,  Next: Compatibility,  Up: FAQ

4.1 General
===========

   * *note Why are all versions of Logtalk numbered 2.x or 3.x?: 857.

   * *note Why do I need a Prolog compiler to use Logtalk?: 858.

   * *note Is the Logtalk implementation based on Prolog modules?: 859.

   * *note Does the Logtalk implementation use term-expansion?: 85a.

* Menu:

* Why are all versions of Logtalk numbered 2.x or 3.x?: Why are all versions of Logtalk numbered 2 x or 3 x?.
* Why do I need a Prolog compiler to use Logtalk?::
* Is the Logtalk implementation based on Prolog modules?::
* Does the Logtalk implementation use term-expansion?::


File: TheLogtalkHandbook-3.96.0.info,  Node: Why are all versions of Logtalk numbered 2 x or 3 x?,  Next: Why do I need a Prolog compiler to use Logtalk?,  Up: General

4.1.1 Why are all versions of Logtalk numbered 2.x or 3.x?
----------------------------------------------------------

The numbers “2” and “3” in the Logtalk version string refer to,
respectively, the second and the third generations of the Logtalk
language.  Development of Logtalk 2 started in January 1998, with the
first alpha release for registered users in July and the first public
beta on October.  The first stable version of Logtalk 2 was released in
February 9, 1999.  Development of Logtalk 3 started in April 2012, with
the first public alpha released in August 21, 2012.  The first stable
version of Logtalk 3 was released in January 7, 2015.


File: TheLogtalkHandbook-3.96.0.info,  Node: Why do I need a Prolog compiler to use Logtalk?,  Next: Is the Logtalk implementation based on Prolog modules?,  Prev: Why are all versions of Logtalk numbered 2 x or 3 x?,  Up: General

4.1.2 Why do I need a Prolog compiler to use Logtalk?
-----------------------------------------------------

Currently, the Logtalk language is implemented as a 'trans-compiler' to
Prolog instead of as a standalone compiler.  Compilation of Logtalk
source files is performed in two steps.  First, the Logtalk compiler
converts a source file to a Prolog file.  Second, the chosen Prolog
compiler is called by Logtalk to compile the intermediate Prolog file
generated on the first step.  The implementation of Logtalk as a
trans-compiler allows users to use Logtalk together with features only
available on specific Prolog compilers.


File: TheLogtalkHandbook-3.96.0.info,  Node: Is the Logtalk implementation based on Prolog modules?,  Next: Does the Logtalk implementation use term-expansion?,  Prev: Why do I need a Prolog compiler to use Logtalk?,  Up: General

4.1.3 Is the Logtalk implementation based on Prolog modules?
------------------------------------------------------------

No.  Logtalk is (currently) implemented in plain Prolog code.  Only a
few Prolog compilers include a module system, with several compatibility
problems between them.  Moreover, the current ISO Prolog standard for
modules is next to worthless and is ignored by most of the Prolog
community.  Nevertheless, the Logtalk compiler is able to compile simple
modules (using a common subset of module directives) as objects for
backward-compatibility with existing code (see the *note Prolog
integration and migration: 389. for details).


File: TheLogtalkHandbook-3.96.0.info,  Node: Does the Logtalk implementation use term-expansion?,  Prev: Is the Logtalk implementation based on Prolog modules?,  Up: General

4.1.4 Does the Logtalk implementation use term-expansion?
---------------------------------------------------------

No.  Term-expansion mechanisms are not standard and are not available in
all supported Prolog compilers.


File: TheLogtalkHandbook-3.96.0.info,  Node: Compatibility,  Next: Installation,  Prev: General,  Up: FAQ

4.2 Compatibility
=================

   * *note What are the backend Prolog compiler requirements to run
     Logtalk?: 862.

   * *note Can I use constraint-based packages with Logtalk?: 863.

   * *note Can I use Logtalk objects and Prolog modules at the same
     time?: 864.

* Menu:

* What are the backend Prolog compiler requirements to run Logtalk?::
* Can I use constraint-based packages with Logtalk?::
* Can I use Logtalk objects and Prolog modules at the same time?::


File: TheLogtalkHandbook-3.96.0.info,  Node: What are the backend Prolog compiler requirements to run Logtalk?,  Next: Can I use constraint-based packages with Logtalk?,  Up: Compatibility

4.2.1 What are the backend Prolog compiler requirements to run Logtalk?
-----------------------------------------------------------------------

See the backend Prolog compiler requirements guide(1).

   ---------- Footnotes ----------

   (1) https://logtalk.org/backend_requirements.html


File: TheLogtalkHandbook-3.96.0.info,  Node: Can I use constraint-based packages with Logtalk?,  Next: Can I use Logtalk objects and Prolog modules at the same time?,  Prev: What are the backend Prolog compiler requirements to run Logtalk?,  Up: Compatibility

4.2.2 Can I use constraint-based packages with Logtalk?
-------------------------------------------------------

Usually, yes.  Some constraint-based packages may define operators which
clash with the ones defined by Logtalk.  In these cases, compatibility
with Logtalk depends on the constraint-based packages providing an
alternative for accessing the functionality provided by those operators.
When the constraint solver is encapsulated using a Prolog module, a
possible workaround is to use either explicit module qualification or
encapsulate the call using the *note {}/1: 191. control construct (thus
bypassing the Logtalk compiler).


File: TheLogtalkHandbook-3.96.0.info,  Node: Can I use Logtalk objects and Prolog modules at the same time?,  Prev: Can I use constraint-based packages with Logtalk?,  Up: Compatibility

4.2.3 Can I use Logtalk objects and Prolog modules at the same time?
--------------------------------------------------------------------

Yes.  In order to call a module predicate from within an object (or
category) you may use an *note use_module/2: 4d. directive or use
explicit module qualification (possibly wrapping the call using the
Logtalk control construct *note {}/1: 191. that allows bypassing of the
Logtalk compiler when compiling a predicate call).  Logtalk also allows
modules to be compiled as objects (see the *note Prolog integration and
migration: 389. for details).


File: TheLogtalkHandbook-3.96.0.info,  Node: Installation,  Next: Portability,  Prev: Compatibility,  Up: FAQ

4.3 Installation
================

   * *note The integration scripts/shortcuts are not working!: 86b.

   * *note I get errors when starting up Logtalk after upgrading to the
     latest version!: 86c.

* Menu:

* The integration scripts/shortcuts are not working!::
* I get errors when starting up Logtalk after upgrading to the latest version!::


File: TheLogtalkHandbook-3.96.0.info,  Node: The integration scripts/shortcuts are not working!,  Next: I get errors when starting up Logtalk after upgrading to the latest version!,  Up: Installation

4.3.1 The integration scripts/shortcuts are not working!
--------------------------------------------------------

Check that the ‘LOGTALKHOME’ and ‘LOGTALKUSER’ environment variables are
defined, that the Logtalk user folder is available in the location
pointed by ‘LOGTALKUSER’ (you can create this folder by running the
‘logtalk_user_setup’ shell script), and that the Prolog compilers that
you want to use are supported and available from the system path.  If
the problem persists, run the shell script that creates the integration
script or shortcut manually and check for any error message or
additional instructions.  For some Prolog compilers such as XSB and
Ciao, the first call of the integration script or shortcut must be made
by an administrator user.  If you are using Windows, make sure that any
anti-virus or other security software that you might have installed is
not silently blocking some of the installer tasks.


File: TheLogtalkHandbook-3.96.0.info,  Node: I get errors when starting up Logtalk after upgrading to the latest version!,  Prev: The integration scripts/shortcuts are not working!,  Up: Installation

4.3.2 I get errors when starting up Logtalk after upgrading to the latest version!
----------------------------------------------------------------------------------

Changes in the Logtalk compiler between releases may render Prolog
adapter files from older versions incompatible with new ones.  You may
need to update your local Logtalk user files by running e.g.  the
‘logtalk_user_setup’ shell script.  Check the ‘UPGRADING.md’ file on the
root of the Logtalk installation directory and the release notes for any
incompatible changes to the adapter files.


File: TheLogtalkHandbook-3.96.0.info,  Node: Portability,  Next: Programming,  Prev: Installation,  Up: FAQ

4.4 Portability
===============

   * *note Are my Logtalk applications portable across Prolog
     compilers?: 872.

   * *note Are my Logtalk applications portable across operating
     systems?: 873.

* Menu:

* Are my Logtalk applications portable across Prolog compilers?::
* Are my Logtalk applications portable across operating systems?::


File: TheLogtalkHandbook-3.96.0.info,  Node: Are my Logtalk applications portable across Prolog compilers?,  Next: Are my Logtalk applications portable across operating systems?,  Up: Portability

4.4.1 Are my Logtalk applications portable across Prolog compilers?
-------------------------------------------------------------------

Yes, as long you don’t use built-in predicates or special features only
available on some Prolog compilers.  There is a *note portability: 1d1.
compiler flag that you can set to instruct Logtalk to print a warning
for each occurrence of non-ISO Prolog standard features such as
proprietary built-in predicates.  In addition, it is advisable that you
constrain, if possible, the use of platform or compiler dependent code
to a small number of objects with clearly defined protocols.  You may
also use Logtalk support for conditional compilation to compile
different entity or predicate definitions depending on the backend
Prolog compiler being used.


File: TheLogtalkHandbook-3.96.0.info,  Node: Are my Logtalk applications portable across operating systems?,  Prev: Are my Logtalk applications portable across Prolog compilers?,  Up: Portability

4.4.2 Are my Logtalk applications portable across operating systems?
--------------------------------------------------------------------

Yes, as long you don’t use built-in predicates or special features that
your chosen backend Prolog compiler only supports on some
operating-systems.  You may need to change the end-of-line characters of
your source files to match the ones on the target operating system and
the expectations of your Prolog compiler.  Some Prolog compilers
silently fail to compile source files with the wrong end-of-line
characters.


File: TheLogtalkHandbook-3.96.0.info,  Node: Programming,  Next: Troubleshooting,  Prev: Portability,  Up: FAQ

4.5 Programming
===============

   * *note Should I use prototypes or classes in my application?: 879.

   * *note Can I use both classes and prototypes in the same
     application?: 87a.

   * *note Can I mix classes and prototypes in the same hierarchy?: 87b.

   * *note Can I use a protocol or a category with both prototypes and
     classes?: 87c.

   * *note What support is provided in Logtalk for defining and using
     components?: 87d.

   * *note What support is provided in Logtalk for reflective
     programming?: 87e.

* Menu:

* Should I use prototypes or classes in my application?::
* Can I use both classes and prototypes in the same application?::
* Can I mix classes and prototypes in the same hierarchy?::
* Can I use a protocol or a category with both prototypes and classes?::
* What support is provided in Logtalk for defining and using components?::
* What support is provided in Logtalk for reflective programming?::


File: TheLogtalkHandbook-3.96.0.info,  Node: Should I use prototypes or classes in my application?,  Next: Can I use both classes and prototypes in the same application?,  Up: Programming

4.5.1 Should I use prototypes or classes in my application?
-----------------------------------------------------------

Prototypes and classes provide different patterns of code reuse.  A
prototype encapsulates code that can be used by itself and by its
descendent prototypes.  A class encapsulates code to be used by its
descendent instances.  Prototypes provide the best replacement to the
use of modules as encapsulation units, avoiding the need to instantiate
a class in order to access its code.


File: TheLogtalkHandbook-3.96.0.info,  Node: Can I use both classes and prototypes in the same application?,  Next: Can I mix classes and prototypes in the same hierarchy?,  Prev: Should I use prototypes or classes in my application?,  Up: Programming

4.5.2 Can I use both classes and prototypes in the same application?
--------------------------------------------------------------------

Yes.  In addition, you may freely exchange messages between prototypes,
classes, and instances.


File: TheLogtalkHandbook-3.96.0.info,  Node: Can I mix classes and prototypes in the same hierarchy?,  Next: Can I use a protocol or a category with both prototypes and classes?,  Prev: Can I use both classes and prototypes in the same application?,  Up: Programming

4.5.3 Can I mix classes and prototypes in the same hierarchy?
-------------------------------------------------------------

No.  However, you may define as many prototype hierarchies and class
hierarchies and classes as needed by your application.


File: TheLogtalkHandbook-3.96.0.info,  Node: Can I use a protocol or a category with both prototypes and classes?,  Next: What support is provided in Logtalk for defining and using components?,  Prev: Can I mix classes and prototypes in the same hierarchy?,  Up: Programming

4.5.4 Can I use a protocol or a category with both prototypes and classes?
--------------------------------------------------------------------------

Yes.  A protocol may be implemented by both prototypes and classes in
the same application.  Likewise, a category may be imported by both
prototypes and classes in the same application.


File: TheLogtalkHandbook-3.96.0.info,  Node: What support is provided in Logtalk for defining and using components?,  Next: What support is provided in Logtalk for reflective programming?,  Prev: Can I use a protocol or a category with both prototypes and classes?,  Up: Programming

4.5.5 What support is provided in Logtalk for defining and using components?
----------------------------------------------------------------------------

Logtalk supports component-based programming (since its inception on
January 1998), by using 'categories' (which are first-class entities
like objects and protocols).  Logtalk categories can be used with both
classes and prototypes and are inspired by the Smalltalk-80
(documentation-only) concept of method categories and by Objective-C
categories, hence the name.  For more information, please consult the
*note Categories: 109. section and the examples provided with the
distribution.


File: TheLogtalkHandbook-3.96.0.info,  Node: What support is provided in Logtalk for reflective programming?,  Prev: What support is provided in Logtalk for defining and using components?,  Up: Programming

4.5.6 What support is provided in Logtalk for reflective programming?
---------------------------------------------------------------------

Logtalk supports meta-classes, behavioral reflection through the use of
event-driven programming, and structural reflection through the use of a
set of built-in predicates and built-in methods which allow us to query
the system about existing entities, entity relations, and entity
predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Troubleshooting,  Next: Usability,  Prev: Programming,  Up: FAQ

4.6 Troubleshooting
===================

   * *note Using compiler options on calls to the Logtalk compiling and
     loading predicates does not work!: 888.

   * *note Gecko-based browsers (e.g., Firefox) show non-rendered HTML
     entities when browsing XML documenting files!: 889.

   * *note Compiling a source file results in errors or warnings but the
     Logtalk compiler reports a successful compilation with zero errors
     and zero warnings!: 88a.

* Menu:

* Using compiler options on calls to the Logtalk compiling and loading predicates does not work!::
* Gecko-based browsers (e.g., Firefox) show non-rendered HTML entities when browsing XML documenting files!: Gecko-based browsers e g Firefox show non-rendered HTML entities when browsing XML documenting files!.
* Compiling a source file results in errors or warnings but the Logtalk compiler reports a successful compilation with zero errors and zero warnings!::


File: TheLogtalkHandbook-3.96.0.info,  Node: Using compiler options on calls to the Logtalk compiling and loading predicates does not work!,  Next: Gecko-based browsers e g Firefox show non-rendered HTML entities when browsing XML documenting files!,  Up: Troubleshooting

4.6.1 Using compiler options on calls to the Logtalk compiling and loading predicates does not work!
----------------------------------------------------------------------------------------------------

Using compiler options on calls to the Logtalk *note logtalk_compile/2:
2b2. and *note logtalk_load/2: 4e. built-in predicates only apply to the
file being compiled.  If the first argument is a *note loader file: 4f,
the compiler options will only be used in the compilation of the loader
file itself, not in the compilation of the files loaded by the loader
file.  The solution is to edit the loader file and add the compiler
options to the calls that compile/load the individual files.


File: TheLogtalkHandbook-3.96.0.info,  Node: Gecko-based browsers e g Firefox show non-rendered HTML entities when browsing XML documenting files!,  Next: Compiling a source file results in errors or warnings but the Logtalk compiler reports a successful compilation with zero errors and zero warnings!,  Prev: Using compiler options on calls to the Logtalk compiling and loading predicates does not work!,  Up: Troubleshooting

4.6.2 Gecko-based browsers (e.g., Firefox) show non-rendered HTML entities when browsing XML documenting files!
---------------------------------------------------------------------------------------------------------------

Using Gecko-based browsers (e.g., Firefox) show non-rendered HTML
entities (e.g., ‘&ndash;’) when browsing XML documenting files after
running the ‘lgt2xml’ shell script in the directory containing the XML
documenting files.  This is a consequence of the lack of support for the
‘disable-output-escaping’ attribute in the browser XSLT processor.  The
workaround is to use another browser (e.g., Safari or Opera) or to use
instead the ‘lgt2html’ shell script in the directory containing the XML
documenting files to convert them to (X)HTML files for browsing.


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiling a source file results in errors or warnings but the Logtalk compiler reports a successful compilation with zero errors and zero warnings!,  Prev: Gecko-based browsers e g Firefox show non-rendered HTML entities when browsing XML documenting files!,  Up: Troubleshooting

4.6.3 Compiling a source file results in errors or warnings but the Logtalk compiler reports a successful compilation with zero errors and zero warnings!
---------------------------------------------------------------------------------------------------------------------------------------------------------

This may happen when your Prolog compiler implementation of the ISO
Prolog standard ‘write_canonical/2’ built-in predicate is buggy and
writes terms that cannot be read back when consulting the intermediate
Prolog files generated by the Logtalk compiler.  Often, syntax errors
found when consulting result in error messages but not in exceptions as
the Prolog compiler tries to continue the compilation despite the
problems found.  As the Logtalk compiler relies on the exception
mechanisms to catch compilation problems, it may report zero errors and
zero warnings despite the error messages.  Send a bug report to the
Prolog compiler developers asking them to fix the ‘write_canonical/2’
buggy implementation.


File: TheLogtalkHandbook-3.96.0.info,  Node: Usability,  Next: Deployment,  Prev: Troubleshooting,  Up: FAQ

4.7 Usability
=============

   * *note Is there a shortcut for compiling and loading source files?:
     891.

   * *note Is there an equivalent directive to the ensure_loaded/1
     Prolog directive?: 892.

   * *note Are there shortcuts for the make functionality?: 893.

* Menu:

* Is there a shortcut for compiling and loading source files?::
* Is there an equivalent directive to the ensure_loaded/1 Prolog directive?::
* Are there shortcuts for the make functionality?::


File: TheLogtalkHandbook-3.96.0.info,  Node: Is there a shortcut for compiling and loading source files?,  Next: Is there an equivalent directive to the ensure_loaded/1 Prolog directive?,  Up: Usability

4.7.1 Is there a shortcut for compiling and loading source files?
-----------------------------------------------------------------

Yes.  With most backend Prolog compilers, you can use ‘{File}’ as a
shortcut for ‘logtalk_load(File)’.  For compiling and loading multiple
files simply use ‘{File1, File2, ...}’.  See the documentation of the
*note logtalk_load/1: 46. predicate for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Is there an equivalent directive to the ensure_loaded/1 Prolog directive?,  Next: Are there shortcuts for the make functionality?,  Prev: Is there a shortcut for compiling and loading source files?,  Up: Usability

4.7.2 Is there an equivalent directive to the ‘ensure_loaded/1’ Prolog directive?
---------------------------------------------------------------------------------

You can use the goal ‘logtalk_load(File, [reload(skip)])’ to ensure that
‘File’ it is only loaded once.  See the documentation of the *note
logtalk_load/2: 4e. predicate for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Are there shortcuts for the make functionality?,  Prev: Is there an equivalent directive to the ensure_loaded/1 Prolog directive?,  Up: Usability

4.7.3 Are there shortcuts for the make functionality?
-----------------------------------------------------

Yes.  With most backend Prolog compilers, you can use ‘{*}’ as a
shortcut for ‘logtalk_make(all)’ to reload all files modified since last
compiled and loaded, ‘{!}’ as a shortcut for ‘logtalk_make(clean)’ to
delete all intermediate Prolog files generated by the compilation of
Logtalk source files, ‘{?}’ as a shortcut for ‘logtalk_make(missing)’ to
list missing entities and predicates, and ‘{@}’ as a shortcut for
‘logtalk_make(circular)’ to list circular references.  See the
documentation of the *note logtalk_make/1: 2a0. predicate for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Deployment,  Next: Performance<3>,  Prev: Usability,  Up: FAQ

4.8 Deployment
==============

   * *note Can I create standalone applications with Logtalk?: 89a.

* Menu:

* Can I create standalone applications with Logtalk?::


File: TheLogtalkHandbook-3.96.0.info,  Node: Can I create standalone applications with Logtalk?,  Up: Deployment

4.8.1 Can I create standalone applications with Logtalk?
--------------------------------------------------------

It depends on the Prolog compiler that you use to run Logtalk.  Assuming
that your Prolog compiler supports the creation of standalone
executables, your application must include the adapter file for your
compiler and the Logtalk compiler and runtime.  The distribution
includes embedding scripts for selected backend Prolog compilers and
embedding examples.

For instructions on how to embed Logtalk and Logtalk applications, see
the embedding guide(1).

   ---------- Footnotes ----------

   (1) https://logtalk.org/embedding.html


File: TheLogtalkHandbook-3.96.0.info,  Node: Performance<3>,  Next: Licensing,  Prev: Deployment,  Up: FAQ

4.9 Performance
===============

   * *note Is Logtalk implemented as a meta-interpreter?: 89f.

   * *note What kind of code Logtalk generates when compiling objects?
     Dynamic code?  Static code?: 8a0.

   * *note How about message-sending performance?  Does Logtalk use
     static binding or dynamic binding?: 8a1.

   * *note How does Logtalk performance compare with plain Prolog and
     with Prolog modules?: 8a2.

* Menu:

* Is Logtalk implemented as a meta-interpreter?::
* What kind of code Logtalk generates when compiling objects? Dynamic code? Static code?::
* How about message-sending performance? Does Logtalk use static binding or dynamic binding?::
* Which Prolog-dependent factors are most crucial for good Logtalk performance?::
* How does Logtalk performance compare with plain Prolog and with Prolog modules?::


File: TheLogtalkHandbook-3.96.0.info,  Node: Is Logtalk implemented as a meta-interpreter?,  Next: What kind of code Logtalk generates when compiling objects? Dynamic code? Static code?,  Up: Performance<3>

4.9.1 Is Logtalk implemented as a meta-interpreter?
---------------------------------------------------

No.  Objects and their encapsulated predicates are compiled, not
meta-interpreted.  In particular, inheritance relations are pre-compiled
for improved performance.  Moreover, no meta-interpreter is used even
for objects compiled in debug mode.


File: TheLogtalkHandbook-3.96.0.info,  Node: What kind of code Logtalk generates when compiling objects? Dynamic code? Static code?,  Next: How about message-sending performance? Does Logtalk use static binding or dynamic binding?,  Prev: Is Logtalk implemented as a meta-interpreter?,  Up: Performance<3>

4.9.2 What kind of code Logtalk generates when compiling objects? Dynamic code? Static code?
--------------------------------------------------------------------------------------------

Static objects are compiled to static code.  Static objects containing
dynamic predicates are also compiled to static code, except, of course,
for the dynamic predicates themselves.  Dynamic objects are necessarily
compiled to dynamic code.  As in Prolog programming, for best
performance, dynamic object predicates and dynamic objects should only
be used when truly needed.


File: TheLogtalkHandbook-3.96.0.info,  Node: How about message-sending performance? Does Logtalk use static binding or dynamic binding?,  Next: Which Prolog-dependent factors are most crucial for good Logtalk performance?,  Prev: What kind of code Logtalk generates when compiling objects? Dynamic code? Static code?,  Up: Performance<3>

4.9.3 How about message-sending performance? Does Logtalk use static binding or dynamic binding?
------------------------------------------------------------------------------------------------

Logtalk supports both static binding and dynamic binding.  When static
binding is not possible, Logtalk uses dynamic binding coupled with a
caching mechanism that avoids repeated lookups of predicate declarations
and predicate definitions.  This is a solution common to other
programming languages supporting dynamic binding.  Message lookups are
automatically cached the first time a message is sent.  Cache entries
are automatically removed when loading entities or using Logtalk dynamic
features that invalidate the cached lookups.  Whenever static binding is
used, message-sending performance is essentially the same as a predicate
call in plain Prolog.  Performance of dynamic binding when lookups are
cached is close to the performance that would be achieved with static
binding.  See the User Manual section on *note performance: 38. for more
details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Which Prolog-dependent factors are most crucial for good Logtalk performance?,  Next: How does Logtalk performance compare with plain Prolog and with Prolog modules?,  Prev: How about message-sending performance? Does Logtalk use static binding or dynamic binding?,  Up: Performance<3>

4.9.4 Which Prolog-dependent factors are most crucial for good Logtalk performance?
-----------------------------------------------------------------------------------

Logtalk compiles objects assuming first-argument indexing for static
code.  First-argument indexing of dynamic code, when available, helps to
improve performance due to the automatic caching of method lookups and
the necessary use of book-keeping tables by the runtime engine (this is
specially important when using event-driven programming).  Dynamic
objects and static objects containing dynamic predicates also benefit
from first-argument indexing of dynamic predicates.  The availability of
multi-argument indexing, notably for dynamic predicates, also benefits
dynamic binding performance.


File: TheLogtalkHandbook-3.96.0.info,  Node: How does Logtalk performance compare with plain Prolog and with Prolog modules?,  Prev: Which Prolog-dependent factors are most crucial for good Logtalk performance?,  Up: Performance<3>

4.9.5 How does Logtalk performance compare with plain Prolog and with Prolog modules?
-------------------------------------------------------------------------------------

Plain Prolog, Prolog modules, and Logtalk objects provide different
trade-offs between performance and features.  In general, for a given
predicate definition, the best performance will be attained using plain
Prolog, second will be Prolog modules (assuming no explicitly qualified
calls are used), and finally Logtalk objects.  Whenever static binding
is used, the performance of Logtalk is equal or close to that of plain
Prolog (depending on the Prolog virtual machine implementation and
compiler optimizations).  See the simple benchmark test results(1) using
some popular Prolog compilers.

   ---------- Footnotes ----------

   (1) https://logtalk.org/performance.html


File: TheLogtalkHandbook-3.96.0.info,  Node: Licensing,  Next: Support,  Prev: Performance<3>,  Up: FAQ

4.10 Licensing
==============

   * *note What’s the Logtalk distribution license?: 8ab.

   * *note Can Logtalk be used in commercial applications?: 8ac.

   * *note What’s the final license for a combination of Logtalk with a
     Prolog compiler?: 8ad.

* Menu:

* What’s the Logtalk distribution license?::
* Can Logtalk be used in commercial applications?::
* What’s the final license for a combination of Logtalk with a Prolog compiler?::


File: TheLogtalkHandbook-3.96.0.info,  Node: What’s the Logtalk distribution license?,  Next: Can Logtalk be used in commercial applications?,  Up: Licensing

4.10.1 What’s the Logtalk distribution license?
-----------------------------------------------

Logtalk follows the Apache License 2.0(1).

   ---------- Footnotes ----------

   (1) https://github.com/LogtalkDotOrg/logtalk3/blob/master/LICENSE.txt


File: TheLogtalkHandbook-3.96.0.info,  Node: Can Logtalk be used in commercial applications?,  Next: What’s the final license for a combination of Logtalk with a Prolog compiler?,  Prev: What’s the Logtalk distribution license?,  Up: Licensing

4.10.2 Can Logtalk be used in commercial applications?
------------------------------------------------------

Yes, the Apache License 2.0 allows commercial use.  See e.g.  the Apache
License and Distribution FAQ(1).

   ---------- Footnotes ----------

   (1) https://www.apache.org/foundation/license-faq.html


File: TheLogtalkHandbook-3.96.0.info,  Node: What’s the final license for a combination of Logtalk with a Prolog compiler?,  Prev: Can Logtalk be used in commercial applications?,  Up: Licensing

4.10.3 What’s the final license for a combination of Logtalk with a Prolog compiler?
------------------------------------------------------------------------------------

See the licensing guide(1) for details and relevant resources.

   ---------- Footnotes ----------

   (1) https://logtalk.org/licensing.html


File: TheLogtalkHandbook-3.96.0.info,  Node: Support,  Prev: Licensing,  Up: FAQ

4.11 Support
============

   * *note Are there professional consulting, training and supporting
     services?: 8b4.

* Menu:

* Are there professional consulting, training and supporting services?: Are there professional consulting training and supporting services?.


File: TheLogtalkHandbook-3.96.0.info,  Node: Are there professional consulting training and supporting services?,  Up: Support

4.11.1 Are there professional consulting, training and supporting services?
---------------------------------------------------------------------------

Yes.  Please visit logtalk.pt(1) for professional consulting,
development, training, and other support services.

   ---------- Footnotes ----------

   (1) https://logtalk.org


File: TheLogtalkHandbook-3.96.0.info,  Node: Developer Tools,  Next: Libraries,  Prev: FAQ,  Up: Top

5 Developer Tools
*****************

The documentation of each developer tool can also be found in the tool
directory in the ‘NOTES.md’ file.

* Menu:

* Overview::
* asdf::
* assertions::
* code_metrics::
* dead_code_scanner::
* debug_messages::
* debugger::
* diagrams::
* doclet::
* help::
* issue_creator::
* lgtdoc::
* lgtunit::
* linter::
* make::
* packs::
* ports_profiler::
* profiler::
* tutor::
* wrapper::


File: TheLogtalkHandbook-3.96.0.info,  Node: Overview,  Next: asdf,  Up: Developer Tools

5.1 Overview
============

The following developer tools are available, each one with its own
‘loader.lgt’ loader file (except for the built-in ‘linter’ and ‘make’
tools, which are integrated with the compiler/runtime) and ‘NOTES.md’
documentation files:

   - ‘asdf’

   - ‘assertions’

   - ‘code_metrics’

   - ‘dead_code_scanner’

   - ‘debug_messages’

   - ‘debugger’

   - ‘diagrams’

   - ‘doclet’

   - ‘help’

   - ‘issue_creator’

   - ‘lgtdoc’

   - ‘lgtunit’

   - ‘linter’

   - ‘make’

   - ‘packs’

   - ‘ports_profiler’

   - ‘profiler’

   - ‘tutor’

   - ‘wrapper’

* Menu:

* Loading the developer tools::
* Tools documentation::
* Tools common flags::
* Tools requirements::


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading the developer tools,  Next: Tools documentation,  Up: Overview

5.1.1 Loading the developer tools
---------------------------------

To load the main developer tools, use the following goal:

     | ?- logtalk_load(tools(loader)).

The ‘ports_profiler’ tool is not loaded by default; however, as it
conflicts with the ‘debugger’ tool as both provide a debug handler that
must be unique in a running session.

The ‘profiler’ tool is also not loaded by default, as it provides
integration with selected backend Prolog compiler profilers that are not
portable.

The ‘tutor’ tool is also not loaded by default, given its usefulness
mainly for new users that need help understanding compiler warning and
error messages.

The ‘wrapper’ tool is also not loaded by default, given its specialized
purpose and beta status.

To load a specific tool, either change your Prolog working directory to
the tool folder and then compile and load the corresponding loader
utility file or simply use library notation as argument for the
compiling and loading predicates.  For example:

     | ?- logtalk_load(lgtunit(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Tools documentation,  Next: Tools common flags,  Prev: Loading the developer tools,  Up: Overview

5.1.2 Tools documentation
-------------------------

Specific notes about each tool can be found in the corresponding
‘NOTES.md’ files.  HTML documentation for each tool API can be found in
the ‘docs’ directory (open the ‘../docs/handbook/index.html’ file with
your web browser).


File: TheLogtalkHandbook-3.96.0.info,  Node: Tools common flags,  Next: Tools requirements,  Prev: Tools documentation,  Up: Overview

5.1.3 Tools common flags
------------------------

The ‘lgtdoc’, ‘lgtunit’, and ‘issue_creator’ tools share a
‘suppress_path_prefix’ flag that can be used to suppress a prefix when
printing file paths.  For example (after loading the tools):

     | ?- set_logtalk_flag(suppress_path_prefix, '/home/jdoe/').

This flag is mainly used to avoid user specific path prefixes appearing
in documentation, test logs, and bug reports.


File: TheLogtalkHandbook-3.96.0.info,  Node: Tools requirements,  Prev: Tools common flags,  Up: Overview

5.1.4 Tools requirements
------------------------

Some of the developer tools have third-party dependencies.  For example,
the ‘lgtdoc’ tool depends on XSLT processors to generate documentation
final formats and uses Sphinx for the preferred HTML final format.  Be
sure to consult the tools documentation details on those requirements
and possible alternatives.  For convenience, follows a global list of
the main tool requirements and suggestions for installing them per
operating-system.  If your operating-system or a dependency for it is
not listed, see the dependency websites for installation instructions.

* Menu:

* Tool dependencies for full functionality::
* Python dependencies (all operating-systems): Python dependencies all operating-systems.
* macOS - MacPorts::
* macOS - Homebrew::
* Ubuntu::
* RedHat::
* Windows - Chocolatey::
* Installers::
* Windows - PowerShell add-ons::


File: TheLogtalkHandbook-3.96.0.info,  Node: Tool dependencies for full functionality,  Next: Python dependencies all operating-systems,  Up: Tools requirements

5.1.4.1 Tool dependencies for full functionality
................................................

   - ‘diagrams’: d2, Graphviz

   - ‘help’: ‘info’

   - ‘issue_creator’: ‘gh’, ‘glab’

   - ‘lgtdoc’: Sphinx, ‘libxslt’, ‘fop’, ‘texlive’, ‘texinfo’, ‘pandoc’,
     ‘xsltproc’

   - ‘lgtunit’: Allure, ‘coreutils’, ‘gsed’

   - ‘packs’: ‘coreutils’, ‘libarchive’, ‘gnupg2’, ‘git’, ‘curl’,
     ‘wget’, ‘direnv’


File: TheLogtalkHandbook-3.96.0.info,  Node: Python dependencies all operating-systems,  Next: macOS - MacPorts,  Prev: Tool dependencies for full functionality,  Up: Tools requirements

5.1.4.2 Python dependencies (all operating-systems)
...................................................

     $ pip install --upgrade pygments
     $ pip install --upgrade sphinx
     $ pip install --upgrade sphinx_rtd_theme

In alternative, if your want to use the same versions used to build
release documentation:

     $ cd manuals/sources
     $ python3 -m pip install -r requirements.txt


File: TheLogtalkHandbook-3.96.0.info,  Node: macOS - MacPorts,  Next: macOS - Homebrew,  Prev: Python dependencies all operating-systems,  Up: Tools requirements

5.1.4.3 macOS - MacPorts
........................

     $ sudo port install d2 graphviz
     $ sudo port install texinfo pandoc
     $ sudo port install libxslt fop texlive
     $ sudo port install gsed
     $ sudo port install coreutils gsed libarchive gnupg2 git curl wget direnv
     $ sudo port install gh glab


File: TheLogtalkHandbook-3.96.0.info,  Node: macOS - Homebrew,  Next: Ubuntu,  Prev: macOS - MacPorts,  Up: Tools requirements

5.1.4.4 macOS - Homebrew
........................

     $ brew install d2 graphviz
     $ brew install texinfo pandoc
     $ brew install libxslt fop texlive
     $ brew install allure gsed
     $ brew install coreutils libarchive gnupg2 git curl wget direnv
     $ brew install gh glab


File: TheLogtalkHandbook-3.96.0.info,  Node: Ubuntu,  Next: RedHat,  Prev: macOS - Homebrew,  Up: Tools requirements

5.1.4.5 Ubuntu
..............

     $ sudo apt install graphviz
     $ sudo apt install texinfo pandoc
     $ sudo apt install xsltproc fop texlive-latex-extra tex-gyre latexmk
     $ sudo apt install coreutils libarchive-tools gnupg2 git curl wget direnv
     $ sudo apt install gh


File: TheLogtalkHandbook-3.96.0.info,  Node: RedHat,  Next: Windows - Chocolatey,  Prev: Ubuntu,  Up: Tools requirements

5.1.4.6 RedHat
..............

     $ sudo dnf install graphviz
     $ sudo dnf install texinfo pandoc
     $ sudo dnf install libxslt fop
     $ sudo dnf install bsdtar gnupg2 git curl wget direnv


File: TheLogtalkHandbook-3.96.0.info,  Node: Windows - Chocolatey,  Next: Installers,  Prev: RedHat,  Up: Tools requirements

5.1.4.7 Windows - Chocolatey
............................

     > choco install pandoc xsltproc
     > choco install d2 graphviz
     > choco install xsltproc apache-fop texlive
     > choco install gnupg git
     > choco install gh glab
     > choco install wget
     > choco install sed


File: TheLogtalkHandbook-3.96.0.info,  Node: Installers,  Next: Windows - PowerShell add-ons,  Prev: Windows - Chocolatey,  Up: Tools requirements

5.1.4.8 Installers
..................

   - ‘https://d2lang.com/tour/install’

   - ‘https://www.graphviz.org/download/’

   - ‘https://allurereport.org/docs/’

   - ‘https://www.gnupg.org/’

   - ‘https://gitforwindows.org’

   - ‘https://cli.github.com’

   - ‘https://glab.readthedocs.io’

   - ‘https://eternallybored.org/misc/wget/’


File: TheLogtalkHandbook-3.96.0.info,  Node: Windows - PowerShell add-ons,  Prev: Installers,  Up: Tools requirements

5.1.4.9 Windows - PowerShell add-ons
....................................

     PS> Install-Module -Name Set-PsEnv


File: TheLogtalkHandbook-3.96.0.info,  Node: asdf,  Next: assertions,  Prev: Overview,  Up: Developer Tools

5.2 ‘asdf’
==========

A Logtalk plugin for the asdf(1) extendable version manager is available
at:

‘https://github.com/LogtalkDotOrg/asdf-logtalk’

This plugin provides an alternative to the ‘logtalk_version_select’
script that can be useful to manage Logtalk versions when developing
solutions that use other languages and tools that can also be handled by
‘asdf’.

   ---------- Footnotes ----------

   (1) https://asdf-vm.com


File: TheLogtalkHandbook-3.96.0.info,  Node: assertions,  Next: code_metrics,  Prev: asdf,  Up: Developer Tools

5.3 ‘assertions’
================

The ‘assertions.lgt’ file contains definitions for two meta-predicates,
‘assertion/1-2’, which allows the use of assertions on your source code
to print warning and error messages (using the message printing
mechanism).  The ‘assertions_messages.lgt’ file defines the default
message translations generated when assertions succeed, fail, or throw
an exception.

* Menu:

* API documentation::
* Loading::
* Testing::
* Adding assertions to your source code::
* Automatically adding file and line context information to assertions::
* Suppressing assertion calls from source code::
* Redirecting assertion failure messages::
* Converting assertion failures into errors::


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation,  Next: Loading,  Up: assertions

5.3.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#assertions’


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading,  Next: Testing,  Prev: API documentation,  Up: assertions

5.3.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(assertions(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing,  Next: Adding assertions to your source code,  Prev: Loading,  Up: assertions

5.3.3 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(assertions(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Adding assertions to your source code,  Next: Automatically adding file and line context information to assertions,  Prev: Testing,  Up: assertions

5.3.4 Adding assertions to your source code
-------------------------------------------

The ‘assertion/1’ predicate takes a goal as argument.  For example:

     foo(L) :-
         assertions::assertion(non_empty_list(L)),
         ...

The ‘assertion/2’ predicate takes as arguments a term for passing
context information and a goal.  Using again a unit test as an example:

     foo(L) :-
         assertions::assertion(foo_list_alerts, non_empty_list(L)),
         ...

When using a large number of assertions, you can use a lighter syntax by
adding a ‘uses/2’ directive.  For example:

     :- uses(assertions, [assertion/1, assertion/2]).


File: TheLogtalkHandbook-3.96.0.info,  Node: Automatically adding file and line context information to assertions,  Next: Suppressing assertion calls from source code,  Prev: Adding assertions to your source code,  Up: assertions

5.3.5 Automatically adding file and line context information to assertions
--------------------------------------------------------------------------

The ‘assertions/1’ parametric object can be used as a hook object to
automatically add file and line context information, represented by the
term ‘file_lines(File, BeginLine-EndLine)’, to calls to the
‘assertion/1’ predicate by goal-expanding it to calls to the
‘assertion/2’ predicate (the expansion assumes that a ‘uses/2’ directive
is being used in the code that will be expanded to direct ‘assertion/1’
calls to the ‘assertions’ object).  For example, assuming the file using
assertions is named ‘source’, it would be compiled and loaded using the
call:

     logtalk_load(source, [hook(assertions(debug))])


File: TheLogtalkHandbook-3.96.0.info,  Node: Suppressing assertion calls from source code,  Next: Redirecting assertion failure messages,  Prev: Automatically adding file and line context information to assertions,  Up: assertions

5.3.6 Suppressing assertion calls from source code
--------------------------------------------------

The ‘assertions/1’ parametric object can be used as a hook object to
suppress calls to the ‘assertion/1-2’ predicates using goal-expansion
(the expansion assumes ‘assertions::assertion/1-2’ messages).  For
example, assuming the file using assertions is named ‘source’, it would
be compiled and loaded using the call:

     logtalk_load(source, [hook(assertions(production))])


File: TheLogtalkHandbook-3.96.0.info,  Node: Redirecting assertion failure messages,  Next: Converting assertion failures into errors,  Prev: Suppressing assertion calls from source code,  Up: assertions

5.3.7 Redirecting assertion failure messages
--------------------------------------------

By default, assertion failures and errors are printed to the standard
output stream.  These messages, however, can be intercepted by defining
the ‘logtalk::message_hook/4’ multifile predicate.  For example:

     :- category(redirect_assertions_messages).

         :- multifile(logtalk::message_hook/4).
         :- dynamic(logtalk::message_hook/4).

         logtalk::message_hook(Message, error, assertions, _) :-
             writeq(my_log_file, Message), write(my_log_file, '.\n').

     :- end_category.


File: TheLogtalkHandbook-3.96.0.info,  Node: Converting assertion failures into errors,  Prev: Redirecting assertion failure messages,  Up: assertions

5.3.8 Converting assertion failures into errors
-----------------------------------------------

If you want an assertion failure to result in a failure or a runtime
error, you can intercept the assertion failure messages, optionally
still printing them, and throw an error.  For example:

     :- category(assertions_failures_to_errors).

         :- multifile(logtalk::message_hook/4).
         :- dynamic(logtalk::message_hook/4).

         logtalk::message_hook(Message, error, assertions, Tokens) :-
             % uncomment the next two lines to also print the default message
             % logtalk::message_prefix_stream(error, assertions, Prefix, Stream),
             % logtalk::print_message_tokens(Stream, Prefix, Tokens),
             throw(error(Message, _)).

     :- end_category.

In alternative, if you want assertions to always trigger an exception,
use instead the ‘lgtunit’ tool ‘assertions/1-2’ public predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: code_metrics,  Next: dead_code_scanner,  Prev: assertions,  Up: Developer Tools

5.4 ‘code_metrics’
==================

The purpose of this tool is to assess qualities of source code that may
predict negative aspects such as entity coupling, cohesion, complexity,
error-proneness, and overall maintainability.  It is meant to be
extensible via the addition of objects implementing new metrics.

This tool provides predicates for computing metrics for source files,
entities, libraries, files, and directories.  The actual availability of
a particular predicate depends on the specific metric.  A set of
predicates prints, by default, the computed metric values to the
standard output.  A second set of predicates computes and returns a
score (usually a compound term with the computed metric values as
arguments).

* Menu:

* API documentation: API documentation<2>.
* Loading: Loading<2>.
* Testing: Testing<2>.
* Available metrics::
* Coupling metrics::
* Halstead metric::
* UPN metric::
* Cyclomatic complexity metric::
* Usage::
* Excluding code from analysis::
* Defining new metrics::
* Third-party tools::
* Applying metrics to Prolog modules::
* Applying metrics to plain Prolog code::


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<2>,  Next: Loading<2>,  Up: code_metrics

5.4.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#code-metrics’


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<2>,  Next: Testing<2>,  Prev: API documentation<2>,  Up: code_metrics

5.4.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(code_metrics(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<2>,  Next: Available metrics,  Prev: Loading<2>,  Up: code_metrics

5.4.3 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(code_metrics(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Available metrics,  Next: Coupling metrics,  Prev: Testing<2>,  Up: code_metrics

5.4.4 Available metrics
-----------------------

Currently, the following metrics are provided:

   - Number of Clauses (‘noc_metric’)

   - Number of Rules (‘nor_metric’)

   - Unique Predicate Nodes (‘upn_metric’)

   - Cyclomatic Complexity (‘cc_metric’)

   - Depth of Inheritance (‘dit_metric’)

   - Efferent coupling, afferent coupling, instability, and abstractness
     (‘coupling_metric’)

   - Documentation (‘doc_metric’)

   - Source code size (‘size_metric’)

   - Halstead complexity (‘halstead_metric’ and
     ‘halstead_metric(Stroud)’)

A helper object, ‘code_metrics’, is also provided, allowing running all
loaded individual metrics.  For code coverage metrics, see the ‘lgtunit’
tool documentation.


File: TheLogtalkHandbook-3.96.0.info,  Node: Coupling metrics,  Next: Halstead metric,  Prev: Available metrics,  Up: code_metrics

5.4.5 Coupling metrics
----------------------

   - Efferent coupling (‘Ce’): Number of entities that an entity depends
     on.  These include objects receiving messages from the entity, plus
     the implemented protocols, imported categories, and
     extended/instantiated/specialized objects.

   - Afferent coupling (‘Ca’): Number of entities that depend on an
     entity.  For a protocol, the number of protocols that extend it,
     plus the number of objects and categories that implement it.  For a
     category, the number of objects that import it.  For an object, the
     number of categories and objects that send messages to it plus the
     number of objects that extend/instantiate/specialize it.

   - Instability: Computed as ‘Ce / (Ce + Ca)’.  Measures an entity
     resilience to change.  Ranging from 0.0 to 1.0, with 0.0 indicating
     a maximally stable entity and 1.0 indicating a maximally unstable
     entity.  Ideally, an entity is either maximally stable or maximally
     unstable.

   - Abstractness: Computed as the ratio between the number of static
     predicates with scope directives without a local definition and the
     number of static predicates with scope directives.  Measures the
     rigidity of an entity.  Ranging from 0.0 to 1.0, with 0.0
     indicating a fully concrete entity and 1.0 indicating a fully
     abstract entity.

The dependencies count includes direct entity relations plus predicate
calls or dynamic updates to predicates in external objects or
categories.

For more information on the interpretation of the coupling metric
scores, see, e.g., the original paper by Robert Martin:

     @inproceedings{citeulike:1579528,
         author = "Martin, Robert",
         booktitle = "Workshop Pragmatic and Theoretical Directions in Object-Oriented Software Metrics",
         citeulike-article-id = 1579528,
         citeulike-linkout-0 = "http://www.objectmentor.com/resources/articles/oodmetrc.pdf",
         keywords = "diplomarbeit",
         organization = "OOPSLA'94",
         posted-at = "2007-08-21 11:08:44",
         priority = 0,
         title = "OO Design Quality Metrics - An Analysis of Dependencies",
         url = "http://www.objectmentor.com/resources/articles/oodmetrc.pdf",
         year = 1994
     }

The coupling metric was also influenced by the metrics rating system in
Microsoft Visual Studio and aims to eventually emulate the functionality
of a maintainability index score.


File: TheLogtalkHandbook-3.96.0.info,  Node: Halstead metric,  Next: UPN metric,  Prev: Coupling metrics,  Up: code_metrics

5.4.6 Halstead metric
---------------------

Predicates declared, user-defined, and called are interpreted as
'operators'.  Built-in predicates and built-in control constructs are
ignored.  Predicate arguments are abstracted, assumed distinct, and
interpreted as 'operands'.  Note that this definition of operands is a
significant deviation from the original definition, which used syntactic
literals.  A computation closer to the original definition of the metric
would require switching to use the parser to collect information on
syntactic literals, which would imply a much larger computation cost.
The number of predicate calls doesn’t include calls to built-in
predicates and can underestimate recursive calls.

The computation of this metric is parameterized by the 'Stroud'
coefficient for computing the time required to program (default is 18).
The following individual measures are computed:

   - Number of distinct predicates (declared, defined, called, or
     updated; ‘Pn’).

   - Number of predicate arguments (assumed distinct; ‘PAn’).

   - Number of predicate calls/updates + number of clauses (‘Cn’).

   - Number of predicate call/update arguments + number of clause head
     arguments (‘CAn’).

   - Entity vocabulary (‘EV’).  Computed as ‘EV = Pn + PAn’.

   - Entity length (‘EL’).  Computed as ‘EL = Cn + CAn’.

   - Volume (‘V’).  Computed as ‘V = EL * log2(EV)’.

   - Difficulty (‘D’).  Computed as ‘D = (Pn/2) * (CAn/An)’.

   - Effort (‘E’).  Computed as ‘E = D * V’.

   - Time required to program (‘T’).  Computed as ‘T = E/k’ seconds
     (where ‘k’ is the Stroud number; defaults to 18).

   - Number of delivered bugs (‘B’).  Computed as ‘B = V/3000’.


File: TheLogtalkHandbook-3.96.0.info,  Node: UPN metric,  Next: Cyclomatic complexity metric,  Prev: Halstead metric,  Up: code_metrics

5.4.7 UPN metric
----------------

The Unique Predicate Nodes (UPN) metric is described in the following
paper:

     @article{MOORES199845,
         title = "Applying Complexity Measures to Rule-Based Prolog Programs",
         journal = "Journal of Systems and Software",
         volume = "44",
         number = "1",
         pages = "45 - 52",
         year = "1998",
         issn = "0164-1212",
         doi = "https://doi.org/10.1016/S0164-1212(98)10042-0",
         url = "http://www.sciencedirect.com/science/article/pii/S0164121298100420",
         author = "Trevor T Moores"
     }

The nodes include called and updated predicates independently of where
they are defined.  It also includes multifile predicates contributed to
other entities.


File: TheLogtalkHandbook-3.96.0.info,  Node: Cyclomatic complexity metric,  Next: Usage,  Prev: UPN metric,  Up: code_metrics

5.4.8 Cyclomatic complexity metric
----------------------------------

The cyclomatic complexity metric evaluates an entity code complexity by
measuring the number of linearly independent paths through the code.  In
its current implementation, all defined predicates that are not called
or updated are counted as graph-connected components (the reasoning
being that these predicates can be considered entry points).  The
implementation uses the same predicate abstraction as the UPN metric.
The defined predicates include multifile predicate definitions
contributed by the entity to other entities.

For more details on this metric, see the original paper by Thomas J.
McCabe:

     @inproceedings{McCabe:1976:CM:800253.807712,
         author = "McCabe, Thomas J.",
         title = "A Complexity Measure",
         booktitle = "Proceedings of the 2Nd International Conference on Software Engineering",
         series = "ICSE '76",
         year = 1976,
         location = "San Francisco, California, USA",
         pages = "407--",
         url = "http://dl.acm.org/citation.cfm?id=800253.807712",
         acmid = 807712,
         publisher = "IEEE Computer Society Press",
         address = "Los Alamitos, CA, USA",
         keywords = "Basis, Complexity measure, Control flow, Decomposition, Graph theory, Independence, Linear, Modularization, Programming, Reduction, Software, Testing",
     }


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage,  Next: Excluding code from analysis,  Prev: Cyclomatic complexity metric,  Up: code_metrics

5.4.9 Usage
-----------

All metrics require the source code to be analyzed to be loaded with the
‘source_data’ flag turned on.  For usage examples, see the ‘SCRIPT.txt’
file in the tool directory.

Be sure to fully understand the metrics individual meanings and any
implementation limitations before using them to support any evaluation
or decision process.


File: TheLogtalkHandbook-3.96.0.info,  Node: Excluding code from analysis,  Next: Defining new metrics,  Prev: Usage,  Up: code_metrics

5.4.10 Excluding code from analysis
-----------------------------------

A set of options is available to specify code that should be excluded
when applying code metrics:

   - 
          ‘exclude_directories(Directories)’
          list of directories to exclude (default is ‘[]’); all sub-directories of the excluded directories are also excluded; directories may be listed by full or relative path

   - 
          ‘exclude_files(Files)’
          list of source files to exclude (default is ‘[]’); files may be listed by full path or basename, with or without extension

   - 
          ‘exclude_libraries(Libraries)’
          list of libraries to exclude (default is ‘[startup, scratch_directory]’)

   - 
          ‘exclude_entities(Entities)’
          list of entities to exclude (default is ‘[]’)


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining new metrics,  Next: Third-party tools,  Prev: Excluding code from analysis,  Up: code_metrics

5.4.11 Defining new metrics
---------------------------

New metrics can be implemented by defining an object that imports the
‘code_metric’ category and implements its score predicates.  There is
also a ‘code_metrics_utilities’ category that defines useful predicates
for the definition of metrics.


File: TheLogtalkHandbook-3.96.0.info,  Node: Third-party tools,  Next: Applying metrics to Prolog modules,  Prev: Defining new metrics,  Up: code_metrics

5.4.12 Third-party tools
------------------------

The following open-source command-line programs can count blank lines,
comment lines, and lines of source code in many programming languages,
including Logtalk:

   - ‘cloc’ - ‘https://github.com/AlDanial/cloc’

   - ‘ohcount’ - ‘https://github.com/blackducksoftware/ohcount’

   - ‘tokei’ - ‘https://github.com/XAMPPRocky/tokei’


File: TheLogtalkHandbook-3.96.0.info,  Node: Applying metrics to Prolog modules,  Next: Applying metrics to plain Prolog code,  Prev: Third-party tools,  Up: code_metrics

5.4.13 Applying metrics to Prolog modules
-----------------------------------------

Some of the metrics can also be applied to Prolog modules that Logtalk
is able to compile as objects.  For example, if the Prolog module file
is named ‘module.pl’, try:

     | ?- logtalk_load(module, [source_data(on)]).

Due to the lack of standardization of module systems and the abundance
of proprietary extensions, this solution is not expected to work for all
cases.


File: TheLogtalkHandbook-3.96.0.info,  Node: Applying metrics to plain Prolog code,  Prev: Applying metrics to Prolog modules,  Up: code_metrics

5.4.14 Applying metrics to plain Prolog code
--------------------------------------------

Some of the metrics can also be applied to plain Prolog code.  For
example, if the Prolog file is named ‘code.pl’, simply define an object
including its code:

     :- object(code).
         :- include('code.pl').
     :- end_object.

Save the object to an e.g.  ‘code.lgt’ file in the same directory as the
Prolog file and then load it in debug mode:

     | ?- logtalk_load(code, [source_data(on)]).

In alternative, use the ‘object_wrapper_hook’ provided by the
‘hook_objects’ library:

     | ?- logtalk_load(hook_objects(loader)).
     ...

     | ?- logtalk_load(code, [hook(object_wrapper_hook), source_data(on)]).

With either wrapping solution, pay special attention to any compilation
warnings that may signal issues that could prevent the plain Prolog code
from working when wrapped by an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: dead_code_scanner,  Next: debug_messages,  Prev: code_metrics,  Up: Developer Tools

5.5 ‘dead_code_scanner’
=======================

This tool detects 'likely' dead code in Logtalk entities and in Prolog
modules compiled as objects.  Predicates (and non-terminals) are
classified as dead code when:

   - There is no scope directive for them, and they are not called,
     directly or indirectly, by any predicate with a (local or
     inherited) scope directive.

   - They are listed in ‘uses/2’ and ‘use_module/2’ directives but not
     called.

Besides dead code, this tool can also help detect other problems in the
code that often result in reporting false positives.  For example, typos
in ‘alias/2’ directives, missing scope directives, and missing
‘meta_non_terminal/1’ and ‘meta_predicate/1’ directives.

Given the possibility of false positives, care must be taken before
deleting reported dead code to ensure that it’s, in fact, code that is
not used.  A common cause of false positives is the use of conditional
compilation directives to provide implementations for predicates missing
in some systems or different predicate implementations per
operating-system.

The ‘dead_code_scanner.lgt’ source file implements the scanning
predicates for finding dead code in entities, libraries, and
directories.  The source file ‘dead_code_scanner_messages.lgt’ defines
the default translations for the messages printed when scanning for dead
code.  These messages can be intercepted to customize the output, e.g.,
to make it less verbose or for integration with, e.g., GUI IDEs and
continuous integration servers.

* Menu:

* API documentation: API documentation<3>.
* Loading: Loading<3>.
* Testing: Testing<3>.
* Usage: Usage<2>.
* Excluding code from analysis: Excluding code from analysis<2>.
* Integration with the make tool::
* Caveats::
* Scanning Prolog modules::
* Scanning plain Prolog files::


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<3>,  Next: Loading<3>,  Up: dead_code_scanner

5.5.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#dead-code-scanner’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<3>,  Next: Testing<3>,  Prev: API documentation<3>,  Up: dead_code_scanner

5.5.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(dead_code_scanner(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<3>,  Next: Usage<2>,  Prev: Loading<3>,  Up: dead_code_scanner

5.5.3 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(dead_code_scanner(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<2>,  Next: Excluding code from analysis<2>,  Prev: Testing<3>,  Up: dead_code_scanner

5.5.4 Usage
-----------

This tool provides a set of predicates that allows scanning entities,
libraries, files, and directories.  See the tool API documentation for
details.  The source code to be analyzed should be loaded with the
‘source_data’ and ‘optimize’ flags turned on (possibly set from a loader
file).

As an example, assume that we want to scan an application with a library
alias ‘my_app’.  The following goals could be used:

     | ?- set_logtalk_flag(source_data, on),
          set_logtalk_flag(optimize, on).
     yes

     | ?- logtalk_load(my_app(loader)).
     ...
     yes

     | ?- dead_code_scanner::library(my_app).
     ...

For complex applications that make use of sub-libraries, there are also
‘rlibrary/1-2’ predicates that perform a recursive scan of a library and
all its sub-libraries.  Conversely, we may be interested in scanning a
single entity:

     | ?- dead_code_scanner::entity(some_object).
     ...

For other usage examples, see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.96.0.info,  Node: Excluding code from analysis<2>,  Next: Integration with the make tool,  Prev: Usage<2>,  Up: dead_code_scanner

5.5.5 Excluding code from analysis
----------------------------------

A set of options is available to specify code that should be excluded
when looking for unused predicates (and non-terminals):

   - 
          ‘exclude_directories(Directories)’
          list of directories to exclude (default is ‘[]’); all sub-directories of the excluded directories are also excluded; directories may be listed by full or relative path

   - 
          ‘exclude_files(Files)’
          list of source files to exclude (default is ‘[]’); files may be listed by full path or basename, with or without extension

   - 
          ‘exclude_libraries(Libraries)’
          list of libraries to exclude (default is ‘[startup, scratch_directory]’)

   - 
          ‘exclude_entities(Entities)’
          list of entities to exclude (default is ‘[]’)


File: TheLogtalkHandbook-3.96.0.info,  Node: Integration with the make tool,  Next: Caveats,  Prev: Excluding code from analysis<2>,  Up: dead_code_scanner

5.5.6 Integration with the ‘make’ tool
--------------------------------------

The ‘loader.lgt’ file sets a make target action that will call the
‘dead_code_scanner::all’ goal whenever the ‘logtalk_make(check)’ goal
(or its top-level abbreviation, ‘{?}’) is called.


File: TheLogtalkHandbook-3.96.0.info,  Node: Caveats,  Next: Scanning Prolog modules,  Prev: Integration with the make tool,  Up: dead_code_scanner

5.5.7 Caveats
-------------

Use of local meta-calls with goal arguments only known at runtime can
result in false positives.  When using library or user-defined
meta-predicates, compilation of the source files with the ‘optimize’
flag turned on may allow meta-calls to be resolved at compile-time and
thus allow calling information for the meta-arguments to be recorded,
avoiding false positives for predicates that are only meta-called.


File: TheLogtalkHandbook-3.96.0.info,  Node: Scanning Prolog modules,  Next: Scanning plain Prolog files,  Prev: Caveats,  Up: dead_code_scanner

5.5.8 Scanning Prolog modules
-----------------------------

This tool can also be applied to Prolog modules that Logtalk is able to
compile as objects.  For example, if the Prolog module file is named
‘module.pl’, try:

     | ?- logtalk_load(module, [source_data(on)]).

Due to the lack of standardization of module systems and the abundance
of proprietary extensions, this solution is not expected to work for all
cases.


File: TheLogtalkHandbook-3.96.0.info,  Node: Scanning plain Prolog files,  Prev: Scanning Prolog modules,  Up: dead_code_scanner

5.5.9 Scanning plain Prolog files
---------------------------------

This tool can also be applied to plain Prolog code.  For example, if the
Prolog file is named ‘code.pl’, simply define an object including its
code:

     :- object(code).
         :- include('code.pl').
     :- end_object.

Save the object to an e.g.  ‘code.lgt’ file in the same directory as the
Prolog file and then load it in debug mode:

     | ?- logtalk_load(code, [source_data(on), optimize(on)]).

In alternative, use the ‘object_wrapper_hook’ provided by the
‘hook_objects’ library:

     | ?- logtalk_load(hook_objects(loader)).
     ...

     | ?- logtalk_load(code, [hook(object_wrapper_hook), source_data(on), optimize(on)]).

With either wrapping solution, pay special attention to any compilation
warnings that may signal issues that could prevent the plain Prolog from
being fully analyzed when wrapped by an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: debug_messages,  Next: debugger,  Prev: dead_code_scanner,  Up: Developer Tools

5.6 ‘debug_messages’
====================

By default, ‘debug’ and ‘debug(Group)’ messages are only printed when
the ‘debug’ flag is turned on.  These messages are also suppressed when
compiling code with the ‘optimize’ flag turned on.  This tool supports
selective enabling of ‘debug’ and ‘debug(Group)’ messages in normal and
debug modes.

* Menu:

* API documentation: API documentation<4>.
* Loading: Loading<4>.
* Testing: Testing<4>.
* Usage: Usage<3>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<4>,  Next: Loading<4>,  Up: debug_messages

5.6.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#debug-messages’

For general information on debugging, open in a web browser the
following link and consult the debugging section of the User Manual:

‘../../handbook/userman/debugging.html’


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<4>,  Next: Testing<4>,  Prev: API documentation<4>,  Up: debug_messages

5.6.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(debug_messages(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<4>,  Next: Usage<3>,  Prev: Loading<4>,  Up: debug_messages

5.6.3 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(debug_messages(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<3>,  Prev: Testing<4>,  Up: debug_messages

5.6.4 Usage
-----------

The tool provides two sets of predicates.  The first set allows enabling
and disabling of all ‘debug’ and ‘debug(Group)’ messages for a given
component.  The second set allows enabling and disabling of
‘debug(Group)’ messages for a given group and component for fine-grained
control.

Upon loading the tool, all debug messages are skipped.  The user is then
expected to use the tool API to selectively enable the messages that
will be printed.  As an example, consider the following object, part of
a ‘xyz’ component:

     :- object(foo).

         :- public([bar/0, baz/0]).
         :- uses(logtalk, [print_message/3]).

         bar :-
             print_message(debug(bar), xyz, @'bar/0 called').

         baz :-
             print_message(debug(baz), xyz, @'baz/0 called').

     :- end_object.

Assuming the object ‘foo’ is compiled and loaded in normal or debug
mode, after also loading this tool, ‘bar/0’ and ‘baz/0’ messages will
not print any debug messages:

     | ?- {debug_messages(loader), foo}.
     ...
     yes

     | ?- foo::(bar, baz).
     yes

We can then enable all debug messages for the ‘xyz’ component:

     | ?- debug_messages::enable(xyx).
     yes

     | ?- foo::(bar, baz).
     bar/0 called
     baz/0 called
     yes

Or we can selectively enable only debug messages for a specific group:

     | ?- debug_messages::disable(xyx).
     yes

     | ?- debug_messages::enable(xyx, bar).
     yes

     | ?- foo::(bar, baz).
     bar/0 called
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: debugger,  Next: diagrams,  Prev: debug_messages,  Up: Developer Tools

5.7 ‘debugger’
==============

This tool provides the default Logtalk command-line debugger.  Unlike
Prolog systems, the Logtalk debugger is a regular application, using a
public API. As a consequence, it must be explicitly loaded by the
programmer, either manually at the top-level interpreter or
automatically from a settings file.

* Menu:

* API documentation: API documentation<5>.
* Loading: Loading<5>.
* Testing: Testing<5>.
* Usage: Usage<4>.
* Alternative debugger tools::
* Known issues::


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<5>,  Next: Loading<5>,  Up: debugger

5.7.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#debugger’


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<5>,  Next: Testing<5>,  Prev: API documentation<5>,  Up: debugger

5.7.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(debugger(loader)).

When the code to be debugged runs computationally expensive
initializations, loading this tool after the code may have a noticeable
impact on loading times.


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<5>,  Next: Usage<4>,  Prev: Loading<5>,  Up: debugger

5.7.3 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(debugger(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<4>,  Next: Alternative debugger tools,  Prev: Testing<5>,  Up: debugger

5.7.4 Usage
-----------

Debugging Logtalk source code (with this debugger) requires compiling
source files using the ‘debug(on)’ compiler flag.  For example:

     | ?- logtalk_load(my_buggy_code, [debug(on)]).

In alternative, you may also turn on the ‘debug’ flag globally by
typing:

     | ?- set_logtalk_flag(debug, on).

But note that loader files may override this flag setting (e.g., by
using ‘debug(off)’ or ‘optimize(on)’ options for loaded files).  If
that’s the case, you will need to either edit the loader files or write
customized loader files enabling debugging.  For detailed information on
using the debugger, consult the debugging section of the User Manual:

‘../../handbook/userman/debugging.html’

The ‘debugger_messages.lgt’ source file defines the default debugger
message translations.

The ‘dump_trace.lgt’ provides a simple solution for dumping a goal trace
to a file.  For example:

     | ?- dump_trace::start_redirect_to_file('trace.txt', some_goal),
          dump_trace::stop_redirect_to_file.

A full trace can also be obtained at the top-level by using the ‘S’
(Skip) command at the call port for the top-level goal when tracing it.


File: TheLogtalkHandbook-3.96.0.info,  Node: Alternative debugger tools,  Next: Known issues,  Prev: Usage<4>,  Up: debugger

5.7.5 Alternative debugger tools
--------------------------------

Logtalk provides basic support for the SWI-Prolog graphical tracer.  The
'required' settings are described in the ‘samples/settings-sample.lgt’
file.  Logtalk queries can be traced using this tool by using the
‘gtrace/0-1’ predicates.  For example:

     | ?- gtrace(foo::bar).

Or alternatively:

     | ?- gtrace, foo::bar.

You can also use the ‘gspy/1’ predicate to spy on a Logtalk predicate
specified as ‘Entity::Functor/Arity’ when using the graphical tracer.
When using this tool, internal Logtalk compiler/runtime predicates and
compiled predicates that resulted from the term-expansion mechanism may
be exposed in some cases.  This issue is shared with Prolog code and
results from the non-availability of source code for the predicates
being traced.


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues,  Prev: Alternative debugger tools,  Up: debugger

5.7.6 Known issues
------------------

Clause breakpoints require a Prolog backend compiler that supports
accessing read term starting line but only some backends (B-Prolog, GNU
Prolog, JIProlog, SICStus Prolog, SWI-Prolog, Trealla Prolog, XVM, and
YAP) provide accurate line numbers.  As a workaround, you can check the
start line number for an entity predicate definition using a query such
as:

     | ?- object_property(Entity, defines(Functor/Arity, Properties)).

Check the returned ‘line_count/1’ property to find if there’s any offset
to the source file number of the predicate clause that you want to
trace.  This issue, if present, usually only affects the first predicate
clause.

Clause breakpoints are currently not available when using XSB as this
backend doesn’t provide line information.

Using the port command ‘p’ (print) requires a backend supporting the
user-defined ‘portray/1’ hook predicate called via the ‘format/2-3’
predicates ‘~p’ control sequence.


File: TheLogtalkHandbook-3.96.0.info,  Node: diagrams,  Next: doclet,  Prev: debugger,  Up: Developer Tools

5.8 ‘diagrams’
==============

This tool generates 'library', 'directory', 'file', 'entity', and
'predicate' diagrams for source files and for libraries of source files
using the Logtalk reflection API to collect the relevant information and
a graph language for representing the diagrams.  Limited support is also
available for generating diagrams for Prolog module applications.  It’s
also possible in general to generate predicate cross-referencing
diagrams for plain Prolog files.

Linking 'library diagrams' to 'entity diagrams' to 'predicate
cross-referencing diagrams' and linking 'directory diagrams' to 'file
diagrams' is also supported when using SVG output.  This feature allows
using diagrams for understanding the architecture of applications by
navigating complex code and zooming into details.  SVG output can also
easily link to both source code repositories and API documentation.
This allows diagrams to be used for source code navigation.

Diagrams can also be used to uncover code issues.  For example,
comparing 'loading diagrams' with 'dependency diagrams' can reveal
implicit dependencies.  Loading diagrams can reveal circular
dependencies that may warrant code refactoring.  Entity diagrams can
provide a good overview of code coupling.  Predicate cross-referencing
diagrams can be used to visually access entity code complexity,
complementing the ‘code_metrics’ tool.

All diagrams support a comprehensive set of options, discussed below, to
customize the final contents and appearance.

Diagram generation can be easily automated using the ‘doclet’ tool and
the ‘logtalk_doclet’ scripts.  See the ‘doclet’ tool examples and
documentation for details.  See also the ‘diagrams’ tool own ‘lgt2svg’
Bash and PowerShell scripts.

* Menu:

* Requirements::
* API documentation: API documentation<6>.
* Loading: Loading<6>.
* Testing: Testing<6>.
* Supported diagrams::
* Graph elements::
* Supported graph languages::
* Customization::
* Linking diagrams::
* Creating diagrams for Prolog module applications::
* Creating diagrams for plain Prolog files::
* Other notes::


File: TheLogtalkHandbook-3.96.0.info,  Node: Requirements,  Next: API documentation<6>,  Up: diagrams

5.8.1 Requirements
------------------

Recent versions of d2 (0.6.9 or later) or Graphviz are required for
generating diagrams in the final formats:

   - ‘https://d2lang.com’

   - ‘https://www.graphviz.org/’

These can be installed using their own installers or using
operating-system package managers:

* Menu:

* macOS - MacPorts: macOS - MacPorts<2>.
* macOS - Homebrew: macOS - Homebrew<2>.
* Windows - Chocolatey: Windows - Chocolatey<2>.
* Installers: Installers<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: macOS - MacPorts<2>,  Next: macOS - Homebrew<2>,  Up: Requirements

5.8.1.1 macOS - MacPorts
........................

     $ sudo port install d2 graphviz


File: TheLogtalkHandbook-3.96.0.info,  Node: macOS - Homebrew<2>,  Next: Windows - Chocolatey<2>,  Prev: macOS - MacPorts<2>,  Up: Requirements

5.8.1.2 macOS - Homebrew
........................

     $ brew install d2 graphviz


File: TheLogtalkHandbook-3.96.0.info,  Node: Windows - Chocolatey<2>,  Next: Installers<2>,  Prev: macOS - Homebrew<2>,  Up: Requirements

5.8.1.3 Windows - Chocolatey
............................

     > choco install d2 graphviz


File: TheLogtalkHandbook-3.96.0.info,  Node: Installers<2>,  Prev: Windows - Chocolatey<2>,  Up: Requirements

5.8.1.4 Installers
..................

   - ‘https://d2lang.com/tour/install’

   - ‘https://www.graphviz.org/download/’


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<6>,  Next: Loading<6>,  Prev: Requirements,  Up: diagrams

5.8.2 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#diagrams’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<6>,  Next: Testing<6>,  Prev: API documentation<6>,  Up: diagrams

5.8.3 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(diagrams(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<6>,  Next: Supported diagrams,  Prev: Loading<6>,  Up: diagrams

5.8.4 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(diagrams(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Supported diagrams,  Next: Graph elements,  Prev: Testing<6>,  Up: diagrams

5.8.5 Supported diagrams
------------------------

The following entity diagrams are supported:

   - 'entity diagrams' showing entity public interfaces, entity
     inheritance relations, and entity predicate cross-reference
     relations

   - 'predicate cross-reference diagrams' (between entities or within an
     entity)

   - 'inheritance diagrams' showing entity inheritance relations

   - 'uses diagrams' showing which entities use resources from other
     entities

The following library diagrams are supported:

   - 'library loading diagrams' showing which libraries load other
     libraries

   - 'library dependency diagrams' showing which libraries contain
     entities with references to entities defined in other libraries

The following file diagrams are supported:

   - 'file loading diagrams' showing which files load or include other
     files

   - 'file dependency diagrams' showing which files contain entities
     with references to entities defined in other files

File dependency diagrams are specially useful in revealing dependencies
that are not represented in file loading diagrams due to files being
loaded indirectly by files external to the libraries being documented.

The following directory diagrams are supported:

   - 'directory loading diagrams' showing which directories contain
     files that load files from other directories

   - 'directory dependency diagrams' showing which directories contain
     entities with references to entities defined in other directories

Comparing directory (or file) loading diagrams with directory (or file)
dependency diagrams allows comparing what is explicitly loaded with the
actual directory (or file) dependencies, which are inferred from the
source code.

Library and directory dependency diagrams are specially useful for large
applications where file diagrams would be too large and complex to be
useful, notably when combined with the 'zoom' option to link to,
respectively, entity and file diagrams.

A utility object, ‘diagrams’, is provided for generating all supported
diagrams in one step.  This object provides an interface common to all
diagrams, but note that some predicates that generate diagrams only make
sense for some types of diagrams.  For best results and fine-grained
customization of each diagram, the individual diagram objects should be
used with the intended set of options.


File: TheLogtalkHandbook-3.96.0.info,  Node: Graph elements,  Next: Supported graph languages,  Prev: Supported diagrams,  Up: diagrams

5.8.6 Graph elements
--------------------

Limitations in both the graph languages and UML force the invention of a
modeling language that can represent all kinds of Logtalk entities and
entity relations.  Currently we use the following Graphviz node shapes
(libraries, entities, predicates, and files) and arrowheads (entity,
predicate, and file relations):

   - 
          libraries
          ‘tab’ (lightsalmon)

   - 
          library loading and dependency relations
          ‘normal’ (arrow ending with a black triangle)

   - 
          objects (classes, instances, and prototypes)
          ‘box’ (rectangle, yellow for instances/classes and beige for prototypes)

   - 
          protocols
          ‘note’ (aqua marine rectangle with folded right-upper corners)

   - 
          categories
          ‘component’ (light cyan rectangle with two small rectangles intercepting the left side)

   - 
          modules
          ‘box’ (plum rectangle with small tab at top)

   - 
          public predicates
          ‘box’ (springgreen)

   - 
          public, multifile, predicates
          ‘box’ (skyblue)

   - 
          protected predicates
          ‘box’ (yellow)

   - 
          private predicates
          ‘box’ (indianred)

   - 
          external predicates
          ‘box’ (beige)

   - 
          exported module predicates
          ‘box’ (springgreen)

   - 
          directories
          ‘tab’ (lightsalmon)

   - 
          directory loading and dependency relations
          ‘normal’ (arrow ending with a black triangle)

   - 
          files
          ‘box’ (pale turquoise rectangle)

   - 
          file loading and dependency relations
          ‘normal’ (arrow ending with a black triangle)

   - 
          specialization relation
          ‘onormal’ (arrow ending with a white triangle)

   - 
          instantiation relation
          ‘normal’ (arrow ending with a black triangle)

   - 
          extends relation
          ‘vee’ (arrow ending with a “v”)

   - 
          implements relation
          ‘dot’ (arrow ending with a black circle)

   - 
          imports relation
          ‘box’ (arrow ending with a black square)

   - 
          complements relation
          ‘obox’ (arrow ending with a white square)

   - 
          uses and use module relations
          ‘rdiamond’ (arrow ending with a black half diamond)

   - 
          predicate calls
          ‘normal’ (arrow ending with a black triangle)

   - 
          dynamic predicate updates
          ‘diamond’ (arrow ending with a black diamond)

When using the d2 graph language, we use similar node shapes and
arrowheads when available.  As d2 evolves, we hope that these graph
elements will converge further.

The library, directory, file, entity, and predicate nodes that are not
part of the predicates, entities, files, or libraries for which we are
generating a diagram use a dashed border, a darker color, and are
described as external.

Note that all the elements above can have captions.  See below the
diagrams ‘node_type_captions/1’ and ‘relation_labels/1’ output options.


File: TheLogtalkHandbook-3.96.0.info,  Node: Supported graph languages,  Next: Customization,  Prev: Graph elements,  Up: diagrams

5.8.7 Supported graph languages
-------------------------------

Currently, both DOT and d2 graph languages support all the features of
the ‘diagrams’ tool.  There’s also preliminary support for Mermaid (its
current version lacks several required features for parity with d2 and
Graphviz, notably support for links on edges).

The diagrams ‘.d2’ and ‘.dot’ files are created in the current directory
by default.  These files can be easily converted into a printable format
such as SVG, PDF, or Postscript.  Sample helper scripts are provided for
converting a directory of ‘.d2’ or ‘.dot’ files to ‘.svg’ files:

   - ‘lgt2svg.sh’ for POSIX systems

   - ‘lgt2svg.ps1’ for Windows systems

The scripts assume that the d2 and Graphviz command-line executables are
available from the system path.  For Graphviz, the default is the ‘dot’
executable, but the scripts accept a command-line option to select in
alternative the ‘circo’, ‘fdp’, or ‘neato’ executables).  For d2, the
default layout engine is ‘elk’, but the scripts accept a command-line
option to select in alternative the ‘dagre’ or ‘tala’ layout engines.

The recommended output format is SVG, as it supports tooltips and URL
links, which can be used for showing, e.g., entity types, relation
types, file paths, and for navigating to files and directories of files
(libraries) or to API documentation.  See the relevant diagram options
below in order to take advantage of these features (see the discussion
below on “linking diagrams”).

To convert to formats other than SVG, you will need to use the d2 and
Graphviz executables directly.  For example, using the Graphviz ‘dot’
executable, we can generate a PDF with the command:

     dot -Tpdf diagram.dot > diagram.pdf

This usually works fine for entity and predicate call cross-referencing
diagrams.  For directory and file diagrams, the ‘fdp’ and ‘circo’
command-line executables may produce better results.  For example:

     fdp -Tsvg diagram.dot > diagram.svg
     circo -Tsvg diagram.dot > diagram.svg

It’s also worth experimenting with different layouts to find the one
that produces the best results (see the ‘layout/1’ option described
below).

When generating diagrams for multiple libraries or directories, it’s
possible to split a diagram with several disconnected library or
directory graphs using the ‘ccomps’ command-line executable.  For
example:

     ccomps -x -o subdiagram.dot diagram.dot

For more information on the DOT language and related tools, see:

     http://www.graphviz.org/

When using Windows, there are known issues with some Prolog compilers
due to the internal representation of paths.  If you encounter problems
with a specific backend Prolog compiler, try, if possible, to use
another supported backend Prolog compiler when generating diagrams.

For printing large diagrams, you will need to either use a tool to slice
the diagram into page-sized pieces or, preferably, use software capable
of tiled printing (e.g., Adobe Reader).  You can also hand-edit the
generated ‘.dot’ files and play with settings such as aspect ratio for
fine-tuning the diagrams layout.


File: TheLogtalkHandbook-3.96.0.info,  Node: Customization,  Next: Linking diagrams,  Prev: Supported graph languages,  Up: diagrams

5.8.8 Customization
-------------------

A set of options is available to specify the details to include in the
generated diagrams.  For entity diagrams, the options are:

   - 
          ‘layout(Layout)’
          diagram layout (one of the atoms ‘{top_to_bottom,bottom_to_top,left_to_right,right_to_left}’; default is ‘bottom_to_top’)

   - 
          ‘title(Title)’
          diagram title (an atom; default is ‘''’)

   - 
          ‘date(Boolean)’
          print current date and time (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘versions(Boolean)’
          print Logtalk and backend version data (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘interface(Boolean)’
          print public predicates (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘file_labels(Boolean)’
          print file labels (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘file_extensions(Boolean)’
          print file name extensions (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘relation_labels(Boolean)’
          print entity relation labels (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘externals(Boolean)’
          print external nodes (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘node_type_captions(Boolean)’
          print node type captions (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘inheritance_relations(Boolean)’
          print inheritance relations (‘true’ or ‘false’; default is ‘true’ for entity inheritance diagrams and ‘false’ for other entity diagrams)

   - 
          ‘provide_relations(Boolean)’
          print provide relations (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘xref_relations(Boolean)’
          print predicate call cross-reference relations (‘true’ or ‘false’; default depends on the specific diagram)

   - 
          ‘xref_calls(Boolean)’
          print predicate cross-reference calls (‘true’ or ‘false’; default depends on the specific diagram)

   - 
          ‘output_directory(Directory)’
          directory for the ‘.d2’ and ‘.dot’ files (an atom; default is ‘'./dot_dias'’)

   - 
          ‘exclude_directories(Directories)’
          list of directories to exclude except as external nodes (default is ‘[]’); all sub-directories of the excluded directories are also excluded; directories may be listed by full or relative path

   - 
          ‘exclude_files(Files)’
          list of source files to exclude except as external nodes (default is ‘[]’); files may be listed by full path or basename, with or without extension

   - 
          ‘exclude_libraries(Libraries)’
          list of libraries to exclude except as external nodes (default is ‘[startup, scratch_directory]’)

   - 
          ‘exclude_entities(Entities)’
          list of entities to exclude except as external nodes (default is ‘[]’)

   - 
          ‘path_url_prefixes(PathPrefix, CodeURLPrefix, DocURLPrefix)’
          code and documenting URL prefixes for a path prefix used when generating cluster, library, directory, file, and entity links (atoms; no default; can be specified multiple times)

   - 
          ‘url_prefixes(CodeURLPrefix, DocURLPrefix)’
          default URL code and documenting URL prefixes used when generating cluster, library, file, and entity links (atoms; no default)

   - 
          ‘entity_url_suffix_target(Suffix, Target)’
          extension for entity documenting URLs (an atom; default is ‘'.html'’) and target separating symbols (an atom; default is ‘'#'’)

   - 
          ‘omit_path_prefixes(Prefixes)’
          omit common path prefixes when printing directory paths and when constructing URLs (a list of atoms; default is a list with the user home directory)

   - 
          ‘zoom(Boolean)’
          generate sub-diagrams and add links and zoom icons to library and entity nodes (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘zoom_url_suffix(Suffix)’
          extension for linked diagrams (an atom; default is ‘'.svg'’)

In the particular case of cross-referencing diagrams, there are also the
options:

   - 
          ‘recursive_relations(Boolean)’
          print recursive predicate relations (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘url_line_references(Host)’
          syntax for the URL source file line part (an atom; possible values are ‘{github,gitlab,bitbucket}’; default is ‘github’); when using this option, the ‘CodeURLPrefix’ should be a permanent link (i.e., it should include the commit SHA1)

   - 
          ‘predicate_url_target_format(Generator)’
          documentation final format generator (an atom; possible values are ‘{sphinx,other}’; default is ‘sphinx’)

For directory and file diagrams, the options are:

   - 
          ‘layout(Layout)’
          diagram layout (one of the atoms ‘{top_to_bottom,bottom_to_top,left_to_right,right_to_left}’; default is ‘top_to_bottom’)

   - 
          ‘title(Title)’
          diagram title (an atom; default is ‘''’)

   - 
          ‘date(Boolean)’
          print current date and time (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘versions(Boolean)’
          print Logtalk and backend version data (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘directory_paths(Boolean)’
          print file directory paths (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘file_extensions(Boolean)’
          print file name extensions (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘path_url_prefixes(PathPrefix, CodeURLPrefix, DocURLPrefix)’
          code and documenting URL prefixes for a path prefix used when generating cluster, directory, file, and entity links (atoms; no default; can be specified multiple times)

   - 
          ‘url_prefixes(CodeURLPrefix, DocURLPrefix)’
          default URL code and documenting URL prefixes used when generating cluster, library, file, and entity links (atoms; no default)

   - 
          ‘omit_path_prefixes(Prefixes)’
          omit common path prefixes when printing directory paths and when constructing URLs (a list of atoms; default is a list with the user home directory)

   - 
          ‘relation_labels(Boolean)’
          print entity relation labels (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘externals(Boolean)’
          print external nodes (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘node_type_captions(Boolean)’
          print node type captions (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘output_directory(Directory)’
          directory for the ‘.d2’ and ‘.dot’ files (an atom; default is ‘'./dot_dias'’)

   - 
          ‘exclude_directories(Directories)’
          list of directories to exclude except as external nodes (default is ‘[]’)

   - 
          ‘exclude_files(Files)’
          list of source files to exclude except as external nodes (default is ‘[]’)

   - 
          ‘zoom(Boolean)’
          generate sub-diagrams and add links and zoom icons to library and entity nodes (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘zoom_url_suffix(Suffix)’
          extension for linked diagrams (an atom; default is ‘'.svg'’)

For library diagrams, the options are:

   - 
          ‘layout(Layout)’
          diagram layout (one of the atoms ‘{top_to_bottom,bottom_to_top,left_to_right,right_to_left}’; default is ‘top_to_bottom’)

   - 
          ‘title(Title)’
          diagram title (an atom; default is ‘''’)

   - 
          ‘date(Boolean)’
          print current date and time (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘versions(Boolean)’
          print Logtalk and backend version data (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘directory_paths(Boolean)’
          print file directory paths (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘path_url_prefixes(PathPrefix, CodeURLPrefix, DocURLPrefix)’
          code and documenting URL prefixes for a path prefix used when generating cluster, library, file, and entity links (atoms; no default; can be specified multiple times)

   - 
          ‘url_prefixes(CodeURLPrefix, DocURLPrefix)’
          default URL code and documenting URL prefixes used when generating cluster, library, file, and entity links (atoms; no default)

   - 
          ‘omit_path_prefixes(Prefixes)’
          omit common path prefixes when printing directory paths and when constructing URLs (a list of atoms; default is a list with the user home directory)

   - 
          ‘relation_labels(Boolean)’
          print entity relation labels (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘externals(Boolean)’
          print external nodes (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘node_type_captions(Boolean)’
          print node type captions (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘output_directory(Directory)’
          directory for the ‘.d2’ and ‘.dot’ files (an atom; default is ‘'./dot_dias'’)

   - 
          ‘exclude_directories(Directories)’
          list of directories to exclude except as external nodes (default is ‘[]’)

   - 
          ‘exclude_files(Files)’
          list of source files to exclude except as external nodes (default is ‘[]’)

   - 
          ‘exclude_libraries(Libraries)’
          list of libraries to exclude except as external nodes (default is ‘[startup, scratch_directory]’)

   - 
          ‘zoom(Boolean)’
          generate sub-diagrams and add links and zoom icons to library and entity nodes (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘zoom_url_suffix(Suffix)’
          extension for linked diagrams (an atom; default is ‘'.svg'’)

When using the ‘zoom(true)’ option, the ‘layout(Layout)’ option applies
only to the top diagram; sub-diagrams will use their own layout default.

The option ‘omit_path_prefixes(Prefixes)’ with a non-empty list of
prefixes should preferably be used together with the option
‘directory_paths(true)’ when generating library or file diagrams that
reference external libraries or files.  To confirm the exact default
options used by each type of diagram, send the ‘default_options/1’
message to the diagram object.

Be sure to set the ‘source_data’ flag ‘on’ before compiling the
libraries or files for which you want to generate diagrams.

Support for displaying Prolog modules and Prolog module files in
diagrams of Logtalk applications:

   - 
          ECLiPSe
          file diagrams don’t display module files

   - 
          SICStus Prolog
          file diagrams don’t display module files

   - 
          SWI-Prolog
          full support (uses the SWI-Prolog ‘prolog_xref’ library)

   - 
          YAP
          full support (uses the YAP ‘prolog_xref’ library)


File: TheLogtalkHandbook-3.96.0.info,  Node: Linking diagrams,  Next: Creating diagrams for Prolog module applications,  Prev: Customization,  Up: diagrams

5.8.9 Linking diagrams
----------------------

When using SVG output, it’s possible to generate diagrams that link to
other diagrams, to API documentation, to local files and directories,
and to source code repositories.

For generating links between diagrams, use the ‘zoom(true)’ option.
This option allows (1) linking library diagrams to entity diagrams to
predicate cross-referencing diagrams and (2) linking directory diagrams
to file diagrams to entity diagrams to predicate cross-referencing
diagrams.  The sub-diagrams are automatically generated.  For example,
using the predicates that generate library diagrams will also
automatically generate the entity and predicate cross-referencing
diagrams.

To generate local links for opening directories, files, and file
locations in selected text editors, set the URL code prefix:

   - VSCode: ‘url_prefixes('vscode://file/', DocPrefix)’

   - VSCodium: ‘url_prefixes('vscodium://file/', DocPrefix)’

   - Cursor: ‘url_prefixes('cursor://file/', DocPrefix)’

   - PearAI: ‘url_prefixes('pearai://file/', DocPrefix)’

   - Windsurf: ‘url_prefixes('windsurf://file/', DocPrefix)’

   - Zed: ‘url_prefixes('zed://file/', DocPrefix)’

   - BBEdit: ‘url_prefixes('x-bbedit://open?url=file://', DocPrefix)’

   - MacVim: ‘url_prefixes('mvim://open?url=file://', DocPrefix)’

   - TextMate: ‘url_prefixes('txmt://open?url=file://', DocPrefix)’

   - IDEA: ‘url_prefixes('idea://open?file=', DocPrefix)’

   - PyCharm: ‘url_prefixes('pycharm://open?file=', DocPrefix)’

In this case, the ‘DocPrefix’ argument should be the path to the
directory containing the HTML version of the application APIs.

As most of the text editor URL scheme handlers require local links to
use absolute paths, the ‘omit_path_prefixes/1’ option is ignored.  Note
that local links require text editor support for URL schemes that can
handle both file and directory links.

To generate links to API documentation and source code repositories, use
the options ‘path_url_prefixes/3’ (or ‘url_prefixes/2’ for simpler
cases) and ‘omit_path_prefixes/1’.  The idea is that the
‘omit_path_prefixes/1’ option specifies local file prefixes that will be
cut and replaced by the URL prefixes (which can be path prefix specific
when addressing multiple code repositories).  To generate local file
system URLs, define the empty atom, ‘''’, as a prefix.  As an example,
consider the Logtalk library.  Its source code is available from a
GitHub repository, and its documentation is published on the Logtalk
website.  The relevant URLs in this case are:

   - ‘https://github.com/LogtalkDotOrg/logtalk3/’ (source code)

   - ‘https://logtalk.org/library/’ (API documentation)

Git source code URLs should include the commit SHA1 to ensure that
entity and predicate file line information in the URLs remain valid if
the code changes in later commits.  Assuming a ‘GitHub’ variable bound
to the SHA1 commit URL we want to reference, an inheritance diagram can
be generated using the goal:

     | ?- GitHub  = 'https://github.com/LogtalkDotOrg/logtalk3/commit/eb156d46e135ac47ef23adcc5d20d49dd8b66abb',
          APIDocs = 'https://logtalk.org/library/',
          logtalk_load(diagrams(loader)),
          set_logtalk_flag(source_data, on),
          logtalk_load(library(all_loader)),
          inheritance_diagram::rlibrary(library, [
              title('Logtalk library'),
              node_type_captions(true),
              zoom(true),
              path_url_prefixes('$LOGTALKUSER/', GitHub, APIDocs),
              path_url_prefixes('$LOGTALKHOME/', GitHub, APIDocs),
              omit_path_prefixes(['$LOGTALKUSER/', '$LOGTALKHOME/', '$HOME/'])
          ]).

The two ‘path_url_prefixes/3’ options take care of source code and API
documentation for entities loaded either from the Logtalk installation
directory (whose location is given by the ‘LOGTALKHOME’ environment
variable) or from the Logtalk user directory (whose location is given by
the ‘LOGTALKUSER’ environment variable).  As we also don’t want any
local operating-system paths to be exposed in the diagram, we use the
‘omit_path_prefixes/1’ option to suppress those path prefixes.  Note
that all the paths and URLs must end with a slash for proper handling.
The ‘git’ library may be useful to retrieve the commit SHA1 from a local
repo directory.

For both ‘path_url_prefixes/3’ and ‘omit_path_prefixes/1’ options, when
a path prefix is itself a prefix of another path, the shorter path must
come last to ensure correct links.

See the ‘SCRIPT.txt’ file in the tool directory for additional examples.
To avoid retyping such complex goals when updating diagrams, use the
‘doclet’ tool to save and reapply them easily (e.g., by using the ‘make’
tool with the ‘documentation’ target).


File: TheLogtalkHandbook-3.96.0.info,  Node: Creating diagrams for Prolog module applications,  Next: Creating diagrams for plain Prolog files,  Prev: Linking diagrams,  Up: diagrams

5.8.10 Creating diagrams for Prolog module applications
-------------------------------------------------------

Currently limited to SWI-Prolog and YAP Prolog module applications due
to the lack of a comprehensive reflection API in other Prolog systems.

Simply load your Prolog module application and its dependencies and then
use diagram entity, directory, or file predicates.  Library diagram
predicates are not supported.  See the ‘SCRIPT.txt’ file in the tool
directory for some usage examples.  Note that support for diagrams with
links to API documentation is quite limited, however, due to the lack of
Prolog standards.


File: TheLogtalkHandbook-3.96.0.info,  Node: Creating diagrams for plain Prolog files,  Next: Other notes,  Prev: Creating diagrams for Prolog module applications,  Up: diagrams

5.8.11 Creating diagrams for plain Prolog files
-----------------------------------------------

This tool can also be used to create predicate cross-referencing
diagrams for plain Prolog files.  For example, if the Prolog file is
named ‘code.pl’, simply define an object including its code:

     :- object(code).
         :- include('code.pl').
     :- end_object.

Save the object to an e.g.  ‘code.lgt’ file in the same directory as the
Prolog file and then load it and create the diagram:

     | ?- logtalk_load(code),
          xref_diagram::entity(code).

An alternative is to use the ‘object_wrapper_hook’ provided by the
‘hook_objects’ library:

     | ?- logtalk_load(hook_objects(loader)).
     ...

     | ?- logtalk_load(code, [hook(object_wrapper_hook)]),
          xref_diagram::entity(code).


File: TheLogtalkHandbook-3.96.0.info,  Node: Other notes,  Prev: Creating diagrams for plain Prolog files,  Up: diagrams

5.8.12 Other notes
------------------

Generating complete diagrams requires that all referenced entities are
loaded.  When that is not the case, notably when generating
cross-referencing diagrams, missing entities can result in incomplete
diagrams.

For complex applications, diagrams can often be made simpler and more
readable by omitting external nodes (see the ‘externals/1’ option)
and/or using one of the alternatives to ‘dot’ provided by Graphviz
depending on the type of the diagram (see the section above on supported
graph languages for more details).

When generating entity predicate call cross-reference diagrams, caller
nodes are not created for auxiliary predicates.  For example, if the
‘meta_compiler’ library is used to optimize meta-predicate calls, the
diagrams may show predicates that are not apparently called by any other
predicate when the callers are from the optimized meta-predicate goals
(which are called via library generated auxiliary predicates).  A
workaround in this case would be creating a dedicated loader file that
doesn’t load (and apply) the ‘meta_compiler’ library when generating the
diagrams.

When generating diagrams in SVG format, a copy of the ‘diagrams.css’
file must exist in any directory used for publishing diagrams using it.
The ‘lgt2svg’ scripts also take care of copying this file.

The Graphviz command-line utilities, e.g., ‘dot’, are notorious for
random crashes (segmentation faults usually), often requiring retrying
conversions from ‘.dot’ files to other formats.  A possible workaround
is to repeat the command until it completes without error.  See, for
example, the ‘lgt2svg.sh’ script.

The conversion by the ‘d2’ command-line executable of ‘.d2’ files to
‘.svg’ files can be quite slow (as of its 0.6.8 version) with the
default ‘elk’ layout engine.  The ‘dagre’ layout engine is much faster
but doesn’t support a node referencing itself (notably, a node
representing a metaclass that instantiates itself).

Using the default d2 layout engine (‘elk’) works fine with graphs with a
relatively small number of nodes and edges.  When that’s not the case,
it’s a good idea to experiment with other layout engines.


File: TheLogtalkHandbook-3.96.0.info,  Node: doclet,  Next: help,  Prev: diagrams,  Up: Developer Tools

5.9 ‘doclet’
============

This folder provides a simple tool for (re)generating documentation for
a project.  The tool defines a ‘doclet’ object that is expected to be
extended by the user to specify a sequence of goals and a sequence of
shell commands that load the application and (re)generate its
documentation.

Doclet source files are preferably named ‘doclet.lgt’ (or
‘doclet.logtalk’) and the doclet objects are usually named after the
application or library to be documented with a ‘_doclet’ suffix.  By
using an ‘initialization/1’ directive to automatically send the
‘update/0’ message that generates the documentation upon doclet loading,
we can abstract the name of the doclet object.  The usual query to load
and run a doclet is therefore:

     | ?- logtalk_load([doclet(loader), doclet]).

For usage examples, see the ‘sample_doclet.lgt’, ‘doclet1.lgt’,
‘zoom_doclet.lgt’, and ‘tools_doclet.lgt’ source files.

* Menu:

* API documentation: API documentation<7>.
* Loading: Loading<7>.
* Automating running doclets::
* Integration with the make tool: Integration with the make tool<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<7>,  Next: Loading<7>,  Up: doclet

5.9.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#doclet’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<7>,  Next: Automating running doclets,  Prev: API documentation<7>,  Up: doclet

5.9.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(doclet(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Automating running doclets,  Next: Integration with the make tool<2>,  Prev: Loading<7>,  Up: doclet

5.9.3 Automating running doclets
--------------------------------

You can use the ‘scripts/logtalk_doclet.sh’ Bash shell script for
automating running doclets.  The script expects the doclet source files
to be named either ‘doclet.lgt’ or ‘doclet.logtalk’.  See the
‘scripts/NOTES.md’ file or the script man page for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Integration with the make tool<2>,  Prev: Automating running doclets,  Up: doclet

5.9.4 Integration with the make tool
------------------------------------

Loading this tool adds a definition for the
‘logtalk_make_target_action/1’ hook predicate for the target
‘documentation’.  The hook definition sends an ‘update/0’ message to
each loaded doclet.


File: TheLogtalkHandbook-3.96.0.info,  Node: help,  Next: issue_creator,  Prev: doclet,  Up: Developer Tools

5.10 ‘help’
===========

This tool provides basic online help for Logtalk features and libraries
when running in most operating-systems.  For help on the Logtalk
compiler error and warning messages, see the ‘tutor’ tool.

* Menu:

* Requirements: Requirements<2>.
* API documentation: API documentation<8>.
* Loading: Loading<8>.
* Testing: Testing<7>.
* Supported operating-systems::
* Usage: Usage<5>.
* Experimental features::
* Known issues: Known issues<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Requirements<2>,  Next: API documentation<8>,  Up: help

5.10.1 Requirements
-------------------

On Windows, the ‘start’ command must be available.  On Linux, the
‘xdg-open’ command must be available.  On macOS, the command ‘open’ is
used.

Experimental features for browsing the Handbook and APIs documentation
at the top-level require Texinfo to be installed.  See the
‘tools/NOTES.md’ file for per operating-system installation
instructions.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<8>,  Next: Loading<8>,  Prev: Requirements<2>,  Up: help

5.10.2 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#help’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<8>,  Next: Testing<7>,  Prev: API documentation<8>,  Up: help

5.10.3 Loading
--------------

     | ?- logtalk_load(help(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<7>,  Next: Supported operating-systems,  Prev: Loading<8>,  Up: help

5.10.4 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(help(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Supported operating-systems,  Next: Usage<5>,  Prev: Testing<7>,  Up: help

5.10.5 Supported operating-systems
----------------------------------

Currently, support is limited to Linux, macOS, and Windows.

This tool relies on the library portable operating-system access
abstraction.


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<5>,  Next: Experimental features,  Prev: Supported operating-systems,  Up: help

5.10.6 Usage
------------

After loading the tool, use the query ‘help::help’ to get started.


File: TheLogtalkHandbook-3.96.0.info,  Node: Experimental features,  Next: Known issues<2>,  Prev: Usage<5>,  Up: help

5.10.7 Experimental features
----------------------------

On POSIX systems, when using Ciao Prolog, ECLiPSe, GNU Prolog (1.5.1 or
later version), SICStus Prolog, SWI-Prolog, Trealla Prolog, XSB, or XVM
as the backend, ‘apis/1’ and ‘handbook/0-1’ predicates are made
available.  These predicates open inline at the top-level interpreter
the Texinfo versions of the Handbook and the APIs documentation.  The
optional argument is a starting node, which can be an atom, a predicate
indicator, or a non-terminal indicator.  When there are several nodes
for the same argument (e.g., multiple implementations of the ‘member/2’
predicate), one of them will be displayed.  Some examples:

     | ?- help::handbook.

     | ?- help::handbook(base64).

     | ?- help::handbook(logtalk_load/2).

     | ?- help::apis.

     | ?- help::apis(check/2).

     | ?- help::apis(message_tokens//2).

Although less useful, you can also browse the ‘man’ pages of Logtalk
scripts.  For example:

     | ?- help::man(logtalk_tester).

When you finish consulting the documentation and quit the ‘info’
process, you will be back to the top-level prompt (if you find that the
top-level have scrolled from its last position, try to set your terminal
terminfo to ‘xterm-256colour’).

If you’re running Logtalk from a git clone of its repo, you will need to
run the ‘docs/apis/sources/build.sh’ or ‘docs/apis/sources/build.ps1’
scripts to generate the APIs documentation ‘.info’ file and also run the
‘docs/handbook/sources/build.sh’ or ‘docs/handbook/sources/build.ps1’
scripts to generate the Handbook ‘.info’ file.  Alternatively, you can
download the ‘.info’ files for the latest stable release from the
Logtalk website and save them to the ‘docs’ and ‘manuals’ directories.

The required ‘info’ command is provided by the third-party ‘texinfo’
package (tested with version 6.8).  On macOS, this package can be
installed with either MacPorts:

     $ sudo port install texinfo

Or using Homebrew:

     $ brew install texinfo

On Linux systems, use the distribution’s own package manager to install
the ‘texinfo’ package.  For example, in Ubuntu systems:

     $ sudo apt install info


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<2>,  Prev: Experimental features,  Up: help

5.10.8 Known issues
-------------------

The open commands used to open documentation URLs drops the fragment
part, thus preventing navigation to the specified position on the
documentation page.

When browsing the Texinfo versions of the Handbook and the APIs
documentation generated with a recent version of Sphinx and using a
recent version of Texinfo, the Texinfo search feature often displays the
previous nodes of the searched nodes.

ECLiPSe defines a ‘help’ prefix operator that forces wrapping this atom
between parentheses when sending messages to the tool.  E.g.  use
‘(help)::help’ instead of ‘help::help’.


File: TheLogtalkHandbook-3.96.0.info,  Node: issue_creator,  Next: lgtdoc,  Prev: help,  Up: Developer Tools

5.11 ‘issue_creator’
====================

This is a complementary tool for the ‘lgtunit’ tool for automatically
creating bug report issues for failed tests in GitHub or GitLab servers.

* Menu:

* Requirements: Requirements<3>.
* Loading: Loading<9>.
* Usage: Usage<6>.
* Known issues: Known issues<3>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Requirements<3>,  Next: Loading<9>,  Up: issue_creator

5.11.1 Requirements
-------------------

This tool requires that the GitHub ‘gh’ and GitLab ‘glab’ CLIs be
installed.  For the installation instructions see:

   - GitHub: ‘https://cli.github.com’

   - GitLab: ‘https://glab.readthedocs.io’


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<9>,  Next: Usage<6>,  Prev: Requirements<3>,  Up: issue_creator

5.11.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(issue_creator(loader)).

But, in the most common usage scenario, this tool is automatically
loaded by the ‘logtalk_tester’ automation script.


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<6>,  Next: Known issues<3>,  Prev: Loading<9>,  Up: issue_creator

5.11.3 Usage
------------

The ‘logtalk_tester’ automation script accepts a ‘-b’ option for
automatically using this tool (see the script man page for details).  In
the most simple case, this option possible values are ‘github’ and
‘gitlab’.  For example:

     $ logtalk_tester \
         -p gnu \
         -b github \
         -s "/home/jdoe/foo/" \
         -u https://github.com/jdoe/foo/tree/55aa900775befa135e0d5b48ea63098df8b97f5c/

The ‘logtalk_tester’ script 'must' be called from a git repo directory
or one of its sub-directories, which is a common setup in CI/CD
pipelines.  Moreover, prior to running the tests, the CLI must be used,
if required, to authenticate and login to the server where the bug
report issues will be created:

   - GitHub: ‘gh auth login --hostname <string> --with-token <
     token.txt’

   - GitLab: ‘glab auth login --hostname <string> --token <string>’

The access token must have the necessary scopes that allow bug reports
to be created.  See the CLIs documentation for details.  Typically, the
‘auth’ command is called from the CI/CD pipeline definition scripts.
However, depending on the CI/CD workflow, the authentication may be done
implicitly.

The bug reports are created using by default the label ‘bug’ and
assigned to the author of the latest commit of the git repo.  The ‘-b’
option can also be used to override the label with a comma separated set
of labels.  For example, to use both ‘bug’ and ‘auto’ labels:

     $ logtalk_tester \
         -p gnu \
         -b github:bug,auto \
         -s "/home/jdoe/foo/" \
         -u https://github.com/jdoe/foo/tree/55aa900775befa135e0d5b48ea63098df8b97f5c/

Note that the labels 'must' be predefined in the issue tracker server
for the bug report to be successfully created.  The ‘auto’ label can be
used to simplify filtering of auto-generated bug reports when browsing
the issue tracker.

The bug reports use Markdown formatting, which is the default in GitHub
and GitLab issue trackers.

But reports are only created for non-flaky tests.  The bug report title
and labels are used to prevent creating duplicated bug reports.
Therefore, the title should not be manually edited and the same labels
should be used for multiple runs of the same tests and preserved when
editing the bug reports.

There are cases where we may want to postpone or temporarily disable the
automatic creation of bug reports.  E.g.  a WIP branch that’s known to
break multiple tests.  A solution is to define a pull/merge request
label, e.g.  ‘NO_AUTO_BUG_REPORTS’, that can then be checked by the
CI/CD workflow.  For example, we can test the presence of that label to
set a ‘AUTO_BUG_REPORTS’ environment variable to either an empty string
or a ‘-b’ option and use:

     logtalk_tester.sh $AUTO_BUG_REPORTS -p ...


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<3>,  Prev: Usage<6>,  Up: issue_creator

5.11.4 Known issues
-------------------

GitLab creates CI/CD pipelines in a detached HEAD state by default.  As
a consequence, the git branch would be reported as HEAD. To workaround
this issue, this tool uses the value of the GitLab CI/CD pipeline
variable ‘CI_COMMIT_REF_NAME’ when defined as the branch name.

This tool is in a beta stage of development.  Your feedback is most
appreciated.


File: TheLogtalkHandbook-3.96.0.info,  Node: lgtdoc,  Next: lgtunit,  Prev: issue_creator,  Up: Developer Tools

5.12 ‘lgtdoc’
=============

This is the default Logtalk documenting tool for generating API
documentation for libraries and applications.  It uses the structural
reflection API to extract and output in XML format relevant
documentation about a source file, a library or directory of source
files, or all loaded source files.  The tool predicates accept several
options for generating the XML files, including the output directory.

The ‘lgtdoc/xml’ directory contains several ready-to-use Bash and
PowerShell scripts for converting the XML documenting files into final
formats, including (X)HTML, PDF, Markdown, and reStructuredText (for use
with Sphinx), and plain text files.  The scripts are described in their
‘man’ pages and made available in the system path by default.

* Menu:

* Requirements: Requirements<4>.
* API documentation: API documentation<9>.
* Loading: Loading<10>.
* Testing: Testing<8>.
* Documenting source code::
* Generating documentation::
* Documentation linter checks::


File: TheLogtalkHandbook-3.96.0.info,  Node: Requirements<4>,  Next: API documentation<9>,  Up: lgtdoc

5.12.1 Requirements
-------------------

This tool requirements for converting the XML files it generates to a
final format are as follows:

  1. Converting XML files to (X)HTML, reStructuredText, Markdown, or
     plain text files requires a XSLT processor.  The supported XSLT
     processors for Bash conversion scripts are:

   - xsltproc: ‘https://gitlab.gnome.org/GNOME/libxslt/-/wikis/home’

   - Xalan: ‘https://xml.apache.org/xalan-c/index.html’

   - Saxon: ‘https://www.saxonica.com’

On Windows, the PowerShell scripts use the .Net XSLT classes.

The reStructuredText files output is usually used as an intermediate
step to generate Sphinx HTML, PDF, ePub, and Texinfo files.  The
additional requirements are:

   - Sphinx: ‘https://www.sphinx-doc.org/’

   - Pygments: ‘https://pygments.org/’

   - Read the Docs theme:
     ‘https://github.com/readthedocs/sphinx_rtd_theme’

  2. Converting XML files to PDF files require a XSL-FO processor.  The
     supported XSL-FO processors for Bash and PowerShell conversion
     scripts are:

   - Apache FOP processor: ‘https://xmlgraphics.apache.org/fop/’

   - RenderX XEP processor: ‘https://www.renderx.com/’

For additional details, including compatible dependency versions and
available conversion scripts, see the ‘xml/NOTES.md’ file.  See the
‘tools/NOTES.md’ file for per operating-system installation instructions
for the above dependencies.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<9>,  Next: Loading<10>,  Prev: Requirements<4>,  Up: lgtdoc

5.12.2 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#lgtdoc’


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<10>,  Next: Testing<8>,  Prev: API documentation<9>,  Up: lgtdoc

5.12.3 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(lgtdoc(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<8>,  Next: Documenting source code,  Prev: Loading<10>,  Up: lgtdoc

5.12.4 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(lgtdoc(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Documenting source code,  Next: Generating documentation,  Prev: Testing<8>,  Up: lgtdoc

5.12.5 Documenting source code
------------------------------

For information on documenting your source code, notably on documenting
directives, consult the documenting section of the User Manual:

‘../../handbook/userman/documenting.html’

Extracting documenting information from your source code using this tool
requires compiling the source files using the ‘source_data(on)’ compiler
flag.  For example:

     | ?- logtalk_load(source_file, [source_data(on)]).

Usually, this flag is set for all application source files in the
corresponding loader file.  In alternative, you may also turn on the
‘source_data’ flag globally by typing:

     | ?- set_logtalk_flag(source_data, on).

The tool API allows generating documentation for libraries, directories,
and files, complemented with library, directory, entity, and predicate
indexes.  Note that the source files to be documented 'must' be loaded
prior to using this tool predicates to generate the documentation.


File: TheLogtalkHandbook-3.96.0.info,  Node: Generating documentation,  Next: Documentation linter checks,  Prev: Documenting source code,  Up: lgtdoc

5.12.6 Generating documentation
-------------------------------

For a simple application, assuming a library alias is defined for it
(e.g.  ‘my_app’), and at the top-level interpreter, we can generate the
application documentation by typing:

     | ?- {my_app(loader)}.
     ...

     | ?- {lgtdoc(loader)}.
     ...

     | ?- lgtdoc::library(my_app).
     ...

By default, the documenting XML files are created in a ‘xml_docs’
directory in the current working directory.  But usually all documenting
files are collected for both the application and the libraries it uses
in a common directory so that all documentation links resolved properly.
The ‘lgtdoc’ predicates can take a list of options to customize the
generated XML documenting files.  See the remarks section in the
lgtdocp(1) protocol documentation for details on the available options.

After generating the XML documenting files, these can be easily
converted into final formats using the provided scripts.  For example,
assuming that we want to generate HTML documentation:

     $ cd xml_docs
     $ lgt2html -t "My app"

To generate the documentation in Sphinx format instead (as used by
Logtalk itself for its APIs):

     $ cd xml_docs
     $ lgt2rst -s -- -q -p "Application name" -a "Author name" -v "Version X.YZ.P"
     $ make html

In this case, the generated documentation will be in the
‘xml_docs/_build/html/’ directory.  See the scripts man pages or call
them using the ‘-h’ option to learn more about their supported options.

For more complex applications, you can use the ‘doclet’ tool to define a
'doclet' to automate all the steps required to generate documentation.
The 'doclet' message that triggers the process can also be sent
automatically when the ‘make’ tool is used with the ‘documentation’
target.

   ---------- Footnotes ----------

   (1) ../../docs/apis/library_index.html#lgtdoc


File: TheLogtalkHandbook-3.96.0.info,  Node: Documentation linter checks,  Prev: Generating documentation,  Up: lgtdoc

5.12.7 Documentation linter checks
----------------------------------

When the ‘lgtdoc_missing_directives’ flag is set to ‘warning’ (its usual
default value), the ‘lgtdoc’ tool prints warnings on missing entity
‘info/1’ directives and missing predicate ‘info/2’ and ‘mode/2’
directives.

When the ‘lgtdoc_missing_info_key’ flag is set to ‘warning’ (its usual
default value), the ‘lgtdoc’ tool prints warnings on entity ‘info/1’
directive and predicate ‘info/2’ directive missing de facto required
keys (e.g., ‘comment’, ‘parameters’ or ‘parnames’ for parametric
entities, ‘arguments’ or ‘argnames’ for predicates/non-terminals with
arguments).

When the ‘lgtdoc_invalid_dates’ flag is set to ‘warning’ (its usual
default value), the ‘lgtdoc’ tool prints warnings on invalid dates
(including dates in the future) in ‘info/1’ directives.

When the ‘lgtdoc_non_standard_exceptions’ flag is set to ‘warning’ (its
usual default value), the ‘lgtdoc’ tool prints warnings on non-standard
exceptions.  This linter check is particularly effective in detecting
typos when specifying standard exceptions.

When the ‘lgtdoc_missing_punctuation’ flag is set to ‘warning’ (its
usual default value), the ‘lgtdoc’ tool prints warnings on missing
ending periods (full stops), exclamation marks, or question marks in
‘info/1-2’ directives (in comments, remarks, parameter descriptions, and
argument descriptions).

Set a flag value to ‘silent’ to turn off the corresponding linter
warnings.


File: TheLogtalkHandbook-3.96.0.info,  Node: lgtunit,  Next: linter,  Prev: lgtdoc,  Up: Developer Tools

5.13 ‘lgtunit’
==============

The ‘lgtunit’ tool provides testing support for Logtalk.  It can also be
used for testing plain Prolog code and Prolog module code.

This tool is inspired by the xUnit frameworks architecture and by the
works of Joachim Schimpf (ECLiPSe library ‘test_util’) and Jan
Wielemaker (SWI-Prolog ‘plunit’ package).

Tests are defined in objects, which represent a 'test set' or 'test
suite'.  In simple cases, we usually define a single object containing
the tests.  But it is also possible to use parametric test objects or
multiple objects defining parametrizable tests or test subsets for
testing more complex units and facilitating tests maintenance.
Parametric test objects are specially useful to test multiple
implementations of the same protocol using a single set of tests by
passing the implementation object as a parameter value.

* Menu:

* Main files::
* API documentation: API documentation<10>.
* Loading: Loading<11>.
* Testing: Testing<9>.
* Writing and running tests::
* Automating running tests::
* Parametric test objects::
* Test dialects::
* User-defined test dialects::
* QuickCheck::
* Skipping tests::
* Selecting tests::
* Checking test goal results::
* Testing local predicates::
* Testing non-deterministic predicates::
* Testing generators::
* Testing input/output predicates::
* Suppressing tested predicates output::
* Tests with timeout limits::
* Setup and cleanup goals::
* Test annotations::
* Test execution times and memory usage::
* Working with test data files::
* Flaky tests::
* Mocking::
* Debugging messages in tests::
* Debugging failed tests::
* Code coverage::
* Utility predicates::
* Exporting test results in xUnit XML format::
* Exporting test results in the TAP output format::
* Generating Allure reports::
* Exporting code coverage results in XML format::
* Automatically creating bug reports at issue trackers::
* Minimizing test results output::
* Help with warnings::
* Known issues: Known issues<4>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Main files,  Next: API documentation<10>,  Up: lgtunit

5.13.1 Main files
-----------------

The ‘lgtunit.lgt’ source file implements a framework for defining and
running unit tests in Logtalk.  The ‘lgtunit_messages.lgt’ source file
defines the default translations for the messages printed when running
unit tests.  These messages can be intercepted to customize the output,
e.g.  to make it less verbose or for integration with e.g.  GUI IDEs and
continuous integration servers.

Other files that are part of this tool provide support for alternative
output formats of test results and are discussed below.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<10>,  Next: Loading<11>,  Prev: Main files,  Up: lgtunit

5.13.2 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#lgtunit’


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<11>,  Next: Testing<9>,  Prev: API documentation<10>,  Up: lgtunit

5.13.3 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(lgtunit(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<9>,  Next: Writing and running tests,  Prev: Loading<11>,  Up: lgtunit

5.13.4 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(lgtunit(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Writing and running tests,  Next: Automating running tests,  Prev: Testing<9>,  Up: lgtunit

5.13.5 Writing and running tests
--------------------------------

In order to write your own unit tests, define objects extending the
‘lgtunit’ object.  You may start by copying the
‘samples/tests-sample.lgt’ file (at the root of the Logtalk
distribution) to a ‘tests.lgt’ file in your project directory and
editing it to add your tests:

     :- object(tests,
         extends(lgtunit)).

         % test definitions
         ...

     :- end_object.

The section on *note test dialects: 939. below describes in detail how
to write tests.  See the ‘tests’ top directory for examples of actual
unit tests.  Other sources of examples are the ‘library’ and ‘examples’
directories.

The tests must be term-expanded by the ‘lgtunit’ object by compiling the
source files defining the test objects using the option ‘hook(lgtunit)’.
For example:

     | ?- logtalk_load(lgtunit(loader)),
          logtalk_load(tests, [hook(lgtunit)]).

As the term-expansion mechanism applies to all the contents of a source
file, the source files defining the test objects should preferably not
contain entities other than the test objects.  Additional code necessary
for the tests should go to separate files.  In general, the tests
themselves can be compiled in 'optimized' mode.  Assuming that’s the
case, also use the ‘optimize(on)’ compiler option for faster execution.

The term-expansion performed by the ‘lgtunit’ object sets the test
object ‘source_data’ flag to ‘on’ and the ‘context_switching_calls’ flag
to ‘allow’ for code coverage and debugging support.  But these settings
can always be overridden in the test objects.

The ‘samples/tester-sample.lgt’ file (at the root of the Logtalk
distribution) exemplifies how to compile and load ‘lgtunit’ tool, the
source code under testing, the unit tests, and how to automatically run
all the tests after loading:

     :- initialization((
         % minimize compilation reports to the essential ones (errors and warnings)
         set_logtalk_flag(report, warnings),
         % load any necessary library files for your application; for example
         logtalk_load(basic_types(loader)),
         % load the unit test tool
         logtalk_load(lgtunit(loader)),
         % load your application files (e.g., "source.lgt") enabling support for
         % code coverage, which requires compilation in debug mode and collecting
         % source data information; if code coverage is not required, remove the
         % "debug(on)" option for faster execution
         logtalk_load(source, [source_data(on), debug(on)]),
         % compile the unit tests file expanding it using "lgtunit" as the hook
         % object to preprocess the tests; if you have failing tests, add the
         % option debug(on) to debug them (see "tools/lgtunit/NOTES.md" for
         % debugging advice); tests should be loaded after the code being tested
         % is loaded to avoid warnings such as references to unknown entities
         logtalk_load(tests, [hook(lgtunit)]),
         % run all the unit tests; assuming your tests object is named "tests"
         tests::run
     )).

You may copy this sample file to a ‘tester.lgt’ file in your project
directory and edit it to load your project and test files.  The
‘logtalk_tester’ testing automation script defaults to looking for test
driver files named ‘tester.lgt’ or ‘tester.logtalk’ (if you have
work-in-progress test sets that you don’t want to run by default, simply
use a different file name such as ‘tester_wip.lgt’; you can still run
them automated by using ‘logtalk_tester -n tester_wip’).

Debugged test sets should preferably be compiled in optimal mode,
specially when containing deterministic tests and when using the utility
benchmarking predicates.

Assuming a ‘tester.lgt’ driver file as exemplified above, the tests can
be run by simply loading this file:

     | ?- logtalk_load(tester).

Assuming your test object is named ‘tests’, you can re-run the tests by
typing:

     | ?- tests::run.

You can also re-run a single test (or a list of tests) using the ‘run/1’
predicate:

     | ?- tests::run(test_identifier).

When testing complex 'units', it is often desirable to split the tests
between several test objects or use parametric test objects to be able
to run the same tests using different parameters (e.g., different data
sets or alternative implementations of the same protocol).  In this
case, you can run all test subsets using the goal:

     | ?- lgtunit::run_test_sets([test_set_1, test_set_2, ...]).

where the ‘run_test_sets/1’ predicate argument is a list of two or more
test object identifiers.  This predicate makes it possible to get a
single code coverage report that takes into account all the tests.

It’s also possible to automatically run loaded tests when using the
‘make’ tool by calling the goal that runs the tests from a definition of
the hook predicate ‘logtalk_make_target_action/1’.  For example, by
adding to the tests ‘tester.lgt’ driver file the following code:

     % integrate the tests with logtalk_make/1
     :- multifile(logtalk_make_target_action/1).
     :- dynamic(logtalk_make_target_action/1).

     logtalk_make_target_action(check) :-
         tests::run.

Alternatively, you can define the predicate ‘make/1’ inside the test set
object.  For example:

     :- object(tests, extends(lgtunit)).

         make(check).
         ...

     :- end_object.

This clause will cause all tests to be run when calling the
‘logtalk_make/1’ predicate with the target ‘check’ (or its top-level
shortcut, ‘{?}’).  The other possible target is ‘all’ (with top-level
shortcut ‘{*}’).

Note that you can have multiple test driver files.  For example, one
driver file that runs the tests collecting code coverage data and a
quicker driver file that skips code coverage and compiles the code to be
tested in optimized mode.


File: TheLogtalkHandbook-3.96.0.info,  Node: Automating running tests,  Next: Parametric test objects,  Prev: Writing and running tests,  Up: lgtunit

5.13.6 Automating running tests
-------------------------------

You can use the ‘scripts/logtalk_tester.sh’ Bash shell script or the
‘scripts/logtalk_tester.ps1’ PowerShell script for automating running
unit tests (e.g., from a CI/CD pipeline).  When using one of the Logtalk
installers, the ‘.sh’ extension can usually be omitted.  For example,
assuming your current directory (or sub-directories) contains one or
more ‘tester.lgt’ files:

     $ logtalk_tester -p gnu

The only required argument is the identifier of the backend Prolog
system.  For other options, see the ‘scripts/NOTES.md’ file or type:

     $ logtalk_tester -h

On POSIX systems, you can also access extended documentation by
consulting the script man page:

     $ man logtalk_tester

The scripts support the same set of options.  But the option for passing
additional arguments to the tests uses different syntax.  For example:

     $ logtalk_tester -p gnu -- foo bar baz

     PS> logtalk_tester -p gnu -a foo,bar,baz

On POSIX systems, assuming Logtalk was installed using one of the
provided installers or installation scripts, there is also a ‘man’ page
for the script:

     $ man logtalk_tester

Alternatively, an HTML version of this man page can be found at:

‘https://logtalk.org/man/logtalk_tester.html’

On POSIX systems, the ‘logtalk_tester.sh’ Bash script timeout option
requires either a ‘timeout’ or a ‘gtimeout’ command (provided by the GNU
coreutils package).  The ‘logtalk_tester.ps1’ PowerShell script timeout
option requires that Git for Windows is also installed, as it requires
the GNU timeout command bundled with it.

In addition to using the ‘logtalk_tester.ps1’ PowerShell script, the
Bash shell version of the automation script can also be used in Windows
operating-systems with selected backends by using the Bash shell
included in the Git for Windows installer.  That requires defining a
‘.profile’ file setting the paths to the Logtalk scripts and the Prolog
backend executables.  For example:

     $ cat ~/.profile
     # YAP
     export PATH="/C/Program Files/Yap64/bin":$PATH
     # GNU Prolog
     export PATH="/C/GNU-Prolog/bin":$PATH
     # SWI/Prolog
     export PATH="/C/Program Files/swipl/bin":$PATH
     # ECLiPSe
     export PATH="/C/Program Files/ECLiPSe 7.0/lib/x86_64_nt":$PATH
     # SICStus Prolog
     export PATH="/C/Program Files/SICStus Prolog VC16 4.6.0/bin":$PATH
     # Logtalk
     export PATH="$LOGTALKHOME/scripts":"$LOGTALKHOME/integration":$PATH

The Git for Windows installer also includes GNU ‘coreutils’ and its
‘timeout’ command, which is used by the ‘logtalk_tester’ script ‘-t’
option.

Note that some tests may give different results when run from within the
Bash shell compared with running the tests manually using a Windows GUI
version of the Prolog backend.  Some backends may also not be usable for
automated testing due to the way they are made available as Windows
applications.

Additional advice on testing and on automating testing using continuous
integration servers can be found at:

‘https://logtalk.org/testing.html’


File: TheLogtalkHandbook-3.96.0.info,  Node: Parametric test objects,  Next: Test dialects,  Prev: Automating running tests,  Up: lgtunit

5.13.7 Parametric test objects
------------------------------

Parameterized unit tests can be easily defined by using parametric test
objects.  A typical example is testing multiple implementations of the
same protocol.  In this case, we can use a parameter to pass the
specific implementation being tested.  For example, assume that we want
to run the same set of tests for the library ‘random_protocol’ protocol.
We can write:

     :- object(tests(_RandomObject_),
         extends(lgtunit)).

         :- uses(_RandomObject_, [
             random/1, between/3, member/2,
             ...
         ]).

         test(between_3_in_interval) :-
             between(1, 10, Random),
             1 =< Random, Random =< 10.

         ...

     :- end_object.

We can then test a specific implementation by instantiating the
parameter.  For example:

     | ?- tests(fast_random)::run.

Or use the ‘lgtunit::run_test_sets/1’ predicate to test all the
implementations:

     | ?- lgtunit::run_test_sets([
             tests(backend_random),
             tests(fast_random),
             tests(random)
          ]).


File: TheLogtalkHandbook-3.96.0.info,  Node: Test dialects,  Next: User-defined test dialects,  Prev: Parametric test objects,  Up: lgtunit

5.13.8 Test dialects
--------------------

Multiple test 'dialects' are supported by default.  See the next section
on how to define your own test dialects.  In all dialects, a 'ground
callable term', usually an atom, is used to uniquely identify a test.
This simplifies reporting failed tests and running tests selectively.
An error message is printed if invalid or duplicated test identifiers
are found.  These errors must be corrected; otherwise the reported test
results can be misleading.  Ideally, tests should have descriptive names
that clearly state the purpose of the test and what is being tested.

Unit tests can be written using any of the following predefined
dialects:

     test(Test) :- Goal.

This is the most simple dialect, allowing the specification of tests
that are expected to succeed.  The argument of the ‘test/1’ predicate is
the test identifier, which must be unique.  A more versatile dialect is:

     succeeds(Test) :- Goal.
     deterministic(Test) :- Goal.
     fails(Test) :- Goal.
     throws(Test, Ball) :- Goal.
     throws(Test, Balls) :- Goal.

This is a straightforward dialect.  For ‘succeeds/1’ tests, ‘Goal’ is
expected to succeed.  For ‘deterministic/1’ tests, ‘Goal’ is expected to
succeed once without leaving a choice-point.  For ‘fails/1’ tests,
‘Goal’ is expected to fail.  For ‘throws/2’ tests, ‘Goal’ is expected to
throw the exception term ‘Ball’ or one of the exception terms in the
list ‘Balls’.  The specified exception must subsume the actual exception
for the test to succeed.

An alternative test dialect that can be used with more expressive power
is:

     test(Test, Outcome) :- Goal.

The possible values of the outcome argument are:

   - 
          ‘true’
          The test is expected to succeed.

   - 
          ‘true(Assertion)’
          The test is expected to succeed and satisfy the ‘Assertion’ goal.

   - 
          ‘deterministic’
          The test is expected to succeed once without leaving a choice-point.

   - 
          ‘deterministic(Assertion)’
          The test is expected to succeed once without leaving a choice-point and satisfy the ‘Assertion’ goal.

   - 
          ‘subsumes(Expected, Result)’
          The test is expected to succeed by binding ‘Result’ to a term that is subsumed by the ‘Expected’ term.

   - 
          ‘variant(Term1, Term2)’
          The test is expected to succeed by binding ‘Term1’ to a term that is a variant of the ‘Term2’ term.

   - 
          ‘exists(Assertion)’
          A solution exists for the test goal that satisfies the ‘Assertion’ goal.

   - 
          ‘all(Assertion)’
          All test goal solutions satisfy the ‘Assertion’ goal.

   - 
          ‘fail’
          The test is expected to fail.

   - 
          ‘false’
          The test is expected to fail.

   - 
          ‘error(Error)’
          The test is expected to throw the exception term ‘error(ActualError, _)’ where ‘ActualError’ is subsumed ‘Error’.

   - 
          ‘errors(Errors)’
          The test is expected to throw an exception term ‘error(ActualError, _)’ where ‘ActualError’ is subsumed by an element of the list ‘Errors’.

   - 
          ‘ball(Ball)’
          The test is expected to throw the exception term ‘ActualBall’ where ‘ActualBall’ is subsumed ‘Ball’.

   - 
          ‘balls(Balls)’
          The test is expected to throw an exception term ‘ActualBall’ where ‘ActualBall’ is subsumed by an element of the list ‘Balls’.

In the case of the ‘true(Assertion)’, ‘deterministic(Assertion)’, and
‘all(Assertion)’ outcomes, a message that includes the assertion goal is
printed for assertion failures and errors to help to debug failed unit
tests.  Same for the ‘subsumes(Expected, Result)’ and ‘variant(Term1,
Term2)’ assertions.  Note that this message is only printed when the
test goal succeeds, as its failure will prevent the assertion goal from
being called.  This allows distinguishing between test goal failure and
assertion failure.

Note that the ‘all(Assertion)’ outcome simplifies pinpointing which test
goal solution failed the assertion.  See also the section below on
testing non-deterministic predicates.

The ‘fail’ and ‘false’ outcomes are better reserved for cases where
there is a single test goal.  With multiple test goals, the test will
succeed when 'any' of those goals fail.

Some tests may require individual condition, setup, or cleanup goals.
In this case, the following alternative test dialect can be used:

     test(Test, Outcome, Options) :- Goal.

The currently supported options are (non-recognized options are
ignored):

   - 
          ‘condition(Goal)’
          Condition for deciding if the test should be run or skipped (default goal is ‘true’).

   - 
          ‘setup(Goal)’
          Setup goal for the test (default goal is ‘true’).

   - 
          ‘cleanup(Goal)’
          Cleanup goal for the test (default goal is ‘true’).

   - 
          ‘flaky’
          Declare the test as a flaky test.

   - 
          ‘note(Term)’
          Annotation to print (between parentheses by default) after the test result (default is ‘''’); the annotation term can share variables with the test goal, which can be used to pass additional information about the test result.

Also supported is QuickCheck testing, where random tests are
automatically generated and run given a predicate mode template with
type information for each argument (see the section below for more
details):

     quick_check(Test, Template, Options).
     quick_check(Test, Template).

The valid options are the same as for the ‘test/3’ dialect plus all the
supported QuickCheck specific options (see the QuickCheck section below
for details).

For examples of how to write unit tests, check the ‘tests’ folder or the
‘testing’ example in the ‘examples’ folder in the Logtalk distribution.
Most of the provided examples also include unit tests, some of them with
code coverage.


File: TheLogtalkHandbook-3.96.0.info,  Node: User-defined test dialects,  Next: QuickCheck,  Prev: Test dialects,  Up: lgtunit

5.13.9 User-defined test dialects
---------------------------------

Additional test dialects can be easily defined by extending the
‘lgtunit’ object and by term-expanding the new dialect into one of the
default dialects.  As an example, suppose that you want a dialect where
you can simply write a file with tests defined by clauses using the
format:

     test_identifier :-
         test_goal.

First, we define an expansion for this file into a test object:

     :- object(simple_dialect,
         implements(expanding)).

         term_expansion(begin_of_file, [(:- object(tests,extends(lgtunit)))]).
         term_expansion((Head :- Body), [test(Head) :- Body]).
         term_expansion(end_of_file, [(:- end_object)]).

     :- end_object.

Then we can use this hook object to expand and run tests written in this
dialect by using a ‘tester.lgt’ driver file with contents such as:

     :- initialization((
         set_logtalk_flag(report, warnings),
         logtalk_load(lgtunit(loader)),
         logtalk_load(hook_flows(loader)),
         logtalk_load(simple_dialect),
         logtalk_load(tests, [hook(hook_pipeline([simple_dialect,lgtunit]))]),
         tests::run
     )).

The hook pipeline first applies our ‘simple_dialect’ expansion, followed
by the default ‘lgtunit’ expansion.  This solution allows other hook
objects (e.g., required by the code being tested) to also be used by
updating the pipeline.


File: TheLogtalkHandbook-3.96.0.info,  Node: QuickCheck,  Next: Skipping tests,  Prev: User-defined test dialects,  Up: lgtunit

5.13.10 QuickCheck
------------------

QuickCheck was originally developed for Haskell.  Implementations for
several other programming languages soon followed.  QuickCheck provides
support for 'property-based testing'.  The idea is to express properties
that predicates must comply with and automatically generate tests for
those properties.  The ‘lgtunit’ tool supports both ‘quick_check/2-3’
test dialects, as described above, and ‘quick_check/1-3’ public
predicates for interactive use:

     quick_check(Template, Result, Options).
     quick_check(Template, Options).
     quick_check(Template).

The following options are supported:

   - ‘n/1’: number of random tests that will be generated and run
     (default is 100).

   - ‘s/1’: maximum number of shrink operations when a counter-example
     is found (default is 64).

   - ‘ec/1’: boolean option deciding if type edge cases are tested
     before generating random tests (default is ‘true’).

   - ‘rs/1’: starting seed to be used when generating the random tests
     (no default).

   - ‘pc/1’: pre-condition closure for generated tests (extended with
     the test arguments; no default).

   - ‘l/1’: label closure for classifying the generated tests (extended
     with the test arguments plus the label argument; no default).

   - ‘v/1’: boolean option for verbose reporting of generated random
     tests (default is ‘false’).

   - ‘pb/2’: progress bar option for executed random tests when the
     verbose option is false (first argument is a boolean, default is
     ‘false’; second argument is the tick number, a positive integer).

The ‘quick_check/1’ predicate uses the default option values.  The
‘quick_check/1-2’ predicates print the test results and are thus better
reserved for testing at the top-level interpreter.  The ‘quick_check/3’
predicate returns results in reified form:

   - ‘passed(SequenceSeed, Discarded, Labels)’

   - ‘failed(Goal, SequenceSeed, TestSeed)’

   - ‘error(Error, Goal, SequenceSeed, TestSeed)’

   - ‘broken(Why, Culprit)’

The ‘broken(Why, Culprit)’ result only occurs when the user-defined
testing setup is broken.  For example, a non-callable template (e.g., a
non-existing predicate), an invalid option, a problem with the
pre-condition closure or with the label closure (e.g., a pre-condition
that always fails or a label that fails to classify a generated test),
or errors/failures when generating tests (e.g., due to an unknown type
being used in the template or a broken custom type arbitrary value
generator).

The ‘Goal’ argument is the random test that failed.

The ‘SequenceSeed’ argument is the starting seed used to generate the
sequence of random tests.  The ‘TestSeed’ is the seed used to generate
the test that failed.  Both seeds should be regarded as opaque terms.
When the test seed is equal to the sequence seed, this means that the
failure or error occurred while using only type edge cases.  See below
how to use the seeds when testing bug fixes.

The ‘Discarded’ argument returns the number of generated tests that were
discarded for failing to comply with a pre-condition specified using the
‘pc/1’ option.  This option is specially useful when constraining or
enforcing a relation between the generated arguments and is often used
as an alternative to define a custom type.  For example, if we define
the following predicate:

     condition(I) :-
         between(0, 127, I).

We can then use it to filter the generated tests:

     | ?- lgtunit::quick_check(integer(+byte), [pc(condition)]).
     % 100 random tests passed, 94 discarded
     % starting seed: seed(416,18610,17023)
     yes

The ‘Labels’ argument returns a list of pairs ‘Label-N’ where ‘N’ is the
number of generated tests that are classified as ‘Label’ by a closure
specified using the ‘l/1’ option.  For example, assuming the following
predicate definition:

     label(I, Label) :-
         (   I mod 2 =:= 0 ->
             Label = even
         ;   Label = odd
         ).

We can try:

     | ?- lgtunit::quick_check(integer(+byte), [l(label), n(10000)]).
     % 10000 random tests passed, 0 discarded
     % starting seed: seed(25513,20881,16407)
     % even: 5037/10000 (50.370000%)
     % odd: 4963/10000 (49.630000%)
     yes

The label statistics are key to verifying that the generated tests
provide the necessary coverage.  The labeling predicates can return a
single test label or a list of test labels.  Labels should be ground and
are typically atoms.  To examine the generated tests themselves, you can
use the verbose option, ‘v/1’.  For example:

     | ?- lgtunit::quick_check(integer(+integer), [v(true), n(7), pc([I]>>(I>5))]).
     % Discarded: integer(0)
     % Passed:    integer(786)
     % Passed:    integer(590)
     % Passed:    integer(165)
     % Discarded: integer(-412)
     % Passed:    integer(440)
     % Discarded: integer(-199)
     % Passed:    integer(588)
     % Discarded: integer(-852)
     % Discarded: integer(-214)
     % Passed:    integer(196)
     % Passed:    integer(353)
     % 7 random tests passed, 5 discarded
     % starting seed: seed(23671,3853,29824)
     yes

When a counter-example is found, the verbose option also prints the
shrink steps.  For example:

     | ?- lgtunit::quick_check(atom(+atomic), [v(true), ec(false)]).
     % Passed:    atom('dyO=Xv_MX-3b/U4KH U')
     *     Failure:   atom(-198)
     *     Shrinked:  atom(-99)
     *     Shrinked:  atom(-49)
     *     Shrinked:  atom(-24)
     *     Shrinked:  atom(-12)
     *     Shrinked:  atom(-6)
     *     Shrinked:  atom(-3)
     *     Shrinked:  atom(-1)
     *     Shrinked:  atom(0)
     *     quick check test failure (at test 2 after 8 shrinks):
     *       atom(0)
     *     starting seed: seed(3172,9814,20125)
     *     test seed:     seed(7035,19506,18186)
     no

The template can be a ‘(::)/2’, ‘(<<)/2’, or ‘(:)/2’ qualified callable
term.  When the template is an unqualified callable term, it will be
used to construct a goal to be called in the context of the 'sender'
using the ‘(<<)/2’ debugging control construct.  Another simple example
is passing a template that will trigger a failed test (as the
‘random::random/1’ predicate always returns non-negative floats):

     | ?- lgtunit::quick_check(random::random(-negative_float)).
     *     quick check test failure (at test 1 after 0 shrinks):
     *       random::random(0.09230089279334841)
     *     starting seed: seed(3172,9814,20125)
     *     test seed:     seed(3172,9814,20125)
     no

When QuickCheck exposes a bug in the tested code, we can use the
reported counter-example to help diagnose it and fix it.  As tests are
randomly generated, we can use the starting seed reported with the
counter-example to confirm the bug fix by calling the ‘quick_check/2-3’
predicates with the ‘rs(Seed)’ option.  For example, assume the
following broken predicate definition:

     every_other([], []).
     every_other([_, X| L], [X | R]) :-
         every_other(L, R).

The predicate is supposed to construct a list by taking every other
element of an input list.  Cursory testing may fail to notice the bug:

     | ?- every_other([1,2,3,4,5,6], List).
     List = [2, 4, 6]
     yes

But QuickCheck will report a bug with lists with an odd number of
elements with a simple property that verifies that the predicate always
succeeds and returns a list of integers:

     | ?- lgtunit::quick_check(every_other(+list(integer), -list(integer))).
     *     quick check test failure (at test 2 after 0 shrinks):
     *       every_other([0],A)
     *     starting seed: seed(3172,9814,20125)
     *     test seed:     seed(3172,9814,20125)
     no

We could fix this particular bug by rewriting the predicate:

     every_other([], []).
     every_other([H| T], L) :-
         every_other(T, H, L).

     every_other([], X, [X]).
     every_other([_| T], X, [X| L]) :-
         every_other(T, L).

By retesting with the same test seed that uncovered the bug, the same
random test that found the bug will be generated and run again:

     | ?- lgtunit::quick_check(
             every_other(+list(integer), -list(integer)),
             [rs(seed(3172,9814,20125))]
          ).
     % 100 random tests passed, 0 discarded
     % starting seed: seed(3172,9814,20125)
     yes

Still, after verifying the bug fix, is also a good idea to re-run the
tests using the sequence seed instead, as bug fixes sometimes cause
regressions elsewhere.

When retesting using the ‘logtalk_tester’ automation script, the
starting seed can be set using the ‘-r’ option.  For example:

     $ logtalk_tester -r "seed(3172,9814,20125)"

We could now move to other properties that the predicate should comply
with (e.g., all elements in the output list being present in the input
list).  Often, both traditional unit tests and QuickCheck tests are
used, complementing each other to ensure the required code coverage.

Another example using a Prolog module predicate:

     | ?- lgtunit::quick_check(
             pairs:pairs_keys_values(
                 +list(pair(atom,integer)),
                 -list(atom),
                 -list(integer)
             )
          ).
     % 100 random tests passed, 0 discarded
     % starting seed: seed(3172,9814,20125)
     yes

As illustrated by the examples above, properties are expressed using
predicates.  In the most simple cases, that can be the predicate that we
are testing itself.  But, in general, it will be an auxiliary predicate
calling the predicate or predicates being tested and checking properties
that the results must comply with.

The QuickCheck test dialects and predicates take as argument the mode
template for a property, generate random values for each input argument
based on the type information, and check each output argument.  For
common types, the implementation tries first (by default) common edge
cases (e.g., empty atom, empty list, or zero) before generating
arbitrary values.  When the output arguments check fails, the QuickCheck
implementation tries (by default) up to 64 shrink operations of the
counter-example to report a simpler case to help debugging the failed
test.  Edge cases, generating arbitrary terms, and shrinking terms make
use of the library ‘arbitrary’ category via the ‘type’ object (both
entities can be extended by the user by defining clauses for multifile
predicates).

The mode template syntax is the same as that used in the ‘info/2’
predicate directives with an additional notation, ‘{}/1’, for passing
argument values as-is instead of generating random values for these
arguments.  For example, assume that we want to verify the
‘type::valid/2’ predicate, which takes as its first argument a type.
Randomly generating random types would be cumbersome at best but the
main problem is that we need to generate random values for the second
argument according to the first argument.  Using the ‘{}/1’ notation, we
can solve this problem for any specific type, e.g.  integer, by writing:

     | ?- lgtunit::quick_check(type::valid({integer}, +integer)).

We can also test all (ground, i.e.  non-parametric) types with arbitrary
value generators by writing:

     | ?- forall(
             (type::type(Type), ground(Type), type::arbitrary(Type)),
             lgtunit::quick_check(type::valid({Type}, +Type))
          ).

You can find the list of the basic supported types for use in the
template in the API documentation for the library entities ‘type’ and
‘arbitrary’.  Note that other library entities, including third-party or
your own, can contribute with additional type definitions, as both
‘type’ and ‘arbitrary’ entities are user-extensible by defining clauses
for their multifile predicates.

The user can define new types to use in the property mode templates to
use with its QuickCheck tests by defining clauses for the ‘type’ library
object and the ‘arbitrary’ library category multifile predicates.
QuickCheck will use the later to generate arbitrary input arguments and
the former to verify output arguments.  As a toy example, assume that
the property mode template has an argument of type ‘bit’ with possible
values ‘0’ and ‘1’.  We would then need to define:

     :- multifile(type::type/1).
     type::type(bit).

     :- multifile(type::check/2).
     type::check(bit, Term) :-
         once((Term == 0; Term == 1)).

     :- multifile(arbitrary::arbitrary/1).
     arbitrary::arbitrary(bit).

     :- multifile(arbitrary::arbitrary/2).
     arbitrary::arbitrary(bit, Arbitrary) :-
         random::member(Arbitrary, [0, 1]).


File: TheLogtalkHandbook-3.96.0.info,  Node: Skipping tests,  Next: Selecting tests,  Prev: QuickCheck,  Up: lgtunit

5.13.11 Skipping tests
----------------------

A test object can define the ‘condition/0’ predicate (which defaults to
‘true’) to test if some necessary condition for running the tests holds.
The tests are skipped if the call to this predicate fails or generates
an error.

Individual tests that for some reason should be unconditionally skipped
can have the test clause head prefixed with the ‘(-)/1’ operator.  For
example:

     - test(not_yet_ready) :-
         ...

In this case, it’s a good idea to use the ‘test/3’ dialect with a
‘note/1’ option that briefly explains why the test is being skipped.
For example:

     - test(xyz_reset, true, [note('Feature xyz reset not yet implemented')]) :-
         ...

The number of skipped tests is reported together with the numbers of
passed and failed tests.  To skip a test depending on some condition,
use the ‘test/3’ dialect and the ‘condition/1’ option.  For example:

     test(test_id, true, [condition(current_prolog_flag(bounded,true))) :-
         ...

The test is skipped if the condition goal fails or generates an error.
The conditional compilation directives can also be used in alternative,
but note that in this case there will be no report on the number of
skipped tests.


File: TheLogtalkHandbook-3.96.0.info,  Node: Selecting tests,  Next: Checking test goal results,  Prev: Skipping tests,  Up: lgtunit

5.13.12 Selecting tests
-----------------------

While debugging an application, we often want to temporarily run just a
selection of relevant tests.  This is specially useful when running all
the tests slows down and distracts from testing fixes for a specific
issue.  This can be accomplished by prefixing the clause heads of the
selected tests with the ‘(+)/1’ operator.  For example:

     :- object(tests,
         extends(lgtunit)).

         cover(ack).

         test(ack_1, true(Result == 11)) :-
             ack::ack(2, 4, Result).

         + test(ack_2, true(Result == 61)) :-
             ack::ack(3, 3, Result).

         test(ack_3, true(Result == 125)) :-
             ack::ack(3, 4, Result).

     :- end_object.

In this case, only the ‘ack_2’ would run.  Just be careful to remove all
‘(+)/1’ test prefixes when done debugging the issue that prompted you to
run just the selected tests.  After, be sure to run all the tests to
ensure there are no regressions introduced by your fixes.


File: TheLogtalkHandbook-3.96.0.info,  Node: Checking test goal results,  Next: Testing local predicates,  Prev: Selecting tests,  Up: lgtunit

5.13.13 Checking test goal results
----------------------------------

Checking test goal results can be performed using the ‘test/2-3’
supported outcomes such as ‘true(Assertion)’ and
‘deterministic(Assertion)’.  For example:

     test(compare_3_order_less, deterministic(Order == (<))) :-
         compare(Order, 1, 2).

For the other test dialects, checking test goal results can be performed
by calling the ‘assertion/1-2’ utility predicates or by writing the
checking goals directly in the test body.  For example:

     test(compare_3_order_less) :-
         compare(Order, 1, 2),
         ^^assertion(Order == (<)).

or:

     succeeds(compare_3_order_less) :-
         compare(Order, 1, 2),
         Order == (<).

Using assertions is, however, preferable to directly checking test
results in the test body as it facilitates debugging by printing the
unexpected results when the assertions fail.

The ‘assertion/1-2’ utility predicates are also useful for the
‘test/2-3’ dialects when we want to check multiple assertions in the
same test.  For example:

     test(dictionary_clone_4_01, true) :-
         as_dictionary([], Dictionary),
         clone(Dictionary, DictionaryPairs, Clone, ClonePairs),
         empty(Clone),
         ^^assertion(original_pairs, DictionaryPairs == []),
         ^^assertion(clone_pairs, ClonePairs == []).

Ground results can be compared using the standard ‘==/2’ term equality
built-in predicate.  Non-ground results can be compared using the
‘variant/2’ predicate provided by ‘lgtunit’.  The standard
‘subsumes_term/2’ built-in predicate can be used when testing a compound
term structure while abstracting some of its arguments.  Floating-point
numbers can be compared using the ‘=~=/2’, ‘approximately_equal/3’,
‘essentially_equal/3’, and ‘tolerance_equal/4’ predicates provided by
‘lgtunit’.  Using the ‘=/2’ term unification built-in predicate is
almost always an error, as it would mask test goals failing to bind
output arguments.  The ‘lgtunit’ tool implements a linter check for the
use of unification goals in test outcome assertions.  In the rare cases
that a unification goal is intended, wrapping the ‘(=)/2’ goal using the
‘{}/1’ control construct avoids the linter warning.

When the meta-argument of the ‘assertion/1-2’ predicates is call to a
local predicate (in the tests object), you need to call them using the
‘(::)/2’ message-sending control construct instead of the ‘(^^)/2’
'super' call control construct.  This is necessary as 'super' calls
preserve the 'sender', and the tests are implicitly run by the ‘lgtunit’
object sending a message to the tests object.  For example:

     :- uses(lgtunit, [
         assertion/1
     ]).

     test(my_test_id, true) :-
         foo(X, Y),
         assertion(consistent(X, Y)).

     consistent(X, Y) :-
         ...

In this case, the 'sender' is the tests object, and the ‘assertion/1’
meta-predicate will call the local ‘consistent/2’ predicate in the
expected context.


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing local predicates,  Next: Testing non-deterministic predicates,  Prev: Checking test goal results,  Up: lgtunit

5.13.14 Testing local predicates
--------------------------------

The ‘(<<)/2’ debugging control construct can be used to access and test
object local predicates (i.e., predicates without a scope directive).
In this case, make sure that the ‘context_switching_calls’ compiler flag
is set to ‘allow’ for those objects.  This is seldom required, however,
as local predicates are usually auxiliary predicates called by public
predicates and thus tested when testing those public predicates.  The
code coverage support can pinpoint any local predicate clause that is
not being exercised by the tests.


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing non-deterministic predicates,  Next: Testing generators,  Prev: Testing local predicates,  Up: lgtunit

5.13.15 Testing non-deterministic predicates
--------------------------------------------

For testing non-deterministic predicates (with a finite and manageable
number of solutions), you can wrap the test goal using the standard
‘findall/3’ predicate to collect all solutions and check against the
list of expected solutions.  When the expected solutions are a set, use
in alternative the standard ‘setof/3’ predicate.

If you want to check that all solutions of a non-deterministic predicate
satisfy an assertion, use the ‘test/2’ or ‘test/3’ test dialect with the
‘all(Assertion)’ outcome.  For example:

     test(atom_list, all(atom(Item))) :-
         member(Item, [a, b, c]).

See also the next section on testing 'generators'.

If you want to check that a solution exists for a non-deterministic
predicate that satisfies an assertion, use the ‘test/2’ or ‘test/3’ test
dialect with the ‘exists(Assertion)’ outcome.  For example:

     test(at_least_one_atom, exists(atom(Item))) :-
         member(Item, [1, foo(2), 3.14, abc, 42]).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing generators,  Next: Testing input/output predicates,  Prev: Testing non-deterministic predicates,  Up: lgtunit

5.13.16 Testing generators
--------------------------

To test all solutions of a predicate that acts as a 'generator', we can
use either the ‘all/1’ outcome or the ‘forall/2’ predicate as the test
goal with the ‘assertion/2’ predicate called to report details on any
solution that fails the test.  For example:

     test(test_solution_generator, all(test(X,Y,Z))) :-
         generator(X, Y, Z).

or:

     :- uses(lgtunit, [assertion/2]).
     ...

     test(test_solution_generator_2) :-
         forall(
             generator(X, Y, Z),
             assertion(generator(X), test(X,Y,Z))
         ).

While using the ‘all/1’ outcome results in a more compact test
definition, using the ‘forall/2’ predicate allows customizing the
assertion description.  In the example above, we use the ‘generator(X)’
description instead of the ‘test(X,Y,Z)’ description implicit when we
use the ‘all/1’ outcome.


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing input/output predicates,  Next: Suppressing tested predicates output,  Prev: Testing generators,  Up: lgtunit

5.13.17 Testing input/output predicates
---------------------------------------

Extensive support for testing input/output predicates is provided, based
on similar support found on the Prolog conformance testing framework
written by Péter Szabó and Péter Szeredi.

Two sets of predicates are provided, one for testing text input/output
and one for testing binary input/output.  In both cases, temporary files
(possibly referenced by a user-defined alias) are used.  The predicates
allow setting, checking, and cleaning text/binary input/output.  These
predicates are declared as protected and thus called using the ‘(^^/1)’
control construct.

As an example of testing an input predicate, consider the standard
‘get_char/1’ predicate.  This predicate reads a single character (atom)
from the current input stream.  Some test for basic functionality could
be:

     test(get_char_1_01, true(Char == 'q')) :-
         ^^set_text_input('qwerty'),
         get_char(Char).

     test(get_char_1_02, true(Assertion)) :-
         ^^set_text_input('qwerty'),
         get_char(_Char),
         ^^text_input_assertion('werty', Assertion).

As you can see in the above example, the testing pattern consists on
setting the input for the predicate being tested, calling it, and then
checking the results.  It is also possible to work with streams other
than the current input/output streams by using the ‘lgtunit’ predicate
variants that take a stream alias as argument.  For example, when
testing the standard ‘get_char/2’ predicate, we could write:

     test(get_char_2_01, true(Char == 'q')) :-
         ^^set_text_input(in, 'qwerty'),
         get_char(in, Char).

     test(get_char_2_02, true(Assertion)) :-
         ^^set_text_input(in, 'qwerty'),
         get_char(in, _Char),
         ^^text_input_assertion(in, 'werty', Assertion).

Testing output predicates follows a similar pattern by using instead the
‘set_text_output/1-2’ and ‘text_output_assertion/2-3’ predicates.  For
example:

     test(put_char_2_02, true(Assertion)) :-
         ^^set_text_output(out, 'qwert'),
         put_char(out, y),
         ^^text_output_assertion(out, 'qwerty', Assertion).

The ‘set_text_output/1’ predicate diverts only the standard output
stream (to a temporary file) using the standard ‘set_output/1’
predicate.  Most backend Prolog systems also support writing to the de
facto standard error stream.  But there’s no standard solution to divert
this stream.  However, several systems provide a ‘set_stream/2’ or
similar predicate that can be used for stream redirection.  For example,
assume that you wanted to test a backend Prolog system warning when an
‘initialization/1’ directive fails that is written to ‘user_error’.  An
hypothetical test could be:

     test(singletons_warning, true(Assertion)) :-
         ^^set_text_output(''),
         current_output(Stream),
         set_stream(Stream, alias(user_error)),
         consult(broken_file),
         ^^text_output_assertion('WARNING: initialization/1 directive failed', Assertion).

For testing binary input/output predicates, equivalent testing
predicates are provided.  There is also a small set of helper predicates
for dealing with stream handles and stream positions.  For testing with
files instead of streams, testing predicates are provided that allow
creating text and binary files with given contents and check text and
binary files for expected contents.

For more practical examples, check the included tests for Prolog
standard conformance of built-in input/output predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Suppressing tested predicates output,  Next: Tests with timeout limits,  Prev: Testing input/output predicates,  Up: lgtunit

5.13.18 Suppressing tested predicates output
--------------------------------------------

Sometimes predicates being tested output text or binary data that, at
best, clutters testing logs and, at worst, can interfere with parsing of
test logs.  If that output itself is not under testing, you can suppress
it by using the goals ‘^^suppress_text_output’ or
‘^^suppress_binary_output’ at the beginning of the tests.  For example:

     test(proxies_04, true(Color == yellow)) :-
         ^^suppress_text_output,
         {circle('#2', Color)}::print.

The ‘suppress_text_output/0’ and ‘suppress_binary_output/0’ predicates
work by redirecting standard output to the operating-system null device.
But the application may also output to e.g.  ‘user_error’ and other
streams.  If this output must also be suppressed, several alternatives
are described next.

Output of expected warnings can be suppressed by turning off the
corresponding linter flags.  In this case, it is advisable to restrict
the scope of the flag value changes as much as possible.

Output of expected compiler errors can be suppressed by defining
suitable clauses for the ‘logtalk::message_hook/4’ hook predicate.  For
example:

     :- multifile(logtalk::message_hook/4).
     :- dynamic(logtalk::message_hook/4).

     % ignore expected domain error
     logtalk::message_hook(compiler_error(_,_,error(domain_error(foo,bar),_)), error, core, _).

In this case, it is advisable to restrict the scope of the clauses as
much as possible to exact exception terms.  For the exact message terms,
see the ‘core_messages’ category source file.  Defining this hook
predicate can also be used to suppress all messages from a given
component.  For example:

     :- multifile(logtalk::message_hook/4).
     :- dynamic(logtalk::message_hook/4).

     logtalk::message_hook(_Message, _Kind, code_metrics, _Tokens).

Note that there’s no portable solution to suppress 'all' output.
However, several systems provide a ‘set_stream/2’ or similar predicate
that can be used for stream redirection.  Check the documentation of the
backend Prolog systems you’re using for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Tests with timeout limits,  Next: Setup and cleanup goals,  Prev: Suppressing tested predicates output,  Up: lgtunit

5.13.19 Tests with timeout limits
---------------------------------

There’s no portable way to call a goal with a timeout limit.  However,
some backend Prolog compilers provide this functionality:

   - B-Prolog: ‘time_out/3’ built-in predicate

   - ECLiPSe: ‘timeout/3’ and ‘timeout/7’ library predicates

   - XVM: ‘call_with_timeout/2-3’ built-in predicates

   - SICStus Prolog: ‘time_out/3’ library predicate

   - SWI-Prolog: ‘call_with_time_limit/2’ library predicate

   - Trealla Prolog: ‘call_with_time_limit/2’ and ‘time_out/3’ library
     predicates

   - XSB: ‘timed_call/2’ built-in predicate

   - YAP: ‘time_out/3’ library predicate

Logtalk provides a ‘timeout’ portability library implementing a simple
abstraction for those backend Prolog compilers.

The ‘logtalk_tester’ automation script accepts a timeout option that can
be used to set a limit per-test set.


File: TheLogtalkHandbook-3.96.0.info,  Node: Setup and cleanup goals,  Next: Test annotations,  Prev: Tests with timeout limits,  Up: lgtunit

5.13.20 Setup and cleanup goals
-------------------------------

A test object can define ‘setup/0’ and ‘cleanup/0’ goals.  The ‘setup/0’
predicate is called, when defined, before running the object unit tests.
The ‘cleanup/0’ predicate is called, when defined, after running all the
object unit tests.  The tests are skipped when the setup goal fails or
throws an error.  For example:

     cleanup :-
         this(This),
         object_property(This, file(_,Directory)),
         atom_concat(Directory, serialized_objects, File),
         catch(ignore(os::delete_file(File)), _, true).

Per test setup and cleanup goals can be defined using the ‘test/3’
dialect and the ‘setup/1’ and ‘cleanup/1’ options.  The test is skipped
when the setup goal fails or throws an error.  Note that a broken test
cleanup goal doesn’t affect the test but may adversely affect any
following tests.  Variables in the setup and cleanup goals are shared
with the test body.


File: TheLogtalkHandbook-3.96.0.info,  Node: Test annotations,  Next: Test execution times and memory usage,  Prev: Setup and cleanup goals,  Up: lgtunit

5.13.21 Test annotations
------------------------

It’s possible to define per-unit and per-test annotations to be printed
after the test results or when tests are skipped.  This is particularly
useful when some units or some unit tests may be run while still being
developed.  Annotations can be used to pass additional information to a
user reviewing test results.  By intercepting the unit test framework
message printing calls (using the ‘message_hook/4’ hook predicate), test
automation scripts and integrating tools can also access these
annotations.

Units can define a global annotation using the predicate ‘note/1’.  To
define per-test annotations, use the ‘test/3’ dialect and the ‘note/1’
option.  For example, you can inform why a test is being skipped by
writing:

     - test(foo_1, true, [note('Waiting for Deep Thought answer')]) :-
         ...

Another common use is to return the execution time of one of the test
sub-goals.  For example:

     test(foobar, true, [note(bar(seconds-Time))]) :-
         foo(...),
         benchmark(bar(...), Time).

Annotations are written, by default, between parentheses after and in
the same line as the test results.


File: TheLogtalkHandbook-3.96.0.info,  Node: Test execution times and memory usage,  Next: Working with test data files,  Prev: Test annotations,  Up: lgtunit

5.13.22 Test execution times and memory usage
---------------------------------------------

Individual test CPU and wall execution times (in seconds) are reported
by default when running the tests.  Total CPU and wall execution times
for passed and failed tests are reported after the tests complete.
Starting and ending date and time when running a set of tests is also
reported by default.  The ‘lgtunit’ object also provides several public
benchmarking predicates that can be useful for e.g.  reporting test
sub-goals execution times using either CPU or wall clocks.  When running
multi-threaded code, the CPU time may or may not include all threads CPU
time depending on the backend.

Be aware that the accuracy of CPU and wall time depends of the backend.
Accuracy can also be different between CPU and wall time (e.g.  CPU time
can have nanosecond accuracy with wall time only having millisecond
accuracy).

Test memory usage is not reported by default due to the lack of a
portable solution to access memory data.  However, several backend
Prolog systems provide a ‘statistics/2’ or similar predicate that can be
used for a custom solution.  Depending on the system, individual keys
may be provided for each memory area (heap, trail, atom table, …).
Aggregating keys may also be provided.  As a hypothetical example,
assume you’re running Logtalk with a backend providing a ‘statistics/2’
predicate with a ‘memory_used’ key:

     test(ack_3, true(Result == 125), [note(memory-Memory)]) :-
         statistics(memory_used, Memory0),
         ack::ack(3, 4, Result),
         statistics(memory_used, Memory1),
         Memory is Memory1 - Memory0.

Consult the documentation of the backend Prolog systems for actual
details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Working with test data files,  Next: Flaky tests,  Prev: Test execution times and memory usage,  Up: lgtunit

5.13.23 Working with test data files
------------------------------------

Frequently, tests make use of test data files that are usually stored in
the test set directory or in sub-directories.  These data files are
referenced using their relative paths.  But to allow the tests to run
independently of the Logtalk process current directory, the relative
paths often must be expanded into an absolute path before being passed
to the predicates being tested.  The ‘file_path/2’ protected predicate
can be used in the test definitions to expand the relative paths.  For
example:

     % check that the encoding/1 option is accepted
     test(lgt_unicode_open_4_01, true) :-
         ^^file_path(sample_utf_8, Path),
         open(Path, write, Stream, [encoding('UTF-8')]),
         close(Stream).

The absolute path is computed relative to the path of 'self', i.e.
relative to the path of the test object that received the message that
runs the tests.

It’s also common for tests to create temporary files and directories
that should be deleted after the tests completion.  The ‘clean_file/1’
and ‘clean_directory/1’ protected predicates can be used for this
purpose.  For example, assuming that the tests create a ‘foo.txt’ text
file and a ‘tmp’ directory in the same directory as the tests object:

     cleanup :-
         ^^clean_file('foo.txt'),
         ^^clean_directory('tmp').

Similar to the ‘file_path/2’ predicate, relative paths are interpreted
as relative to the path of the test object.  This predicate also closes
any open stream connected to the file before deleting it.


File: TheLogtalkHandbook-3.96.0.info,  Node: Flaky tests,  Next: Mocking,  Prev: Working with test data files,  Up: lgtunit

5.13.24 Flaky tests
-------------------

Flaky tests are tests that pass or fail non-deterministically, usually
due to external conditions (e.g., computer or network load).  Thus,
flaky tests often don’t result from bugs in the code being tested itself
but from test execution conditions that are not predictable.  The
‘flaky/0’ test option declares a test to be flaky.  For example:

     test(foo, true, [flaky]) :-
         ...

For backwards compatibility, the ‘note/1’ annotation can also be used to
alert that a test failure is for a flaky test when its argument is an
atom containing the sub-atom ‘flaky’.

The testing automation support outputs the text ‘[flaky]’ when reporting
failed flaky tests.  Moreover, the ‘logtalk_tester’ automation script
will ignore failed flaky tests when setting its exit status.


File: TheLogtalkHandbook-3.96.0.info,  Node: Mocking,  Next: Debugging messages in tests,  Prev: Flaky tests,  Up: lgtunit

5.13.25 Mocking
---------------

Sometimes the code being tested performs complex tasks that are not
feasible or desirable when running tests.  For example, the code may
perform a login operation requiring the user to provide a username and a
password using some GUI widget.  In this case, the tests may require the
login operation to still be performed but using canned data (also
simplifying testing automation).  I.e.  we want to 'mock' (as in
'imitate') the login procedure.  Ideally, this should be accomplished
without requiring any changes to the code being tested.  Logtalk
provides two solutions that can be used for mocking: 'term-expansion'
and 'hot patching'.  A third solution is possible if the code we want to
mock uses the 'message printing mechanism'.

Using the term-expansion mechanism, we would define a 'hook object' that
expands the login predicate into a fact:

     :- object(mock_login,
         implements(expanding)).

         term_expansion((login(_, _) :- _), login(jdoe, test123)).

     :- end_object.

The tests driver file would then load the application object responsible
for user management using this hook object:

     :- initialization((
         ...,
         logtalk_load(mock_login),
         logtalk_load(user_management, [hook(mock_login)]),
         ...
     )).

Using hot patching, we would define a 'complementing category' patching
the object that defines the login predicate:

     :- category(mock_login,
         complements(user_management)).

         login(jdoe, test123).

     :- end_category.

The tests driver file would then set the ‘complements’ flag to ‘allow’
and load the patch after loading application code:

     :- initialization((
         ...,
         set_logtalk_flag(complements, allow),
         logtalk_load(application),
         logtalk_load(mock_login),
         ...
     )).

There are pros and cons for each solution.  Term-expansion works by
defining hook objects that are used at compile-time, while hot patching
happens at runtime.  Complementing categories can also be dynamically
created, stacked, and abolished.  Hot patching disables static binding
optimizations, but that’s usually not a problem as the code being tested
is often compiled in debug mode to collect code coverage data.  Two
advantages of the term-expansion solution are that it allows defining
conditions for expanding terms and goals and can replace both predicate
definitions and predicate calls.  Limitations in the current Prolog
standards prevent patching callers to local predicates being patched.
But often both solutions can be used, with the choice depending on code
clarity and user preference.  See the Handbook sections on
term-expansion and hot patching for more details on these mechanisms.

In those cases where the code we want to mock uses the message printing
mechanism, the solution is to intercept and rewrite the messages being
printed and/or the questions being asked using the
‘logtalk::message_hook/4’ and ‘logtalk::question_hook/6’ hook
predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Debugging messages in tests,  Next: Debugging failed tests,  Prev: Mocking,  Up: lgtunit

5.13.26 Debugging messages in tests
-----------------------------------

Sometimes it is useful to write debugging or logging messages from tests
when running them manually.  But those messages are better suppressed
when running the tests automated.  A common solution is to use debug
'meta-messages'.  For example:

     :- uses(logtalk, [
         print_message(debug, my_app, Message) as dbg(Message)
     ]).

     test(some_test_id, ...) :-
         ...,
         dbg('Some intermediate value'-Value),
         ...,
         dbg([Stream]>>custom_print_goal(Stream, ...)),
         ...

The messages are only printed (and the user-defined printing goals are
only called) when the ‘debug’ flag is turned on.  Note that this doesn’t
require compiling the tests in debug mode: you simply toggle the flag to
toggle the debug messages.  Also note that the ‘print_message/3’ goals
are suppressed by the compiler when compiling with the ‘optimize’ flag
turned on.


File: TheLogtalkHandbook-3.96.0.info,  Node: Debugging failed tests,  Next: Code coverage,  Prev: Debugging messages in tests,  Up: lgtunit

5.13.27 Debugging failed tests
------------------------------

Debugging of failed unit tests is simplified by using test assertions as
the reason for the assertion failures is printed out.  Thus, use
preferably the ‘test/2-3’ dialects with ‘true(Assertion)’,
‘deterministic(Assertion)’, ‘subsumes(Expected, Result)’, or
‘variant(Term1, Term2)’ outcomes.  If a test checks multiple assertions,
you can use the predicate ‘assertion/2’ in the test body.  In the case
of QuickCheck tests, the ‘v(true)’ verbose option can be used to print
the generated test case that failed if necessary.

If the assertion failures don’t provide enough information, you can use
the ‘debugger’ tool to debug failed unit tests.  Start by compiling the
unit test objects and the code being tested in debug mode.  Load the
debugger and trace the test that you want to debug.  For example,
assuming your tests are defined in a ‘tests’ object and that the
identifier of the test to be debugged is ‘test_foo’:

     | ?- logtalk_load(debugger(loader)).
     ...

     | ?- debugger::trace.
     ...

     | ?- tests::run(test_foo).
     ...

You can also compile the code and the tests in debug mode but without
using the ‘hook/1’ compiler option for the tests compilation.  Assuming
that the ‘context_switching_calls’ flag is set to ‘allow’, you can then
use the ‘(<<)/2’ debugging control construct to debug the tests.  For
example, assuming that the identifier of the test to be debugged is
‘test_foo’ and that you used the ‘test/1’ dialect:

     | ?- logtalk_load(debugger(loader)).
     ...

     | ?- debugger::trace.
     ...

     | ?- tests<<test(test_foo).
     ...

In the more complicated cases, it may be worth defining
‘loader_debug.lgt’ and ‘tester_debug.lgt’ driver files that load code
and tests in debug mode and also load the debugger.


File: TheLogtalkHandbook-3.96.0.info,  Node: Code coverage,  Next: Utility predicates,  Prev: Debugging failed tests,  Up: lgtunit

5.13.28 Code coverage
---------------------

If you want entity predicate clause coverage information to be collected
and printed, you will need to compile the entities that you’re testing
using the flags ‘debug(on)’ and ‘source_data(on)’.  Be aware, however,
that compiling in debug mode results in a performance penalty.

A single test object may include tests for one or more entities
(objects, protocols, and categories).  The entities being tested by a
unit test object for which code coverage information should be collected
must be declared using the ‘cover/1’ predicate.  For example, to collect
code coverage data for the objects ‘foo’ and ‘bar’ include in the tests
object the two clauses:

     cover(foo).
     cover(bar).

Code coverage is listed using the predicates clause indexes (counting
from one).  For example, using the ‘points’ example in the Logtalk
distribution:

     % point: default_init_option/1 - 2/2 - (all)
     % point: instance_base_name/1 - 1/1 - (all)
     % point: move/2 - 1/1 - (all)
     % point: position/2 - 1/1 - (all)
     % point: print/0 - 1/1 - (all)
     % point: process_init_option/1 - 1/2 - [1]
     % point: position_/2 - 0/0 - (all)
     % point: 7 out of 8 clauses covered, 87.500000% coverage

The numbers after the predicate indicators represent the clauses covered
and the total number of clauses.  E.g.  for the ‘process_init_option/1’
predicate, the tests cover 1 out of 2 clauses.  After these numbers, we
either get ‘(all)’ telling us that all clauses are covered or a list of
indexes for the covered clauses.  E.g.  only the first clause for the
‘process_init_option/1’ predicate, ‘[1]’.  Summary clause coverage
numbers are also printed for entities and for clauses across all
entities.

In the printed predicate clause coverage information, you may get a
total number of clauses smaller than the covered clauses.  This results
from the use of dynamic predicates with clauses asserted at runtime.
You may easily identify dynamic predicates in the results as their
clauses often have an initial count equal to zero.

The list of indexes of the covered predicate clauses can be quite long.
Some backend Prolog compilers provide a flag or a predicate to control
the depth of printed terms that can be useful:

   - CxProlog: ‘write_depth/2’ predicate

   - ECLiPSe: ‘print_depth’ flag

   - SICStus Prolog: ‘toplevel_print_options’ flag

   - SWI-Prolog 7.1.10 or earlier: ‘toplevel_print_options’ flag

   - SWI-Prolog 7.1.11 or later: ‘answer_write_options’ flag

   - Trealla Prolog: ‘answer_write_options’ flag

   - XSB: ‘set_file_write_depth/1’ predicate

   - XVM 3.2.0 or later: ‘answer_write_options’ flag

   - YAP: ‘write_depth/2-3’ predicates

Code coverage is only available when testing Logtalk code.  But Prolog
modules can often be compiled as Logtalk objects and plain Prolog code
may be wrapped in a Logtalk object.  For example, assuming a ‘module.pl’
module file, we can compile and load the module as an object by simply
calling:

     | ?- logtalk_load(module).
     ...

The module exported predicates become object public predicates.  For a
plain Prolog file, say ‘plain.pl’, we can define a Logtalk object that
wraps the code using an ‘include/1’ directive:

     :- object(plain).

         :- include('plain.pl').

     :- end_object.

The object can also declare as public the top Prolog predicates to
simplify writing the tests.  In alternative, we can use the
‘object_wrapper_hook’ provided by the ‘hook_objects’ library:

     | ?- logtalk_load(hook_objects(loader)).
     ...

     | ?- logtalk_load(plain, [hook(object_wrapper_hook)]).
     ...

These workarounds may thus allow generating code coverage data also for
Prolog code by defining tests that use the ‘(<<)/2’ debugging control
construct to call the Prolog predicates.

See also the section below on exporting code coverage results to XML
files, which can be easily converted and published as e.g.  HTML
reports.


File: TheLogtalkHandbook-3.96.0.info,  Node: Utility predicates,  Next: Exporting test results in xUnit XML format,  Prev: Code coverage,  Up: lgtunit

5.13.29 Utility predicates
--------------------------

The ‘lgtunit’ tool provides several public utility predicates to
simplify writing unit tests and for general use:

   - 
          ‘variant(Term1, Term2)’
          To check when two terms are a variant of each other (e.g., to check expected test results against actual results when they contain variables).

   - 
          ‘assertion(Goal)’
          To generate an exception in case the goal argument fails or throws an error.

   - 
          ‘assertion(Description, Goal)’
          To generate an exception in case the goal argument fails or throws an error (the first argument allows assertion failures to be distinguished when using multiple assertions).

   - 
          ‘approximately_equal(Number1, Number2)’
          For number approximate equality using the ‘epsilon’ arithmetic constant value.

   - 
          ‘approximately_equal(Number1, Number2, Epsilon)’
          For number approximate equality. Weaker equality than essential equality.

   - 
          ‘essentially_equal(Number1, Number2, Epsilon)’
          For number essential equality. Stronger equality than approximate equality.

   - 
          ‘tolerance_equal(Number1, Number2, RelativeTolerance, AbsoluteTolerance)’
          For number equality within tolerances.

   - 
          ‘Number1 =~= Number2’
          For number (or list of numbers) close equality (usually floating-point numbers).

   - 
          ‘benchmark(Goal, Time)’
          For timing a goal.

   - 
          ‘benchmark_reified(Goal, Time, Result)’
          Reified version of ‘benchmark/2’.

   - 
          ‘benchmark(Goal, Repetitions, Time)’
          For finding the average time to prove a goal.

   - 
          ‘benchmark(Goal, Repetitions, Clock, Time)’
          For finding the average time to prove a goal using a ‘cpu’ or a ‘wall’ clock.

   - 
          ‘deterministic(Goal)’
          For checking that a predicate succeeds without leaving a choice-point.

   - 
          ‘deterministic(Goal, Deterministic)’
          Reified version of the ‘deterministic/1’ predicate.

The ‘assertion/1-2’ predicates can be used in the body of tests where
using two or more assertions is convenient or in the body of tests
written using the ‘test/1’, ‘succeeds/1’, and ‘deterministic/1’ dialects
to help differentiate between the test goal and checking the test goal
results and to provide more informative test failure messages.

When the assertion, benchmarking, and deterministic meta-predicates call
a local predicate of the tests object, you must call them using an
implicit or explicit message instead of using a 'super' call.  For
example, to use an implicit message to call the ‘assertion/1-2’
meta-predicates, add the following directive to the tests object:

     :- uses(lgtunit, [assertion/1, assertion/2]).

The reason this is required is that meta-predicates goals arguments are
always called in the context of the 'sender', which would be the
‘lgtunit’ object in the case of a ‘(^^)/2’ call (as it preserves both
'self' and 'sender' and the tests are internally run by a message sent
from the ‘lgtunit’ object to the tests object).

As the ‘benchmark/2-4’ predicates are meta-predicates, turning on the
‘optimize’ compiler flag is advised to avoid runtime compilation of the
meta-argument, which would add an overhead to the timing results.  But
this advice conflicts with collecting code coverage data, which requires
compilation in debug mode.  The solution is to use separate test objects
for benchmarking and for code coverage.  Note that the CPU and wall
execution times (in seconds) for each individual test are reported by
default when running the tests.

The ‘(=~=)/2’ predicate is typically used by adding the following
directive to the object (or category) calling it:

     :- uses(lgtunit, [
         op(700, xfx, =~=), (=~=)/2
     ]).

Consult the ‘lgtunit’ object API documentation for more details on these
predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Exporting test results in xUnit XML format,  Next: Exporting test results in the TAP output format,  Prev: Utility predicates,  Up: lgtunit

5.13.30 Exporting test results in xUnit XML format
--------------------------------------------------

To output test results in the xUnit XML format (from JUnit; see e.g.
‘https://github.com/windyroad/JUnit-Schema’ or
‘https://llg.cubic.org/docs/junit/’), simply load the ‘xunit_output.lgt’
file before running the tests.  This file defines an object,
‘xunit_output’, that intercepts and rewrites unit test execution
messages, converting them to the xUnit XML format.

To export the test results to a file using the xUnit XML format, simply
load the ‘xunit_report.lgt’ file before running the tests.  A file named
‘xunit_report.xml’ will be created in the same directory as the object
defining the tests.  When running a set of test suites as a single
unified suite (using the ‘run_test_sets/1’ predicate), the single xUnit
report is created in the directory of the first test suite object in the
set.

To use the xUnit.net v2 XML format
(‘https://xunit.net/docs/format-xml-v2’), load either the
‘xunit_net_v2_output.lgt’ file or the ‘xunit_net_v2_report.lgt’ file.

When using the ‘logtalk_tester’ automation script, use either the ‘-f
xunit’ option or the ‘-f xunit_net_v2’ option to generate the
‘xunit_report.xml’ files in the test set directories.

There are several third-party xUnit report converters that can generate
HTML files for easy browsing.  For example:

   - ‘https://allurereport.org/docs/’ (supports multiple reports)

   - ‘https://github.com/Zir0-93/xunit-to-html’ (supports multiple test
     sets in a single report)

   - ‘https://www.npmjs.com/package/xunit-viewer’

   - ‘https://github.com/JatechUK/NUnit-HTML-Report-Generator’

   - ‘https://plugins.jenkins.io/xunit’


File: TheLogtalkHandbook-3.96.0.info,  Node: Exporting test results in the TAP output format,  Next: Generating Allure reports,  Prev: Exporting test results in xUnit XML format,  Up: lgtunit

5.13.31 Exporting test results in the TAP output format
-------------------------------------------------------

To output test results in the TAP (Test Anything Protocol) format,
simply load the ‘tap_output.lgt’ file before running the tests.  This
file defines an object, ‘tap_output’, that intercepts and rewrites unit
test execution messages, converting them to the TAP output format.

To export the test results to a file using the TAP (Test Anything
Protocol) output format, load instead the ‘tap_report.lgt’ file before
running the tests.  A file named ‘tap_report.txt’ will be created in the
same directory as the object defining the tests.

When using the ‘logtalk_tester’ automation script, use the ‘-f tap’
option to generate the ‘tap_report.xml’ files in the test set
directories.

When using the ‘test/3’ dialect with the TAP format, a ‘note/1’ option
whose argument is an atom starting with a ‘TODO’ or ‘todo’ word results
in a test report with a TAP TODO directive.

When running a set of test suites as a single unified suite, the single
TAP report is created in the directory of the first test suite object in
the set.

There are several third-party TAP report converters that can generate
HTML files for easy browsing.  For example:

   - ‘https://github.com/Quobject/tap-to-html’

   - ‘https://plugins.jenkins.io/tap/’


File: TheLogtalkHandbook-3.96.0.info,  Node: Generating Allure reports,  Next: Exporting code coverage results in XML format,  Prev: Exporting test results in the TAP output format,  Up: lgtunit

5.13.32 Generating Allure reports
---------------------------------

A ‘logtalk_allure_report.pl’ Bash shell script and a
‘logtalk_allure_report.ps1’ PowerShell script are provided for
generating Allure reports(1) (version 2.26.0 or later required).  This
requires exporting test results in xUnit XML format.  A simple usage
example (assuming a current directory containing tests):

     $ logtalk_tester -p gnu -f xunit
     $ logtalk_allure_report
     $ allure open

The ‘allure open’ command accepts ‘--host’ and ‘--port’ arguments in
case their default values are not suitable (e.g., when running Logtalk
in a remote host over a SSH connection).

The ‘logtalk_allure_report’ script supports command-line options to pass
the tests directory (i.e., the directory where the ‘logtalk_tester’
script was run), the directory where to collect all the xUnit report
files for generating the report, the directory where the report is to be
saved, and the report title (see the script man page or type
‘logtalk_allure_report -h’).  The script also supports saving the
history of past test runs.  In this case, a persistent location for both
the results and report directories must be used.

It’s also possible to use the script just to collect the xUnit report
files generated by ‘lgtunit’ and delegate the actual generation of the
report to e.g.  an Allure Docker container or to a Jenkins plug-in.  Two
examples are:

   - ‘https://github.com/fescobar/allure-docker-service’

   - ‘https://plugins.jenkins.io/allure-jenkins-plugin/’

In this case, we would use the ‘logtalk_allure_report’ script option to
only perform the preprocessing step:

     $ logtalk_allure_report -p

The script also supports passing 'environment pairs', which are
displayed in the generated Allure reports in the environment pane.  This
feature can be used to pass e.g.  the backend name and the backend
version or git commit hash.  The option syntax differs, however, between
the two scripts.  For example, using the Bash script:

     $ logtalk_allure_report -- Backend='GNU Prolog' Version=1.5.0

Or:

     $ logtalk_allure_report -- Project='Deep Thought' Commit=`git rev-parse --short HEAD`

In the case of the PowerShell script, the pairs are passed comma
separated inside a string:

     PS> logtalk_allure_report -e "Backend='GNU Prolog',Version=1.5.0"

Or:

     PS> logtalk_allure_report -e "Project='Deep Thought',Commit=bf166b6"

To show test run trends in the report (e.g., when running the tests for
each application source code commit), save the processed test results
and the report data to permanent directories.  For example:

     $ logtalk_allure_report \
       -i "$HOME/my_project/allure-results" \
       -o "$HOME/my_project/allure-report"
     $ allure open "$HOME/my_project/allure-report"

Note that Allure cleans the report directory when generating a new
report.  Be careful to always specify a dedicated directory to prevent
accidental data loss.

The generated reports can include links to the tests source code.  This
requires using the ‘logtalk_tester’ shell script option that allows
passing the base URL for those links.  This option needs to be used
together with the option to suppress the tests directory prefix so that
the links can be constructed by appending the tests file relative path
to the base URL. For example, assuming that you want to generate a
report for the tests included in the Logtalk distribution when using the
GNU Prolog backend:

     $ cd $LOGTALKUSER
     $ logtalk_tester \
       -p gnu \
       -f xunit \
       -s "$LOGTALKUSER" \
       -u "https://github.com/LogtalkDotOrg/logtalk3/tree/3e4ea295986fb09d0d4aade1f3b4968e29ef594e"

The use of a git hash in the base URL ensures that the generated links
will always show the exact versions of the tests that were run.  The
links include the line number for the tests in the test files (assuming
that the git repo is stored in a BitBucket, GitHub, or GitLab server).
But note that not all supported backends provide accurate line numbers.

It’s also possible to generate single-file reports.  For example:

     $ logtalk_allure_report -s -t "My Amazing Tests Report"

There are some caveats when generating Allure reports that users must be
aware of.  First, Allure expects test names to be unique across
different tests sets.  If there are two tests with the same name in two
different test sets, only one of them will be reported.  Second, when
using the ‘xunit’ format, dates are reported as MM/DD/YYYY. Finally,
when using the ‘xunit_net_v2’ format, tests are reported in a random
order instead of their run order, and dates are displayed as “unknown”
in the overview page.

   ---------- Footnotes ----------

   (1) https://allurereport.org/docs/


File: TheLogtalkHandbook-3.96.0.info,  Node: Exporting code coverage results in XML format,  Next: Automatically creating bug reports at issue trackers,  Prev: Generating Allure reports,  Up: lgtunit

5.13.33 Exporting code coverage results in XML format
-----------------------------------------------------

To export code coverage results in XML format, load the
‘coverage_report.lgt’ file before running the tests.  A file named
‘coverage_report.xml’ will be created in the same directory as the
object defining the tests.

The XML file can be opened in most web browsers (with the notorious
exception of Google Chrome) by copying to the same directory the
‘coverage_report.dtd’ and ‘coverage_report.xsl’ files found in the
‘tools/lgtunit’ directory (when using the ‘logtalk_tester’ script, these
two files are copied automatically).  In alternative, an XSLT processor
can be used to generate an XHTML file instead of relying on a web
browser for the transformation.  For example, using the popular
‘xsltproc’ processor:

     $ xsltproc -o coverage_report.html coverage_report.xml

On Windows operating-systems, this processor can be installed using e.g.
Chocolatey.  On a POSIX operating-systems (e.g., Linux, macOS, …) use
the system package manager to install it if necessary.

The coverage report can include links to the source code when hosted on
Bitbucket, GitHub, or GitLab.  This requires passing the base URL as the
value for the ‘url’ XSLT parameter.  The exact syntax depends on the
XSLT processor, however.  For example:

     $ xsltproc \
       --stringparam url https://github.com/LogtalkDotOrg/logtalk3/blob/master \
       -o coverage_report.html coverage_report.xml

Note that the base URL should preferably be a permanent link (i.e., it
should include the commit SHA1) so that the links to source code files
and lines remain valid if the source code is later updated.  It’s also
necessary to suppress the local path prefix in the generated
‘coverage_report.xml’ file.  For example:

     $ logtalk_tester -c xml -s $HOME/logtalk/

Alternatively, you can pass the local path prefix to be suppressed to
the XSLT processor (note that the ‘logtalk_tester’ script suppresses the
‘$HOME’ prefix by default):

     $ xsltproc \
       --stringparam prefix logtalk/ \
       --stringparam url https://github.com/LogtalkDotOrg/logtalk3/blob/master \
       -o coverage_report.html coverage_report.xml

If you are using Bitbucket, GitHub, or GitLab hosted on your own
servers, the ‘url’ parameter may not contain a ‘bitbucket’, ‘github’, or
‘gitlab’ string.  In this case, you can use the XSLT parameter ‘host’ to
indicate which service you are running.


File: TheLogtalkHandbook-3.96.0.info,  Node: Automatically creating bug reports at issue trackers,  Next: Minimizing test results output,  Prev: Exporting code coverage results in XML format,  Up: lgtunit

5.13.34 Automatically creating bug reports at issue trackers
------------------------------------------------------------

To automatically create bug report issues for failed tests in GitHub or
GitLab servers, see the ‘issue_creator’ tool.


File: TheLogtalkHandbook-3.96.0.info,  Node: Minimizing test results output,  Next: Help with warnings,  Prev: Automatically creating bug reports at issue trackers,  Up: lgtunit

5.13.35 Minimizing test results output
--------------------------------------

To minimize the test results output, simply load the
‘minimal_output.lgt’ file before running the tests.  This file defines
an object, ‘minimal_output’, that intercepts and summarizes the unit
test execution messages.


File: TheLogtalkHandbook-3.96.0.info,  Node: Help with warnings,  Next: Known issues<4>,  Prev: Minimizing test results output,  Up: lgtunit

5.13.36 Help with warnings
--------------------------

Load the ‘tutor’ tool to get help with selected warnings printed by the
‘lgtunit’ tool.


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<4>,  Prev: Help with warnings,  Up: lgtunit

5.13.37 Known issues
--------------------

Deterministic unit tests are currently not available when using Quintus
Prolog as it lacks built-in support that cannot be sensibly defined in
Prolog.

Parameter variables (‘_VariableName_’) cannot currently be used in the
definition of the ‘condition/1’, ‘setup/1’, and ‘cleanup/1’ test options
when using the ‘test/3’ dialect.  For example, the following condition
will not work:

     test(some_id, true, [condition(_ParVar_ == 42)]) :-
         ...

The workaround is to define an auxiliary predicate called from those
options.  For example:

     test(check_xyz, true, [condition(xyz_condition)]) :-
         ...

     xyz_condition :-
         _ParVar_ == 42.


File: TheLogtalkHandbook-3.96.0.info,  Node: linter,  Next: make,  Prev: lgtunit,  Up: Developer Tools

5.14 ‘linter’
=============

Logtalk provides a built-in linter tool that runs automatically when
compiling and loading source files.  The lint warnings are controlled by
a set of flags(1).  The default values for these flags are defined in
the backend Prolog compiler adapter files and can be overridden from a
settings file, from a source file (e.g., a loader file), or from an
entity.  These flags can be set globally using the set_logtalk_flag/2(2)
built-in predicate.  For (source file or entity) local scope, use
instead the set_logtalk_flag/2(3) directive.

The linter flags can be managed as a group using the linter(4)
meta-flag.  See the documentation for details.

Some lint checks are turned off by default, specially when
computationally expensive.  Still, it’s a good idea to turn them on to
check your code on a regular basis (e.g., in CI/CD pipelines).

Note that, in some cases, the linter may generate false warnings due to
source code analysis limitations or special cases that, while valid when
intended, usually result from programming issues.  When a code rewrite
is not a sensible solution to avoid the warning, the workaround is to
turn off as locally as possible the flag that controls the warning.

* Menu:

* Main linter checks::
* Help on linter warnings::
* Extending the linter::
* Linting Prolog modules::
* Linting plain Prolog files::

   ---------- Footnotes ----------

   (1) ../userman/programming.html#programming-flags-lint

   (2) ../refman/predicates/set_logtalk_flag_2.html

   (3) ../refman/directives/set_logtalk_flag_2.html

   (4) ../userman/programming.html#flag-linter


File: TheLogtalkHandbook-3.96.0.info,  Node: Main linter checks,  Next: Help on linter warnings,  Up: linter

5.14.1 Main linter checks
-------------------------

Lint checks include:

   - Missing directives (including scope, meta-predicate, dynamic,
     discontiguous, and multifile directives)

   - Duplicated directives, clauses, and grammar rules

   - Missing predicates (unknown messages plus calls to non-declared and
     non-defined predicates)

   - Calls to declared but not defined static predicates

   - Non-terminals called as predicates (instead of via the ‘phrase/2-3’
     built-in methods)

   - Predicates called as non-terminals (instead of via the ‘call//1’
     built-in method)

   - Non-portable predicate calls, predicate options, arithmetic
     function calls, directives, flags, and flag values

   - Missing arithmetic functions (with selected backends)

   - Suspicious calls (syntactically valid calls that are likely
     semantic errors; e.g.  float comparisons using the standard
     arithmetic comparison operators or comparing numbers using
     unification)

   - Deprecated directives, predicates, arithmetic functions, control
     constructs, and flags

   - References to unknown entities (objects, protocols, categories, or
     modules)

   - Top-level shortcuts used as directives

   - Unification goals that will succeed without binding any variables

   - Unification goals that will succeed by creating a cyclic term

   - Goals that are always true or always false

   - Trivial goal failures (due to no matching predicate clause)

   - Redefined built-in predicates

   - Redefined standard operators

   - Lambda expression unclassified variables and mixed up variables

   - Lambda expression with parameter variables used elsewhere in a
     clause

   - Singleton variables

   - If-then-else and soft cut control constructs without an else part

   - If-then-else and soft cut control constructs where the test is a
     unification between a variable and a ground term

   - Missing parentheses around if-then-else and disjunction control
     constructs in the presence of cuts in the first argument

   - Cuts in clauses for multifile predicates

   - Missing cut in repeat loops

   - Possible non-steadfast predicate definitions

   - Non-tail recursive predicate definitions

   - Redundant calls to control constructs and built-in predicates

   - Calls to all-solutions predicates with existentially qualified
     variables not occurring in the qualified goal

   - Calls to all-solutions predicates with no shared variables between
     template and goal

   - Calls to ‘bagof/3’ and ‘setof/3’ where the goal argument contains
     singleton variables

   - Calls to ‘findall/3’ used to backtrack over all solutions of a goal
     without collecting them

   - Calls to ‘catch/3’ that catch all exceptions

   - Calls to standard predicates that have more efficient alternatives

   - Unsound calls in grammar rules

   - File, entity, predicate, and variable names not following official
     coding guidelines

   - Variable names that differ only on case

   - Clauses whose body is a disjunction (and that can be rewritten as
     multiple clauses per coding guidelines)

   - Naked meta-variables in cut-transparent control constructs

   - Left-recursion in clauses and grammar rules

Additional lint checks are provided by the ‘lgtunit’, ‘lgtdoc’, ‘make’,
and ‘dead_code_scanner’ tools.  For large projects, the data generated
by the ‘code_metrics’ tool may also be relevant in accessing code
quality and suggesting code refactoring candidates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Help on linter warnings,  Next: Extending the linter,  Prev: Main linter checks,  Up: linter

5.14.2 Help on linter warnings
------------------------------

By loading the ‘tutor’ tool, most lint warnings are expanded with
explanations and suggestions on how to fix the reported issues.  See
also the coding guidelines(1) for additional explanations.

   ---------- Footnotes ----------

   (1) https://logtalk.org/coding_style_guidelines.html


File: TheLogtalkHandbook-3.96.0.info,  Node: Extending the linter,  Next: Linting Prolog modules,  Prev: Help on linter warnings,  Up: linter

5.14.3 Extending the linter
---------------------------

Experimental support for extending the linter with user-defined warnings
is available using the logtalk_linter_hook/7(1) multifile hook
predicate.  For example, the ‘format’ and ‘list’ library objects define
this hook predicate to lint calls to the ‘format/2-3’ and ‘append/3’
predicates for common errors and misuses.

   ---------- Footnotes ----------

   (1) ../refman/predicates/logtalk_linter_hook_7.html


File: TheLogtalkHandbook-3.96.0.info,  Node: Linting Prolog modules,  Next: Linting plain Prolog files,  Prev: Extending the linter,  Up: linter

5.14.4 Linting Prolog modules
-----------------------------

This tool can also be applied to Prolog modules that Logtalk is able to
compile as objects.  For example, if the Prolog module file is named
‘module.pl’, try:

     | ?- logtalk_load(module, [source_data(on)]).

Due to the lack of standardization of module systems and the abundance
of proprietary extensions, this solution is not expected to work for all
cases.


File: TheLogtalkHandbook-3.96.0.info,  Node: Linting plain Prolog files,  Prev: Linting Prolog modules,  Up: linter

5.14.5 Linting plain Prolog files
---------------------------------

This tool can also be applied to plain Prolog code.  For example, if the
Prolog file is named ‘code.pl’, simply define an object including its
code:

     :- object(code).
         :- include('code.pl').
     :- end_object.

Save the object to an e.g.  ‘code.lgt’ file in the same directory as the
Prolog file and then load it:

     | ?- logtalk_load(code, [source_data(on)]).

In alternative, use the ‘object_wrapper_hook’ provided by the
‘hook_objects’ library:

     | ?- logtalk_load(hook_objects(loader)).
     ...

     | ?- logtalk_load(code, [hook(object_wrapper_hook), source_data(on)]).

With either wrapping solution, pay special attention to any compilation
warnings that may signal issues that could prevent the plain Prolog from
being fully checked when wrapped by an object.


File: TheLogtalkHandbook-3.96.0.info,  Node: make,  Next: packs,  Prev: linter,  Up: Developer Tools

5.15 ‘make’
===========

Logtalk provides a make tool supporting several targets using the
‘logtalk_make/0-1’ built-in predicates.  Top-level shortcuts for the
targets are also provided.

* Menu:

* API documentation: API documentation<11>.
* Help with warnings: Help with warnings<2>.
* Known issues: Known issues<5>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<11>,  Next: Help with warnings<2>,  Up: make

5.15.1 API documentation
------------------------

To consult the documentation of the ‘logtalk_make/0-1’ built-in
predicates, open in a web browser the links:

   - ‘../refman/predicates/logtalk_make_0.html’

   - ‘../refman/predicates/logtalk_make_1.html’

There is also a user-defined hook predicate that supports defining
additional actions for the make targets (e.g., running tests
automatically on make check or regenerating API documentation on make
documentation):

   - ‘../refman/predicates/logtalk_make_target_action_1.html’


File: TheLogtalkHandbook-3.96.0.info,  Node: Help with warnings<2>,  Next: Known issues<5>,  Prev: API documentation<11>,  Up: make

5.15.2 Help with warnings
-------------------------

Load the ‘tutor’ tool to get help with selected warnings printed by the
‘make’ tool.


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<5>,  Prev: Help with warnings<2>,  Up: make

5.15.3 Known issues
-------------------

The implementation of the ‘logtalk_make/0-1’ predicates for the target
‘all’ tries to avoid or minimize compilation warnings due to
out-of-order loading of modified source files by performing a file
topological sort based on the dependencies in the previous versions of
the files.  But it’s always possible that the new versions of the files
bring changes to those dependencies and thus result in compilation
warnings that could possibly be avoided with a different loading order.


File: TheLogtalkHandbook-3.96.0.info,  Node: packs,  Next: ports_profiler,  Prev: make,  Up: Developer Tools

5.16 ‘packs’
============

This tool provides predicates for downloading, installing, upgrading,
and uninstalling third-party libraries and applications, generically
known as 'packs'.  Collections of pack specifications are made available
using 'registries'.  Registries can be local to a system, publicly
shared, or private to a company (e.g., only available in a VPN). There
is no concept of a central registry.  Users can decide which registries
they trust and want to use and add them using their published URLs.  The
tool supports both pack checksums and signatures and takes several steps
to sanitize registry and pack specifications.  As with other Logtalk
developer tools, portability is a main goal.  This tool can be used with
any supported Prolog backend and run on both POSIX and Windows systems.
Moreover, this tool can be used not only for handling Logtalk packs but
also for Prolog only packs, thus providing a solution for sharing
portable resources between multiple systems.

A list of public Logtalk and Prolog pack registries is available at:

‘https://github.com/LogtalkDotOrg/pack-registries’

This tool is in the beta stage of development.  Feedback is most
welcome.

* Menu:

* Requirements: Requirements<5>.
* API documentation: API documentation<12>.
* Loading: Loading<12>.
* Testing: Testing<10>.
* Usage: Usage<7>.
* Registries and packs storage::
* Virtual environments::
* Registry specification::
* Registry handling::
* Registry development::
* Pack specification::
* Encrypted packs::
* Signed packs::
* Pack URLs and Single Sign-On::
* Multiple pack versions::
* Pack dependencies::
* Pack portability::
* Pack development::
* Pack handling::
* Pack documentation::
* Pinning registries and packs::
* Testing packs::
* Security considerations::
* Best practices::
* Installing Prolog packs::
* Help with warnings: Help with warnings<3>.
* Known issues: Known issues<6>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Requirements<5>,  Next: API documentation<12>,  Up: packs

5.16.1 Requirements
-------------------

On POSIX systems (Linux, macOS, …), the following shell commands are
required:

   - ‘sha256sum’ (provided by GNU ‘coreutils’)

   - ‘curl’ (default file downloader)

   - ‘wget’ (alternative file downloader)

   - ‘bsdtar’ (provided by ‘libarchive’ or ‘libarchive-tools’)

   - ‘gpg’ (provided by ‘gnupg2’)

   - ‘git’

   - ‘direnv’ (when using virtual environments)

The tool uses ‘bsdtar’ instead of GNU ‘tar’ so that it can uncompress
‘.zip’ archives (‘unzip’ doesn’t provide the desired options that allow
a simple and reliable solution for ignoring the non-predictable name of
the wrapper directory).

On Windows systems, the following shell commands are required:

   - ‘certutil.exe’

   - ‘curl.exe’ (default file downloader)

   - ‘wget.exe’ (alternative file downloader)

   - ‘tar.exe’

   - ‘gpg.exe’

   - ‘git.exe’

   - ‘Set-PsEnv’ (when using virtual environments)

In recent Windows 10 builds, only ‘wget’, ‘gpg’, ‘git’, and ‘Set-PsEnv’
should require installation.  You can download the GnuPG software from:

‘https://www.gnupg.org/’

You can download Git from:

‘https://gitforwindows.org’

You can download Wget from:

‘https://eternallybored.org/misc/wget/’

You can also use Chocolatey to install the commands above:

     > choco install gnupg git wget

To install Set-PsEnv(1) from the PowerShell Gallery:

     PS> Install-Module -Name Set-PsEnv

On macOS systems, Apple bundles both ‘curl’ and BSD ‘tar’ (under the
name ‘tar’; you can simply create a ‘bsdtar’ alias or install a more
recent version).  The required commands can be easily installed using
MacPorts:

     $ sudo port install coreutils wget libarchive gnupg2 git direnv

Or using Homebrew:

     $ brew install coreutils wget libarchive gnupg2 git direnv

On Linux systems, use the distribution’s own package manager to install
any missing command.  For example, in recent Ubuntu versions:

     $ sudo apt update
     $ sudo apt install coreutils curl wget libarchive-tools gnupg2 git direnv

   ---------- Footnotes ----------

   (1) https://github.com/rajivharris/Set-PsEnv


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<12>,  Next: Loading<12>,  Prev: Requirements<5>,  Up: packs

5.16.2 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#packs’


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<12>,  Next: Testing<10>,  Prev: API documentation<12>,  Up: packs

5.16.3 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(packs(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<10>,  Next: Usage<7>,  Prev: Loading<12>,  Up: packs

5.16.4 Testing
--------------

To run the tool tests, use the query:

     | ?- logtalk_load(packs(tester)).

The tests can be run without interfering with the user packs setup.


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<7>,  Next: Registries and packs storage,  Prev: Testing<10>,  Up: packs

5.16.5 Usage
------------

The ‘packs’ tool loads at startup all the currently defined registry and
pack specifications (from the registries/packs storage directory; see
below).  When no registry/pack setup exists, a new one is automatically
created.

The tool provides two main objects, ‘registries’ and ‘packs’, for
handling, respectively, registries and packs.  Both objects accept a
‘help/0’ message that describes the most common queries.


File: TheLogtalkHandbook-3.96.0.info,  Node: Registries and packs storage,  Next: Virtual environments,  Prev: Usage<7>,  Up: packs

5.16.6 Registries and packs storage
-----------------------------------

The tool uses a directory specified using the ‘logtalk_packs’ library
alias when defined (in a settings file or in a backend Prolog
initialization file).  When this library alias is not defined, the tool
uses the value of the ‘LOGTALKPACKS’ environment variable when defined.
Otherwise, it defaults to the ‘~/logtalk_packs’ directory.  The actual
directory can be retrieved by the query:

     | ?- packs::logtalk_packs(Directory).
     ...

This directory holds sub-directories for registries, packs, and
archives.  These sub-directories are automatically created when loading
the ‘packs’ tool if they don’t exist.  Users should not manually modify
the contents of these directories.  Multiple and independent
registry/pack setups are possible using 'virtual environments' as
explained next.

Your registries and packs setup can be saved and restored (e.g., in a
different system) by using the ‘packs::save/1-2’ and
‘packs::restore/1-2’ predicates, as explained in the next section about
virtual environments.  If necessary, before restoring, the
‘packs::reset/0’ predicate can be called to delete any defined
registries and installed packs.


File: TheLogtalkHandbook-3.96.0.info,  Node: Virtual environments,  Next: Registry specification,  Prev: Registries and packs storage,  Up: packs

5.16.7 Virtual environments
---------------------------

An application may require specific pack versions.  These requirements
may differ between applications.  Different applications may also have
conflicting requirements.  Therefore, a 'virtual environment' where an
application requirements are fulfilled may be required to develop and/or
run it.  A virtual environment is essentially a registries/packs storage
directory.

Defining the ‘logtalk_packs’ library alias in a settings file or
defining the ‘LOGTALKPACKS’ environment variable before starting Logtalk
allows easy creation and switching between virtual environments.  By
using a per-application settings file (or a per-application environment
variable definition), each application can thus use its own virtual
environment.  The ‘settings.lgt’ file can define the ‘logtalk_packs’
library alias using code such as:

     :- initialization((
         logtalk_load_context(directory, Directory),
         assertz(logtalk_library_path(logtalk_packs, Directory))
     )).

The definition of the ‘logtalk_packs’ library alias 'must' always be an
atom and thus never use library notation (i.e., it must never depend on
other library aliases).

When a virtual environment also requires a specific Logtalk version
(e.g., the version used to test and certify it), this can be installed
as a pack from the official talkshow(1) registry and used by
(re)defining the ‘LOGTALKHOME’ and ‘LOGTALKUSER’ environment variables
to point to its pack directory (which can be queried by using the
‘packs::directory/2’ message).

Experimental ‘lgtenv.sh’ and ‘lgtenv.ps1’ scripts are included to
simplify creating virtual environments.  For example:

     $ lgtenv -d ~/my_venv -c -p logtalk_packs
     $ cd ~/my_venv
     direnv: loading ~/my_venv/.envrc
     direnv: export +LOGTALKPACKS

Type ‘lgtenv -h’ for details on the script options.

These scripts require, respectively, direnv(2) and Set-PsEnv(3) to be
installed.  These utilities load and unload environment variables when
changing the current directory.  On Windows systems, when using the
‘lgtenv.ps1’ script, you also need to redefine the PowerShell prompt in
a profile file (e.g., ‘$HOME\Documents\PowerShell\Profile.ps1’) to mimic
the functionality of ‘direnv’ of automatically loading an existing
‘.env’ file when changing to its directory.  For example:

     function prompt {
         Set-PsEnv
         'PS ' + $(Get-Location) + '> '
     }

A virtual environment setup (i.e., the currently defined registries and
installed packs) can be saved into a file (e.g., ‘requirements.lgt’)
using the ‘packs::save/1’ predicate:

     | ?- packs::save('requirements.lgt').
     ...

This query saves a listing of all the installed packs and their
registries.  Using the saved file, the virtual environment setup can
then be restored using the ‘packs::restore/1-2’ predicates.  The file
uses a simple format with ‘registry/2’, ‘pack/3’, ‘pinned_registry/1’,
and ‘pinned_pack/1’ facts (in this order) and can be manually created or
edited if necessary.  For example:

     registry(talkshow, 'https://github.com/LogtalkDotOrg/talkshow.git').
     pack(talkshow, logtalk, 3:45:0).
     pack(talkshow, lflat, 2:1:0).

These files can be distributed with applications so that users can
easily fulfill application requirements by running the query once:

     | ?- packs::restore('requirements.lgt').

Subsequently, the application ‘loader.lgt’ file can then load the
required packs using their loader files:

     :- initialization((
         % load required packs
         logtalk_load(foo(loader)),
         logtalk_load(bar(loader)),
         ...
         % load application files
         ...
     )).

Note that restoring encrypted registries or encrypted packs requires
entering the required passphrases.  Although the ‘restore/2’ predicate
accepts a list of options that include the ‘gpg/1’ option, this only
allows specifying a single and common passphrase when interactive
entering of passphrases is not convenient or possible.

   ---------- Footnotes ----------

   (1) https://github.com/LogtalkDotOrg/talkshow

   (2) https://github.com/direnv/direnv

   (3) https://github.com/rajivharris/Set-PsEnv


File: TheLogtalkHandbook-3.96.0.info,  Node: Registry specification,  Next: Registry handling,  Prev: Virtual environments,  Up: packs

5.16.8 Registry specification
-----------------------------

A registry is a git remote repo that can be cloned, a downloadable or
local archive, or a local directory containing a Logtalk loader file
that loads source files defining the registry itself and the packs it
provides.  The registry name is ideally a valid unquoted atom.  The
registry directory must contain at least two Logtalk source files:

   - A file defining an object named after the registry with a
     ‘_registry’ suffix, implementing the ‘registry_protocol’.  This
     naming convention helps prevent name conflicts.

   - A loader file (named ‘loader.lgt’ or ‘loader.logtalk’) that loads
     the registry object file and all pack object files.

An example of a registry specification object would be:

     :- object(jdoe_awesome_packs_registry,
         implements(registry_protocol)).

         :- info([
             version is 1:0:0,
             author is 'John Doe',
             date is 2021-10-18,
             comment is 'John Doe awesome packs registry spec.'
         ]).

         name(jdoe_awesome_packs).

         description('John Doe awesome packs').

         home('https://example.com/jdoe_awesome_packs').

         clone('https://github.com/jdoe/jdoe_awesome_packs.git').

         archive('https://github.com/jdoe/jdoe_awesome_packs/archive/main.zip').

     :- end_object.

Optionally, the registry object can also define a ‘note(Action, Note)’
predicate.  The ‘Action’ argument is an atom: ‘add’, ‘update’, or
‘delete’.  The ‘Note’ argument is also an atom.  The tool will print any
available notes when executing one of the registry actions.  See the
‘registry_protocol’ documentation for more details.

The registry directory should also contain ‘LICENSE’ and ‘README.md’
files (individual packs can use a different license, however).  The path
to the ‘README.md’ file is printed when the registry is added.  It can
also be queried using the ‘registries::directory/2’ predicate.  The
‘NOTES.md’ file name can also be used in alternative to the recommended
‘README.md’ file name.

Summarizing the required directory structure using the above example
(note that the registry and pack specification files are named after the
objects):

     jdoe_awesome_packs
         LICENSE
         README.md
         jdoe_awesome_packs_registry.lgt
         loader.lgt
         foo_pack.lgt
         bar_pack.lgt
         ...

With the contents of the ‘loader.lgt’ file being:

     :- initialization((
         logtalk_load(jdoe_awesome_packs_registry),
         logtalk_load(foo_pack),
         logtalk_load(bar_pack),
         ...
     )).

It would be, of course, possible to have all objects in a single source
file.  But having a file per-object and a loader file helps maintenance,
and it’s also a tool requirement for applying safety procedures to the
source file contents and thus successfully loading the registry and pack
specs.

As registries are git repos in the most common case, and thus adding
them performs a git repo cloning, they should only contain the strictly
required files.


File: TheLogtalkHandbook-3.96.0.info,  Node: Registry handling,  Next: Registry development,  Prev: Registry specification,  Up: packs

5.16.9 Registry handling
------------------------

Registries can be added using the ‘registries::add/1-3’ predicates,
which take a registry URL. Using the example above:

     | ?- registries::add('https://github.com/jdoe/jdoe_awesome_packs.git').

HTTPS URLs must end with either a ‘.git’ extension or an archive
extension (same valid extensions as for pack archives, including ‘gpg’
encrypted).  Git cloning URLs are preferred as they simplify updating
registries.  But a registry can also be made available via a local
directory (using a ‘file://’ URL) or a downloadable archive (using a
‘https://’ URL).

For registries made available using an archive, the
‘registries::add/2-3’ predicates 'must' be used as the registry name
cannot in general be inferred from the URL basename or from the archived
directory name.  The registry argument must also be the declared
registry name in the registry specification object.  For example:

     | ?- registries::add(
             jdoe_awesome_packs,
             'https://github.com/jdoe/jdoe_awesome_packs/archive/main.zip'
          ).

When a registry may be already defined, you can use the ‘update(true)’
option to ensure that the registry will be updated to its latest
definition:

     | ?- registries::add(
             jdoe_awesome_packs,
             'https://github.com/jdoe/jdoe_awesome_packs/archive/main.zip',
             [update(true)]
          ).

The added registries can be listed using the ‘registries::list/0’
predicate:

     | ?- registries::list.

     % Defined registries:
     %   jdoe_awesome_packs (git)
     %   ...

The ‘registries::describe/1’ predicate can be used to print the details
of a registry:

     | ?- registries::describe(jdoe_awesome_packs).

     % Registry:    jdoe_awesome_packs
     % Description: John Doe awesome packs
     % Home:        https://example.com/jdoe_awesome_packs
     % Cloning URL: https://github.com/jdoe/jdoe_awesome_packs.git
     % Archive URL: https://github.com/jdoe/jdoe_awesome_packs/archive/main.zip

To update all registries, use the ‘registries::update/0’ predicate.  To
update a single registry, use the ‘registries::update/1-2’ predicates.
After updating, you can use the ‘packs::outdated/0-1’ predicates to list
any outdated packs.

Registries can also be deleted using the ‘registries::delete/1-2’
predicate.  By default, any registries with installed packs cannot be
deleted.  If you force deletion (by using the ‘force(true)’ option), you
can use the ‘packs::orphaned/0’ predicate to list any orphaned packs
that are installed.

See the tool API documentation on the registries(1) object for other
useful predicates.

   ---------- Footnotes ----------

   (1) ../../docs/registries_0.html


File: TheLogtalkHandbook-3.96.0.info,  Node: Registry development,  Next: Pack specification,  Prev: Registry handling,  Up: packs

5.16.10 Registry development
----------------------------

To simplify registry development and testing, use a local directory and
a ‘file://’ URL when calling the ‘registries::add/1’ predicate.  For
example:

     | ?- registries::add('file:///home/jdoe/work/my_pack_collection').

If the directory is a git repo, the tool will clone it when adding it.
Otherwise, the files in the directory are copied to the registry
definition directory.  This allows the registry to be added and deleted
without consequences for the original registry source files.

To check your registry specifications, use the ‘registries::lint/0-1’
predicates after adding the registry.


File: TheLogtalkHandbook-3.96.0.info,  Node: Pack specification,  Next: Encrypted packs,  Prev: Registry development,  Up: packs

5.16.11 Pack specification
--------------------------

A pack is specified using a Logtalk source file defining an object that
implements the ‘pack_protocol’.  The source file should be named after
the pack with a ‘_pack’ suffix.  This naming convention helps prevent
name conflicts, notably with the pack’s own objects.  The file must be
available from a declared pack registry (by having the registry loader
file loading it).  The pack name is preferably a valid unquoted atom.
An example of a pack specification object would be:

     :- object(lflat_pack,
         implements(pack_protocol)).

         :- info([
             version is 1:0:0,
             author is 'Paulo Moura',
             date is 2021-10-18,
             comment is 'L-FLAT - Logtalk Formal Language and Automata Toolkit pack spec.'
         ]).

         name(lflat).

         description('L-FLAT - Logtalk Formal Language and Automata Toolkit').

         license('MIT').

         home('https://github.com/l-flat/lflat').

         version(
             2:1:0,
             stable,
             'https://github.com/l-flat/lflat/archive/refs/tags/v2.1.0.tar.gz',
             sha256 - '9c298c2a08c4e2a1972c14720ef1498e7f116c7cd8bf7702c8d22d8ff549b6a1',
             [logtalk @>= 3:42:0],
             all
         ).

         version(
             2:0:2,
             stable,
             'https://github.com/l-flat/lflat/archive/refs/tags/v2.0.2.tar.gz',
             sha256 - '8774b3863efc03bb6c284935885dcf34f69f115656d2496a33a446b6199f3e19',
             [logtalk @>= 3:36:0],
             all
         ).

     :- end_object.

The ‘license/1’ argument must be an atom and should, whenever possible,
be a license identifier as specified in the SPDX standard(1).

Optionally, the pack object can also define a ‘note(Action, Version,
Note)’ predicate.  The ‘Action’ argument is an atom: ‘install’,
‘update’, or ‘uninstall’.  The ‘Note’ argument is also an atom.  The
tool will print any available notes when executing one of the registry
actions.  See the ‘pack_protocol’ documentation for more details.

The pack sources must be available either as a local directory (when
using a ‘file://’ URL) or for downloading as a supported archive.  The
checksum for the archive must use the SHA-256 hash algorithm (‘sha256’).
The pack may optionally be signed.  Supported archive formats and
extensions are:

   - ‘.zip’

   - ‘.tgz’, ‘.tar.gz’

   - ‘.tbz2’, ‘.tar.bz2’

Also, for encrypted packs, all the extensions above with a ‘.gpg’ suffix
(e.g., ‘.zip.gpg’).

The pack sources should contain ‘LICENSE’, ‘README.md’ (or ‘NOTES.md’),
and ‘loader.lgt’ (or ‘loader.logtalk’) files.  Ideally, it should also
contain a ‘tester.lgt’ (‘tester.logtalk’) file.  The path to the
‘README.md’ file is printed when the pack is installed or updated.  It
can also be queried using the ‘packs::directory/2’ predicate.

   ---------- Footnotes ----------

   (1) https://spdx.org/licenses/


File: TheLogtalkHandbook-3.96.0.info,  Node: Encrypted packs,  Next: Signed packs,  Prev: Pack specification,  Up: packs

5.16.12 Encrypted packs
-----------------------

Packs can be ‘gpg’ encrypted, with a choice of passphrase-based
encryption, key-based encryption, or both.  Encrypted pack archives must
always have a ‘.gpg’ extension.  For example, to encrypt a pack archive
with a symmetric cipher using a passphrase:

     $ tar -cvzf - my_pack | gpg -c --cipher-algo AES256 > v1.2.1.tar.gz.gpg

In this case, the passphrase would need to be securely communicated to
any users installing or updating the pack.

See the ‘gpg’ documentation for full details on encrypting and
decrypting archives.  If you get a “gpg: problem with the agent:
Inappropriate ioctl for device” error message with the command above,
try:

     $ export GPG_TTY=$(tty)


File: TheLogtalkHandbook-3.96.0.info,  Node: Signed packs,  Next: Pack URLs and Single Sign-On,  Prev: Encrypted packs,  Up: packs

5.16.13 Signed packs
--------------------

Packs can be ‘gpg’ signed.  Detached signature files are assumed and
expected to share the name of the archive and use ‘.asc’ or ‘.sig’
extensions.  For example, if the pack archive name is ‘v1.0.0.tar.gz’,
the signature file must be named ‘v1.0.0.tar.gz.asc’ or
‘v1.0.0.tar.gz.sig’.  When the ‘checksig(true)’ option is used, the
signature file is automatically downloaded using a URL constructed from
the pack archive URL. When both ‘.asc’ and ‘.sig’ files exist, the
‘.asc’ file is used.  An example of signing a pack and creating the
‘.asc’ file (assuming the default signing key) is:

     $ gpg --armor --detach-sign v1.0.0.tar.gz

To create instead a ‘.sig’ file:

     $ gpg --detach-sign v1.0.0.tar.gz

See the ‘gpg’ documentation for full details on signing archives and
sharing the public keys required to verify the signatures.


File: TheLogtalkHandbook-3.96.0.info,  Node: Pack URLs and Single Sign-On,  Next: Multiple pack versions,  Prev: Signed packs,  Up: packs

5.16.14 Pack URLs and Single Sign-On
------------------------------------

Typically, pack archive download URLs are HTTPS URLs and handled using
‘curl’.  It’s also possible to use ‘git archive’ to download pack
archives, provided that the server supports it (as of this writing,
Bitbucket and GitLab public hosting services support it but not GitHub).
Using ‘git archive’ is specially useful when the packs registry is
hosted on a server using Single Sign-On (SSO) for authentication.  In
this case, HTTPS URLs can only be handled by ‘curl’ by passing a token
(see below for an example).  When the user has setup SSH keys to
authenticate to the packs registry server, ‘git archive’ simplifies pack
installation, providing a better user experience.  For example:

     version(
         1:0:1,
         stable,
         'git@gitlab.com:me/foo.git/v1.0.1.zip',
         sha256 - '0894c7cdb8968b6bbcf00e3673c1c16cfa98232573af30ceddda207b20a7a207',
         [logtalk @>= 3:36:0],
         all
     ).

The pseudo-URL must be the concatenation of the SSH repo cloning URL
with the archive name.  The archive name must be the concatenation of a
valid tag with a supported archive extension.  SSH repo cloning URLs use
the format:

     git@<hostname>:path/to/project.git

They can usually be easily copied from the hosting service repo webpage.
To compute the checksum, you must first download the archive.  For
example:

     $ git archive --output=foo-v1.0.1.zip --remote=git@gitlab.com:me/foo.git v1.0.1
     $ openssl sha256 foo-v1.0.1.zip

Be sure to use a format that is supported by both the ‘packs’ tool and
the ‘git archive’ command (the format is inferred from the ‘--output’
option).  Do not download the archive from the web interface of the git
hosting service in order to compute the checksum.  Different
implementations of the archiving and compressing algorithms may be used,
resulting in mismatched checksums.

Users installing packs available using ‘git archive’ URLs are advised to
run a SSH agent to avoid being prompted for passwords when installing or
updating packs.  They must also upload their SSH public keys to the pack
provider hosts.


File: TheLogtalkHandbook-3.96.0.info,  Node: Multiple pack versions,  Next: Pack dependencies,  Prev: Pack URLs and Single Sign-On,  Up: packs

5.16.15 Multiple pack versions
------------------------------

A pack may specify multiple versions.  Each version is described using a
‘version/6’ predicate clause as illustrated in the example above.  The
versions must be listed in order from newest to oldest.  For details,
see the ‘pack_protocol’ API documentation.

Listing multiple versions allows the pack specification to be updated
(by updating its registry) without forcing existing users into
installing (or updating to) the latest version of the pack.  It allows
different applications depending on different pack versions to continue
to be built and deployed.

The pack version is complemented by the pack status.  Valid values are
‘stable’, ‘rc’, ‘beta’, ‘alpha’, ‘experimental’, and ‘deprecated’.
Packs with a ‘experimental’ or ‘deprecated’ status are 'never' installed
by default when using the install and update predicates unless their
version is explicitly specified.  When updating packs, we can restrict
the valid status of the updates using the ‘status/1’ option.  For
example, we can ensure that we only update to new stable pack versions
by using the option ‘status([stable])’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Pack dependencies,  Next: Pack portability,  Prev: Multiple pack versions,  Up: packs

5.16.16 Pack dependencies
-------------------------

Pack dependencies on other packs can be specified using a list of
‘Registry::Pack Operator Version’ terms where ‘Operator’ is a standard
term comparison operator:

   - ‘Registry::Pack @>= Version’ - the pack requires a dependency with
     a version equal or above the specified one.  For example, ‘logtalk
     @>= 3:36:0’ means that the pack requires Logtalk 3.36.0 or a later
     version.

   - ‘Registry::Pack @=< Version’ - the pack requires a dependency with
     a version up to the specified one.  For example, ‘common::bits @=<
     2:1’ means that the pack requires a ‘common::bits’ pack up to 2.1.
     This includes all previous versions and also all patches for
     version 2.1 (e.g., 2.1.7, 2.1.8, …) but not version 2.2 or newer.

   - ‘Registry::Pack @< Version’ - the pack requires a dependency with
     version older than the specified one.  For example, ‘common::bits
     @< 3’ means that the pack requires a ‘common::bits’ 2.x or older
     version.

   - ‘Registry::Pack @> Version’ - the pack requires a dependency with
     version newer than the specified one.  For example, ‘common::bits
     @> 2:4’ means that the pack requires a ‘common::bits’ 2.5 or newer
     version.

   - ‘Registry::Pack == Version’ - the pack requires a dependency with a
     specific version.  For example, ‘common::bits == 2:1’ means that
     the pack requires a ‘common::bits’ pack version 2.1.x (thus, from
     version 2.1.0 to the latest patch for version 2.1).

   - ‘Registry::Pack \== Version’ - the pack requires a dependency with
     any version other than the one specified.  For example,
     ‘common::bits \== 2.1’ means that the pack requires a
     ‘common::bits’ pack version other than any 2.1.x version.

To specify 'range' dependencies by using two consecutive elements with
the lower bound followed by the upper bound.  For example, ‘common::bits
@>= 2, common::bits @< 3’ means all ‘common::bits’ 2.x versions but not
older or newer major versions.

It’s also possible to specify 'alternative' dependencies using the
‘(;)/2’ operator.  For example, ‘(common::bits == 1:9; common::bits @>=
2:3)’ means either ‘common::bits’ 1.9.x versions or 2.3.x and later
versions.  Alternatives should be listed in decreasing order of
preference.

When a pack also depends on a Logtalk or backend version, the name
‘logtalk’ or the backend identifier atom can be used in place of
‘Registry::Pack’ (see below for the table of backend specifiers).  For
example, ‘logtalk @>= 3.36.0’.

When a pack also depends on an operating-system version (e.g., a pack
containing shared libraries with executable code), the
‘os(Name,Machine)’ compound term can also be used in place of
‘Registry::Pack’.  For example, ‘os('Darwin',x86_64) @>= '23.0.0'’.
Note that, in this case, the release is an atom.  The operating-system
data (name, machine, and release) is queried using the corresponding
‘os’ library predicates (see the library documentation for details).


File: TheLogtalkHandbook-3.96.0.info,  Node: Pack portability,  Next: Pack development,  Prev: Pack dependencies,  Up: packs

5.16.17 Pack portability
------------------------

Ideally, packs are fully portable and can be used with all
Logtalk-supported Prolog backends.  This can be declared by using the
atom ‘all’ in the last argument of the ‘version/6’ predicate (see
example above).

When a pack can only be used with a subset of the Prolog backends, the
last argument of the ‘version/6’ predicate is a list of backend
identifiers (atoms):

   - B-Prolog: ‘b’

   - Ciao Prolog: ‘ciao’

   - CxProlog: ‘cx’

   - ECLiPSe: ‘eclipse’

   - GNU Prolog: ‘gnu’

   - JIProlog: ‘ji’

   - Quintus Prolog: ‘quintus’

   - SICStus Prolog: ‘sicstus’

   - SWI-Prolog: ‘swi’

   - Tau Prolog: ‘tau’

   - Trealla Prolog: ‘trealla’

   - XSB: ‘xsb’

   - XVM: ‘xvm’

   - YAP: ‘yap’


File: TheLogtalkHandbook-3.96.0.info,  Node: Pack development,  Next: Pack handling,  Prev: Pack portability,  Up: packs

5.16.18 Pack development
------------------------

To simplify pack development and testing, define a local registry and
add to it a pack specification with the development version available
from a local directory.  For example:

     version(
         0:11:0,
         beta,
         'file:///home/jdoe/work/my_awesome_library',
         none,
         [],
         all
     ).

If the directory is a git repo, the tool will clone it when installing
the pack.  Otherwise, the files in the directory are copied to the pack
installation directory.  This allows the pack to be installed, updated,
and uninstalled without consequences for the pack source files.

You can also use a local archive instead of a directory.  For example:

     version(
         1:0:0,
         stable,
         'file:///home/jdoe/work/my_awesome_library/v1.0.0.tar.gz',
         sha256 - '1944773afba1908cc6194297ff6b5ac649a844ef69a69b2bcdf267cfa8bfce1e',
         [],
         all
     ).

Packs that are expected to be fully portable should always be checked by
loading them with the ‘portability’ flag set to ‘warning’.

To check your pack manifest files, use the ‘packs::lint/0-2’ predicates
after adding the registry that provides the packs.


File: TheLogtalkHandbook-3.96.0.info,  Node: Pack handling,  Next: Pack documentation,  Prev: Pack development,  Up: packs

5.16.19 Pack handling
---------------------

Packs must be available from a defined registry.  To list all packs that
are available for installation, use the ‘packs::available/0’ predicate:

     | ?- packs::available.

To list all installed packs, call the ‘packs::installed/0’ predicate:

     | ?- packs::installed.

To list only the installed packs from a specific registry, call instead
the ‘packs::installed/1’ predicate.  For example:

     | ?- packs::installed(talkshow).

To know more about a specific pack, use the ‘packs::describe/1-2’
predicates.  For example:

     | ?- packs::describe(bar).

The ‘packs::describe/2’ predicate can be used when two or more
registries provide packs with the same name.  For example:

     | ?- packs::describe(reg, bar).

To install the latest version of a pack, we can use the
‘packs::install/1-4’ predicates.  In the most simple case, when a pack
name is unique among registries, we can use the ‘packs::install/1’
predicate.  For example:

     | ?- packs::install(bar).

Any pack dependencies are also checked and installed or updated if
necessary.  Other install predicates are available to disambiguate
between registries and to install a specific pack version.

Packs become available for loading immediately after successful
installation (no restarting of the Logtalk session is required).  For
example, after the pack ‘bar’ is installed, you can load it at the
top-level by typing:

     | ?- {bar(loader)}.

or load it from a loader file using the goal
‘logtalk_load(bar(loader))’.

After updating the defined registries, outdated packs can be listed
using the ‘packs::outdated/0’ predicate.  You can update all outdated
packs by calling the ‘packs::update/0’ predicate or update a single pack
using the ‘packs::update/1-2’ predicates.  For example:

     | ?- packs::update(bar).

By default, updating a pack fails if it would break any dependent pack
(the ‘force(true)’ option, described below, can be used to force
updating in this case).

The tool provides versions of the pack install, update, and uninstall
predicates that accept a list of options:

   - ‘verbose(Boolean)’ (default is ‘false’)

   - ‘clean(Boolean)’ (default is ‘false’)

   - ‘update(Boolean)’ (default is ‘false’)

   - ‘force(Boolean)’ (default is ‘false’)

   - ‘compatible(Boolean)’ (default is ‘true’)

   - ‘checksum(Boolean)’ (default is ‘true’)

   - ‘checksig(Boolean)’ (default is ‘false’)

   - ‘git(Atom)’ (extra command-line options; default is ‘''’)

   - ‘downloader(Atom)’ (downloader utility; default is ‘curl’)

   - ‘curl(Atom)’ (extra command-line options; default is ‘''’)

   - ‘wget(Atom)’ (extra command-line options; default is ‘''’)

   - ‘gpg(Atom)’ (extra command-line options; default is ‘''’)

   - ‘tar(Atom)’ (extra command-line options; default is ‘''’)

Note that, by default, only compatible packs can be installed.  To
install a pack that is incompatible with the current Logtalk version,
backend version, or operating-system version, use the ‘install/4’ or
‘update/3’ predicates with the option ‘compatible(false)’.

When installing large packs over unreliable network conditions, you may
try switching the default downloader utility from ‘curl’ to ‘wget’.

When a pack may already be installed, you can use the ‘update(true)’
option to ensure that the installation will be updated to the specified
version:

     | ?- packs::install(reg, bar, 1:1:2, [update(true)]).

When using a ‘checksig(true)’ option to check a pack signature, it is
strongly advised that you also use the ‘verbose(true)’ option.  For
example:

     | ?- packs::install(reg, bar, 1:1:2, [verbose(true), checksig(true)]).

Note that the public key used to sign the pack archive must already be
present in your local system.

Downloading pack archives may require passing extra command-line options
to ‘curl’ for authentication.  A common solution is to use a personal
access token.  The details depend on the server software.  An example
when using GitHub:

     | ?- packs::install(reg, bar, 1:1:2, [curl('--header "Authorization: token foo42"')]).

Another example when using GitLab:

     | ?- packs::install(reg, bar, 1:1:2, [curl('--header "PRIVATE-TOKEN: foo42"')]).

Pack archives may be ‘gpg’ encrypted.  Encryption can be
passphrase-based, key-based, or both.  When using only passphrase-based
encryption, the archive passphrase must be entered (if not cached) when
installing or updating a pack.  In this case, the passphrase can be
entered interactively or using the ‘gpg/1’ option.  For example:

     | ?- packs::install(reg, bar, 1:1:2, [gpg('--batch --passphrase test123')]).

See the ‘gpg’ documentation for details.  When using the ‘gpg/1’ option,
you should be careful to not leak passphrases in, e.g., the query
history.

To uninstall a pack that you no longer need, use the
‘packs::uninstall/1-2’ predicates.  By default, only packs with no
dependent packs can be uninstalled.  You can print or get a list of the
packs that depend on a given pack by using the ‘packs::dependents/1-3’
predicates.  For example:

     | ?- packs::dependents(reg, bar, Dependents).

See the tool API documentation on the packs(1) object for other useful
predicates.

   ---------- Footnotes ----------

   (1) ../../docs/packs_0.html


File: TheLogtalkHandbook-3.96.0.info,  Node: Pack documentation,  Next: Pinning registries and packs,  Prev: Pack handling,  Up: packs

5.16.20 Pack documentation
--------------------------

The path to the pack ‘README.md’ file is printed when the pack is
installed or updated.  It can also be retrieved at any time by using the
‘readme/2’ predicate.  For example:

     | ?- packs::readme(lflat, Path).

Additional documentation may also be available from the pack home page,
which can be printed by using the ‘describe/1-2’ predicates.  For
example:

     | ?- packs::describe(lflat).

     % Registry:    ...
     % Pack:        lflat
     % Description: L-FLAT - Logtalk Formal Language and Automata Toolkit
     % License:     MIT
     % Home:        https://github.com/l-flat/lflat
     % Versions:
     ...

The pack API documentation can be generated using the ‘lgtdoc’ tool
library and directory predicates (depending on the pack source files
organization).  For example:

     | ?- {lflat(loader)},
          {lgtdoc(loader)},
          logtalk::expand_library_path(lflat, Path),
          lgtdoc::rdirectory(Path).
     ...

This query creates a ‘xml_docs’ directory in the current directory.  The
XML documentation files can then be converted into a final format, e.g.,
HTML, using one of the scripts provided by the ‘lgtdoc’ tool.  For
example:

     $ cd xml_docs
     $ lgt2html

For more details and alternatives, see the ‘lgtdoc’ tool documentation.

It is also possible to add API documentation and diagrams for all the
installed packs to the Logtalk distribution API documentation and
diagrams by calling the ‘build’ and ‘update_svg_diagrams’ scripts in the
‘docs/apis/sources’ directory with the ‘-i’ option.  See the scripts
documentation for more details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Pinning registries and packs,  Next: Testing packs,  Prev: Pack documentation,  Up: packs

5.16.21 Pinning registries and packs
------------------------------------

Registries and packs can be 'pinned' after installation to prevent
accidental updating or deleting, e.g., when using the batch ‘update/0’
predicate.  This is useful when your application requires a specific
version or for security considerations (see below).  For example, if we
want the ‘bar’ pack to stay at its current installed version:

     | ?- packs::pin(bar).
     yes

After, any attempt to update or uninstall the pack will fail with an
error message:

     | ?- packs::update(bar).
     !     Cannot update pinned pack: bar
     no

     | ?- packs::uninstall(bar).
     !     Cannot uninstall pinned pack: bar
     no

To enable the pack to be updated or uninstalled, the pack must first be
unpinned.  Alternatively, the ‘force(true)’ option can be used.  Note
that if you force update a pinned pack, the new version will be
unpinned.

It’s also possible to pin (or unpin) all defined registries or installed
packs at once by using the ‘pin/0’ (or ‘unpin/0’) predicates.  But note
that registries added after or packs installed after will not be
automatically pinned.


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing packs,  Next: Security considerations,  Prev: Pinning registries and packs,  Up: packs

5.16.22 Testing packs
---------------------

Logtalk packs (as most Logtalk libraries, tools, and examples) are
expected to have a ‘tester.lgt’ or ‘tester.logtalk’ tests driver file at
the root of their directory, which can be used for both automated and
manual testing.  For example, after installing the ‘foo’ pack:

     | ?- {foo(tester)}.

To test all installed packs, you can use the ‘logtalk_tester’ automation
script from the installed packs directory, which you can query using the
goal:

     | ?- packs::prefix(Directory).

Note that running the packs tests, like simply loading the pack, can
result in calling arbitrary code, which can potentially harm your
system.  Always take into account the security considerations discussed
below.


File: TheLogtalkHandbook-3.96.0.info,  Node: Security considerations,  Next: Best practices,  Prev: Testing packs,  Up: packs

5.16.23 Security considerations
-------------------------------

New pack registries should be examined before being added, specially if
public and from a previously unknown source.  The same precautions
should be taken when adding or updating a pack.  Note that a registry
can always index third-party packs.

Pack checksums are checked by default.  But pack signatures are only
checked if requested, as packs are often unsigned.  Care should be taken
when adding public keys for pack signers to your local system.

Registry and pack spec files, plus the registry loader file, are
compiled by term-expanding them so that only expected terms are actually
loaded and only expected ‘logtalk_load/2’ goals with expected relative
file paths are allowed.  Predicates defining URLs are discarded if the
URLs are neither ‘https://’ nor ‘file://’ URLs or if they contain
non-allowed characters (currently, only alpha-numeric ASCII characters
plus the ASCII ‘/’, ‘.’, ‘-’, and ‘_’ characters are accepted).  But
note that this tool makes no attempt to audit pack source files
themselves.

Registries and packs can always be pinned so that they are not
accidentally updated to a version that you may not have had the chance
to audit.


File: TheLogtalkHandbook-3.96.0.info,  Node: Best practices,  Next: Installing Prolog packs,  Prev: Security considerations,  Up: packs

5.16.24 Best practices
----------------------

   - Make available a new pack registry as a git repo.  This simplifies
     updating the registry and rolling back to a previous version.

   - Use registry and pack names that are valid unquoted atoms, thus
     simplifying usage.  Use descriptive names with underscores if
     necessary to link words.

   - Name the registry and pack specification objects after their names
     with a ‘_registry’ or ‘_pack’ suffix.  Save the objects in files
     named after the objects.

   - Create new pack versions from git tags.

   - If the sources of a pack are available from a git repo, consider
     using signed commits and signed tags for increased security.

   - When a new pack version breaks backwards compatibility, list both
     the old and the new versions on the pack specification file.

   - Pin registries and packs when specific versions are critical for
     your work so that you can still easily batch update the remaining
     packs and registries.

   - Include the ‘$LOGTALKPACKS’ directory (or the default
     ‘~/logtalk_packs’ directory) on your regular backups.


File: TheLogtalkHandbook-3.96.0.info,  Node: Installing Prolog packs,  Next: Help with warnings<3>,  Prev: Best practices,  Up: packs

5.16.25 Installing Prolog packs
-------------------------------

This tool can also be used to install Prolog packs that don’t use
Logtalk.  After installing a ‘pl_pack’ Prolog pack from a ‘pl_reg’
registry, it can be found in the ‘$LOGTALKPACKS/packs/pl_reg/pl_pack’
directory.  When the ‘LOGTALKPACKS’ environment variable is not defined,
the pack directory is by default ‘~/logtalk_packs/packs/pl_reg/pl_pack’.

Different Prolog systems provide different solutions for locating Prolog
code.  For example, several Prolog systems adopted the Quintus Prolog
‘file_search_path/2’ hook predicate.  For these systems, a solution
could be to add a fact to this predicate for each installed Prolog pack.
For example, assuming a ‘pl_pack’ Prolog pack:

     :- multifile(file_search_path/2).
     :- dynamic(file_search_path/2).

     file_search_path(library, '$LOGTALKPACKS/packs/pl_pack').

If the Prolog system also supports reading an initialization file at
startup, the above definition could be added there.


File: TheLogtalkHandbook-3.96.0.info,  Node: Help with warnings<3>,  Next: Known issues<6>,  Prev: Installing Prolog packs,  Up: packs

5.16.26 Help with warnings
--------------------------

Load the ‘tutor’ tool to get help with selected warnings printed by the
‘packs’ tool.


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<6>,  Prev: Help with warnings<3>,  Up: packs

5.16.27 Known issues
--------------------

Using the ‘verbose(true)’ option on Windows systems may not provide the
shell commands output depending on the backend.

On Windows systems, the reset, delete, and uninstall predicates may fail
to delete all affected folders and files due to a operating-system bug.
Depending on the backend, this bug may cause some of the tests to fail.
For details on this bug, see:

‘https://github.com/microsoft/terminal/issues/309’

The workaround is to use the Windows File Explorer to delete the
leftover folders and files.

When using Ciao Prolog 1.20.0, a workaround is used for this system
non-standard support for multifile predicates.

When using GNU Prolog 1.5.0 as the backend on Windows, you may get an
error on ‘directory_files/2’ calls.  For details and a workaround, see:

‘https://github.com/didoudiaz/gprolog/issues/4’

This issue is fixed in the latest GNU Prolog git version.

Using SICStus Prolog as the backend on Windows doesn’t currently work in
version 4.7.0 and earlier versions.  The underlying issues are fixed in
the SICStus Prolog 4.7.1 version.

XSB has an odd bug (likely in its parser) when reading files that may
cause a pack installed version to be reported as the ‘end_of_file’ atom.

Some tests fail on Windows when using ECLiPSe or XSB due to file path
representation issues.


File: TheLogtalkHandbook-3.96.0.info,  Node: ports_profiler,  Next: profiler,  Prev: packs,  Up: Developer Tools

5.17 ‘ports_profiler’
=====================

This tool counts and reports the number of times each port in the
'procedure box model' is traversed during the execution of queries.  It
can also report the number of times each clause (or grammar rule) is
used.  It is inspired by the ECLiPSe ‘port_profiler’ tool.

The procedure box model is the same as the one used in the debugger
tool.  This is an extended version of the original Byrd’s four-port
model.  Besides the standard ‘call’, ‘exit’, ‘fail’, and ‘redo’ ports,
Logtalk also defines two post-unification ports, ‘fact’ and ‘rule’, and
an ‘exception’ port.  This tool can also distinguish between
deterministic exits (reported in the ‘exit’ column in the profiling
result tables) and exits that leave choice-points (reported in the
‘*exit’ column).

* Menu:

* API documentation: API documentation<13>.
* Loading: Loading<13>.
* Testing: Testing<11>.
* Compiling source files for port profiling::
* Generating profiling data::
* Printing profiling data reports::
* Interpreting profiling data::
* Profiling Prolog modules::
* Profiling plain Prolog code::
* Known issues: Known issues<7>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<13>,  Next: Loading<13>,  Up: ports_profiler

5.17.1 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#ports-profiler’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<13>,  Next: Testing<11>,  Prev: API documentation<13>,  Up: ports_profiler

5.17.2 Loading
--------------

     | ?- logtalk_load(ports_profiler(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<11>,  Next: Compiling source files for port profiling,  Prev: Loading<13>,  Up: ports_profiler

5.17.3 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ports_profiler(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiling source files for port profiling,  Next: Generating profiling data,  Prev: Testing<11>,  Up: ports_profiler

5.17.4 Compiling source files for port profiling
------------------------------------------------

To compile source files for port profiling, simply compile them in debug
mode and with the ‘source_data’ flag turned on.  For example:

     | ?- logtalk_load(my_source_file, [debug(on), source_data(on)]).

Alternatively, you can also simply turn on the ‘debug’ and ‘source_data’
flags globally before compiling your source files:

     | ?- set_logtalk_flag(debug, on), set_logtalk_flag(source_data, on).

Be aware, however, that loader files (e.g., library loader files) may
override the default flag values, and thus the loaded files may not be
compiled in debug mode.  In this case, you will need to modify the
loader files themselves.


File: TheLogtalkHandbook-3.96.0.info,  Node: Generating profiling data,  Next: Printing profiling data reports,  Prev: Compiling source files for port profiling,  Up: ports_profiler

5.17.5 Generating profiling data
--------------------------------

After loading this tool and compiling the source files that you want to
profile in debug mode, simply call the ‘ports_profiler::start’ goal
followed by the goals to be profiled.  Use the ‘ports_profiler::stop’
goal to stop profiling.

Note that the ‘ports_profiler::start/0’ predicate implicitly selects the
‘ports_profiler’ tool as the active debug handler.  If you have
additional debug handlers loaded (e.g., the ‘debugger’ tool), those
would no longer be active (there can be only one active debug handler at
any given time).


File: TheLogtalkHandbook-3.96.0.info,  Node: Printing profiling data reports,  Next: Interpreting profiling data,  Prev: Generating profiling data,  Up: ports_profiler

5.17.6 Printing profiling data reports
--------------------------------------

After calling the goals that you want to profile, you can print a table
with all profile data by typing:

     | ?- ports_profiler::data.

To print a table with data for a single entity, use the query:

     | ?- ports_profiler::data(Entity).

To print a table with data for a single entity predicate, use the query:

     | ?- ports_profiler::data(Entity, Predicate).

In this case, the second argument must be either a predicate indicator,
‘Name/Arity’, or a non-terminal indicator, ‘Name//Arity’.

The profiling data can be reset using the query:

     | ?- ports_profiler::reset.

To reset only the data for a specific entity, use the query:

     | ?- ports_profiler::reset(Entity).

To illustrate the tool output, consider the ‘family’ example in the
Logtalk distribution:

     | ?- {ports_profiler(loader)}.
     ...
     yes

     | ?- set_logtalk_flag(debug, on).
     yes

     | ?- logtalk_load(family(loader)).
     ...
     yes

     | ?- ports_profiler::start.
     yes

     | ?- addams::sister(Sister, Sibling).
     Sister = wednesday,
     Sibling = pubert ;
     Sister = wednesday,
     Sibling = pugsley ;
     Sister = wednesday,
     Sibling = pubert ;
     Sister = wednesday,
     Sibling = pugsley ;
     no

     | ?- ports_profiler::data.
     ----------------------------------------------------------------------
     Entity     Predicate    Fact  Rule  Call  Exit *Exit  Fail  Redo Error
     ----------------------------------------------------------------------
     addams     female/1        2     0     1     1     1     0     1     0
     addams     parent/2        8     0     4     3     5     1     5     0
     relations  sister/2        0     1     1     0     4     1     4     0
     ----------------------------------------------------------------------
     yes

     | ?- ports_profiler::data(addams).
     -----------------------------------------------------------
     Predicate    Fact  Rule  Call  Exit *Exit  Fail  Redo Error
     -----------------------------------------------------------
     female/1        2     0     1     1     1     0     1     0
     parent/2        8     0     4     3     5     1     5     0
     -----------------------------------------------------------
     yes

     | ?- ports_profiler::data(addams, parent/2).
     -------------
     Clause  Count
     -------------
          1      1
          2      1
          3      2
          4      1
          5      1
          6      2
     -------------
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Interpreting profiling data,  Next: Profiling Prolog modules,  Prev: Printing profiling data reports,  Up: ports_profiler

5.17.7 Interpreting profiling data
----------------------------------

Some useful information that can be inferred from the profiling data
include:

   - which predicates are called more often (from the ‘call’ port)

   - unexpected failures (from the ‘fail’ port)

   - unwanted non-determinism (from the ‘*exit’ port)

   - performance issues due to backtracking (from the ‘*exit’ and ‘redo’
     ports)

   - predicates acting like a generator of possible solutions (from the
     ‘*exit’ and ‘redo’ ports)

   - inefficient indexing of predicate clauses (from the ‘fact’, ‘rule’,
     and ‘call’ ports)

   - clauses that are never used or seldom used

The profiling data should be analyzed by taking into account the
expected behavior for the profiled predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Profiling Prolog modules,  Next: Profiling plain Prolog code,  Prev: Interpreting profiling data,  Up: ports_profiler

5.17.8 Profiling Prolog modules
-------------------------------

This tool can also be applied to Prolog modules that Logtalk is able to
compile as objects.  For example, if the Prolog module file is named
‘module.pl’, try:

     | ?- logtalk_load(module, [debug(on), source_data(on)]).

Due to the lack of standardization of module systems and the abundance
of proprietary extensions, this solution is not expected to work for all
cases.


File: TheLogtalkHandbook-3.96.0.info,  Node: Profiling plain Prolog code,  Next: Known issues<7>,  Prev: Profiling Prolog modules,  Up: ports_profiler

5.17.9 Profiling plain Prolog code
----------------------------------

This tool can also be applied to plain Prolog code.  For example, if the
Prolog file is named ‘code.pl’, simply define an object including its
code and declaring as public any predicates that you want to use as
messages to the object.  For example:

     :- object(code).

         :- public(foo/2).
         :- include('code.pl').

     :- end_object.

Save the object to an e.g.  ‘code.lgt’ file in the same directory as the
Prolog file and then load it in debug mode:

     | ?- logtalk_load(code, [debug(on), source_data(on)]).

In alternative, use the ‘object_wrapper_hook’ provided by the
‘hook_objects’ library:

     | ?- logtalk_load(hook_objects(loader)).
     ...

     | ?- logtalk_load(
              code,
              [hook(object_wrapper_hook), debug(on),
               source_data(on), context_switching_calls(allow)]
          ).

In this second alternative, you can then use the ‘(<<)/2’ context switch
control construct to call the wrapped predicates.  E.g.

     | ?- code<<foo(X, Y).

With either wrapping solution, pay special attention to any compilation
warnings that may signal issues that could prevent the plain Prolog code
from working as-is when wrapped by an object.  Often any required
changes are straightforward (e.g., adding ‘use_module/2’ directives for
called module library predicates).


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<7>,  Prev: Profiling plain Prolog code,  Up: ports_profiler

5.17.10 Known issues
--------------------

Determinism information is currently not available when using Quintus
Prolog as the backend compiler.


File: TheLogtalkHandbook-3.96.0.info,  Node: profiler,  Next: tutor,  Prev: ports_profiler,  Up: Developer Tools

5.18 ‘profiler’
===============

This tool contains simple wrappers for selected Prolog profiler tools.

* Menu:

* Loading: Loading<14>.
* Testing: Testing<12>.
* Supported backend Prolog compilers::
* Compiling source code for profiling::


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<14>,  Next: Testing<12>,  Up: profiler

5.18.1 Loading
--------------

This tool can be loaded using the query:

     ?- logtalk_load(profiler(loader)).

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<12>,  Next: Supported backend Prolog compilers,  Prev: Loading<14>,  Up: profiler

5.18.2 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(profiler(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Supported backend Prolog compilers,  Next: Compiling source code for profiling,  Prev: Testing<12>,  Up: profiler

5.18.3 Supported backend Prolog compilers
-----------------------------------------

Currently, this tool supports the profilers provided with SICStus Prolog
4, SWI-Prolog, and YAP. The tool includes two files:

   - 
          ‘yap_profiler.lgt’
          simple wrapper for the YAP count profiler

   - 
          ‘sicstus_profiler.lgt’
          simple wrapper for the SICStus Prolog 4 profiler

Logtalk also supports the YAP tick profiler (using the latest YAP
development version) and the SWI-Prolog XPCE profiler.  When using the
XPCE profiler, you can avoid profiling the Logtalk compiler (which is
invoked, e.g., when you use the ‘(::)/2’ message-sending operator at the
top-level interpreter) by compiling your code with the ‘optimize’ flag
turned on:

     ?- set_logtalk_flag(optimize, on).
     true.

     ?- use_module(library(statistics)).
     true.

     ?- profile(... :: ...).
     ...

Given that ‘prolog_statistics:profile/1’ is a meta-predicate, Logtalk
will compile its argument before calling it thanks to the
‘goal_expansion/2’ hook predicate definitions in the adapter file.
Without this hook definition, you would need to use instead (to avoid
profiling the compiler itself):

     ?- logtalk << (prolog_statistics:profile(... :: ...)).
     ...

In either case, don’t forget, however, to load the ‘prolog_statistics’
module 'before' using or compiling calls to the ‘profile/1’ to allow the
Logtalk compiler to access its meta-predicate template.

The profiler support attempts to conceal internal Logtalk
compiler/runtime predicates and the generated entity predicates that
implement predicate inheritance.  Calls to internal compiler and runtime
predicates have functors starting with ‘$lgt_’.  Calls to predicates
with functors such as ‘_def’, ‘_dcl’, or ‘_super’, used to implement
inheritance, may still be listed in a few cases.  Note that the time and
the number of calls/redos of concealed predicates are added to the
caller predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: Compiling source code for profiling,  Prev: Supported backend Prolog compilers,  Up: profiler

5.18.4 Compiling source code for profiling
------------------------------------------

To get the user-level object and predicate names instead of the
compiler-generated internal names when using the SWI-Prolog and YAP
profilers, you must set ‘code_prefix’ flag to a character other than the
default ‘$’ before compiling your source code.  For example:

     ?- set_logtalk_flag(code_prefix, '.').

See also the ‘samples/settings-sample.lgt’ file for automating the
necessary setup at Logtalk startup.


File: TheLogtalkHandbook-3.96.0.info,  Node: tutor,  Next: wrapper,  Prev: profiler,  Up: Developer Tools

5.19 ‘tutor’
============

This tool adds explanations and suggestions for selected warning and
error messages from the compiler/runtime and the developer tools.  It’s
specially useful for new users not yet familiar with the warning and
error messages and looking for advice on how to solve the reported
issues.

* Menu:

* API documentation: API documentation<14>.
* Loading: Loading<15>.
* Usage: Usage<8>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<14>,  Next: Loading<15>,  Up: tutor

5.19.1 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#tutor’


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<15>,  Next: Usage<8>,  Prev: API documentation<14>,  Up: tutor

5.19.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(tutor(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<8>,  Prev: Loading<15>,  Up: tutor

5.19.3 Usage
------------

Simply load the tool at startup (e.g., from a settings file).  As an
example, with this tool loaded, instead of terse compiler warnings such
as:

     *     No matching clause for goal: baz(a)
     *       while compiling object main_include_compiler_warning
     *       in file logtalk/examples/errors/include_compiler_warning.lgt between lines 37-38
     *
     *     Duplicated clause: b(one)
     *       first found at or above line 45
     *       while compiling object main_include_compiler_warning
     *       in file logtalk/examples/errors/include_compiler_warning.lgt at or above line 48

the user will get:

     *     No matching clause for goal: baz(a)
     *       while compiling object main_include_compiler_warning
     *       in file logtalk/examples/errors/include_compiler_warning.lgt between lines 37-38
     *     Calls to locally defined predicates without a clause with a matching head
     *     fail. Typo in a predicate argument? Predicate definition incomplete?
     *
     *     Duplicated clause: b(one)
     *       first found at or above line 45
     *       while compiling object main_include_compiler_warning
     *       in file logtalk/examples/errors/include_compiler_warning.lgt at or above line 48
     *     Duplicated clauses are usually a source code editing error and can
     *     result in spurious choice-points, degrading performance. Delete or
     *     correct the duplicated clause to fix this warning.


File: TheLogtalkHandbook-3.96.0.info,  Node: wrapper,  Prev: tutor,  Up: Developer Tools

5.20 ‘wrapper’
==============

This is a prototype tool to help port a plain Prolog application to
Logtalk.  It can also be used to enable applying other Logtalk developer
tools, such as the documenting and diagramming tools, to plain Prolog
code.

The tool takes a directory of Prolog files or a list of Prolog files,
loads and wraps the code in each file using an object wrapper, and
advises on missing directives to be added to those objects by using the
compiler lint checker and the reflection API. The user can then either
save the generated wrapper objects or copy and paste the printed advice
into the Prolog files (updating them to Logtalk files by adding the
object opening and closing directives to the Prolog files).  The wrapper
objects use ‘include/1’ directives to include the Prolog files and can
be loaded for testing and for use with other tools.  The wrapped Prolog
files are not modified and thus require only read permission.

* Menu:

* API documentation: API documentation<15>.
* Loading: Loading<16>.
* Workflows::
* Customization: Customization<2>.
* Current limitations::


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<15>,  Next: Loading<16>,  Up: wrapper

5.20.1 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#wrapper’


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<16>,  Next: Workflows,  Prev: API documentation<15>,  Up: wrapper

5.20.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(wrapper(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Workflows,  Next: Customization<2>,  Prev: Loading<16>,  Up: wrapper

5.20.3 Workflows
----------------

The typical porting workflow is:

     | ?- wrapper::rdirectory(root_directory_of_prolog_code).
     ...
     | ?- wrapper::save.
     ...

See the next section on how to customize the API calls for more flexible
processing.


File: TheLogtalkHandbook-3.96.0.info,  Node: Customization<2>,  Next: Current limitations,  Prev: Workflows,  Up: wrapper

5.20.4 Customization
--------------------

The tool can be customized by extending the ‘wrapper’ object.  A common
scenario is when wrapping plain Prolog code just to take advantage, for
example, of the documenting tool or for generating cross-referencing
diagrams.  In this case, we can workaround any compiler errors by
specializing the inherited definitions for the ‘term_expansion/2’ and
‘goal_expansion/2’ predicates and then load the wrapper objects for
further processing by using the ‘include_wrapped_files(false)’ option
described below.

The API predicates also accept a set of options for customization:

   - 
          ‘prolog_extensions(Extensions)’
          list of file name extensions used to recognize Prolog source files (default is ‘['.pl', '.pro', '.prolog']’)

   - 
          ‘logtalk_extension(Extension)’
          Logtalk file name extension to be used for the generated wrapper files (default is ‘'.lgt'’)

   - 
          ‘exclude_files(Files)’
          list of Prolog source files to exclude (default is ‘[]’)

   - 
          ‘exclude_directories(Files)’
          list of sub-directories to exclude (default is ‘[]’)

   - 
          ‘include_wrapped_files(Boolean)’
          generate ‘include/1’ directives for the wrapped Prolog source files (default is ‘true’)

The use, by default, of ‘include/1’ directives to wrap the code in
Prolog source files facilitates running in parallel the Logtalk port and
the original Prolog code.  This is specially useful when the Prolog code
being ported lacks a comprehensive set of tests that could be adapted to
verify the Logtalk port.  The generated Logtalk files can also take
advantage of ‘uses/2’ directives, including predicate aliases and
predicate shorthands to minimize the changes to the original Prolog code
and help verify if replacement calls to Logtalk library predicates
provide the same semantics as the original calls.


File: TheLogtalkHandbook-3.96.0.info,  Node: Current limitations,  Prev: Customization<2>,  Up: wrapper

5.20.5 Current limitations
--------------------------

   - The tool cannot deal with syntax errors in the Prolog files.  These
     errors usually occur when using a backend Prolog system different
     from the one used to compile the original plain Prolog code.  A
     common cause of syntax errors is operator definitions.  These can
     often be solved by defining those operators for the Prolog backend
     used to run Logtalk and this tool.  An alternative is to preload
     the Prolog files where those operators are declared.  Preloading
     the plain Prolog application can also help in wrapping it by
     ensuring that its dependencies are also loaded.

   - The tool assumes that all files to be wrapped have different names
     (even if found in different directories).  If that is not the case,
     the name conflicts must be manually solved before using the tool.

   - There’s only preliminary support for dealing with meta-predicates
     and advise on missing meta-predicate directives.


File: TheLogtalkHandbook-3.96.0.info,  Node: Libraries,  Next: Ports,  Prev: Developer Tools,  Up: Top

6 Libraries
***********

The documentation of each library can also be found in the library
directory in the ‘NOTES.md’ file.

* Menu:

* Overview: Overview<2>.
* arbitrary::
* assignvars::
* base64::
* basic_types::
* cbor::
* core::
* coroutining::
* csv::
* dates::
* dependents::
* dictionaries::
* dif::
* edcg::
* events::
* expand_library_alias_paths::
* expecteds::
* format::
* genint::
* gensym::
* git::
* grammars::
* heaps::
* hierarchies::
* hook_flows::
* hook_objects::
* html::
* ids::
* intervals::
* java::
* json::
* json_lines::
* listing::
* logging::
* loops::
* meta::
* meta_compiler::
* mutations::
* nested_dictionaries::
* optionals::
* options::
* os::
* queues::
* random::
* reader::
* recorded_database::
* redis::
* sets::
* statistics::
* term_io::
* timeout::
* tsv::
* types::
* ulid::
* unicode_data::
* union_find::
* uuid::
* zippers::


File: TheLogtalkHandbook-3.96.0.info,  Node: Overview<2>,  Next: arbitrary,  Up: Libraries

6.1 Overview
============

This folder contains libraries of useful objects, categories, and
protocols.  Specific notes about individual libraries can be found in
the corresponding library directory ‘NOTES.md’ files.

A plain Prolog version of the Unicode 6.2 standard is also included in
the ‘unicode_data’ folder.  See its ‘README.md’ file for details.

A ‘parallel_logtalk_processes_setup.pl’ Prolog file is also provided
with sample code for selected backend Prolog compilers for initializing
Logtalk processes such that each process uses a unique scratch
directory, therefore allowing parallel process execution (e.g., for
usage at continuous integration servers).  Starting with Logtalk 3.48.0,
this setup is only required in general when running with the ‘clean’
flag turned off.  See the comments in the file itself for usage
instructions.

* Menu:

* Library documentation::
* Loading libraries::
* Testing libraries::
* Credits::
* Other notes: Other notes<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Library documentation,  Next: Loading libraries,  Up: Overview<2>

6.1.1 Library documentation
---------------------------

Specific notes about each library can be found in the corresponding
‘NOTES.md’ files.  HTML documentation for each library API can be found
on the ‘docs’ directory (open the ‘../docs/handbook/index.html’ file
with your web browser).


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading libraries,  Next: Testing libraries,  Prev: Library documentation,  Up: Overview<2>

6.1.2 Loading libraries
-----------------------

All the individual libraries can be loaded using the ‘<library
name>(loader)’ notation as argument for the compiling and loading
predicates.  For example:

     | ?- logtalk_load(random(loader)).

There is also a file named ‘all_loader.lgt’ that will load all
libraries.  Simply type the goal:

     | ?- logtalk_load(library(all_loader)).

As a general rule, always use the corresponding loader file to load a
library.  Most library entities are part of small hierarchies or depend
on other libraries and thus cannot be loaded and compiled separately
(e.g., the ‘list’ object implements the ‘listp’ protocol and is part of
a basic types hierarchy).  Using the loader files takes care of all
dependencies and also ensures compilation in optimized mode.


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing libraries,  Next: Credits,  Prev: Loading libraries,  Up: Overview<2>

6.1.3 Testing libraries
-----------------------

Most of the libraries include unit tests in their directory, together
with a ‘tester.lgt’ file for running them.  For example, to run the
tests for the ‘random’ library, we can use the goal:

     | ?- logtalk_load(random(tester)).

To run all library tests, we can use the ‘logtalk_tester’ automation
script from the ‘library’ directory at the root of the Logtalk
distribution.  For example, assuming the Logtalk user directory is
‘~/logtalk’ and that we want to run the tests using ECLiPSe as the
backend Prolog compiler:

     $ cd ~/logtalk/library
     $ logtalk_tester -p eclipse


File: TheLogtalkHandbook-3.96.0.info,  Node: Credits,  Next: Other notes<2>,  Prev: Testing libraries,  Up: Overview<2>

6.1.4 Credits
-------------

Some code in this library is based on public domain Prolog code, in
particular, code adopted from the Edinburgh Prolog library.  The
definition of the predicate ‘reverse/2’ in the ‘list’ object is from
Richard O’Keefe and can be found in its book “The Craft of Prolog”.

Some elements of this library are inspired by Richard O’Keefe library
proposal available at:

‘http://www.cs.otago.ac.nz/staffpriv/ok/pllib.htm’

Some libraries, or parts of libraries, are either ports of Prolog system
libraries or inspired by Prolog system libraries.  See the individual
library notes for details.  See also the ‘NOTICE.txt’ file at the root
of the Logtalk distribution for copyright information on third-party
source code.


File: TheLogtalkHandbook-3.96.0.info,  Node: Other notes<2>,  Prev: Credits,  Up: Overview<2>

6.1.5 Other notes
-----------------

Some files contained in this directory represent work in progress and
are not loaded by default by any loader utility file.


File: TheLogtalkHandbook-3.96.0.info,  Node: arbitrary,  Next: assignvars,  Prev: Overview<2>,  Up: Libraries

6.2 ‘arbitrary’
===============

The ‘arbitrary’ library defines an ‘arbitrary’ category providing
predicates for generating random values for selected types to the ‘type’
object, complementing its type checking predicates.  Both the object and
the category predicates can be extended by the user with definitions for
new types by defining clauses for multifile predicates.  This library is
notably used in the QuickCheck implementation by the ‘lgtunit’ tool.
See also the documentation of the ‘mutations’ library for related
functionality.

* Menu:

* API documentation: API documentation<16>.
* Loading: Loading<17>.
* Testing: Testing<13>.
* Pre-defined types::
* Usage: Usage<9>.
* Defining new generators and shrinkers::
* Scoped generators and shrinkers::
* Reproducing sequences of arbitrary terms::
* Default size of generated terms::
* Known issues: Known issues<8>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<16>,  Next: Loading<17>,  Up: arbitrary

6.2.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#arbitrary’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<17>,  Next: Testing<13>,  Prev: API documentation<16>,  Up: arbitrary

6.2.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(arbitrary(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<13>,  Next: Pre-defined types,  Prev: Loading<17>,  Up: arbitrary

6.2.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(arbitrary(tester)).

Several of the provided tests are generic and verify the correct
behavior of all pre-defined and loaded user-defined generators and
shrinkers for all ground types.


File: TheLogtalkHandbook-3.96.0.info,  Node: Pre-defined types,  Next: Usage<9>,  Prev: Testing<13>,  Up: arbitrary

6.2.4 Pre-defined types
-----------------------

This library defines random generators for the most common Logtalk and
Prolog types.  See the API documentation(1) for a listing of all the
pre-defined types.

   ---------- Footnotes ----------

   (1) ../../apis/library_index.html#arbitrary


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<9>,  Next: Defining new generators and shrinkers,  Prev: Pre-defined types,  Up: arbitrary

6.2.5 Usage
-----------

The ‘arbitrary’ category complements the ‘type’ object and thus its
predicates are accessed via this object.  For example:

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = -816
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining new generators and shrinkers,  Next: Scoped generators and shrinkers,  Prev: Usage<9>,  Up: arbitrary

6.2.6 Defining new generators and shrinkers
-------------------------------------------

To define a generator of arbitrary values for a type, define a clause
for the ‘arbitrary::arbitrary/1’ multifile predicate specifying the type
and a clause for the ‘arbitrary::arbitrary/2’ multifile predicate
generating an arbitrary term of the specified type.  As a simple
example, assume that we want to define an “odd integer type”.  We start
by defining both the type checker and the arbitrary generator:

     :- multifile(type::type/1).
     type::type(odd).

     :- multifile(type::check/2).
     type::check(odd, Term) :-
         (   var(Term) ->
             throw(instantiation_error)
         ;   integer(Term),
             Term mod 2 =:= 1 ->
             true
         ;   throw(type_error(odd, Term))
         ).

     :- multifile(arbitrary::arbitrary/1).
     arbitrary::arbitrary(odd).

     :- multifile(arbitrary::arbitrary/2).
     arbitrary::arbitrary(odd, Arbitrary) :-
         type::arbitrary(integer, Arbitrary0),
         (   Arbitrary0 mod 2 =:= 1 ->
             Arbitrary = Arbitrary0
         ;   Arbitrary is Arbitrary0 + 1
         ).

The ‘arbitrary’ library also provides 'meta-types' that can simplify the
definition of new generators.  For example, the ‘odd’ type above can
also be defined using the ‘constrain/2’ meta-type to only generate
values that satisfy a closure:

     arbitrary::arbitrary(odd, Arbitrary) :-
         arbitrary(constrain(integer, [Arbitrary]>>(Arbitrary mod 2 =:= 1)), Arbitrary).

Another example is using the ‘transform/2’ meta-type to transform
generated values for a base type using a closure.  Assuming that we want
to generate a sorted list of random integers, we can write:

     arbitrary::arbitrary(sorted_integer_list, Arbitrary) :-
         arbitrary(transform(list(integer), sort), Arbitrary).

We can also define a clause for the ‘arbitrary::shrinker/1’ multifile
predicate to declare a new shrinker and a ‘arbitrary::shrink/3’
multifile predicate for shrinking arbitrary values for QuickCheck usage:

     :- multifile(arbitrary::shrinker/1).
     arbitrary::shrinker(odd).

     :- multifile(arbitrary::shrink/3).
     arbitrary::shrink(odd, Large, Small) :-
         integer(Large),
         (   Large < -1 ->
             Small is Large + 2
         ;   Large > 1,
             Small is Large - 2
         ).

Definitions for the ‘shrink/3’ predicate should either succeed or fail
but never throw an exception.  The ‘shrink_sequence/3’ predicate can be
used to help test that shrinking a value results in a finite sequence of
values.

It is also possible to define edge cases for a given type for use with
QuickCheck implementations.  For example:

     :- multifile(arbitrary::edge_case/2).
     arbitrary::edge_case(odd,  1).
     arbitrary::edge_case(odd, -1).

Edge cases are tried before resorting to generating arbitrary values for
a type.

A more complex example is generating arbitrary values for a recursive
type.  A simple example of a recursive type is a binary tree.  Assuming
that we are working with a binary tree holding integers where each node
is represented by a ‘node(Left, Right)’ compound term, we can define a
‘node(Depth)’ type where ‘Depth’ is the maximum depth of the tree.  This
argument allows us to prevent excessively deep trees:

     :- category(binary_tree).

         :- multifile(type::type/1).
         type::type(node(_)).

         :- multifile(type::check/2).
         type::check(node(_), Term) :-
             (   check(Term) ->
                 true
             ;   var(Term) ->
                 throw(instantiation_error)
             ;   throw(type_error(node(_), Term))
             ).

         check(Term) :-
             (   integer(Term) ->
                 true
             ;   compound(Term),
                 Term = node(Left, Right),
                 check(Left),
                 check(Right)
             ).

         :- multifile(arbitrary::arbitrary/1).
         arbitrary::arbitrary(node(_)).

         :- multifile(arbitrary::arbitrary/2).
         arbitrary::arbitrary(node(Depth), Arbitrary) :-
         (   Depth > 1 ->
             NewDepth is Depth - 1,
             type::arbitrary(
                 types_frequency([
                     integer - 1,
                     compound(
                         node,
                         [
                             types([node(NewDepth), integer]),
                             types([node(NewDepth), integer])
                         ]
                     ) - 3
                 ]),
                 Arbitrary
             )
         ;   type::arbitrary(
         integer, Arbitrary)
         ).

     :- end_category.

In this second example, we use some of the pre-defined types provided by
the library.  The ‘types_frequency(Pairs)’ type supports generating
random terms for a type in the ‘Type-Frequency’ pairs list where the
type is randomly chosen after the types relative frequency.  The
‘compound(Name, Types)’ type supports generating compound terms with a
given name and random arguments after the given types:

     | ?- type::arbitrary(node(4), Arbitrary).
     Arbitrary = 907
     yes

     | ?- type::arbitrary(node(4), Arbitrary).
     Arbitrary = node(node(node(522, 509), node(83, 453)), node(454, -197))
     yes

     | ?- type::arbitrary(node(4), Arbitrary).
     Arbitrary = node(node(-875, -866), -254)
     yes

     | ?- type::arbitrary(node(4), Arbitrary).
     Arbitrary = node(-133, -831)
     yes

The source code of these examples can be found in the ‘test_files’
directory.  Other examples of arbitrary term generators can be found in
the implementation of the ‘optionals’ and ‘expecteds’ libraries.


File: TheLogtalkHandbook-3.96.0.info,  Node: Scoped generators and shrinkers,  Next: Reproducing sequences of arbitrary terms,  Prev: Defining new generators and shrinkers,  Up: arbitrary

6.2.7 Scoped generators and shrinkers
-------------------------------------

Declaring a new generator and possibly a shrinker for a custom type
raises the possibility of a conflict with third-party-defined generators
and shrinkers.  An alternative is to use the ‘(::)/2’ meta-type to
define scoped generators and shrinkers.  For example:

     :- object(scoped).

         % the same predicate is used for both generating and validating
         :- public(custom/1).
         custom(Term) :-
             (   var(Term) ->
                 % assume predicate used as a generator
                 random::random(Term)
             ;   % assume predicate used as a validator
                 float(Term)
             ).

         % a predicate with the same name is used for shrinking
         :- public(custom/2).
         custom(Larger, Small) :-
             Small is Larger / 2.

     :- end_object.

Some sample calls:

     | ?- type::arbitrary(scoped::custom, Arbitrary).
     Arbitrary = 0.5788130906607927
     yes

     | ?- type::valid(scoped::custom, foo).
     no

     | ?- type::check(scoped::custom, _).
     ERROR: type_error(instantiation_error)

     | ?- type::check(scoped::custom, foo).
     ERROR: type_error(scoped::custom, foo)

     | ?- type::shrink(scoped::custom, 0.42, Smaller).
     Smaller = 0.21
     yes

The source code of this example can be found in the ‘test_files’
directory.


File: TheLogtalkHandbook-3.96.0.info,  Node: Reproducing sequences of arbitrary terms,  Next: Default size of generated terms,  Prev: Scoped generators and shrinkers,  Up: arbitrary

6.2.8 Reproducing sequences of arbitrary terms
----------------------------------------------

The ‘arbitrary’ category provides access to the pseudo-random generator
it uses via the ‘get_seed/1’ and ‘set_seed/1’.  This allows sequences of
arbitrary values to be reproduced.  For example:

     | ?- type::get_seed(Seed).
     Seed = seed(3172, 9814, 20125)
     yes

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = -816
     yes

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = -113
     yes

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = 446

     | ?- type::set_seed(seed(3172, 9814, 20125)).
     yes

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = -816
     yes

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = -113
     yes

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = 446
     yes

The seed should be regarded as an opaque term and handled using the
‘get_seed/1’ and ‘set_seed/1’ predicates.  These predicates are notably
used in the QuickCheck implementation provided by the ‘lgtunit’ tool.


File: TheLogtalkHandbook-3.96.0.info,  Node: Default size of generated terms,  Next: Known issues<8>,  Prev: Reproducing sequences of arbitrary terms,  Up: arbitrary

6.2.9 Default size of generated terms
-------------------------------------

The library uses the value 42 for the default size of generated terms
for types where size is meaningful and implicit.  To override this
default value, define a clause for the ‘arbitrary::max_size/1’ multifile
predicate.  The new default size must be a positive integer.  For
example:

     :- multifile(arbitrary::max_size/1).
     arbitrary::max_size(7).

When multiple definitions exist, the first valid one found is used.
When no definition is valid, the default value of 42 is used.


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<8>,  Prev: Default size of generated terms,  Up: arbitrary

6.2.10 Known issues
-------------------

Some Prolog systems either don’t support the null character or provide
buggy results when calling ‘char_code/2’ with a code of zero.  When
that’s the case, the null character is excluded when generating
arbitrary characters or character codes.

Generating arbitrary Unicode characters (instead of Unicode codepoints)
is inherently problematic as the process first generates codepoints and
then tries to use the standard ‘char_code/2’ to convert them to
characters.  But, depending on the backend Prolog system and its
internal (if any) Unicode normalization, it may not be possible to
convert a codepoint to a single character.


File: TheLogtalkHandbook-3.96.0.info,  Node: assignvars,  Next: base64,  Prev: arbitrary,  Up: Libraries

6.3 ‘assignvars’
================

The ‘assignvarsp’ protocol declares the predicates used for logical
assignment of Prolog terms developed by Nobukuni Kino.

The ‘assignvars’ object provides a declarative implementation of the
‘assignvarsp’ protocol.  It can be used with any backend Prolog
compiler.

The ‘nd_assignvars’ object provides a non-declarative but faster
implementation of the ‘assignvarsp’ protocol.  It can be used with the
following backend Prolog compilers: B-Prolog, CxProlog, ECLiPSe, GNU
Prolog, SICStus Prolog, SWI-Prolog, and YAP.

For more information on assignvars, please consult the URL:

‘https://web.archive.org/web/20160818050049/http://www.kprolog.com/en/logical_assignment/’

The representation of assignable terms should be regarded as an opaque
term and only accessed using the library predicates.

* Menu:

* API documentation: API documentation<17>.
* Loading: Loading<18>.
* Testing: Testing<14>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<17>,  Next: Loading<18>,  Up: assignvars

6.3.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#assignvars’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<18>,  Next: Testing<14>,  Prev: API documentation<17>,  Up: assignvars

6.3.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(assignvars(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<14>,  Prev: Loading<18>,  Up: assignvars

6.3.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(assignvars(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: base64,  Next: basic_types,  Prev: assignvars,  Up: Libraries

6.4 ‘base64’
============

The ‘base64’ library provides predicates for parsing and generating data
in the Base64 and Base64URL formats as per the specification found at:

‘https://www.rfc-editor.org/rfc/rfc4648’

* Menu:

* API documentation: API documentation<18>.
* Loading: Loading<19>.
* Testing: Testing<15>.
* Encoding::
* Decoding::


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<18>,  Next: Loading<19>,  Up: base64

6.4.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#base64’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<19>,  Next: Testing<15>,  Prev: API documentation<18>,  Up: base64

6.4.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(base64(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<15>,  Next: Encoding,  Prev: Loading<19>,  Up: base64

6.4.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(base64(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Encoding,  Next: Decoding,  Prev: Testing<15>,  Up: base64

6.4.4 Encoding
--------------

Encoding a list of bytes in Base64 format is accomplished by the
‘base64::generate/2’ predicate.  For example:

     | ?- atom_codes('Hello world!', Bytes),
          base64::generate(atom(Base64), Bytes).
     Base64 = 'SGVsbG8gd29ybGQh'
     Bytes = [72,101,108,108,111,32,119,111,114,108,100,33]
     yes

     | ?- atom_codes('Hello world!', Bytes),
          base64::generate(codes(Base64), Bytes).
     Base64 = [83,71,86,115,98,71,56,103,100,50,57,121,98,71,81,104]
     Bytes = [72,101,108,108,111,32,119,111,114,108,100,33]
     yes

The Base64 result can also be represented using a list of chars, written
to a file or to a stream.  See the API documentation for details.

For safe encoding of URLs, use instead the Base64URL format.  For
example:

     | ?- base64url::generate(atom(Base64URL), 'https://logtalk.org').
     Base64URL == 'aHR0cHM6Ly9sb2d0YWxrLm9yZw'
     yes

The Base64URL can also be represented using a list of chars or a list of
codes.  The input URL should be in the same format.


File: TheLogtalkHandbook-3.96.0.info,  Node: Decoding,  Prev: Encoding,  Up: base64

6.4.5 Decoding
--------------

Decoding of Base64 data is accomplished using the ‘base64::parse/2’
predicate.  For example:

     | ?- base64::parse(atom('SGVsbG8gd29ybGQh'), Bytes),
          atom_codes(Atom, Bytes).
     Atom = 'Hello world!'
     Bytes = [72,101,108,108,111,32,119,111,114,108,100,33]
     yes

     | ?- base64::parse(chars(['S','G','V',s,b,'G','8',g,d,'2','9',y,b,'G','Q',h]), Bytes),
          atom_codes(Atom, Bytes).
     Atom = 'Hello world!'
     Bytes = [72,101,108,108,111,32,119,111,114,108,100,33]
     yes

The ‘base64::parse/2’ predicate accepts other input source such as a
file or a stream.  See the API documentation for details.

For decoding of URLs in the Base64URL format, use the
‘base64url::parse/2’ predicate.  For example:

     | ?- base64url::parse(atom('aHR0cHM6Ly9sb2d0YWxrLm9yZw'), URL).
     URL == 'https://logtalk.org'
     yes

The ‘base64url::parse/2’ predicate also accepts a list of chars or a
list of codes as input.  See the API documentation for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: basic_types,  Next: cbor,  Prev: base64,  Up: Libraries

6.5 ‘basic_types’
=================

The ‘basic_types’ library is a virtual library that loads only basic
types from the ‘types’ library:

   - ‘comparingp’

   - ‘termp’, ‘term’

   - ‘atomic’, ‘atom’, ‘number’, ‘float’, ‘integer’

   - ‘compound’, ‘listp’, ‘list’

   - ‘type’

* Menu:

* API documentation: API documentation<19>.
* Loading: Loading<20>.
* Testing: Testing<16>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<19>,  Next: Loading<20>,  Up: basic_types

6.5.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#types’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<20>,  Next: Testing<16>,  Prev: API documentation<19>,  Up: basic_types

6.5.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(basic_types(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<16>,  Prev: Loading<20>,  Up: basic_types

6.5.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file for the
‘types’ library:

     | ?- logtalk_load(types(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: cbor,  Next: core,  Prev: basic_types,  Up: Libraries

6.6 ‘cbor’
==========

The ‘cbor’ library implements predicates for importing and exporting
data in the Concise Binary Object Representation (CBOR) format:

   - ‘https://www.rfc-editor.org/rfc/rfc8949.html’

   - ‘http://cbor.io/’

This library is a work-in-progress.  Currently it requires a backend
supporting unbounded integer arithmetic.

* Menu:

* Representation::
* Encoding: Encoding<2>.
* Decoding: Decoding<2>.
* API documentation: API documentation<20>.
* Loading: Loading<21>.
* Testing: Testing<17>.


File: TheLogtalkHandbook-3.96.0.info,  Node: Representation,  Next: Encoding<2>,  Up: cbor

6.6.1 Representation
--------------------

   - Maps are represented using curly-bracketed terms, ‘{Pairs}’, where
     each pair uses the representation ‘Key-Value’.

   - Arrays are represented using lists.

   - Byte strings uses ‘bytes(List)’ compound terms.

   - Text strings can be represented as atoms, ‘chars(List)’, or
     ‘codes(List)’.  The default when decoding is to use atoms when
     using the ‘cbor’ object.  To decode text strings into lists of
     chars or code, use the ‘cbor/1’ with the parameter bound to ‘chars’
     or ‘codes’.  For example:

          | ?- cbor::parse([0x65,0x68,0x65,0x6c,0x6c,0x6f], Term).
          Term = hello
          yes

          | ?- cbor(atom)::parse([0x65,0x68,0x65,0x6c,0x6c,0x6f], Term).
          Term = hello
          yes

          | ?- cbor(chars)::parse([0x65,0x68,0x65,0x6c,0x6c,0x6f], Term).
          Term = chars([h,e,l,l,o])
          yes

          | ?- cbor(codes)::parse([0x65,0x68,0x65,0x6c,0x6c,0x6f], Term).
          Term = codes([104,101,108,108,111])
          yes

   - Tagged data uses ‘tag(Tag, Data)’ compound terms.

   - Simple values can be represented using ‘simple(Simple)’ compound
     terms.

   - The CBOR elements ‘false’, ‘true’, ‘null’, and ‘undefined’ are
     represented by, respectively, the ‘@false’, ‘@true’, ‘@null’, and
     ‘@undefined’ compound terms.

   - The compound terms ‘@infinity’, ‘@negative_infinity’, and
     ‘@not_a_number’ are used to represent the corresponding CBOR
     elements.

   - Only some backends distinguish between positive zero and negative
     zero.  The compound terms ‘@zero’ and ‘@negative_zero’ can be used
     as an alternative for encoding.  The decoder, however, produces the
     ‘0.0’ and ‘-0.0’ floats.


File: TheLogtalkHandbook-3.96.0.info,  Node: Encoding<2>,  Next: Decoding<2>,  Prev: Representation,  Up: cbor

6.6.2 Encoding
--------------

Encoding is accomplished using the ‘generate/2’ predicate.  For example:

     | ?- cbor::generate([a,{b-c}], Encoding).
     Encoding = [0x9f,0x61,0x61,0xbf,0x61,0x62,0x61,0x63,0xff,0xff]
     yes

The encoding of arrays and maps uses indefinite-length encoding.  All
floats are currently encoded using decimal fractions.  Encoding
indicators and big floats are not currently supported.


File: TheLogtalkHandbook-3.96.0.info,  Node: Decoding<2>,  Next: API documentation<20>,  Prev: Encoding<2>,  Up: cbor

6.6.3 Decoding
--------------

Decoding is accomplished using the ‘parse/2’ predicate.  For example:

     | ?- cbor::parse([0x9f,0x61,0x61,0xbf,0x61,0x62,0x61,0x63,0xff,0xff], Term).
     Term = [a,{b-c}]
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<20>,  Next: Loading<21>,  Prev: Decoding<2>,  Up: cbor

6.6.4 API documentation
-----------------------

Open the ‘../../apis/library_index.html#cbor’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<21>,  Next: Testing<17>,  Prev: API documentation<20>,  Up: cbor

6.6.5 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(cbor(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<17>,  Prev: Loading<21>,  Up: cbor

6.6.6 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(cbor(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: core,  Next: coroutining,  Prev: cbor,  Up: Libraries

6.7 ‘core’
==========

This library consists of built-in entities.

* Menu:

* API documentation: API documentation<21>.
* Loading: Loading<22>.
* Testing: Testing<18>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<21>,  Next: Loading<22>,  Up: core

6.7.1 API documentation
-----------------------

See this Handbook “Objects”, “Protocols”, and “Categories” sections.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<22>,  Next: Testing<18>,  Prev: API documentation<21>,  Up: core

6.7.2 Loading
-------------

All entities in this library are automatically loaded at Logtalk
startup.


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<18>,  Prev: Loading<22>,  Up: core

6.7.3 Testing
-------------

Tests for this library can be found in the ‘tests/logtalk/entities’
directory.


File: TheLogtalkHandbook-3.96.0.info,  Node: coroutining,  Next: csv,  Prev: core,  Up: Libraries

6.8 ‘coroutining’
=================

The ‘coroutining’ object provides a portable abstraction over how common
coroutining predicates are made available by the supported backend
Prolog systems (ECLiPSe, SICStus Prolog, SWI-Prolog, Trealla Prolog,
XVM, and YAP) that provide them.  Partial support for XSB is provided
(the predicate ‘frozen/2’ is not available and calls to it fail).

Calls to the library predicates are inlined when compiled with the
‘optimize’ flag turned on.  In this case, there is no overhead compared
with calling the abstracted predicates directly.

See also the ‘dif’ library.

* Menu:

* API documentation: API documentation<22>.
* Loading: Loading<23>.
* Testing: Testing<19>.
* Usage: Usage<10>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<22>,  Next: Loading<23>,  Up: coroutining

6.8.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#coroutining’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<23>,  Next: Testing<19>,  Prev: API documentation<22>,  Up: coroutining

6.8.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(coroutining(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<19>,  Next: Usage<10>,  Prev: Loading<23>,  Up: coroutining

6.8.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(coroutining(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<10>,  Prev: Testing<19>,  Up: coroutining

6.8.4 Usage
-----------

Load this library from your application loader file.  To call the
coroutining predicates using implicit message-sending, add the following
directive to any object or category calling the predicates (adjust the
list to the predicates actually called):

     :- uses(coroutining, [
         dif/2, dif/1, freeze/2, frozen/2, when/2
     ]).


File: TheLogtalkHandbook-3.96.0.info,  Node: csv,  Next: dates,  Prev: coroutining,  Up: Libraries

6.9 ‘csv’
=========

The ‘csv’ library provides predicates for reading and writing CSV files
and streams:

‘https://www.rfc-editor.org/rfc/rfc4180.txt’

The main object, ‘csv/3’, is a parametric object allowing passing
options for the handling of the header of the file, the fields
separator, and the handling of double-quoted fields.  The ‘cvs’ object
extends the ‘csv/3’ parametric object using default option values.

The library also includes predicates to guess the separator and guess
the number of columns in a given CSV file.

Files and streams can be read into a list of rows (with each row being
represented by a list of fields) or asserted using a user-defined
dynamic predicate.  Reading can be done by first loading the whole file
(using the ‘read_file/2-3’ predicates) into memory or line by line
(using the ‘read_file_by_line/2-3’ predicates).  Reading line by line is
usually the best option for parsing large CSV files.

Data can be saved to a CSV file or stream by providing the object and
predicate for accessing the data plus the name of the destination file
or the stream handle or alias.

* Menu:

* API documentation: API documentation<23>.
* Loading: Loading<24>.
* Testing: Testing<20>.
* Usage: Usage<11>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<23>,  Next: Loading<24>,  Up: csv

6.9.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#csv’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<24>,  Next: Testing<20>,  Prev: API documentation<23>,  Up: csv

6.9.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(csv(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<20>,  Next: Usage<11>,  Prev: Loading<24>,  Up: csv

6.9.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(csv(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<11>,  Prev: Testing<20>,  Up: csv

6.9.4 Usage
-----------

The ‘csv(Header, Separator, IgnoreQuotes)’ parametric object allows
passing the following options:

  1. ‘Header’: possible values are ‘missing’, ‘skip’, and ‘keep’.

  2. ‘Separator’: possible values are ‘comma’, ‘tab’, ‘semicolon’, and
     ‘colon’.

  3. ‘IgnoreQuotes’: possible values are ‘true’ to ignore double quotes
     surrounding field data and ‘false’ to preserve the double quotes.

The ‘csv’ object uses the default values ‘keep’, ‘comma’, and ‘false’.

When writing CSV files or streams, set the quoted fields option to
‘false’ to write all non-numeric fields double-quoted (i.e., escaped).

The library objects can also be used to guess the separator used in a
CSV file if necessary.  For example:

     | ?- csv::guess_separator('test_files/crlf_ending.csv', Separator).
     Is this the proper reading of a line of this file (y/n)? [aaa,bb,ccc]
     |> y.

     Separator = comma ?

This information can then be used to read the CSV file returning a list
of rows:

     | ?- csv(keep, comma, true)::read_file('test_files/crlf_ending.csv', Rows).

     Rows = [[aaa,bbb,ccc],[zzz,yyy,xxx]] ?

Alternatively, the CSV data can be saved using a public and dynamic
object predicate (that must be previously declared).  For example:

     | ?- assertz(p(_,_,_)), retractall(p(_,_,_)).
     yes

     | ?- csv(keep, comma, true)::read_file('test_files/crlf_ending.csv', user, p/3).
     yes

     | ?-  p(A,B,C).

     A = aaa
     B = bbb
     C = ccc ? ;

     A = zzz
     B = yyy
     C = xxx

Given a predicate representing a table, the predicate data can be
written to a file or stream.  For example:

     | ?- csv(keep, comma, true)::write_file('output.csv', user, p/3).
     yes

leaving the content just as the original file thanks to the use of
‘true’ for the ‘IgnoreQuotes’ option:

     aaa,bbb,ccc
     zzz,yyy,xxx

Otherwise:

     | ?- csv(keep, comma, false)::write_file('output.csv', user, p/3).
     yes

results in the following file content:

     "aaa","bbb","ccc"
     "zzz","yyy","xxx"

The ‘guess_arity/2’ method, to identify the arity, i.  e.  the number of
fields or columns per record in a given CSV file, for example:

     | ?- csv(keep, comma, false)::guess_arity('test_files/crlf_ending.csv', Arity).
     Is this the proper reading of a line of this file (y/n)? [aaa,bbb,ccc]
     |> y.

     Arity = 3


File: TheLogtalkHandbook-3.96.0.info,  Node: dates,  Next: dependents,  Prev: csv,  Up: Libraries

6.10 ‘dates’
============

The ‘date’ object implements some useful calendar date predicates.

The ‘time’ object implements some useful time predicates.

Please note that the functionality of these objects depends on the
chosen Prolog support for accessing the operating system time and date.

* Menu:

* API documentation: API documentation<24>.
* Loading: Loading<25>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<24>,  Next: Loading<25>,  Up: dates

6.10.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#dates’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<25>,  Prev: API documentation<24>,  Up: dates

6.10.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(dates(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: dependents,  Next: dictionaries,  Prev: dates,  Up: Libraries

6.11 ‘dependents’
=================

The ‘observer’ and ‘subject’ categories implement the Smalltalk
dependents handling mechanism.  This mechanism can be used as an
alternative to Logtalk system-wide support for event-driven programming.

* Menu:

* API documentation: API documentation<25>.
* Loading: Loading<26>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<25>,  Next: Loading<26>,  Up: dependents

6.11.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#dependents’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<26>,  Prev: API documentation<25>,  Up: dependents

6.11.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(dependents(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: dictionaries,  Next: dif,  Prev: dependents,  Up: Libraries

6.12 ‘dictionaries’
===================

This library provides a dictionary (also known as associative array,
map, or symbol table) protocol and binary tree, AVL tree, and Red–Black
tree implementations.  The different representations of a dictionary
should be regarded as opaque terms and only accessed using the library
predicates.

* Menu:

* API documentation: API documentation<26>.
* Loading: Loading<27>.
* Testing: Testing<21>.
* Usage: Usage<12>.
* Credits: Credits<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<26>,  Next: Loading<27>,  Up: dictionaries

6.12.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#dictionaries’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<27>,  Next: Testing<21>,  Prev: API documentation<26>,  Up: dictionaries

6.12.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(dictionaries(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<21>,  Next: Usage<12>,  Prev: Loading<27>,  Up: dictionaries

6.12.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(dictionaries(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<12>,  Next: Credits<2>,  Prev: Testing<21>,  Up: dictionaries

6.12.4 Usage
------------

First, select the dictionary implementation that you want to use.  For
cases where the number of elements is relatively small and performance
is not critical, ‘bintree’ can be a good choice.  For other cases,
‘avltree’ or ‘rbtree’ are likely better choices.  If you want to compare
the performance of the implementations, either define an object alias or
use a ‘uses/2’ directive so that you can switch between implementations
by simply changing the alias definition or the first argument of the
directive.  Note that you can switch between implementations at runtime
without code changes by using a parameter variable in the first argument
of a ‘uses/2’ directive.

Dictionary keys should preferably be ground terms.  If the keys contain
variables, the user must ensure that any instantiation of those
variables when calling this library predicates will not affect the key
ordering.

To create a new dictionary, you can use the ‘new/1’ predicate.  For
example:

     | ?- avltree::new(Dictionary).
     Dictionary = ...
     yes

You can also create a new dictionary from a list of key-value pairs by
using the ‘as_dictionary/2’ predicate.  For example:

     | ?- avltree::as_dictionary([a-1,c-3,b-2], Dictionary).
     Dictionary = ...
     yes

Several predicates are provided for inserting key-value pairs, lookup
key-value pairs updating the value associated with a key, and deleting
key-value pairs.  For example:

     | ?- avltree::(
             new(Dictionary0),
             insert(Dictionary0, a, 1, Dictionary1),
             update(Dictionary1, a, 2, Dictionary2),
             lookup(a, Value, Dictionary2)
         ).
     Dictionary0 = ...,
     Dictionary1 = ...,
     Dictionary2 = ...,
     Value = 2
     yes

For details on these and other provided predicates, consult the library
API documentation.


File: TheLogtalkHandbook-3.96.0.info,  Node: Credits<2>,  Prev: Usage<12>,  Up: dictionaries

6.12.5 Credits
--------------

The AVL tree implementation is an adaptation to Logtalk of the ‘assoc’
SWI-Prolog library authored by R.A.O’Keefe, L.Damas, V.S.Costa, Glenn
Burgess, Jiri Spitz, and Jan Wielemaker.  Additional predicates authored
by Paulo Moura.

The Red–Black tree implementation is an adaptation to Logtalk of the
‘rbtrees’ Prolog library authored by Vitor Santos Costa.


File: TheLogtalkHandbook-3.96.0.info,  Node: dif,  Next: edcg,  Prev: dictionaries,  Up: Libraries

6.13 ‘dif’
==========

The ‘dif’ object provides a portable abstraction over how the ‘dif/2’
predicate is made available by the supported backend Prolog systems that
implement it (B-Prolog, ECLiPSe, SICStus Prolog, SWI-Prolog, Trealla
Prolog, XSB, XVM, and YAP).

Calls to the library predicates are inlined when compiled with the
‘optimize’ flag turned on.  In this case, there is no overhead compared
with calling the abstracted predicate directly.

See also the ‘coroutining’ library.

* Menu:

* API documentation: API documentation<27>.
* Loading: Loading<28>.
* Testing: Testing<22>.
* Usage: Usage<13>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<27>,  Next: Loading<28>,  Up: dif

6.13.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#dif’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<28>,  Next: Testing<22>,  Prev: API documentation<27>,  Up: dif

6.13.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(dif(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<22>,  Next: Usage<13>,  Prev: Loading<28>,  Up: dif

6.13.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(dif(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<13>,  Prev: Testing<22>,  Up: dif

6.13.4 Usage
------------

Load this library from your application loader file.  To call the
‘dif/1-2’ predicates using implicit message-sending, add the following
directive to any object or category calling the predicates:

     :- uses(dif, [
         dif/2, dif/1
     ]).


File: TheLogtalkHandbook-3.96.0.info,  Node: edcg,  Next: events,  Prev: dif,  Up: Libraries

6.14 ‘edcg’
===========

This library provides a Logtalk port of Peter Van Roy’s extended DCG
implementation.  For full documentation on EDCGs, see:

‘https://webperso.info.ucl.ac.be/~pvr/edcg.html’

This Logtalk version defines a hook object, ‘edcg’.  Source files
defining EDCGs must be compiled using the compiler option ‘hook(edcg)’:

     | ?- logtalk_load(source, [hook(edcg)]).

Alternatively, the following directive can be added at the beginning of
the source file containing the EDCGs:

     :- set_logtalk_flag(hook, edcg).

The hook object automatically adds the EDCGs ‘-->>’ infix operator
scoped to the source file.

This port has simplified by copying and then modifying Michael
Hendricks’s ‘edcg’ repo at:

‘https://github.com/mndrix/edcg’

A notable difference is that Michael’s version declares Peter’s original
predicates for declaring accumulators and predicates using the hidden
arguments as multifile predicates.  But this is risky as two independent
EDCGs may use e.g.  the same accumulator names and introduce conflicts.
The Logtalk version uses instead the ‘edcg’ hook object internal state
to temporarily save those predicates in order to parse the corresponding
EDCGs.

* Menu:

* API documentation: API documentation<28>.
* Loading: Loading<29>.
* Testing: Testing<23>.
* Usage: Usage<14>.
* Introduction::
* Syntax::
* Declaration of Predicates::
* Declaration of Accumulators::
* Declaration of Passed Arguments::
* Additional documentation::


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<28>,  Next: Loading<29>,  Up: edcg

6.14.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#edcg’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<29>,  Next: Testing<23>,  Prev: API documentation<28>,  Up: edcg

6.14.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(edcg(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<23>,  Next: Usage<14>,  Prev: Loading<29>,  Up: edcg

6.14.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file of the
‘edcgs’ example:

     | ?- logtalk_load(edcgs(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<14>,  Next: Introduction,  Prev: Testing<23>,  Up: edcg

6.14.4 Usage
------------

Follows the usage documentation written by Michael Hendricks (with a
contribution from Peter Ludemann), used here with permission, with the
necessary changes for the Logtalk port.

     % declare accumulators
     acc_info(adder, X, In, Out, integer::plus(X,In,Out)).

     % declare predicates using these hidden arguments
     pred_info(len,0,[adder,dcg]).
     pred_info(increment,0,[adder]).

     increment -->>
         % add one to the accumulator
         [1]:adder.


     len(Xs,N) :-
         len(0,N,Xs,[]).

     len -->>
         % 'dcg' accumulator has an element
         [_],
         !,
         % increment the 'adder' accumulator
         increment,
         len.
     len -->>
         [].


File: TheLogtalkHandbook-3.96.0.info,  Node: Introduction,  Next: Syntax,  Prev: Usage<14>,  Up: edcg

6.14.5 Introduction
-------------------

DCG notation gives us a single, hidden accumulator.  Extended DCG
notation (implemented by this library) lets predicates have arbitrarily
many hidden accumulators.  As demonstrated by the synopsis above, those
accumulators can be implemented with arbitrary goals (like
‘integer::plus/3’).

Benefits of this library:

   - avoid tedium and errors from manually threading accumulators
     through your predicates

   - add or remove accumulators with a single declaration

   - change the accumulator implementation with a single declaration
     (ex, switching from ordsets to rbtrees)


File: TheLogtalkHandbook-3.96.0.info,  Node: Syntax,  Next: Declaration of Predicates,  Prev: Introduction,  Up: edcg

6.14.6 Syntax
-------------

Extended DCG syntax is very similar to DCG notation.  An EDCG is created
with clauses whose neck is the ‘-->>’ operator.  The following syntax is
supported inside an EDCG clause:

   - ‘{Goal}’ - don’t expand any hidden arguments of ‘Goal’

   - ‘Goal’ - expand all hidden arguments of Goal that are also in the
     head.  Those hidden arguments not in the head are given default
     values.

   - ‘Goal:L’ - If ‘Goal’ has no hidden arguments then force the
     expansion of all arguments in ‘L’ in the order given.  If ‘Goal’
     has hidden arguments then expand all of them, using the contents of
     ‘L’ to override the expansion.  ‘L’ is either a term of the form
     ‘Acc’, ‘Acc(Left,Right)’, ‘Pass’, ‘Pass(Value)’, or a list of such
     terms.  When present, the arguments ‘Left’, ‘Right’, and ‘Value’
     override the default values of arguments not in the head.

   - ‘List:Acc’ - Accumulate a list of terms in the accumulator ‘Acc’

   - ‘List’ - Accumulate a list of terms in the accumulator ‘dcg’

   - ‘X/Acc’ - Unify ‘X’ with the left term for the accumulator ‘Acc’

   - ‘Acc/X’ - Unify ‘X’ with the right term for the accumulator ‘Acc’

   - ‘X/Acc/Y’ - Unify ‘X’ with the left and ‘Y’ with the right term for
     the accumulator ‘Acc’

   - ‘insert(X,Y):Acc’ - Insert the arguments ‘X’ and ‘Y’ into the chain
     implementing the accumulator ‘Acc’.  This is useful when the value
     of the accumulator changes radically because ‘X’ and ‘Y’ may be the
     arguments of an arbitrary relation

   - ‘insert(X,Y)’ - Insert the arguments ‘X’ and ‘Y’ into the chain
     implementing the accumulator ‘dcg’.  This inserts the difference
     list X-Y into the accumulated list


File: TheLogtalkHandbook-3.96.0.info,  Node: Declaration of Predicates,  Next: Declaration of Accumulators,  Prev: Syntax,  Up: edcg

6.14.7 Declaration of Predicates
--------------------------------

Predicates are declared with facts of the following form:

     pred_info(Name, Arity, List).

The predicate ‘Name/Arity’ has the hidden parameters given in ‘List’.
The parameters are added in the order given by ‘List’ and their names
must be atoms.


File: TheLogtalkHandbook-3.96.0.info,  Node: Declaration of Accumulators,  Next: Declaration of Passed Arguments,  Prev: Declaration of Predicates,  Up: edcg

6.14.8 Declaration of Accumulators
----------------------------------

Accumulators are declared with facts in one of two forms.  The short
form is:

     acc_info(Acc, Term, Left, Right, Joiner).

The long form is:

     acc_info(Acc, Term, Left, Right, Joiner, LStart, RStart).

In most cases the short form gives sufficient information.  It declares
the accumulator ‘Acc’, which must be an atom, along with the
accumulating function, ‘Joiner’, and its arguments ‘Term’, the term to
be accumulated, and ‘Left’ & ‘Right’, the variables used in chaining.

The long form of ‘acc_info’ is useful in more complex programs.  It
contains two additional arguments, ‘LStart’ and ‘RStart’, that are used
to give default starting values for an accumulator occurring in a body
goal that does not occur in the head.  The starting values are given to
the unused accumulator to ensure that it will execute correctly even
though its value is not used.  Care is needed to give correct values for
‘LStart’ and ‘RStart’.  For DCG-like list accumulation both may remain
unbound.

Two conventions are used for the two variables used in chaining
depending on which direction the accumulation is done.  For forward
accumulation, ‘Left’ is the input and ‘Right’ is the output.  For
reverse accumulation, ‘Right’ is the input and ‘Left’ is the output.


File: TheLogtalkHandbook-3.96.0.info,  Node: Declaration of Passed Arguments,  Next: Additional documentation,  Prev: Declaration of Accumulators,  Up: edcg

6.14.9 Declaration of Passed Arguments
--------------------------------------

Passed arguments are conceptually the same as accumulators with ‘=/2’ as
the joiner function.  Passed arguments are declared as facts in one of
two forms.  The short form is:

     pass_info(Pass).

The long form is:

     pass_info(Pass, PStart).

In most cases the short form is sufficient.  It declares a passed
argument ‘Pass’, that must be an atom.  The long form also contains the
starting value ‘PStart’ that is used to give a default value for a
passed argument in a body goal that does not occur in the head.  Most of
the time this situation does not occur.


File: TheLogtalkHandbook-3.96.0.info,  Node: Additional documentation,  Prev: Declaration of Passed Arguments,  Up: edcg

6.14.10 Additional documentation
--------------------------------

Peter Van Roy’s page: Declarative Programming with State(1)

Technical Report UCB/CSD-90-583 Extended DCG Notation: A Tool for
Applicative Programming in Prolog(2) by Peter Van Roy

   - The Tech Report’s PDF is here(3)

A short Wikipedia article(4) on DCGs and extensions.

   ---------- Footnotes ----------

   (1) https://webperso.info.ucl.ac.be/~pvr/edcg.html

   (2) https://www2.eecs.berkeley.edu/Pubs/TechRpts/1990/5471.html

   (3) https://www2.eecs.berkeley.edu/Pubs/TechRpts/1990/CSD-90-583.pdf

   (4) https://en.wikipedia.org/wiki/Definite_clause_grammar#Extensions


File: TheLogtalkHandbook-3.96.0.info,  Node: events,  Next: expand_library_alias_paths,  Prev: edcg,  Up: Libraries

6.15 ‘events’
=============

The objects ‘event_registry’, ‘before_event_registry’, and
‘after_event_registry’ implement convenient predicates for registering
before and after events.

The code makes use of the ‘monitoring’ built-in protocol, which declares
the two basic event handler predicates (‘before/3’ and ‘after/3’).  You
will need to refer to this protocol in your objects if you want to use
the super control structure ‘(^^/1)’ with these predicates.

The ‘monitor’ object implements more sophisticated event handling
predicates.

* Menu:

* API documentation: API documentation<29>.
* Loading: Loading<30>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<29>,  Next: Loading<30>,  Up: events

6.15.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#events’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<30>,  Prev: API documentation<29>,  Up: events

6.15.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ loader file:

     | ?- logtalk_load(events(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: expand_library_alias_paths,  Next: expecteds,  Prev: events,  Up: Libraries

6.16 ‘expand_library_alias_paths’
=================================

This library provides provides a hook object,
‘expand_library_alias_paths’, for expanding library alias paths in
‘logtalk_library_path/2 facts’ in source files.  It is mainly used when
embedding Logtalk and Logtalk applications.

* Menu:

* API documentation: API documentation<30>.
* Loading: Loading<31>.
* Usage: Usage<15>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<30>,  Next: Loading<31>,  Up: expand_library_alias_paths

6.16.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#expand-library-alias-paths’ link
in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<31>,  Next: Usage<15>,  Prev: API documentation<30>,  Up: expand_library_alias_paths

6.16.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(expand_library_alias_paths(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<15>,  Prev: Loading<31>,  Up: expand_library_alias_paths

6.16.3 Usage
------------

Use the ‘hook/1’ option when compiling a source file:

     | ?- logtalk_load(my_source_file, [hook(expand_library_alias_paths)]).
     ...

Alternatively, assuming it is the only hook object you are using, you
can set it as thew default hook object:

     | ?- set_logtalk_flag(hook, expand_library_alias_paths).
     ...


File: TheLogtalkHandbook-3.96.0.info,  Node: expecteds,  Next: format,  Prev: expand_library_alias_paths,  Up: Libraries

6.17 ‘expecteds’
================

This library provides an implementation of 'expected terms' with an API
that is inspired by the ‘optional’ library and C++ standardization
proposals for an ‘Expected<T>’ type.  An expected term is an opaque
compound term that either contains an expected value or an error
informing why the expected value is not present.  Expected terms provide
an alternative to generating an exception (or a failure) when something
unexpected happens when asking for a value.  This allows, e.g.,
separating the code that constructs expected terms from the code that
processes them, which is then free to deal if necessary and at its
convenience with any unexpected events.

* Menu:

* API documentation: API documentation<31>.
* Loading: Loading<32>.
* Testing: Testing<24>.
* Usage: Usage<16>.
* See also::


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<31>,  Next: Loading<32>,  Up: expecteds

6.17.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#expecteds’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<32>,  Next: Testing<24>,  Prev: API documentation<31>,  Up: expecteds

6.17.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(expecteds(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<24>,  Next: Usage<16>,  Prev: Loading<32>,  Up: expecteds

6.17.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(expecteds(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<16>,  Next: See also,  Prev: Testing<24>,  Up: expecteds

6.17.4 Usage
------------

The ‘expected’ object provides constructors for expected terms.  For
example:

     | ?- expected::of_expected(1, Expected).
     ...

The created expected terms can then be passed as parameters to the
‘expected/1’ parametric object.  For example:

     | ?- expected::of_expected(1, Expected), expected(Expected)::or_else(Value, 0).
     Expected = expected(1),
     Value = 1
     yes

     | ?- expected::of_unexpected(-1, Expected), expected(Expected)::or_else(Value, 0).
     Expected = unexpected(-1),
     Value = 0
     yes

The ‘either’ object provides types and predicates for extended
type-checking and predicates for handling lists of expected terms.


File: TheLogtalkHandbook-3.96.0.info,  Node: See also,  Prev: Usage<16>,  Up: expecteds

6.17.5 See also
---------------

The ‘optionals’ library.


File: TheLogtalkHandbook-3.96.0.info,  Node: format,  Next: genint,  Prev: expecteds,  Up: Libraries

6.18 ‘format’
=============

The ‘format’ object provides a portable abstraction over how the de
facto standard ‘format/2-3’ predicates are made available by the
supported backend Prolog systems.  Some systems provide these predicates
as built-in predicates, while others make them available using a library
that must be explicitly loaded.

Calls to the library predicates are inlined when compiled with the
‘optimize’ flag turned on for most of the backends.  When that’s the
case, there is no overhead compared with calling the abstracted
predicates directly.

This library provides linter checks for calls to the ‘format/2-3’
predicates.  Given the differences between the implementations of these
predicates among Prolog systems, the linter checks focus on detecting
common errors such as missing arguments and too many arguments.  The
linter warnings are printed when the ‘suspicious_calls’ flag is set to
‘warning’ (its usual default).

* Menu:

* API documentation: API documentation<32>.
* Loading: Loading<33>.
* Testing: Testing<25>.
* Usage: Usage<17>.
* Portability: Portability<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<32>,  Next: Loading<33>,  Up: format

6.18.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#format’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<33>,  Next: Testing<25>,  Prev: API documentation<32>,  Up: format

6.18.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(format(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<25>,  Next: Usage<17>,  Prev: Loading<33>,  Up: format

6.18.3 Testing
--------------

Minimal tests for this library predicates can be run by loading the
‘tester.lgt’ file:

     | ?- logtalk_load(format(tester)).

Detailed tests for the ‘format/2-3’ predicates are available in the
‘tests/prolog/predicates’ directory as part of the Prolog standards
conformance test suite.  Use those tests to confirm the portability of
the format specifiers that you want to use.


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<17>,  Next: Portability<2>,  Prev: Testing<25>,  Up: format

6.18.4 Usage
------------

Load this library from your application loader file.  To call the
‘format/2-3’ predicates using implicit message-sending, add the
following directive to any object or category calling the predicates:

     :- uses(format, [
         format/2, format/3
     ]).


File: TheLogtalkHandbook-3.96.0.info,  Node: Portability<2>,  Prev: Usage<17>,  Up: format

6.18.5 Portability
------------------

Some Prolog systems provide only a subset of the expected format
specifiers.  Notably, table-related format specifiers are only fully
supported by a few systems.  See the section below on testing.

Only some of the supported Prolog backends provide implementations of
the ‘format/2-3’ predicates that allow using not only an atom or a list
of character codes for the format string (as de facto standard) but also
using a list of characters.  These currently include ECLiPSe, GNU
Prolog, SICStus Prolog, SWI-Prolog, Trealla Prolog, XVM, and YAP.
Therefore, when wide portability is sought, atoms must be used for the
format specifier argument as they bypass any dependency on the
‘double_quotes’ standard Prolog flag.  Some systems, like Tau Prolog,
only accept a list of characters for the format string.  In this case,
this library will convert the atom format string before calling these
systems native implementations.


File: TheLogtalkHandbook-3.96.0.info,  Node: genint,  Next: gensym,  Prev: format,  Up: Libraries

6.19 ‘genint’
=============

The ‘genint’ library implements predicates for generating positive
integers in increasing order.  The public predicates are declared
synchronized to prevent race conditions when using a backend Prolog
compiler with multi-threading support.

* Menu:

* API documentation: API documentation<33>.
* Loading: Loading<34>.
* Testing: Testing<26>.
* Usage: Usage<18>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<33>,  Next: Loading<34>,  Up: genint

6.19.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#genint’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<34>,  Next: Testing<26>,  Prev: API documentation<33>,  Up: genint

6.19.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(genint(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<26>,  Next: Usage<18>,  Prev: Loading<34>,  Up: genint

6.19.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(genint(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<18>,  Prev: Testing<26>,  Up: genint

6.19.4 Usage
------------

The ‘genint_core’ category implements the library predicates.  This
category is imported by the default ‘genint’ object to provide
application global named counters.  To make the counters local and thus
minimize the potential for counter name clashes, the category can be
imported by one or more application objects.  Use protected or private
import to restrict the scope of the library predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: gensym,  Next: git,  Prev: genint,  Up: Libraries

6.20 ‘gensym’
=============

The ‘gensym’ library implements predicates for generating unique atoms.
The public predicates are declared synchronized to prevent race
conditions when using a backend Prolog compiler with multi-threading
support.

* Menu:

* API documentation: API documentation<34>.
* Loading: Loading<35>.
* Testing: Testing<27>.
* Usage: Usage<19>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<34>,  Next: Loading<35>,  Up: gensym

6.20.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#gensym’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<35>,  Next: Testing<27>,  Prev: API documentation<34>,  Up: gensym

6.20.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(gensym(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<27>,  Next: Usage<19>,  Prev: Loading<35>,  Up: gensym

6.20.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(gensym(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<19>,  Prev: Testing<27>,  Up: gensym

6.20.4 Usage
------------

The ‘gensym_core’ category implements the library predicates.  This
category is imported by the default ‘gensym’ object to provide
application global generators.  To make the generators local and thus
minimize the potential for generator name clashes, the category can be
imported by one or more application objects.  Use protected or private
import to restrict the scope of the library predicates.  For example:

     :- object(foo,
         imports(private::gensym_core)).

         bar :-
             ^^gensym(p, S),
             ...

     :- end_object.


File: TheLogtalkHandbook-3.96.0.info,  Node: git,  Next: grammars,  Prev: gensym,  Up: Libraries

6.21 ‘git’
==========

This library provides access to a git project current branch and latest
commit data (e.g., commit hash).  Support for using this library on
Windows operating-systems is experimental and may or may not work
depending on the used Prolog backend.

* Menu:

* API documentation: API documentation<35>.
* Loading: Loading<36>.
* Testing: Testing<28>.
* Usage: Usage<20>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<35>,  Next: Loading<36>,  Up: git

6.21.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#git’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<36>,  Next: Testing<28>,  Prev: API documentation<35>,  Up: git

6.21.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(git(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<28>,  Next: Usage<20>,  Prev: Loading<36>,  Up: git

6.21.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(git(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<20>,  Prev: Testing<28>,  Up: git

6.21.4 Usage
------------

All predicates take as first argument a directory, which should be
either a git repository directory or a sub-directory of a git repository
directory.  The main predicate is ‘commit_log/3’.  It provides access to
the ‘git log’ command when called with the ‘--oneline -n 1
--pretty=format:’ options.  By passing as second argument the desired
format, it returns an atom with the formatted output.  For example:

     | ?- git::commit_log('/Users/pmoura/logtalk3', '%h%n%B', Output),
          write(Output), nl.

     eccaa1a2a
     Update SVG diagrams

     Output = 'eccaa1a2a\nUpdate SVG diagrams\n'
     yes

See e.g.  the official documentation on ‘git log’ pretty formats for
details:

‘https://git-scm.com/docs/pretty-formats’

Convenient predicates are also provided for commonly used formats such
as the commit author and the commit hash.  For example:

     | ?- git::commit_author('/Users/pmoura/Documents/Logtalk/logtalk3', Author).

     Author = 'Paulo Moura'
     yes

     | ?- git::commit_hash('/Users/pmoura/Documents/Logtalk/logtalk3', Hash).

     Hash = eccaa1a2a9495fef441915bbace84e0a4b0394a2
     yes

It’s also possible to get the name of the current local branch.  For
example:

     | ?- git::branch('/Users/pmoura/Documents/Logtalk/logtalk3', Branch).

     Branch = master
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: grammars,  Next: heaps,  Prev: git,  Up: Libraries

6.22 ‘grammars’
===============

This library provides Definite Clause Grammars (DCGs) for common parsing
tasks.  The DCGs support parsing both lists of characters (aka chars)
and lists of character codes (aka codes).

Currently, four groups of DCGs are available, each defined in its own
file:

   - blanks (‘blank_grammars.lgt’)

   - numbers (‘number_grammars.lgt’)

   - sequences (‘sequence_grammars.lgt’)

   - IP addresses (‘ip_grammars.lgt’; depends on ‘number_grammars.lgt’)

* Menu:

* API documentation: API documentation<36>.
* Loading: Loading<37>.
* Testing: Testing<29>.
* Usage: Usage<21>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<36>,  Next: Loading<37>,  Up: grammars

6.22.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#grammars’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<37>,  Next: Testing<29>,  Prev: API documentation<36>,  Up: grammars

6.22.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(grammars(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<29>,  Next: Usage<21>,  Prev: Loading<37>,  Up: grammars

6.22.3 Testing
--------------

Minimal tests for this library predicates can be run by loading the
‘tester.lgt’ file:

     | ?- logtalk_load(grammars(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<21>,  Prev: Testing<29>,  Up: grammars

6.22.4 Usage
------------

The library uses (when necessary) parametric objects where the single
parameter can be either ‘chars’ or ‘codes’.  The parameter must be bound
when using the DCGs.  For example, when using implicit message-sending:

     :- uses(blank_grammars(chars), [
         white_spaces//0, new_lines//0
     ]).


File: TheLogtalkHandbook-3.96.0.info,  Node: heaps,  Next: hierarchies,  Prev: grammars,  Up: Libraries

6.23 ‘heaps’
============

This library implements minimum and maximum heaps.

* Menu:

* API documentation: API documentation<37>.
* Loading: Loading<38>.
* Testing: Testing<30>.
* Credits: Credits<3>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<37>,  Next: Loading<38>,  Up: heaps

6.23.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#heaps’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<38>,  Next: Testing<30>,  Prev: API documentation<37>,  Up: heaps

6.23.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(heaps(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<30>,  Next: Credits<3>,  Prev: Loading<38>,  Up: heaps

6.23.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(heaps(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Credits<3>,  Prev: Testing<30>,  Up: heaps

6.23.4 Credits
--------------

Original code by Richard O’’Keefe.  Adapted to Logtalk by Paulo Moura
and Victor Lagerkvist.


File: TheLogtalkHandbook-3.96.0.info,  Node: hierarchies,  Next: hook_flows,  Prev: heaps,  Up: Libraries

6.24 ‘hierarchies’
==================

This library provides categories implementing reflection predicates over
class and prototype hierarchies.  These categories can be imported by
any object that requires reasoning about hierarchies.

* Menu:

* API documentation: API documentation<38>.
* Loading: Loading<39>.
* Testing: Testing<31>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<38>,  Next: Loading<39>,  Up: hierarchies

6.24.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#hierarchies’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<39>,  Next: Testing<31>,  Prev: API documentation<38>,  Up: hierarchies

6.24.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hierarchies(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<31>,  Prev: Loading<39>,  Up: hierarchies

6.24.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hierarchies(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: hook_flows,  Next: hook_objects,  Prev: hierarchies,  Up: Libraries

6.25 ‘hook_flows’
=================

Hook objects (i.e., objects that define term- and goal-expansion rules)
can be combined to define expansion 'workflows'.  While in some cases
the expansions are independent and thus can be applied in any order, in
other cases a specific order is required.  The ‘hook_pipeline’ and
‘hook_set’ parametric objects in this library implement the two most
common scenarios of combining multiple hook objects for the expansion of
source files.  These parametric hook objects can be combined to define
workflows of any complexity (e.g., a pipeline where one of the steps is
set with an element that is a pipeline).  These two basic hook flows can
also be used as examples of how to construct your own custom expansion
workflows.

* Menu:

* API documentation: API documentation<39>.
* Loading: Loading<40>.
* Testing: Testing<32>.
* Usage: Usage<22>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<39>,  Next: Loading<40>,  Up: hook_flows

6.25.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#hook-flows’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<40>,  Next: Testing<32>,  Prev: API documentation<39>,  Up: hook_flows

6.25.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hook_flows(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<32>,  Next: Usage<22>,  Prev: Loading<40>,  Up: hook_flows

6.25.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hook_flows(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<22>,  Prev: Testing<32>,  Up: hook_flows

6.25.4 Usage
------------

Pre-processing a source file with a hook object can be accomplished by
either compiling the source file using the option ‘hook(HookObject)’ or
by adding to the top of the file the directive:

     :- set_logtalk_flag(hook, HookObject).

Note that ‘set_logtalk_flag/2’ directives are local to an entity or a
source file.

The ‘hook_pipeline(Pipeline)’ is a parametric object where the parameter
is a list of hook objects, interpreted as a pre-processing pipeline: the
results of a hook object are passed to the next hook object.  Terms and
goals that are not expanded by a hook object are passed as-is to the
next hook object.  This parametric object is used when a set of
expansions must be applied in a specific order.  It also allows
overriding the default compiler semantics where term-expansion rules are
tried in sequence only until one of them succeeds.

The ‘hook_set(Set)’ is a parametric object where the parameter is a list
of hook objects, interpreted as a set of hook objects.  The hook objects
are tried in sequence until one of them succeeds in expanding the
current term (goal) into a different term (goal).  This parametric
object is used when applying multiple independent expansions (i.e.,
expansions that don’t apply to the same terms or goals).

Both the ‘hook_pipeline(Pipeline)’ and ‘hook_set(Set)’ objects assume
that the individual hook objects publicly implement the ‘expanding’
protocol (this is the default) as they send ‘term_expansion/2’ and
‘goal_expansion/2’ messages to those objects.

When using a backend Prolog compiler that supports modules, it’s also
possible to use as parameter a list of hook modules as long as their
names do not coincide with the names of loaded objects.


File: TheLogtalkHandbook-3.96.0.info,  Node: hook_objects,  Next: html,  Prev: hook_flows,  Up: Libraries

6.26 ‘hook_objects’
===================

This library provides a set of convenient hook objects for defining
custom expansion workflows (using, e.g., the ‘hook_flows’ library) and
for debugging.  They are usable and useful as-is but should also be
regarded as term- and goal-expansion examples that you can learn from,
clone, and change to fit your application requirements.

* Menu:

* API documentation: API documentation<40>.
* Loading: Loading<41>.
* Testing: Testing<33>.
* Usage: Usage<23>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<40>,  Next: Loading<41>,  Up: hook_objects

6.26.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#hook-objects’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<41>,  Next: Testing<33>,  Prev: API documentation<40>,  Up: hook_objects

6.26.2 Loading
--------------

To load all hook objects in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hook_objects(loader)).

To load a specific hook object, e.g., the ‘backend_adapter_hook’ object:

     | ?- logtalk_load(hook_objects(backend_adapter_hook)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<33>,  Next: Usage<23>,  Prev: Loading<41>,  Up: hook_objects

6.26.3 Testing
--------------

To test this library hook objects, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hook_objects(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<23>,  Prev: Testing<33>,  Up: hook_objects

6.26.4 Usage
------------

The provided hook objects cover different expansion scenarios as
follows.

* Menu:

* Using the Prolog backend adapter file expansion rules::
* Restoring the default compiler expansion workflow::
* Preventing applying any (other) user-defined expansion rules: Preventing applying any other user-defined expansion rules.
* Expanding grammar rules into clauses independently of the compiler::
* Using the expansion rules defined in a Prolog module::
* Wrap the contents of a plain Prolog file as an object::
* Outputting term-expansion results to a stream or a file::
* Printing entity predicate goals before or after calling them::
* Suppressing goals::


File: TheLogtalkHandbook-3.96.0.info,  Node: Using the Prolog backend adapter file expansion rules,  Next: Restoring the default compiler expansion workflow,  Up: Usage<23>

6.26.4.1 Using the Prolog backend adapter file expansion rules
..............................................................

Useful when defining a custom expansion workflow.  This can be
accomplished by loading the ‘backend_adapter_hook.lgt’ file, which
defines a ‘backend_adapter_hook’ hook object that can be used as a
workflow step.


File: TheLogtalkHandbook-3.96.0.info,  Node: Restoring the default compiler expansion workflow,  Next: Preventing applying any other user-defined expansion rules,  Prev: Using the Prolog backend adapter file expansion rules,  Up: Usage<23>

6.26.4.2 Restoring the default compiler expansion workflow
..........................................................

In this case, load the ‘default_workflow_hook.lgt’ file, which defines a
‘default_workflow_hook’ hook object, and use the following 'goal' to set
the default hook object:

     | ?- set_logtalk_flag(hook, default_workflow_hook).


File: TheLogtalkHandbook-3.96.0.info,  Node: Preventing applying any other user-defined expansion rules,  Next: Expanding grammar rules into clauses independently of the compiler,  Prev: Restoring the default compiler expansion workflow,  Up: Usage<23>

6.26.4.3 Preventing applying any (other) user-defined expansion rules
.....................................................................

When compiling a source file, we sometimes want to prevent applying
expansion rules.  This can be accomplished by simply loading the
‘identity_hook.lgt’ file, which defines the ‘identity_hook’ hook object,
whose expansion rules simply succeed without changing the terms and
goals, and setting it as the file-specific hook object writing as the
first term in the file the 'directive':

     :- set_logtalk_flag(hook, identity_hook).

Note that the compiler will always convert any grammar rules defined in
the file into clauses.  Although this conversion can also be performed
as an expansion, grammar rules are part of the Logtalk language.  If you
want to preserve the grammar rules, use the hook objects described below
to write them to a stream.


File: TheLogtalkHandbook-3.96.0.info,  Node: Expanding grammar rules into clauses independently of the compiler,  Next: Using the expansion rules defined in a Prolog module,  Prev: Preventing applying any other user-defined expansion rules,  Up: Usage<23>

6.26.4.4 Expanding grammar rules into clauses independently of the compiler
...........................................................................

Load the ‘grammar_rules_hook.lgt’ and use the term-expansion rules in
the ‘grammar_rules_hook’ object.  For example:

     | ?- grammar_rules_hook::term_expansion((a --> [b],c), Clause).

     Clause = (a([b|T], C) :- c(T, C))
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Using the expansion rules defined in a Prolog module,  Next: Wrap the contents of a plain Prolog file as an object,  Prev: Expanding grammar rules into clauses independently of the compiler,  Up: Usage<23>

6.26.4.5 Using the expansion rules defined in a Prolog module
.............................................................

Load the ‘prolog_module_hook.lgt’, which defines the parametric hook
object ‘prolog_module_hook(Module)’.  To use this hook object, you need
to instantiate the parameter to the name of the module.  For example:

     :- set_logtalk_flag(hook, prolog_module_hook(user)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Wrap the contents of a plain Prolog file as an object,  Next: Outputting term-expansion results to a stream or a file,  Prev: Using the expansion rules defined in a Prolog module,  Up: Usage<23>

6.26.4.6 Wrap the contents of a plain Prolog file as an object
..............................................................

Load the ‘object_wrapper_hook.lgt’, which defines the
‘object_wrapper_hook/0-2’ hook objects.  Use them to wrap the contents
of a plain Prolog file as an object named after the file (optionally
implementing a protocol) or an object with the given name and object
relations.  Can be used to apply Logtalk developer tools to plain Prolog
code or when porting a Prolog application to Logtalk.  For example:

     | ?- logtalk_load('plain.pl', [hook(object_wrapper_hook)]).
     ...

     | ?- current_object(plain).
     yes

Or:

     | ?- logtalk_load('world_1.pl', [hook(object_wrapper_hook(some_protocol))]).
     ...

     | ?- current_object(world_1).
     yes

     | ?- implements_protocol(world_1, Protocol).
     Protocol = some_protocol
     yes

Or:

     | ?- logtalk_load('foo.pl', [hook(object_wrapper_hook(bar,[imports(some_category))]).
     ...

     | ?- current_object(bar).
     yes

     | ?- imports_category(bar, Category).
     Category = some_category
     yes

The ‘object_wrapper_hook’ object sets the ‘context_switching_calls’ flag
to ‘allow’ for the generated object.  This enables calling the
predicates using the ‘(<<)/2’ context-switching control construct.  But
it’s usually better to define a protocol for the predicates being
encapsulated and use instead the ‘object_wrapper_hook/1-2’ objects.


File: TheLogtalkHandbook-3.96.0.info,  Node: Outputting term-expansion results to a stream or a file,  Next: Printing entity predicate goals before or after calling them,  Prev: Wrap the contents of a plain Prolog file as an object,  Up: Usage<23>

6.26.4.7 Outputting term-expansion results to a stream or a file
................................................................

Load the ‘write_to_stream_hook.lgt’ file and use the
‘write_to_stream_hook(Stream)’ or ‘write_to_stream_hook(Stream,
Options)’ hook objects.  Alternatively, you can load the
‘write_to_file_hook.lgt’ file and use the ‘write_to_file_hook(File)’ or
‘write_to_file_hook(File, Options)’ hook objects.  The terms are not
modified and thus these hook objects may be used at any point in an
expansion workflow.  The terms are written followed by a period and a
new line.

For example, assume that we want to expand all terms in a ‘input.pl’
source file, writing the resulting terms to a ‘output.pl’ file, using
the expansion rules defined in a ‘expansions’ hook object.  Taking
advantage of the ‘hook_flows’ library ‘hook_pipeline/1’ object, we can
write:

     | ?- logtalk_compile(
              'input.pl',
              [hook(hook_pipeline([
                  expansions,
                  write_to_file_hook('output.pl')
              ]))]
          ).


File: TheLogtalkHandbook-3.96.0.info,  Node: Printing entity predicate goals before or after calling them,  Next: Suppressing goals,  Prev: Outputting term-expansion results to a stream or a file,  Up: Usage<23>

6.26.4.8 Printing entity predicate goals before or after calling them
.....................................................................

This is helpful for quick debugging.  Load the ‘print_goal_hook.lgt’
file and use the ‘print_goal_hook’ hook object.  For example, we can set
this hook object as the default hook:

     | ?- set_logtalk_flag(hook, print_goal_hook).

Then, edit the entity source code to print selected goals:

     foo :-
         - bar,   % print goal before calling it
         + baz,   % print goal after calling it
         * quux.  % print goal before and after calling it


File: TheLogtalkHandbook-3.96.0.info,  Node: Suppressing goals,  Prev: Printing entity predicate goals before or after calling them,  Up: Usage<23>

6.26.4.9 Suppressing goals
..........................

The ‘suppress_goal_hook.lgt’ file provides the ‘suppress_goal_hook’ hook
object that supports suppressing a goal in a clause body by prefixing it
using the ‘--’ operator.  We can set this hook object as the default
hook using the goal:

     | ?- set_logtalk_flag(hook, suppress_goal_hook).

If the expansion is only to be used in a single file, use instead the
source file directive:

     :- set_logtalk_flag(hook, suppress_goal_hook).

Then, edit entity predicates to suppress goals.  For example:

     foo :-
         bar,
         -- baz,
         quux.

The suppressed goals are replaced by calls to ‘true/0’.


File: TheLogtalkHandbook-3.96.0.info,  Node: html,  Next: ids,  Prev: hook_objects,  Up: Libraries

6.27 ‘html’
===========

This library provides predicates for generating HTML content using
either HTML 5 or XHTML 1.1 formats from a term representation.  The
library performs minimal validation, checking only that all elements are
valid.  No attempt is made to generate nicely indented output.

Normal elements are represented using a compound term with one argument
(the element content) or two arguments (the element attributes
represented by a list of ‘Key=Value’ or ‘Key-Value’ pairs and the
element content).  The element content can be another element or a list
of elements.  For example:

     ol([type-a], [li(foo), li(bar), li(baz)])

The two exceptions are the ‘pre’ or ‘code’ elements whose content is
never interpreted as an element or a list of elements.  For example, the
fragment:

     pre([foo,bar,baz])

is translated to:

     <pre>
     [foo,bar,baz]
     </pre>

Void elements are represented using a compound term with one argument,
the (possibly empty) list of attributes represented by a list of
‘Key=Value’ or ‘Key-Value’ pairs.  For example:

     hr([class-separator])

Atomic arguments of the compound terms are interpreted as element
content.  Non-atomic element content can be represented as a quoted atom
or by using the ‘pre’ or ‘code’ elements as explained above.

This library is a work in progress.

* Menu:

* API documentation: API documentation<41>.
* Loading: Loading<42>.
* Testing: Testing<34>.
* Generating a HTML document::
* Generating a HTML fragment::
* Working with callbacks to generate content::
* Working with custom elements::


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<41>,  Next: Loading<42>,  Up: html

6.27.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#html’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<42>,  Next: Testing<34>,  Prev: API documentation<41>,  Up: html

6.27.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(html(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<34>,  Next: Generating a HTML document,  Prev: Loading<42>,  Up: html

6.27.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(html(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Generating a HTML document,  Next: Generating a HTML fragment,  Prev: Testing<34>,  Up: html

6.27.4 Generating a HTML document
---------------------------------

HTML documents can be generated from a compound term representation and
written to a file or a stream.  For example, assuming we want to
generate a HTML 5 file:

     | ?- html5::generate(
              file('hello.html'),
              html([lang=en], [head(title('Hello world!')), body(p('Bye!'))])
          ).

When the second argument is a ‘html/1’ or ‘html/2’ compound term, a
'doctype' is automatically written.  If we prefer instead e.g.  a XHTML
1.1 document, we use the ‘xhtml11’ object:

     | ?- xhtml11::generate(
              file('hello.html'),
              html([lang=en], [head(title('Hello world!')), body(p('Bye!'))])
          ).


File: TheLogtalkHandbook-3.96.0.info,  Node: Generating a HTML fragment,  Next: Working with callbacks to generate content,  Prev: Generating a HTML document,  Up: html

6.27.5 Generating a HTML fragment
---------------------------------

It’s also possible to generate just a fragment of a (X)HTML document by
using a list of compound terms or a compound term for an element other
than ‘html’.  For example:

     | ?- current_output(Stream),
          html5::generate(stream(Stream), ul([li(foo), li(bar), li(baz)])).

     <ul>
     <li>
     foo</li>
     <li>
     bar</li>
     <li>
     baz</li>
     </ul>

     Stream = ...


File: TheLogtalkHandbook-3.96.0.info,  Node: Working with callbacks to generate content,  Next: Working with custom elements,  Prev: Generating a HTML fragment,  Up: html

6.27.6 Working with callbacks to generate content
-------------------------------------------------

Often we need to programmatically generate HTML content from queries.
In other cases, we may have fixed content that we don’t want to keep
repeating (e.g., a navigation bar).  The library supports a ‘(::)/2’
pseudo-element that sends a message to an object to retrieve content.
As an example, assume the following predicate definition in ‘user’:

     content(strong('Hello world!')).

This predicate can then be called from the HTML term representation.
For example:

     | ?- current_output(Stream),
          html5::generate(stream(Stream), span(user::content)).

     <span><strong>Hello world!</strong></span>

     Stream = ...

Note that the callback always takes the form ‘Object::Closure’ where
‘Closure’ is extended with a single argument (to be bound to the
generated content).  More complex callbacks are possible by using lambda
expressions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Working with custom elements,  Prev: Working with callbacks to generate content,  Up: html

6.27.7 Working with custom elements
-----------------------------------

The ‘html5’ and ‘xhtml11’ objects recognize the same set of standard
HTML 5 normal and void elements and generate an error for non-standard
elements.  If you need to generate HTML content containing custom
elements, define a new object that extends one of the library objects.
For example:

     :- object(html5custom,
         extends(html5)).

         normal_element(foo, inline).
         normal_element(bar, block).
         normal_element(Name, Display) :-
             ^^normal_element(Name, Display).

     :- end_object.


File: TheLogtalkHandbook-3.96.0.info,  Node: ids,  Next: intervals,  Prev: html,  Up: Libraries

6.28 ‘ids’
==========

This library generates random identifiers given the number of bytes of
randomness.  The identifiers are Base64 encoded.  By default, 20 bytes
(160 bits) are used.

The generation of random identifiers uses the ‘/dev/urandom’ random
number generator when available.  This includes macOS, Linux, *BSD, and
other POSIX operating-systems.  On Windows, a pseudo-random generator is
used, but randomized using the current wall time.

Identifiers can be generated as atoms, lists of characters, or lists of
character codes.

See also the ‘uuid’ and ‘ulid’ libraries.

* Menu:

* API documentation: API documentation<42>.
* Loading: Loading<43>.
* Testing: Testing<35>.
* Usage: Usage<24>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<42>,  Next: Loading<43>,  Up: ids

6.28.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#ids’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<43>,  Next: Testing<35>,  Prev: API documentation<42>,  Up: ids

6.28.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ids(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<35>,  Next: Usage<24>,  Prev: Loading<43>,  Up: ids

6.28.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ids(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<24>,  Prev: Testing<35>,  Up: ids

6.28.4 Usage
------------

To generate an identifier using the default 160 bits of randomness:

     | ?- ids::generate(Identifier).
     Identifier = '2gpMzqAFXBO5mYFIPX1qMkHxgGE='
     yes

To generate an identifier represented by an atom using 240 bits (30
bytes) of randomness:

     | ?- ids(atom, 30)::generate(Identifier).
     Identifier = 'ie/jYcLsqo8ZguCOF1ZNPFDRvJ03Ww5Qa9e0FxRB'
     yes

To generate an identifier represented by a list of characters using 64
bits (8 bytes) of randomness:

     | ?- ids(chars, 8)::generate(Identifier).
     Identifier = ['5','0','8','V',d,'S',c,y,n,o,'A',=]
     yes

To generate an identifier represented by a list of character codes using
64 bits (8 bytes) of randomness:

     | ?- ids(codes, 8)::generate(Identifier).
     Identifier = [111,81,86,55,99,79,70,77,65,74,103,61]
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: intervals,  Next: java,  Prev: ids,  Up: Libraries

6.29 ‘intervals’
================

This library provides an ‘intervalp’ protocol and an ‘interval’ object
that implement basic temporal interval relations protocol (based on the
James F. Allen Interval Algebra work).

* Menu:

* API documentation: API documentation<43>.
* Loading: Loading<44>.
* Testing: Testing<36>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<43>,  Next: Loading<44>,  Up: intervals

6.29.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#intervals’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<44>,  Next: Testing<36>,  Prev: API documentation<43>,  Up: intervals

6.29.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(intervals(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<36>,  Prev: Loading<44>,  Up: intervals

6.29.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(intervals(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: java,  Next: json,  Prev: intervals,  Up: Libraries

6.30 ‘java’
===========

The library Java entities define a minimal abstraction for calling Java
from Logtalk.  This abstraction makes use of Logtalk parametric objects
and allows creating Java objects, accessing Java class fields, and
calling Java class and object methods using syntax closer to Logtalk.
It also gives access to some Java utility predicates.

This abstraction was developed primarily to work with XVM (with its
‘jni’ plug-in installed) or the JPL library bundled with SWI-Prolog and
YAP. However, it’s expected to be implementable with alternative Java
interfaces found in other backend Prolog compilers.  Currently, a
preliminary implementation is also available for JIProlog.

The main idea in this abstraction layer is to use parametric objects
where the first parameter holds the Java reference (usually to a class
or object) and an optional second parameter holds the return value.
Together with a forward message handler, this allows the use of Java
messages with the same functor and number of arguments as found in the
relevant JavaDocs.

* Menu:

* API documentation: API documentation<44>.
* Loading: Loading<45>.
* Testing: Testing<37>.
* Usage: Usage<25>.
* Known issues: Known issues<9>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<44>,  Next: Loading<45>,  Up: java

6.30.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#java’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<45>,  Next: Testing<37>,  Prev: API documentation<44>,  Up: java

6.30.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(java(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<37>,  Next: Usage<25>,  Prev: Loading<45>,  Up: java

6.30.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(java(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<25>,  Next: Known issues<9>,  Prev: Testing<37>,  Up: java

6.30.4 Usage
------------

The two main objects in this library are ‘java(Reference, ReturnValue)’
and ‘java(Reference)’.  Use the latter if you want to ignore the return
value or when calling a void Java method.

The ‘java’ object implements utility predicates.  For some backend Java
interfaces such as JPL (available in SWI-Prolog, XVM, and YAP) there is
also a ‘java_hook’ hook object for removing any overhead when using this
library abstraction.

For usage examples and additional tests, see the ‘clustering’,
‘document_converter’, ‘jpl’, and ‘neo4j’ examples.


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<9>,  Prev: Usage<25>,  Up: java

6.30.5 Known issues
-------------------

When running Java GUI examples on the macOS Terminal application, you
may get a Java error saying that the AWT cannot be started.  In
alternative, try to run the example from within the SWI-Prolog macOS
application instead of using the shell integration script.  This issue
is due to a macOS Java issue that’s orthogonal to both Prolog backends
and Logtalk.


File: TheLogtalkHandbook-3.96.0.info,  Node: json,  Next: json_lines,  Prev: java,  Up: Libraries

6.31 ‘json’
===========

The ‘json’ library provides predicates for parsing and generating data
in the JSON format based on the specification and standard found at:

   - ‘https://www.rfc-editor.org/rfc/rfc8259’

   - 
     ‘https://ecma-international.org/publications-and-standards/standards/ecma-404/’

It includes parametric objects whose parameters allow selecting the
representation for parsed JSON objects (‘curly’ or ‘list’), JSON text
strings (‘atom’, ‘chars’, or ‘codes’) and JSON pairs (‘dash’, ‘equal’,
or ‘colon’).

* Menu:

* API documentation: API documentation<45>.
* Loading: Loading<46>.
* Testing: Testing<38>.
* Representation: Representation<2>.
* Encoding: Encoding<3>.
* Decoding: Decoding<3>.
* Known issues: Known issues<10>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<45>,  Next: Loading<46>,  Up: json

6.31.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#json’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<46>,  Next: Testing<38>,  Prev: API documentation<45>,  Up: json

6.31.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(json(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<38>,  Next: Representation<2>,  Prev: Loading<46>,  Up: json

6.31.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(json(tester)).

Some of the sample JSON test files are based on examples published at:

‘https://www.json.org/’


File: TheLogtalkHandbook-3.96.0.info,  Node: Representation<2>,  Next: Encoding<3>,  Prev: Testing<38>,  Up: json

6.31.4 Representation
---------------------

The following choices of syntax have been made to represent JSON
elements as terms:

   - By default, JSON objects are represented using curly-bracketed
     terms, ‘{Pairs}’, where each pair uses the representation
     ‘Key-Value’ (see below for alternative representations).

   - Arrays are represented using lists.

   - Text strings can be represented as atoms, ‘chars(List)’, or
     ‘codes(List)’.  The default when decoding is to use atoms when
     using the ‘json’ object.  To decode text strings into lists of
     chars or codes, use the ‘json/1’ with the parameter bound to
     ‘chars’ or ‘codes’.  For example:

          | ?- json::parse(codes([34,104,101,108,108,111,34]), Term).
          Term = hello
          yes

          | ?- json(atom)::parse(codes([34,104,101,108,108,111,34]), Term).
          Term = hello
          yes

          | ?- json(chars)::parse(codes([34,104,101,108,108,111,34]), Term).
          Term = chars([h,e,l,l,o])
          yes

          | ?- json(codes)::parse(codes([34,104,101,108,108,111,34]), Term).
          Term = codes([104,101,108,108,111])
          yes

   - The JSON values ‘false’, ‘true’ and ‘null’ are represented by,
     respectively, the ‘@false’, ‘@true’ and ‘@null’ compound terms.

The following table exemplifies the term equivalents of JSON elements
using default representations for objects, pairs, and strings:

JSON                          term
                              
------------------------------------------------------------
[1,2]                         [1,2]
                              
true                          @true
                              
false                         @false
                              
null                          @null
                              
-1                            -1
                              
[1.2345]                      [1.2345]
                              
[]                            []
                              
[2147483647]                  [2147483647]
                              
[0]                           [0]
                              
[1234567890123456789]         [1234567890123456789]
                              
[false]                       [@false]
                              
[-2147483648]                 [-2147483648]
                              
{“a”:null,”foo”:”bar”}        <{a-@null>, foo-bar}
                              
[2.225073858507201e-308]      [2.225073858507201e-308]
                              
[0,1]                         [0,1]
                              
[2.2250738585072014e-308]     [2.2250738585072014e-308]
                              
[1.7976931348623157e+308]     [1.7976931348623157e+308]
                              
[0.0]                         [0.0]
                              
[4294967295]                  [4294967295]
                              
[-1234567890123456789]        [-1234567890123456789]
                              
[“foo”]                       [foo]
                              
[1]                           [1]
                              
[null]                        [@null]
                              
[-1.2345]                     [-1.2345]
                              
[5.0e-324]                    [5.0e-324]
                              
[-1]                          [-1]
                              
[true]                        [@true]
                              
[9223372036854775807]         [9223372036854775807]
                              

For JSON objects that are two possible term representations:

JSON object               term (curly)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a-1, b-2, c-3}
                          
{}                        {}
                          

and:

JSON object               term (list)
                          
----------------------------------------------------
{“a”:1, “b”:2, “c”:3}     json([a-1, b-2, c-3])
                          
{}                        json([])
                          

For JSON pairs that are three possible representations:

JSON object               term (dash)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a-1, b-2, c-3}
                          

and:

JSON object               term (equal)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a=1, b=2, c=3}
                          

and:

JSON object               term (colon)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a:1, b:2, c:3}
                          

By default, the curly-term representation and the dash pair
representation are used.  The ‘json/3’ parametric object allows
selecting the desired representation choices.  For example:

     | ?- json(curly,dash,atom)::parse(atom('{"a":1, "b":2, "c":3}'), JSON).
     JSON = {a-1, b-2, c-3}
     yes

     | ?- json(list,equal,atom)::parse(atom('{"a":1, "b":2, "c":3}'), JSON).
     JSON = json([a=1, b=2, c=3])
     yes

     | ?- json(curly,colon,atom)::parse(atom('{"a":1, "b":2, "c":3}'), JSON).
     JSON = {a:1, b:2, c:3}
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Encoding<3>,  Next: Decoding<3>,  Prev: Representation<2>,  Up: json

6.31.5 Encoding
---------------

Encoding is accomplished using the ‘generate/2’ predicate.  For example:

     | ?- json::generate(codes(Encoding), [a,{b-c}]).
     Encoding = [91,34,97,34,44,123,34,98,34,58,34,99,34,125,93]
     yes

Alternatively:

     | ?- json::generate(chars(Encoding), [a,{b-c}]).
     Encoding = ['[','"',a,'"',',','{','"',b,'"',:,'"',c,'"','}',']']
     Yes

     | ?- json::generate(atom(Encoding), [a,{b-c}]).
     Encoding = '["a",{"b":"c"}]'
     Yes

Notice that ‘generate/2’ takes, as second argument, a Prolog term that
corresponds to the JSON syntax in Prolog and produces the corresponding
JSON output in the format specified in the first argument:
(‘codes(Variable)’, ‘stream(Stream)’, ‘file(File)’, ‘chars(Variable)’ or
‘atom(Variable)’).


File: TheLogtalkHandbook-3.96.0.info,  Node: Decoding<3>,  Next: Known issues<10>,  Prev: Encoding<3>,  Up: json

6.31.6 Decoding
---------------

Decoding is accomplished using the ‘parse/2’ predicate.  For example, to
decode a given json file:

     | ?- json::parse(file('simple/roundtrip_array_obj_array.json'), Term).
     Term = [{a-[b]}]
     yes

The ‘parse/2’ predicate first argument must indicate the input source
(‘codes(Codes)’, ‘stream(Stream)’, ‘line(Stream)’, ‘file(Path)’,
‘chars(Chars)’ or ‘atom(Atom)’) containing a JSON payload to be decoded
into the Prolog term in the second argument.


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<10>,  Prev: Decoding<3>,  Up: json

6.31.7 Known issues
-------------------

Some tests, notably ‘parse_simple_valid_files’ and
‘roundtrip_hexadecimals’, fail on backends such as ECLiPSe and GNU
Prolog that don’t support Unicode.


File: TheLogtalkHandbook-3.96.0.info,  Node: json_lines,  Next: listing,  Prev: json,  Up: Libraries

6.32 ‘json_lines’
=================

The ‘json_lines’ library provides predicates for parsing and generating
data in the JSON Lines format based on the proposal found at:

‘https://jsonlines.org’

It includes parametric objects whose parameters allow selecting the
representation for parsed JSON objects (‘curly’ or ‘list’), JSON text
strings (‘atom’, ‘chars’, or ‘codes’) and JSON pairs (‘dash’, ‘equal’,
or ‘colon’).

* Menu:

* API documentation: API documentation<46>.
* Loading: Loading<47>.
* Testing: Testing<39>.
* Representation: Representation<3>.
* Encoding: Encoding<4>.
* Decoding: Decoding<4>.
* Known issues: Known issues<11>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<46>,  Next: Loading<47>,  Up: json_lines

6.32.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#json_lines’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<47>,  Next: Testing<39>,  Prev: API documentation<46>,  Up: json_lines

6.32.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(json_lines(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<39>,  Next: Representation<3>,  Prev: Loading<47>,  Up: json_lines

6.32.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(json_lines(tester)).

Some of the sample JSON test files are based on examples published at:

‘https://jsonlines.org/’


File: TheLogtalkHandbook-3.96.0.info,  Node: Representation<3>,  Next: Encoding<4>,  Prev: Testing<39>,  Up: json_lines

6.32.4 Representation
---------------------

The following choices of syntax have been made to represent JSON
elements as terms:

   - By default, JSON objects are represented using curly-bracketed
     terms, ‘{Pairs}’, where each pair uses the representation
     ‘Key-Value’ (see below for alternative representations).

   - Arrays are represented using lists.

   - Text strings can be represented as atoms, ‘chars(List)’, or
     ‘codes(List)’.  The default when decoding is to use atoms when
     using the ‘json_lines’ object.  To decode text strings into lists
     of chars or codes, use the ‘json_lines/1’ object with the parameter
     bound to ‘chars’ or ‘codes’.  For example:

          | ?- json_lines::parse(codes([34,104,101,108,108,111,34]), Terms).
          Terms = [hello]
          yes

          | ?- json_lines(atom)::parse(codes([34,104,101,108,108,111,34]), Terms).
          Terms = [hello]
          yes

          | ?- json_lines(chars)::parse(codes([34,104,101,108,108,111,34]), Terms).
          Terms = [chars([h,e,l,l,o])]
          yes

          | ?- json_lines(codes)::parse(codes([34,104,101,108,108,111,34]), Terms).
          Terms = [codes([104,101,108,108,111])]
          yes

   - The JSON values ‘false’, ‘true’ and ‘null’ are represented by,
     respectively, the ‘@false’, ‘@true’ and ‘@null’ compound terms.

The following table exemplifies the term equivalents of JSON elements
using default representations for objects, pairs, and strings:

JSON                          term
                              
------------------------------------------------------------
[1,2]                         [1,2]
                              
true                          @true
                              
false                         @false
                              
null                          @null
                              
-1                            -1
                              
[1.2345]                      [1.2345]
                              
[]                            []
                              
[2147483647]                  [2147483647]
                              
[0]                           [0]
                              
[1234567890123456789]         [1234567890123456789]
                              
[false]                       [@false]
                              
[-2147483648]                 [-2147483648]
                              
{“a”:null,”foo”:”bar”}        <{a-@null>, foo-bar}
                              
[2.225073858507201e-308]      [2.225073858507201e-308]
                              
[0,1]                         [0,1]
                              
[2.2250738585072014e-308]     [2.2250738585072014e-308]
                              
[1.7976931348623157e+308]     [1.7976931348623157e+308]
                              
[0.0]                         [0.0]
                              
[4294967295]                  [4294967295]
                              
[-1234567890123456789]        [-1234567890123456789]
                              
[“foo”]                       [foo]
                              
[1]                           [1]
                              
[null]                        [@null]
                              
[-1.2345]                     [-1.2345]
                              
[5.0e-324]                    [5.0e-324]
                              
[-1]                          [-1]
                              
[true]                        [@true]
                              
[9223372036854775807]         [9223372036854775807]
                              

For JSON objects that are two possible term representations:

JSON object               term (curly)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a-1, b-2, c-3}
                          
{}                        {}
                          

and:

JSON object               term (list)
                          
----------------------------------------------------
{“a”:1, “b”:2, “c”:3}     json([a-1, b-2, c-3])
                          
{}                        json([])
                          

For JSON pairs that are three possible representations:

JSON object               term (dash)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a-1, b-2, c-3}
                          

and:

JSON object               term (equal)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a=1, b=2, c=3}
                          

and:

JSON object               term (colon)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a:1, b:2, c:3}
                          

By default, the curly-term representation and the dash pair
representation are used.  The ‘json/3’ parametric object allows
selecting the desired representation choices.  For example:

     | ?- json_lines(curly,dash,atom)::parse(atom('{"a":1, "b":2, "c":3}'), JSONL).
     JSONL = [{a-1, b-2, c-3}]
     yes

     | ?- json_lines(list,equal,atom)::parse(atom('{"a":1, "b":2, "c":3}'), JSONL).
     JSONL = [json([a=1, b=2, c=3])]
     yes

     | ?- json_lines(curly,colon,atom)::parse(atom('{"a":1, "b":2, "c":3}'), JSONL).
     JSONL = [{a:1, b:2, c:3}]
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Encoding<4>,  Next: Decoding<4>,  Prev: Representation<3>,  Up: json_lines

6.32.5 Encoding
---------------

Encoding is accomplished using the ‘generate/2’ predicate.  For example:

     | ?- json_lines::generate(codes(Encoding), [a,{b-c}]).
     Encoding = [34,97,34,10,123,34,98,34,58,34,99,34,125,10]
     yes

Alternatively:

     | ?- json_lines::generate(chars(Encoding), [a,{b-c}]).
     Encoding = ['"',a,'"','\n','{','"',b,'"',:,'"',c,'"','}','\n']
     Yes

     | ?- json_lines::generate(atom(Encoding), [a,{b-c}]).
     Encoding = '"a"\n{"b":"c"}\n'
     Yes

Notice that ‘generate/2’ takes, as second argument, a Prolog term that
corresponds to the JSON syntax in Prolog and produces the corresponding
JSON output in the format specified in the first argument:
(‘codes(Variable)’, ‘stream(Stream)’, ‘file(File)’, ‘chars(Variable)’ or
‘atom(Variable)’).


File: TheLogtalkHandbook-3.96.0.info,  Node: Decoding<4>,  Next: Known issues<11>,  Prev: Encoding<4>,  Up: json_lines

6.32.6 Decoding
---------------

Decoding is accomplished using the ‘parse/2’ predicate.  For example, to
decode a given json file:

     | ?- json_lines::parse(file('simple/data.jsonl'), Terms).
     Term = [{a-[b]}]
     yes

The ‘parse/2’ predicate first argument must indicate the input source
(‘codes(Codes)’, ‘stream(Stream)’, ‘line(Stream)’, ‘file(Path)’,
‘chars(Chars)’ or ‘atom(Atom)’) containing a JSON payload to be decoded
into the Prolog term in the second argument.


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<11>,  Prev: Decoding<4>,  Up: json_lines

6.32.7 Known issues
-------------------

Some tests may fail on backends such as ECLiPSe and GNU Prolog that
don’t support Unicode.


File: TheLogtalkHandbook-3.96.0.info,  Node: listing,  Next: logging,  Prev: json_lines,  Up: Libraries

6.33 ‘listing’
==============

This library provides support for listing object dynamic predicate
clauses.  The predicates must (also) be declared using a scope directive
to make them visible to the listing predicates.

* Menu:

* API documentation: API documentation<47>.
* Loading: Loading<48>.
* Testing: Testing<40>.
* Usage: Usage<26>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<47>,  Next: Loading<48>,  Up: listing

6.33.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#listing’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<48>,  Next: Testing<40>,  Prev: API documentation<47>,  Up: listing

6.33.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(listing(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<40>,  Next: Usage<26>,  Prev: Loading<48>,  Up: listing

6.33.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(listing(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<26>,  Prev: Testing<40>,  Up: listing

6.33.4 Usage
------------

This library provides a ‘listing’ category that can be imported by any
number of objects.  The main predicates are declared public.  If you
want to restrict their scope, use protected or private import.  For
example:

     :- object(data_store,
         imports(private::listing)).

         debug :-
             ^^listing(data/4).
         ...

     :- end_object.

The ‘listing’ category provides a bare-bones ‘portray_clause/1’
predicate implementation.  As this predicate is called (by the
‘listing/0-1’ predicates) using the ‘(::)/1’ control construct, the
object importing the category can easily override the inherited
definition with its own or with a call to the backend system native
implementation of the predicate.  For example, assuming a backend that
provides ‘portray_clause/1’ as a built-in predicate, we can write:

     :- object(thing,
         imports(listing)).

         :- uses(user, [portray_clause/1]).
         ...

     :- end_object.

The main predicate, ‘listing/1’, accepts as argument a predicate
indicator, a non-terminal indicator, or a clause head template (to list
only clauses with a matching head).

This library is often useful as a debugging helper.  For example,
assuming that we want to list dynamic predicate clauses for an object
‘data’ compiled (or created) with the ‘complements’ flag set to ‘allow’,
we can hot patch it to add the ‘listing’ category:

     | ?- create_category(patch, [extends(listing),complements(data)], [], []).
     yes

     | ?- data::listing.
     ...

Another example:

     | ?- create_category(
              patch,
              [extends(listing),complements(data)],
              [public(debug/1)],
              [(debug(Key) :- ::listing(p(Key,Datum)))]
          ).
     yes

     | ?- data::debug(k42).
     ...

Note that the semantics of complementing categories require that we use
the ‘(::)/2’ control construct instead of the ‘(^^)/2’ control construct
as a 'super' call would be interpreted as made from the complemented
object.


File: TheLogtalkHandbook-3.96.0.info,  Node: logging,  Next: loops,  Prev: listing,  Up: Libraries

6.34 ‘logging’
==============

This library provides support for logging events to files.

* Menu:

* API documentation: API documentation<48>.
* Loading: Loading<49>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<48>,  Next: Loading<49>,  Up: logging

6.34.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#logging’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<49>,  Prev: API documentation<48>,  Up: logging

6.34.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(logging(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: loops,  Next: meta,  Prev: logging,  Up: Libraries

6.35 ‘loops’
============

This library provides implementations of several kinds of loops typical
of imperative languages.

* Menu:

* API documentation: API documentation<49>.
* Loading: Loading<50>.
* Testing: Testing<41>.
* Usage: Usage<27>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<49>,  Next: Loading<50>,  Up: loops

6.35.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#loops’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<50>,  Next: Testing<41>,  Prev: API documentation<49>,  Up: loops

6.35.2 Loading
--------------

To load the main entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(loops(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<41>,  Next: Usage<27>,  Prev: Loading<50>,  Up: loops

6.35.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(loops(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<27>,  Prev: Testing<41>,  Up: loops

6.35.4 Usage
------------

See e.g.  the ‘searching’ example.


File: TheLogtalkHandbook-3.96.0.info,  Node: meta,  Next: meta_compiler,  Prev: loops,  Up: Libraries

6.36 ‘meta’
===========

This library provides implementations of common meta-predicates.  The
‘meta’ object implements common meta-predicates like ‘map/3’ and
‘fold_left/4’.

See also the ‘meta_compiler’ library, which provides optimized
compilation of meta-predicate calls.

* Menu:

* API documentation: API documentation<50>.
* Loading: Loading<51>.
* Testing: Testing<42>.
* Usage: Usage<28>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<50>,  Next: Loading<51>,  Up: meta

6.36.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#meta’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<51>,  Next: Testing<42>,  Prev: API documentation<50>,  Up: meta

6.36.2 Loading
--------------

To load the main entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(meta(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<42>,  Next: Usage<28>,  Prev: Loading<51>,  Up: meta

6.36.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(meta(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<28>,  Prev: Testing<42>,  Up: meta

6.36.4 Usage
------------

See e.g.  the ‘metapredicates’ example and unit tests.


File: TheLogtalkHandbook-3.96.0.info,  Node: meta_compiler,  Next: mutations,  Prev: meta,  Up: Libraries

6.37 ‘meta_compiler’
====================

This library supports implementations optimized compilation of
meta-calls for the predicates defined in the ‘meta’ library.

* Menu:

* API documentation: API documentation<51>.
* Loading: Loading<52>.
* Testing: Testing<43>.
* Usage: Usage<29>.
* Known issues: Known issues<12>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<51>,  Next: Loading<52>,  Up: meta_compiler

6.37.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#meta-compiler’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<52>,  Next: Testing<43>,  Prev: API documentation<51>,  Up: meta_compiler

6.37.2 Loading
--------------

To load the main entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(meta_compiler(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<43>,  Next: Usage<29>,  Prev: Loading<52>,  Up: meta_compiler

6.37.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(meta_compiler(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<29>,  Next: Known issues<12>,  Prev: Testing<43>,  Up: meta_compiler

6.37.4 Usage
------------

If ‘meta_compiler’ is the only hook object you are using, you can set it
as the default hook object (but note that the optimizations are only
applied to entities compiled with the ‘optimize’ flag turned on):

     | ?- set_logtalk_flag(hook, meta_compiler).
     ...

Otherwise, use the ‘hook(meta_compiler)’ and ‘optimize(on)’ compiler
options when compiling and loading the code that you want to optimize.
For example:

     | ?- logtalk_load(my_source_file, [hook(meta_compiler), optimize(on)]).
     ...

See also the ‘metapredicates_compiled’ example and unit tests.


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<12>,  Prev: Usage<29>,  Up: meta_compiler

6.37.5 Known issues
-------------------

Goals in clauses containing parameter variables are currently not
expanded by this library and thus not optimized.


File: TheLogtalkHandbook-3.96.0.info,  Node: mutations,  Next: nested_dictionaries,  Prev: meta_compiler,  Up: Libraries

6.38 ‘mutations’
================

Experimental library.  Should not be used in production code.  Details
can be changed without advance notice.

The ‘mutations’ library provides support for generating random mutations
of selected types.  The library defines default mutation algorithms for
the following basic types:

   - ‘atom’

   - ‘integer’

   - ‘float’

   - ‘compound’

   - ‘list’

The user can add additional mutation algorithms for these or other types
by defining objects or categories providing clauses for the ‘mutation/3’
predicate and expanding the entity source files using the
‘mutations_store’ object as the hook object.

This library is expected to eventually be used to support mutation-based
'fuzz testing'.

By default, loading this library loads a set of default mutation
algorithms.  These can be overridden by defining alternative mutations
and a custom loader file.

* Menu:

* API documentation: API documentation<52>.
* Loading: Loading<53>.
* Testing: Testing<44>.
* Usage: Usage<30>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<52>,  Next: Loading<53>,  Up: mutations

6.38.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#mutations’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<53>,  Next: Testing<44>,  Prev: API documentation<52>,  Up: mutations

6.38.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(mutations(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<44>,  Next: Usage<30>,  Prev: Loading<53>,  Up: mutations

6.38.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(mutations(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<30>,  Prev: Testing<44>,  Up: mutations

6.38.4 Usage
------------

The ‘mutations’ category complements the ‘type’ object and thus its
predicates are accessed via this object.  For example:

     | ?- type::mutation(integer, 123, M).
     M = 1293
     yes

     | type::mutation(integer, 123, M).
     M = 5123
     yes

     | type::mutation(integer, 123, M).
     M = -123
     yes

     | type::mutation(integer, 123, M).
     M = 23
     yes

When there are multiple mutation algorithms for a given type, the
predicate ‘type::mutation/3’ chooses one of them randomly.  We can query
the number of mutation algorithms available per type using the
‘mutations_store::counter/2’ predicate:

     | ?- mutations_store::counter(Type, Count).
     Type = atom,
     Count = 6 ;
     Type = integer,
     Count = 7 ;
     ...

Loading this library also loads the ‘arbitrary’ library, which provides
‘get_seed/1’ and ‘set_seed/1’ predicates that can be used to control the
pseudo-random number generator.


File: TheLogtalkHandbook-3.96.0.info,  Node: nested_dictionaries,  Next: optionals,  Prev: mutations,  Up: Libraries

6.39 ‘nested_dictionaries’
==========================

This library provides nested dictionary implementations based on private
extensions to the ‘dictionaries’ library objects.  The representations
of a nested dictionary should be regarded as opaque terms and only
accessed using the library predicates.

This library is experimental, a work in progress, and future versions
can introduce incompatible changes.

* Menu:

* API documentation: API documentation<53>.
* Loading: Loading<54>.
* Testing: Testing<45>.
* Usage: Usage<31>.
* Curly term representation::


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<53>,  Next: Loading<54>,  Up: nested_dictionaries

6.39.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#nested-dictionaries’ link in a
web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<54>,  Next: Testing<45>,  Prev: API documentation<53>,  Up: nested_dictionaries

6.39.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(nested_dictionaries(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<45>,  Next: Usage<31>,  Prev: Loading<54>,  Up: nested_dictionaries

6.39.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(nested_dictionaries(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<31>,  Next: Curly term representation,  Prev: Testing<45>,  Up: nested_dictionaries

6.39.4 Usage
------------

First, select the nested dictionary implementation that you want to use.
For cases where the number of elements is relatively small and
performance is not critical, ‘nbintree’ can be a good choice.  For other
cases, ‘navltree’ or ‘nrbtree’ are likely better choices.  If you want
to compare the performance of the implementations, either define an
object alias or use a ‘uses/2’ directive so that you can switch between
implementations by simply changing the alias definition or the first
argument of the directive.  Note that you can switch between
implementations at runtime without code changes by using a parameter
variable in the first argument of a ‘uses/2’ directive.

To create an empty nested dictionary, you can use the ‘new/1’ predicate.
For example:

     | ?- navltree::new(Dictionary).
     Dictionary = ...
     yes

You can also create a new nested dictionary from a 'curly bracketed term
representation' (see below) by using the predicate
‘as_nested_dictionary/2’.  For example:

     | ?- navltree::as_nested_dictionary(
             {a-1, b-{c-3, d-{e-7,f-8}}},
             Dictionary
          ).

     Dictionary = ...
     yes

Several predicates are provided to insert, lookup, update, and delete
key-value pairs given a list of keys interpreted as an 'access path' to
a nested dictionary.  For example:

     | ?- navltree::as_nested_dictionary(
             {a-1, b-{c-3, d-{e-7,f-8}}},
             Dictionary
          ),
          navltree::lookup_in([b,d,f], Value, Dictionary).

     Dictionary = ...
     Value = 8
     yes

For details on these and other provided predicates, consult the library
API documentation.


File: TheLogtalkHandbook-3.96.0.info,  Node: Curly term representation,  Prev: Usage<31>,  Up: nested_dictionaries

6.39.5 Curly term representation
--------------------------------

To simplify importing and exporting data into a nested dictionary, the
library provides ‘as_nested_dictionary/2’ and ‘as_curly_bracketed/2’
predicates that work with a 'curly term representation'.  This format is
based on the JSON data interchange format.

A dictionary is represented by the ‘{Pairs}’ term where Pairs is a
conjunction of ‘Key-Value’ or ‘Key:Value’ pairs and ‘Value’ can be a
nested dictionary or lists of pairs.  An empty dictionary is represented
using the ‘{}’ term.


File: TheLogtalkHandbook-3.96.0.info,  Node: optionals,  Next: options,  Prev: nested_dictionaries,  Up: Libraries

6.40 ‘optionals’
================

This library provides an implementation of 'optional terms' with an API
modeled after the Java 8 ‘Optional’ class (originally due to requests by
users working in Logtalk/Java hybrid applications).  An optional term is
an opaque compound term that may or may not hold a value.  Optional
terms avoid forcing the user to define a representation for the absence
of a value by providing an API with predicates that depend on the
presence or absence of a value.  Optional terms also allow separating
the code that constructs optional terms from the code that processes
them, which is then free to deal if necessary and at its convenience
with any case where the values held by optional terms are not present.

* Menu:

* API documentation: API documentation<54>.
* Loading: Loading<55>.
* Testing: Testing<46>.
* Usage: Usage<32>.
* See also: See also<2>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<54>,  Next: Loading<55>,  Up: optionals

6.40.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#optionals’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<55>,  Next: Testing<46>,  Prev: API documentation<54>,  Up: optionals

6.40.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(optionals(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<46>,  Next: Usage<32>,  Prev: Loading<55>,  Up: optionals

6.40.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(optionals(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<32>,  Next: See also<2>,  Prev: Testing<46>,  Up: optionals

6.40.4 Usage
------------

The ‘optional’ object provides constructors for optional terms.  For
example:

     | ?- optional::of(1, Optional).
     ...

The created optional terms can then be passed as parameters to the
‘optional/1’ parametric object.  For example:

     | ?- optional::of(1, Optional), optional(Optional)::or_else(Term, 0).
     Optional = optional(1),
     Term = 1
     yes

     | ?- optional::empty(Optional), optional(Optional)::or_else(Term, 0).
     Optional = empty,
     Term = 0
     yes

The ‘maybe’ object provides types and predicates for type-checking of
the term held by optional terms.  It also provides some predicates for
handling lists of optional terms.


File: TheLogtalkHandbook-3.96.0.info,  Node: See also<2>,  Prev: Usage<32>,  Up: optionals

6.40.5 See also
---------------

The ‘expecteds’ library.


File: TheLogtalkHandbook-3.96.0.info,  Node: options,  Next: os,  Prev: optionals,  Up: Libraries

6.41 ‘options’
==============

This library provides useful predicates for managing developer tool and
application options.

* Menu:

* API documentation: API documentation<55>.
* Loading: Loading<56>.
* Testing: Testing<47>.
* Usage: Usage<33>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<55>,  Next: Loading<56>,  Up: options

6.41.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#options’ file in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<56>,  Next: Testing<47>,  Prev: API documentation<55>,  Up: options

6.41.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(options(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<47>,  Next: Usage<33>,  Prev: Loading<56>,  Up: options

6.41.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(options(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<33>,  Prev: Testing<47>,  Up: options

6.41.4 Usage
------------

The ‘options’ category is usually imported by the root object of the
developer tool or application.  The importing object should define the
‘default_option/1’ predicate and, if option type-checking is required,
the ‘valid_option/1’ predicate must be defined for each option.  This
library requires options to be represented by compound terms where the
functor is the option name (e.g., ‘trim(true)’ or (‘box(0,2)’)).  The
‘option/2-3’ can be used to get or test an option given a list of
options.  When an option appears multiple times in a list, the
‘option/2-3’ predicates get or test the first (leftmost) occurrence.

The library also supports a user-defined ‘fix_option/2’ predicate.  A
usage example is when an option value can be a relative file path that
should be expanded before use.  Another usage example would be
converting from a user-friendly option to a form more suitable for
internal processing.  When a call to the ‘fix_option/2’ predicate fails,
the option is used as-is.

A simple example:

     :- object(foo,
         imports(options)).

         :- uses(type, [
             valid/2
         ]).

         :- public(p/0).
         p :-
             % use default options
             p([]).

         :- public(p/1).
         p(UserOptions) :-
             ^^check_options(UserOptions),
             % construct the full set of options from
             % the user options and the default options
             ^^merge_options(UserOptions, Options),
             ...
             % query an option
             ^^option(baz(Boolean), Options),
             q(Boolean),
             ...

         default_option(baz(true)).
         ...

         valid_option(baz(Boolean)) :-
             valid(boolean, Boolean).
         ...

     :- end_object.

Note that you can use protected or private import of the ‘options’
category if you don’t want to add its public predicates to the object
protocol.


File: TheLogtalkHandbook-3.96.0.info,  Node: os,  Next: queues,  Prev: options,  Up: Libraries

6.42 ‘os’
=========

This library provides a 'portable' operating-system interface for the
supported backend Prolog compilers.

The ‘os_types’ category defines some useful operating-system types for
type-checking when using with the ‘type’ library object.

* Menu:

* API documentation: API documentation<56>.
* Loading: Loading<57>.
* Testing: Testing<48>.
* Known issues: Known issues<13>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<56>,  Next: Loading<57>,  Up: os

6.42.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#os’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<57>,  Next: Testing<48>,  Prev: API documentation<56>,  Up: os

6.42.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(os(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<48>,  Next: Known issues<13>,  Prev: Loading<57>,  Up: os

6.42.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(os(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<13>,  Prev: Testing<48>,  Up: os

6.42.4 Known issues
-------------------

Some predicates may only be supported by a subset of backend Prolog
compilers on a subset of operating-systems.  They should be used with
care and fully tested in your application domain, as some backend Prolog
compilers have buggy and inconsistent interfaces, notably across
operating-systems.  See the remarks section in the ‘os’ object
documentation for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: queues,  Next: random,  Prev: os,  Up: Libraries

6.43 ‘queues’
=============

This library implements queues.  The queue representation should be
regarded as an opaque term and only accessed using the library
predicates.

* Menu:

* API documentation: API documentation<57>.
* Loading: Loading<58>.
* Testing: Testing<49>.
* Usage: Usage<34>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<57>,  Next: Loading<58>,  Up: queues

6.43.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#queues’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<58>,  Next: Testing<49>,  Prev: API documentation<57>,  Up: queues

6.43.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(queues(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<49>,  Next: Usage<34>,  Prev: Loading<58>,  Up: queues

6.43.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(queues(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<34>,  Prev: Testing<49>,  Up: queues

6.43.4 Usage
------------

To create a new queue, use the ‘new/1’ predicate:

     | ?- queue::new(Queue).
     Queue = ...
     yes

Elements can be added to either the end of the queue or the front of the
queue using, respectively, the ‘join/3’ and ‘join_all/3’ predicates or
the ‘jump/3’ and ‘jump_all/3’.  For example:

     | ?- queue::(new(Queue0), join_all([1,2,3], Queue0, Queue1)).
     Queue0 = ...,
     Queue1 = ...
     yes

We can query the head of the queue or remove the head of the queue
using, respectively, the ‘head/2’ and ‘serve/3’ predicates.  For
example:

     | ?- queue::(new(Queue0), join(1, Queue0, Queue1), head(Queue1, Head)).
     Queue0 = ...,
     Queue1 = ...,
     Head = 1
     yes

For details on these and other provided predicates, consult the library
API documentation.


File: TheLogtalkHandbook-3.96.0.info,  Node: random,  Next: reader,  Prev: queues,  Up: Libraries

6.44 ‘random’
=============

This library provides portable random number generators and an
abstraction over the native backend Prolog compiler random number
generator if available.  It includes predicates for generating random
floats and random integers in a given interval; predicates for
generating random sequences and sets; predicates for randomly selecting,
enumerating, and swapping elements from a list; predicates that succeed,
fail, or call another predicate with a given probability; and predicates
for sampling common probability distributions.

* Menu:

* API documentation: API documentation<58>.
* Loading: Loading<59>.
* Testing: Testing<50>.
* Usage: Usage<35>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<58>,  Next: Loading<59>,  Up: random

6.44.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#random’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<59>,  Next: Testing<50>,  Prev: API documentation<58>,  Up: random

6.44.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(random(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<50>,  Next: Usage<35>,  Prev: Loading<59>,  Up: random

6.44.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(random(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<35>,  Prev: Testing<50>,  Up: random

6.44.4 Usage
------------

The ‘random’ object implements a portable random number generator and
supports multiple random number generators, using different seeds, by
defining derived objects.  For example:

     :- object(my_random_generator_1,
         extends(random)).

         :- initialization(::reset_seed).

     :- end_object.

The ‘fast_random’ object also implements a portable random number
generator but does not support deriving multiple random number
generators, which makes it a bit faster than the ‘random’ object.

The ‘random’ and ‘fast_random’ objects manage the random number
generator seed using internal dynamic state.  The predicates that update
the seed are declared as synchronized (when running on Prolog backends
that support threads).  Still, care must be taken when using these
objects from multi-threaded applications, as there is no portable
solution to protect seed updates from signals and prevent inconsistent
state when threads are canceled.

The ‘random’ and ‘fast_random’ objects always initialize the random
generator seed to the same value, thus providing a pseudo random number
generator.  The ‘randomize/1’ predicate can be used to initialize the
seed with a random value.  The argument should be a large positive
integer.  In alternative, when using a small integer argument, discard
the first dozen random values.

The ‘backend_random’ object abstracts the native backend Prolog compiler
random number generator for the basic ‘random/1’, ‘get_seed/1’, and
‘set_seed/1’ predicates providing a portable implementation for the
remaining predicates.  This makes the object stateless, which allows
reliable use from multiple threads.  Consult the backend Prolog compiler
documentation for details on its random number generator properties.
Note that several of the supported backend Prolog systems, notably
B-Prolog, CxProlog, ECLiPSe, JIProlog, and Quintus Prolog, do not
provide implementations for both the ‘get_seed/1’ and ‘set_seed/1’
predicates and calling these predicates simply succeed without
performing any action.

All random objects (‘random’, ‘fast_random’, and ‘backend_random’)
implement the ‘sampling_protocol’ protocol.  To maximize performance,
the shared implementations of the sampling predicates is defined in the
‘sampling.lgt’ file that’s included in the random objects.  This allows
these predicates to call the basic ‘random/1’ and ‘random/3’ predicates
as locally defined predicates.


File: TheLogtalkHandbook-3.96.0.info,  Node: reader,  Next: recorded_database,  Prev: random,  Up: Libraries

6.45 ‘reader’
=============

The ‘reader’ object provides portable predicates for reading text file
and text stream contents to lists of terms, characters, or character
codes and for reading binary files to lists of bytes.  The text file API
is loosely based on the SWI-Prolog ‘readutil’ module.

* Menu:

* API documentation: API documentation<59>.
* Loading: Loading<60>.
* Testing: Testing<51>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<59>,  Next: Loading<60>,  Up: reader

6.45.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#reader’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<60>,  Next: Testing<51>,  Prev: API documentation<59>,  Up: reader

6.45.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(reader(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<51>,  Prev: Loading<60>,  Up: reader

6.45.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(reader(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: recorded_database,  Next: redis,  Prev: reader,  Up: Libraries

6.46 ‘recorded_database’
========================

The ‘recorded_database’ library aims to help port Prolog code using the
legacy recorded database.  Ported applications should still consider
migrating to more standard solutions to handle dynamic data that must
survive backtracking.

* Menu:

* API documentation: API documentation<60>.
* Loading: Loading<61>.
* Testing: Testing<52>.
* Usage: Usage<36>.
* Known issues: Known issues<14>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<60>,  Next: Loading<61>,  Up: recorded_database

6.46.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#recorded_database’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<61>,  Next: Testing<52>,  Prev: API documentation<60>,  Up: recorded_database

6.46.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(recorded_database(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<52>,  Next: Usage<36>,  Prev: Loading<61>,  Up: recorded_database

6.46.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(recorded_database(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<36>,  Next: Known issues<14>,  Prev: Testing<52>,  Up: recorded_database

6.46.4 Usage
------------

The ‘recorded_database_core’ category implements the library predicates.
This category is imported by the default ‘recorded_database’ object to
provide application global database.  To make the database local and
thus minimize potential record clashes, the category can be imported by
one or more application objects.  Use protected or private import to
restrict the scope of the library predicates.  For example:

     :- object(foo,
         imports(private::recorded_database_core)).

         bar :-
             ^^recorda(key, value(1)),
             ...

     :- end_object.


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<14>,  Prev: Usage<36>,  Up: recorded_database

6.46.5 Known issues
-------------------

Currently, references are non-negative integers.  They still must be
regarded as opaque terms and subject to change without notice.  But
using integers can result in integer overflows when running on backends
with bounded integers in applications performing a large number of
database updates.


File: TheLogtalkHandbook-3.96.0.info,  Node: redis,  Next: sets,  Prev: recorded_database,  Up: Libraries

6.47 ‘redis’
============

Redis client library.  Supports GNU Prolog, SICStus Prolog, SWI-Prolog,
XSB, and XVM. Support for Ciao Prolog and ECLiPSe is also included but
requires fixes for issues in these systems.

For general information on Redis, including a list of the available
commands, visit:

     https://redis.io

* Menu:

* API documentation: API documentation<61>.
* Loading: Loading<62>.
* Testing: Testing<53>.
* Credits: Credits<4>.
* Known issues: Known issues<15>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<61>,  Next: Loading<62>,  Up: redis

6.47.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#redis’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<62>,  Next: Testing<53>,  Prev: API documentation<61>,  Up: redis

6.47.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(redis(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<53>,  Next: Credits<4>,  Prev: Loading<62>,  Up: redis

6.47.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(redis(tester)).

The tests assume a localhost Redis server running on the default port
(6379) if the ‘REDIS_HOST’ and ‘REDIS_PORT’ environment variables are
not defined.  If the server is not detected, the tests are skipped.

The unit tests were originally written by Sean Charles for his GNU
Prolog Redis client library:

     https://github.com/emacstheviking/gnuprolog-redisclient

The Logtalk version is a straight-forward port of the original tests
using the ‘test/1’ dialect of ‘lgtunit’.


File: TheLogtalkHandbook-3.96.0.info,  Node: Credits<4>,  Next: Known issues<15>,  Prev: Testing<53>,  Up: redis

6.47.4 Credits
--------------

This library is inspired by the Sean Charles GNU Prolog Redis client
library.


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<15>,  Prev: Credits<4>,  Up: redis

6.47.5 Known issues
-------------------

Recent versions of macOS seem to disable the mapping of ‘localhost’ to
‘127.0.0.1’.  This issue may prevent running this library unit tests and
the ‘redis::connect/1’ predicate from working.  This can be fixed either
by editing the ‘/etc/hosts file or by using in alternative the
predicate’redis::connect/3‘with’’127.0.0.1’' as the first argument.


File: TheLogtalkHandbook-3.96.0.info,  Node: sets,  Next: statistics,  Prev: redis,  Up: Libraries

6.48 ‘sets’
===========

This library provides a set protocol and two implementations of this
protocol using 'ordered lists', one of them a parametric object that
takes the type of the set elements as a parameter.  Although
representing sets as ordered lists is a common solution, the best
practice is to regard sets as 'opaque terms' and only construct, access,
and update them using the library predicates.  For better performance
when handling large sets, alternative implementations of the protocol
can always be written.

The current implementations use ‘==/2’ for element comparison and
standard term ordering.  This allows non-ground set elements.  But
requires caution with later unifications with output arguments and when
using the ‘member/2’ and ‘select/3’ predicates, which can break the
ordered representation.  Note also that, per the ISO Prolog Core
Standard, variable ordering is implementation dependent.  This can
result in unexpected results and portability issues.

* Menu:

* API documentation: API documentation<62>.
* Loading: Loading<63>.
* Testing: Testing<54>.
* Usage: Usage<37>.
* Credits: Credits<5>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<62>,  Next: Loading<63>,  Up: sets

6.48.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#sets’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<63>,  Next: Testing<54>,  Prev: API documentation<62>,  Up: sets

6.48.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(sets(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<54>,  Next: Usage<37>,  Prev: Loading<63>,  Up: sets

6.48.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(sets(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<37>,  Next: Credits<5>,  Prev: Testing<54>,  Up: sets

6.48.4 Usage
------------

First, select a set implementation.  Use the ‘set(Type)’ object if you
want to type-check the set elements.  Otherwise, use the ‘set’ object.

To create a new set, you can use the ‘new/1’ predicate.  For example:

     | ?- set::new(Set).
     Set = []
     yes

You can also create a new set with all unique elements from a list of
terms by using the ‘as_set/2’ predicate.  For example:

     | ?- set::as_set([1,3,2,1,2], Set).
     Set = [1, 2, 3]
     yes

Predicates are provided for the most common set operations.  For
example:

     | ?- set::(
             as_set([1,3,2,1,2], Set1),
             as_set([7,4,2,5,1], Set2),
             intersection(Set1, Set2, Intersection),
             symdiff(Set1, Set2, Difference)
         ).
     Set1 = [1, 2, 3],
     Set2 = [1, 2, 4, 5, 7],
     Intersection = [1, 2],
     Difference = [3, 4, 5, 7]
     yes

When working with a custom type of set elements, the corresponding
object must implement the ‘comparingp’ protocol.  For example:

     :- object(rainbow_colors,
         implements(comparingp)).

         order(red,    1).
         order(orange, 2).
         order(yellow, 3).
         order(green,  4).
         order(blue,   5).
         order(indigo, 6).
         order(violet, 7).

         Color1 < Color2 :-
             order(Color1, N1),
             order(Color2, N2),
             {N1 < N2}.

         Color1 =< Color2 :-
             order(Color1, N1),
             order(Color2, N2),
             {N1 =< N2}.

         ...

     :- end_object.

We can then use this object with the ‘set/1’ parametric object.  For
example:

     | ?- set(rainbow_colors)::as_set([blue, yellow, violet], Set).
     Set = [yellow, blue, violet]
     yes

For details on these and other provided predicates, consult the library
API documentation.


File: TheLogtalkHandbook-3.96.0.info,  Node: Credits<5>,  Prev: Usage<37>,  Up: sets

6.48.5 Credits
--------------

Some predicates adapted from code authored by Richard O’Keefe.


File: TheLogtalkHandbook-3.96.0.info,  Node: statistics,  Next: term_io,  Prev: sets,  Up: Libraries

6.49 ‘statistics’
=================

The entities in this library define some useful predicates for
descriptive statistics.  Data is represented as a list of numbers
(integers or floats).  Use the object ‘sample’ of your data represents a
sample.  Use the object ‘population’ if your data represents a
population.

* Menu:

* API documentation: API documentation<63>.
* Loading: Loading<64>.
* Testing: Testing<55>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<63>,  Next: Loading<64>,  Up: statistics

6.49.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#statistics’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<64>,  Next: Testing<55>,  Prev: API documentation<63>,  Up: statistics

6.49.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(statistics(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<55>,  Prev: Loading<64>,  Up: statistics

6.49.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(statistics(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: term_io,  Next: timeout,  Prev: statistics,  Up: Libraries

6.50 ‘term_io’
==============

This library implements predicates for reading/writing terms from/to
atoms, chars (lists of characters), and codes (lists of character
codes).  These predicates are implemented using a single temporary file
created when the library is loaded.  This temporary file is unique per
Logtalk process.  The predicates can be safely used in multi-threaded
applications.

* Menu:

* API documentation: API documentation<64>.
* Loading: Loading<65>.
* Testing: Testing<56>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<64>,  Next: Loading<65>,  Up: term_io

6.50.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#term-io’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<65>,  Next: Testing<56>,  Prev: API documentation<64>,  Up: term_io

6.50.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(term_io(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<56>,  Prev: Loading<65>,  Up: term_io

6.50.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(term_io(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: timeout,  Next: tsv,  Prev: term_io,  Up: Libraries

6.51 ‘timeout’
==============

The ‘timeout’ object provides a portable abstraction over calling a goal
deterministically with a time limit as made available in some form by
some of the supported backend Prolog systems (B-Prolog, ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, XSB, XVM, and YAP).

For better performance, compile calls to this library meta-predicates
with the ‘optimize’ flag turned on so that the meta-arguments, i.e.  the
goals that you are timing, are also compiled.

* Menu:

* API documentation: API documentation<65>.
* Loading: Loading<66>.
* Testing: Testing<57>.
* Known issues: Known issues<16>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<65>,  Next: Loading<66>,  Up: timeout

6.51.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#timeout’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<66>,  Next: Testing<57>,  Prev: API documentation<65>,  Up: timeout

6.51.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(timeout(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<57>,  Next: Known issues<16>,  Prev: Loading<66>,  Up: timeout

6.51.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(timeout(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<16>,  Prev: Testing<57>,  Up: timeout

6.51.4 Known issues
-------------------

Two tests are currently skipped when using the SWI-Prolog backend as
they cannot be interrupted and generate the expected timeout exceptions
due to tests being run from an ‘initialization/1’ directive goal that,
in the SWI-Prolog implementation of this directive, ignores signals.
The test goals do generate the expected timeout exception when not
called from an ‘initialization/1’ directive.


File: TheLogtalkHandbook-3.96.0.info,  Node: tsv,  Next: types,  Prev: timeout,  Up: Libraries

6.52 ‘tsv’
==========

The ‘tsv’ library provides predicates for reading and writing TSV files
and streams:

‘https://www.iana.org/assignments/media-types/text/tab-separated-values’

The main object, ‘tsv/1’, is a parametric object allowing passing a
single option for the handling of the header of the file (‘keep’ or
‘skip’).  The ‘tvs’ object extends the ‘tsv/1’ parametric object using
the default ‘keep’ option value.

Files and streams can be read into a list of rows (with each row being
represented by a list of fields) or asserted using a user-defined
dynamic predicate.  Reading can be done by first loading the whole file
(using the ‘read_file/2-3’ predicates) into memory or line by line
(using the ‘read_file_by_line/2-3’ predicates).  Reading line by line is
usually the best option for parsing large TSV files.

Data can be saved to a TSV file or stream by providing the object and
predicate for accessing the data plus the name of the destination file
or the stream handle or alias.

* Menu:

* API documentation: API documentation<66>.
* Loading: Loading<67>.
* Testing: Testing<58>.
* Usage: Usage<38>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<66>,  Next: Loading<67>,  Up: tsv

6.52.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#tsv’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<67>,  Next: Testing<58>,  Prev: API documentation<66>,  Up: tsv

6.52.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(tsv(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<58>,  Next: Usage<38>,  Prev: Loading<67>,  Up: tsv

6.52.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(tsv(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<38>,  Prev: Testing<58>,  Up: tsv

6.52.4 Usage
------------

A TSV file can be read as a list of rows:

     | ?- tsv::read_file('test_files/data.tsv', Rows).

     Rows = [['Name','Age','Address'], ['Paul',23,'1115 W Franklin'], ['Bessy the Cow',5,'Big Farm Way'], ['Zeke,45,'W Main St']]
     yes

Alternatively, The TSV data can be saved using a public and dynamic
object predicate (that must be previously declared).  For example:

     | ?- assertz(p(_,_,_)), retractall(p(_,_,_)).
     yes

     | ?- tsv(skip)::read_file('test_files/data.tsv', user, p/3).
     yes

     | ?-  p(A,B,C).

     A = 'Paul', B = 23, C = '1115 W Franklin' ? ;
     ...

Given a predicate representing a table, the predicate data can be
written to a file or stream.  For example:

     | ?- tsv::write_file('output.tsv', user, p/3).
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: types,  Next: ulid,  Prev: tsv,  Up: Libraries

6.53 ‘types’
============

This library implements predicates over standard Prolog term types and
also terms representing common data structures such as lists and pairs.

It also includes a user-extensible ‘type’ object defining type checking
predicates over common Logtalk and Prolog term types.  The types define
a hierarchy with the Prolog type ‘term’ at the root (i.e., type-checking
a predicate argument of type ‘term’ trivially succeeds).  Some types are
only meaningful for backend Prolog systems supporting non-universal
features (e.g., ‘cyclic’ or ‘char(CharSet)’ with a Unicode character
set).  See the API documentation for a full list of the types defined by
default.

* Menu:

* API documentation: API documentation<67>.
* Loading: Loading<68>.
* Testing: Testing<59>.
* Type-checking: Type-checking<2>.
* Defining new types::
* Examples: Examples<166>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<67>,  Next: Loading<68>,  Up: types

6.53.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#types’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<68>,  Next: Testing<59>,  Prev: API documentation<67>,  Up: types

6.53.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(types(loader)).

If your code only requires the most basic types, you can load in
alternative the file:

     | ?- logtalk_load(basic_types(loader)).

See the notes on the ‘basic_types’ virtual library for details.


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<59>,  Next: Type-checking<2>,  Prev: Loading<68>,  Up: types

6.53.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(types(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Type-checking<2>,  Next: Defining new types,  Prev: Testing<59>,  Up: types

6.53.4 Type-checking
--------------------

This library ‘type’ object can be used to type-check common Logtalk and
Prolog term types (see the object documentation for a listing of all the
pre-defined types).  The ‘valid/2’ predicate succeeds or fails if a term
is of a given type.  For example:

     | ?- type::valid(positive_integer, 42).
     yes

     | ?- type::valid(positive_integer, -13).
     no

The ‘check/2’ and ‘check/3’ predicates throw an exception if a term is
not of a given type.  For example:

     | ?- catch(type::check(integer, abc), Error, true).
     Error = type_error(integer, abc)
     yes

If we require a standard ‘error/2’ exception term, the ‘check/3’
predicate takes a 'context' argument.  For example:

     | ?- catch(type::check(integer, abc, foo/3), Error, true).
     Error = error(type_error(integer, abc), foo/3)
     yes

Typically, the context is provided by calling the built-in ‘context/1’
method.


File: TheLogtalkHandbook-3.96.0.info,  Node: Defining new types,  Next: Examples<166>,  Prev: Type-checking<2>,  Up: types

6.53.5 Defining new types
-------------------------

To define a custom type, define clauses for the multifile predicates
‘type::type/1’ (to declare the type) and ‘type::check/2’ (to type-check
values).  For example:

     :- multifile(type::type/1).
     type::type(age).

     :- multifile(type::check/2).
     type::check(age, Term) :-
         type::check(between(non_negative_integer, 0, 150), Term).

Be careful to ensure that the new type definitions don’t introduce
spurious choice-points for these predicates.  The unit tests of the
‘types’ library perform this check for pre-defined and loaded
user-defined ground types.

When defining a meta-type (i.e., a type with arguments that are also
types), add also a clause for the ‘type::meta_type/3’ multifile
predicate.  For example:

     :- multifile(type::meta_type/3).
     type::meta_type(tuple(Type1, Type2, Type3), [Type1, Type2, Type3], []).

This predicate is called when checking if a type is a defined type.  For
meta-types, that check must extend to the sub-types.


File: TheLogtalkHandbook-3.96.0.info,  Node: Examples<166>,  Prev: Defining new types,  Up: types

6.53.6 Examples
---------------

See e.g.  the ‘os’ library implementation of custom types for files and
directories.  Or the ‘expecteds’ and ‘optionals’ libraries custom types.
See also the ‘my_types’ programming example.


File: TheLogtalkHandbook-3.96.0.info,  Node: ulid,  Next: unicode_data,  Prev: types,  Up: Libraries

6.54 ‘ulid’
===========

This library implements a Universally Unique Lexicographically Sortable
Identifier (ULID) generator.

‘https://github.com/ulid/spec’

Note that most backends provide time stamps with lower granularity than
required (i.e., seconds but not milliseconds).  Also note that, per
spec, within the same millisecond, monotonic sort order is not
guaranteed.

The generation of ULIDs uses the ‘/dev/urandom’ random number generator
when available.  This includes macOS, Linux, *BSD, and other POSIX
operating-systems.  On Windows, a pseudo-random generator is used, but
randomized using the current wall time.

ULIDs can be generated as atoms, lists of characters, or lists of
character codes.

See also the ‘ids’ and ‘uuid’ libraries.

* Menu:

* API documentation: API documentation<68>.
* Loading: Loading<69>.
* Testing: Testing<60>.
* Generating ULIDs::
* Type-checking ULIDs::


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<68>,  Next: Loading<69>,  Up: ulid

6.54.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#ulid’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<69>,  Next: Testing<60>,  Prev: API documentation<68>,  Up: ulid

6.54.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ulid(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<60>,  Next: Generating ULIDs,  Prev: Loading<69>,  Up: ulid

6.54.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ulid(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Generating ULIDs,  Next: Type-checking ULIDs,  Prev: Testing<60>,  Up: ulid

6.54.4 Generating ULIDs
-----------------------

By default, ULIDs are generated as atoms.  For example:

     | ?- ulid::generate(ULID).
     ULID = '01H0J31SYQXHJZWPRAKHQ6YVYH'
     yes

To generate a ULID using a list of characters representation, use
instead the ‘ulid/1’ parametric object:

     | ?- ulid(chars)::generate(ULID).
     ULID = ['0','1','H','0','J','3','2','Y','V','5','V','S','P','K','5','P','4','5','G','G','0','9','8','8','M','2']
     yes

Similarly, to get a ULID using a list of character codes representation:

     | ?- ulid(codes)::generate(ULID).
     ULID = [48,49,72,48,74,51,52,66,54,48,55,57,54,49,67,82,70,65,67,51,67,67,86,82,48,66]
     yes

It’s also possible to generate ULIDs from a given timestamp, i.e.  the
number of milliseconds since the Unix epoch (00:00:00 UTC on January 1,
1970), using the ‘generate/2’ predicate.  The timestamp must be an
integer.  For example, assuming a backend Prolog system providing a
‘time_stamp/1’ predicate returning the Unix epoch in milliseconds:

     | ?- time_stamp(Milliseconds), ulid(atom)::generate(Seconds, ULID).
     Seconds = 1684245175344, ULID = '01H0JDBQ1GAWJF35C44Y5S97DX'
     yes

You can also use timestamp discrete components using the ‘generate/8’
predicate.  For example:

     | ?- ulid(atom)::generate(2023, 5, 17, 16, 23, 38, 591, ULID).
     ULID = '01H0N8CDAZK75C5H3BJSGS4VCQ'
     yes

To extract the timestamp from a given ULID, use the ‘timestamp/2’ and
‘timestamp/8’ predicates.  For example:

     | ?- ulid(atom)::timestamp('01H0JDBQ1GAWJF35C44Y5S97DX', Milliseconds).
     Milliseconds = 1684245175344
     yes

     | ?- ulid(atom)::timestamp('01H0N8CDAZK75C5H3BJSGS4VCQ', Year, Month, Day, Hours, Minutes, Seconds, Milliseconds).
     Year = 2023, Month = 5, Day = 17, Hours = 16, Minutes = 23, Seconds = 38, Milliseconds = 591
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Type-checking ULIDs,  Prev: Generating ULIDs,  Up: ulid

6.54.5 Type-checking ULIDs
--------------------------

This library also defines a ‘ulid(Representation)’ type for
type-checking ULIDs.  For example, with an atom containing invalid
characters:

     | ?- type::check(ulid(atom), '01BX5ZIKBKALTAV9OEVGEMMVRY').
     uncaught exception: domain_error(ulid,'01BX5ZIKBKALTAV9OEVGEMMVRY')


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_data,  Next: union_find,  Prev: ulid,  Up: Libraries

6.55 ‘unicode_data’
===================

VivoMind Prolog Unicode Resources

* Menu:

* Authors::
* License::
* Website::
* Description: Description<165>.
* Requirements: Requirements<6>.
* Usage: Usage<39>.
* Known issues: Known issues<17>.
* Acknowledgements::
* Files and API Summary::


File: TheLogtalkHandbook-3.96.0.info,  Node: Authors,  Next: License,  Up: unicode_data

6.55.1 Authors
--------------

     Arun Majumdar @ VivoMind LLC
     Paulo Moura @ VivoMind LLC


File: TheLogtalkHandbook-3.96.0.info,  Node: License,  Next: Website,  Prev: Authors,  Up: unicode_data

6.55.2 License
--------------

Creative Commons CC0 1.0 Universal (CC0 1.0) - Public Domain Dedication:

     https://creativecommons.org/publicdomain/zero/1.0/

We do appreciate acknowledgment if you use these resources, however, and
we also welcome contributions to improve them.


File: TheLogtalkHandbook-3.96.0.info,  Node: Website,  Next: Description<165>,  Prev: License,  Up: unicode_data

6.55.3 Website
--------------

The latest release of the VivoMind Prolog Unicode Resources is available
at the URL:

     https://github.com/VivoMind

At this address you can also find additional information about the
VivoMind Prolog Unicode Resources and submit your bug reports and
contributions.


File: TheLogtalkHandbook-3.96.0.info,  Node: Description<165>,  Next: Requirements<6>,  Prev: Website,  Up: unicode_data

6.55.4 Description
------------------

The VivoMind Prolog Unicode Resources are a set of files resulting from
the conversion of most (but not all) official UCD 6.1 files and updated
for the few changes in the 6.2 standard.  The original files can be
downloaded from:

     http://www.unicode.org

The conversion of the UCD files resulted in a large number of Prolog
tables and also a set of auxiliary predicates (described below) for
accessing these tables.  Other than the obvious conversion in the
provided predicate names, no attempt was made to convert the identifiers
used for properties and other data.


File: TheLogtalkHandbook-3.96.0.info,  Node: Requirements<6>,  Next: Usage<39>,  Prev: Description<165>,  Up: unicode_data

6.55.5 Requirements
-------------------

Most of the auxiliary predicates assume that the de facto Prolog
standard predicate ‘between/3’ is available.  Unicode code point values
are represented using the ISO Prolog standard notation for hexadecimal
integers.  In addition, the ISO Prolog standard directives ‘include/1’
and ‘ensure_loaded/1’ are used in some of the files to load auxiliary
files.


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<39>,  Next: Known issues<17>,  Prev: Requirements<6>,  Up: unicode_data

6.55.6 Usage
------------

Most applications only require some of the tables present in these
resources.  Most of these tables define properties for ranges of code
points and not for single code points, but the provided auxiliary
predicates allow access for a single code point.  When increased
performance is required, consider using the existing tables and
auxiliary predicates to generate derived tables more fit for your
specific application.


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<17>,  Next: Acknowledgements,  Prev: Usage<39>,  Up: unicode_data

6.55.7 Known issues
-------------------

In the file ‘unicode_unihan_variant.pl’, when there’s more than one
variant for a code point, only the first one (as listed in the original
UCD file) is returned.

The ‘include/1’ and ‘ensure_loaded/1’ directives are specified in the
ISO Prolog standard published in 1995.  But some Prolog compilers either
don’t implement one or both directives or have flawed implementations.
Thus, you may need to change how some of the files are loaded depending
on the chosen Prolog compiler.  Using conditional compilation directives
would help in some cases, but it would also raise portability issues on
its own.


File: TheLogtalkHandbook-3.96.0.info,  Node: Acknowledgements,  Next: Files and API Summary,  Prev: Known issues<17>,  Up: unicode_data

6.55.8 Acknowledgements
-----------------------

We thank Richard O’Keefe for helpful suggestions to improve the
usability of these resources.


File: TheLogtalkHandbook-3.96.0.info,  Node: Files and API Summary,  Prev: Acknowledgements,  Up: unicode_data

6.55.9 Files and API Summary
----------------------------

The Prolog file names are derived from the original file names by
prefixing them with the ‘unicode_’ string, converting to lower case, and
replacing the camel case spelling with underscores.  There are, however,
two exceptions: the files and directories holding the code point
categories and names.

There’s also a utility file, ‘unicode_data.pl’, that can be used to load
all the files in these resources.  It is mostly used to test the
portability of the code across Prolog compilers.  Also included is a
Logtalk version of this file, ‘unicode_data.lgt’, which uses Logtalk’s
own implementation of the ‘include/1’ directive and the ‘logtak_load/1’
predicate to load all files.  This file can be used to workaround Prolog
systems with buggy or missing implementations of the ‘ensure_loaded/1’
and ‘include/1’ directives.

An overview of the original file names and the code point properties can
be found at:

     http://www.unicode.org/reports/tr44/#Directory_Structure

     http://www.unicode.org/reports/tr44/#Property_Definitions

* Menu:

* unicode_arabic_shaping.pl: unicode_arabic_shaping pl.
* unicode_bidi_mirroring.pl: unicode_bidi_mirroring pl.
* unicode_blocks.pl: unicode_blocks pl.
* unicode_case_folding.pl: unicode_case_folding pl.
* unicode_categories.pl: unicode_categories pl.
* unicode_cjk_radicals.pl: unicode_cjk_radicals pl.
* unicode_composition_exclusions.pl: unicode_composition_exclusions pl.
* unicode_core_properties.pl: unicode_core_properties pl.
* unicode_decomposition_type.pl: unicode_decomposition_type pl.
* unicode_derived_age.pl: unicode_derived_age pl.
* unicode_derived_bidi_class.pl: unicode_derived_bidi_class pl.
* unicode_derived_combining_class.pl: unicode_derived_combining_class pl.
* unicode_derived_core_properties.pl: unicode_derived_core_properties pl.
* unicode_derived_decomposition_type.pl: unicode_derived_decomposition_type pl.
* unicode_derived_east_asian_width.pl: unicode_derived_east_asian_width pl.
* unicode_derived_joining_group.pl: unicode_derived_joining_group pl.
* unicode_derived_joining_type.pl: unicode_derived_joining_type pl.
* unicode_derived_line_break.pl: unicode_derived_line_break pl.
* unicode_derived_normalization_props.pl: unicode_derived_normalization_props pl.
* unicode_derived_numeric_type.pl: unicode_derived_numeric_type pl.
* unicode_derived_numeric_values.pl: unicode_derived_numeric_values pl.
* unicode_hangul_syllable_type.pl: unicode_hangul_syllable_type pl.
* unicode_indic_matra_category.pl: unicode_indic_matra_category pl.
* unicode_indic_syllabic_category.pl: unicode_indic_syllabic_category pl.
* unicode_jamo.pl: unicode_jamo pl.
* unicode_name_aliases.pl: unicode_name_aliases pl.
* unicode_names.pl: unicode_names pl.
* unicode_prop_list.pl: unicode_prop_list pl.
* unicode_range_scripts.pl: unicode_range_scripts pl.
* unicode_script_extensions.pl: unicode_script_extensions pl.
* unicode_scripts.pl: unicode_scripts pl.
* unicode_special_casing.pl: unicode_special_casing pl.
* unicode_unihan_variants.pl: unicode_unihan_variants pl.
* unicode_version.pl: unicode_version pl.


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_arabic_shaping pl,  Next: unicode_bidi_mirroring pl,  Up: Files and API Summary

6.55.9.1 ‘unicode_arabic_shaping.pl’
....................................

   - Provides: ‘unicode_arabic_shaping/4’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_bidi_mirroring pl,  Next: unicode_blocks pl,  Prev: unicode_arabic_shaping pl,  Up: Files and API Summary

6.55.9.2 ‘unicode_bidi_mirroring.pl’
....................................

   - Provides: ‘unicode_bidi_mirroring/2’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_blocks pl,  Next: unicode_case_folding pl,  Prev: unicode_bidi_mirroring pl,  Up: Files and API Summary

6.55.9.3 ‘unicode_blocks.pl’
............................

   - Provides: ‘unicode_block/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_case_folding pl,  Next: unicode_categories pl,  Prev: unicode_blocks pl,  Up: Files and API Summary

6.55.9.4 ‘unicode_case_folding.pl’
..................................

   - Provides: ‘unicode_case_folding/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_categories pl,  Next: unicode_cjk_radicals pl,  Prev: unicode_case_folding pl,  Up: Files and API Summary

6.55.9.5 ‘unicode_categories.pl’
................................

   - Provides: ‘unicode_category/2’

   - Dependencies: files in the ‘unicode_categories’ directory


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_cjk_radicals pl,  Next: unicode_composition_exclusions pl,  Prev: unicode_categories pl,  Up: Files and API Summary

6.55.9.6 ‘unicode_cjk_radicals.pl’
..................................

   - Provides: ‘unicode_cjk_radical/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_composition_exclusions pl,  Next: unicode_core_properties pl,  Prev: unicode_cjk_radicals pl,  Up: Files and API Summary

6.55.9.7 ‘unicode_composition_exclusions.pl’
............................................

   - Provides: ‘unicode_composition_exclusion/1’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_core_properties pl,  Next: unicode_decomposition_type pl,  Prev: unicode_composition_exclusions pl,  Up: Files and API Summary

6.55.9.8 ‘unicode_core_properties.pl’
.....................................

   - Provides: ‘unicode_math/1-2’ ‘unicode_alphabetic/1-2’
     ‘unicode_range_alphabetic/2’ ‘unicode_lowercase/1-2’
     ‘unicode_uppercase/1-2’ ‘unicode_cased/1-2’
     ‘unicode_case_ignorable/1-2’ ‘unicode_changes_when_lowercased/1-2’
     ‘unicode_changes_when_uppercased/1-2’
     ‘unicode_changes_when_titlecased/1-2’
     ‘unicode_changes_when_casefolded/1-2’
     ‘unicode_changes_when_casemapped/1-2’ ‘unicode_id_start/1-2’
     ‘unicode_id_continue/1-2’ ‘unicode_xid_start/1-2’
     ‘unicode_xid_continue/1-2’ ‘unicode_default_ignorable/1-2’
     ‘unicode_grapheme_extend/1-2’ ‘unicode_grapheme_base/1-2’
     ‘unicode_grapheme_link/1-2’

   - Dependencies: files in the ‘unicode_core_properties’ directory


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_decomposition_type pl,  Next: unicode_derived_age pl,  Prev: unicode_core_properties pl,  Up: Files and API Summary

6.55.9.9 ‘unicode_decomposition_type.pl’
........................................

   - Provides: ‘unicode_canonical/1-2’ ‘unicode_compat/1-2’
     ‘unicode_font/1-2’ ‘unicode_nobreak/1-2’ ‘unicode_initial/1-2’
     ‘unicode_medial/1-2’ ‘unicode_final/1-2’ ‘unicode_isolated/1-2’
     ‘unicode_circle/1-2’ ‘unicode_super/1-2’ ‘unicode_sub/1-2’
     ‘unicode_vertical/1-2’ ‘unicode_wide/1-2’ ‘unicode_narrow/1-2’
     ‘unicode_small/1-2’ ‘unicode_square/1-2’ ‘unicode_fraction/1-2’

   - Dependencies: files in the ‘unicode_decomposition_type’ directory


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_derived_age pl,  Next: unicode_derived_bidi_class pl,  Prev: unicode_decomposition_type pl,  Up: Files and API Summary

6.55.9.10 ‘unicode_derived_age.pl’
..................................

   - Provides: ‘unicode_age/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_derived_bidi_class pl,  Next: unicode_derived_combining_class pl,  Prev: unicode_derived_age pl,  Up: Files and API Summary

6.55.9.11 ‘unicode_derived_bidi_class.pl’
.........................................

   - Provides: ‘unicode_bidi_class/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_derived_combining_class pl,  Next: unicode_derived_core_properties pl,  Prev: unicode_derived_bidi_class pl,  Up: Files and API Summary

6.55.9.12 ‘unicode_derived_combining_class.pl’
..............................................

   - Provides: ‘unicode_combining_class/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_derived_core_properties pl,  Next: unicode_derived_decomposition_type pl,  Prev: unicode_derived_combining_class pl,  Up: Files and API Summary

6.55.9.13 ‘unicode_derived_core_properties.pl’
..............................................

   - Provides: ‘unicode_core_property/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_derived_decomposition_type pl,  Next: unicode_derived_east_asian_width pl,  Prev: unicode_derived_core_properties pl,  Up: Files and API Summary

6.55.9.14 ‘unicode_derived_decomposition_type.pl’
.................................................

   - Provides: ‘unicode_decomposition_type/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_derived_east_asian_width pl,  Next: unicode_derived_joining_group pl,  Prev: unicode_derived_decomposition_type pl,  Up: Files and API Summary

6.55.9.15 ‘unicode_derived_east_asian_width.pl’
...............................................

   - Provides: ‘unicode_east_asian_width/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_derived_joining_group pl,  Next: unicode_derived_joining_type pl,  Prev: unicode_derived_east_asian_width pl,  Up: Files and API Summary

6.55.9.16 ‘unicode_derived_joining_group.pl’
............................................

   - Provides: ‘unicode_joining_group/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_derived_joining_type pl,  Next: unicode_derived_line_break pl,  Prev: unicode_derived_joining_group pl,  Up: Files and API Summary

6.55.9.17 ‘unicode_derived_joining_type.pl’
...........................................

   - Provides: ‘unicode_joining_type/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_derived_line_break pl,  Next: unicode_derived_normalization_props pl,  Prev: unicode_derived_joining_type pl,  Up: Files and API Summary

6.55.9.18 ‘unicode_derived_line_break.pl’
.........................................

   - Provides: ‘unicode_line_break/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_derived_normalization_props pl,  Next: unicode_derived_numeric_type pl,  Prev: unicode_derived_line_break pl,  Up: Files and API Summary

6.55.9.19 ‘unicode_derived_normalization_props.pl’
..................................................

   - Provides: ‘unicode_fc_nfkc/2’ ‘unicode_nfkc_cf/2’
     ‘unicode_full_composition_exclusion/1-2’ ‘unicode_nfd_qc_no/1-2’
     ‘unicode_nfc_qc_no/1-2’ ‘unicode_nfc_qc_maybe/1-2’
     ‘unicode_nfkd_qc_no/1-2’ ‘unicode_nfkc_qc_no/1-2’
     ‘unicode_nfkc_qc_maybe/1-2’ ‘unicode_expands_on_nfd/1-2’
     ‘unicode_expands_on_nfc/1-2’ ‘unicode_expands_on_nfkd/1-2’
     ‘unicode_expands_on_nfkc/1-2’
     ‘unicode_changes_when_nfkc_casefolded/1-2’

   - Dependencies: files in the ‘unicode_derived_normalization_props’
     directory


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_derived_numeric_type pl,  Next: unicode_derived_numeric_values pl,  Prev: unicode_derived_normalization_props pl,  Up: Files and API Summary

6.55.9.20 ‘unicode_derived_numeric_type.pl’
...........................................

   - Provides: ‘unicode_numeric_type/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_derived_numeric_values pl,  Next: unicode_hangul_syllable_type pl,  Prev: unicode_derived_numeric_type pl,  Up: Files and API Summary

6.55.9.21 ‘unicode_derived_numeric_values.pl’
.............................................

   - Provides: ‘unicode_numerical_value/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_hangul_syllable_type pl,  Next: unicode_indic_matra_category pl,  Prev: unicode_derived_numeric_values pl,  Up: Files and API Summary

6.55.9.22 ‘unicode_hangul_syllable_type.pl’
...........................................

   - Provides: ‘unicode_hangul_syllable_type/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_indic_matra_category pl,  Next: unicode_indic_syllabic_category pl,  Prev: unicode_hangul_syllable_type pl,  Up: Files and API Summary

6.55.9.23 ‘unicode_indic_matra_category.pl’
...........................................

   - Provides: ‘unicode_indic_matra_category/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_indic_syllabic_category pl,  Next: unicode_jamo pl,  Prev: unicode_indic_matra_category pl,  Up: Files and API Summary

6.55.9.24 ‘unicode_indic_syllabic_category.pl’
..............................................

   - Provides: ‘unicode_indic_syllabic_category/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_jamo pl,  Next: unicode_name_aliases pl,  Prev: unicode_indic_syllabic_category pl,  Up: Files and API Summary

6.55.9.25 ‘unicode_jamo.pl’
...........................

   - Provides: ‘unicode_jamo/2’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_name_aliases pl,  Next: unicode_names pl,  Prev: unicode_jamo pl,  Up: Files and API Summary

6.55.9.26 ‘unicode_name_aliases.pl’
...................................

   - Provides: ‘unicode_name_alias/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_names pl,  Next: unicode_prop_list pl,  Prev: unicode_name_aliases pl,  Up: Files and API Summary

6.55.9.27 ‘unicode_names.pl’
............................

   - Provides: ‘unicode_name/2’

   - Dependencies: files in the ‘unicode_names’ directory


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_prop_list pl,  Next: unicode_range_scripts pl,  Prev: unicode_names pl,  Up: Files and API Summary

6.55.9.28 ‘unicode_prop_list.pl’
................................

   - Provides: ‘unicode_white_space/1-2’ ‘unicode_bidi_control/1-2’
     ‘unicode_join_control/1-2’ ‘unicode_dash/1-2’ ‘unicode_hyphen/1-2’
     ‘unicode_quotation_mark/1-2’ ‘unicode_terminal_punctuation/1-2’
     ‘unicode_other_math/1-2’ ‘unicode_hex_digit/1-2’
     ‘unicode_ascii_hex_digit/1-2’ ‘unicode_other_alphabetic/1-2’
     ‘unicode_ideographic/1-2’ ‘unicode_diacritic/1-2’
     ‘unicode_extender/1-2’ ‘unicode_other_lowercase/1-2’
     ‘unicode_other_uppercase/1-2’ ‘unicode_noncharacter_code_point/1-2’
     ‘unicode_other_grapheme_extend/1-2’
     ‘unicode_ids_binary_operator/1-2’
     ‘unicode_ids_trinary_operator/1-2’ ‘unicode_radical/1-2’
     ‘unicode_unified_ideograph/1-2’
     ‘unicode_other_default_ignorable/1-2’ ‘unicode_deprecated/1-2’
     ‘unicode_soft_dotted/1-2’ ‘unicode_logical_order_exception/1-2’
     ‘unicode_other_id_start/1-2’ ‘unicode_other_id_continue/1-2’
     ‘unicode_sterm/1-2’ ‘unicode_variation_selector/1-2’
     ‘unicode_pattern_white_space/1-2’ ‘unicode_pattern_syntax/1-2’

   - Dependencies: files in the ‘unicode_prop_list’ directory


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_range_scripts pl,  Next: unicode_script_extensions pl,  Prev: unicode_prop_list pl,  Up: Files and API Summary

6.55.9.29 ‘unicode_range_scripts.pl’
....................................

   - Provides: ‘unicode_range_script/3’ ‘unicode_script/2’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_script_extensions pl,  Next: unicode_scripts pl,  Prev: unicode_range_scripts pl,  Up: Files and API Summary

6.55.9.30 ‘unicode_script_extensions.pl’
........................................

   - Provides: ‘unicode_script_extension/2-3’

   - Dependencies: ‘unicode_scripts.pl’


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_scripts pl,  Next: unicode_special_casing pl,  Prev: unicode_script_extensions pl,  Up: Files and API Summary

6.55.9.31 ‘unicode_scripts.pl’
..............................

   - Provides: ‘unicode_script/6’ ‘unicode_script_category/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_special_casing pl,  Next: unicode_unihan_variants pl,  Prev: unicode_scripts pl,  Up: Files and API Summary

6.55.9.32 ‘unicode_special_casing.pl’
.....................................

   - Provides: ‘unicode_special_casing/5’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_unihan_variants pl,  Next: unicode_version pl,  Prev: unicode_special_casing pl,  Up: Files and API Summary

6.55.9.33 ‘unicode_unihan_variants.pl’
......................................

   - Provides: ‘unicode_unihan_variant/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: unicode_version pl,  Prev: unicode_unihan_variants pl,  Up: Files and API Summary

6.55.9.34 ‘unicode_version.pl’
..............................

   - Provides: ‘unicode_version/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.96.0.info,  Node: union_find,  Next: uuid,  Prev: unicode_data,  Up: Libraries

6.56 ‘union_find’
=================

This library implements a union-find data structure.  This structure
tracks a set of elements partitioned into a number of disjoint
(non-overlapping) subsets.  It provides fast operations to add new sets,
to merge existing sets, and to determine whether elements are in the
same set.  This implementation of the union-find algorithm provides the
following features:

   - Path compression: Path compression flattens the structure of the
     tree by making every node point to the root whenever a find
     predicate is used on it.

   - Union by rank: Union predicates always attach the shorter tree to
     the root of the taller tree.  Thus, the resulting tree is no taller
     than the original unless they were of equal height, in which case
     the resulting tree is taller by one node.

For a general and extended discussion on this data structure, see e.g.

‘https://en.wikipedia.org/wiki/Disjoint-set_data_structure’

* Menu:

* API documentation: API documentation<69>.
* Loading: Loading<70>.
* Testing: Testing<61>.
* Usage: Usage<40>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<69>,  Next: Loading<70>,  Up: union_find

6.56.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#union-find’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<70>,  Next: Testing<61>,  Prev: API documentation<69>,  Up: union_find

6.56.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(union_find(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<61>,  Next: Usage<40>,  Prev: Loading<70>,  Up: union_find

6.56.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(union_find(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Usage<40>,  Prev: Testing<61>,  Up: union_find

6.56.4 Usage
------------

An usage example is Kruskal’s algorithm, a minimum-spanning-tree
algorithm which finds an edge of the least possible weight that connects
any two trees in the forest.  It is a greedy algorithm in graph theory
as it finds a minimum spanning tree for a connected weighted graph by
adding increasing cost arcs at each step.

     :- object(kruskal).

         :- public(kruskal/2).

         :- uses(union_find, [
             new/2, find/4, union/4
         ]).

         kruskal(g(Vertices-Edges), g(Vertices-Tree)) :-
             new(Vertices, UnionFind),
             keysort(Edges, Sorted),
             kruskal(UnionFind, Sorted, Tree).

         kruskal(_, [], []).
         kruskal(UnionFind0, [Edge| Edges], [Edge| Tree]) :-
             Edge = _-(Vertex1, Vertex2),
             find(UnionFind0, Vertex1, Root1, UnionFind1),
             find(UnionFind1, Vertex2, Root2, UnionFind2),
             Root1 \== Root2,
             !,
             union(UnionFind2, Vertex1, Vertex2, UnionFind3),
             kruskal(UnionFind3, Edges, Tree).
         kruskal(UnionFind, [_| Edges], Tree) :-
             kruskal(UnionFind, Edges, Tree).

     :- end_object.

Sample query:

     | ?- kruskal::kruskal(g([a,b,c,d,e,f,g]-[7-(a,b), 5-(a,d), 8-(b,c), 7-(b,e), 9-(b,d), 5-(c,e), 15-(d,e), 6-(d,f), 8-(e,f), 9-(e,g), 11-(f,g)]), Tree).

     Tree = g([a,b,c,d,e,f,g]-[5-(a,d),5-(c,e),6-(d,f),7-(a,b),7-(b,e),9-(e,g)])
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: uuid,  Next: zippers,  Prev: union_find,  Up: Libraries

6.57 ‘uuid’
===========

This library implements a Universally Unique Identifier (UUID)
generator.  Currently only version 1 and version 4 UUIDs are supported.
For reference material, see e.g.

‘https://en.wikipedia.org/wiki/Universally_unique_identifier’

Some backends provide time stamps with low granularity (e.g., seconds
but not milliseconds or nanoseconds).  To compensate, the generation of
version 1 UUIDs uses 14 random bits for the clock sequence.

The generation of version 4 UUIDs uses the ‘/dev/urandom’ random number
generator when available.  This includes macOS, Linux, *BSD, and other
POSIX operating-systems.  On Windows, a pseudo-random generator is used,
but randomized using the current wall time.

UUIDs can be generated as atoms, lists of characters, or lists of
character codes.

See also the ‘ids’ and ‘ulid’ libraries.

* Menu:

* API documentation: API documentation<70>.
* Loading: Loading<71>.
* Testing: Testing<62>.
* Generating version 1 UUIDs::
* Generating version 4 UUIDs::
* Generating the null UUID::


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<70>,  Next: Loading<71>,  Up: uuid

6.57.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#uuid’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<71>,  Next: Testing<62>,  Prev: API documentation<70>,  Up: uuid

6.57.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(uuid(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<62>,  Next: Generating version 1 UUIDs,  Prev: Loading<71>,  Up: uuid

6.57.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(uuid(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Generating version 1 UUIDs,  Next: Generating version 4 UUIDs,  Prev: Testing<62>,  Up: uuid

6.57.4 Generating version 1 UUIDs
---------------------------------

By default, version 1 UUIDs are generated as atoms.  For example:

     | ?- uuid::uuid_v1([0xf2,0xd1,0x90,0x94,0xdc,0x4b], UUID).
     UUID = '00a66fc0-82cf-11eb-bc83-f2d19094dc4b'
     yes

To generate a UUID using a list of characters representation, use
instead the ‘uuid/1’ parametric object:

     | ?- uuid(chars)::uuid_v1([0xf2,0xd1,0x90,0x94,0xdc,0x4b], UUID).
     UUID = ['0','0',d,e,'9','0',c,'0',-,'8','2',c,f,-,'1','1',e,b,-,
             a,'9','8','5',-,f,'2',d,'1','9','0','9','4',d,c,'4',b]
     yes

Similarly, to get a UUID using a list of character codes representation:

     | ?- uuid(codes)::uuid_v1([0xf2,0xd1,0x90,0x94,0xdc,0x4b], UUID).
     UUID = [48,48,52,99,99,54,99,48,45,56,50,99,102,45,49,49,101,98,45,
             98,57,102,52,45,102,50,100,49,57,48,57,52,100,99,52,98]
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Generating version 4 UUIDs,  Next: Generating the null UUID,  Prev: Generating version 1 UUIDs,  Up: uuid

6.57.5 Generating version 4 UUIDs
---------------------------------

By default, version 4 UUIDs are generated as atoms.  For example:

     | ?- uuid::uuid_v4(UUID).
     UUID = '1c652782-69c5-4252-88c8-09e576a44db5'
     yes

To generate a UUID using a list of characters representation, use
instead the ‘uuid/1’ parametric object:

     | ?- uuid(chars)::uuid_v4(UUID).
     UUID = [d,'3',d,'3','3','5','1','3',-,'8','1',e,c,-,'4',d,'2','6',-,
             '9',f,'2','2',-,e,d,'9','5',e,'0','0',e,'1','5','7','0']
     yes

Similar to get a UUID using a list of character codes representation:

     | ?- uuid(codes)::uuid_v4(UUID).
     UUID = [102,97,52,54,57,98,100,50,45,51,57,54,51,45,52,97,100,55,45,
             98,50,50,55,45,101,100,52,99,56,55,99,54,53,55,102,98]
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: Generating the null UUID,  Prev: Generating version 4 UUIDs,  Up: uuid

6.57.6 Generating the null UUID
-------------------------------

A predicate is also provided that returns the null UUID:

     | ?- uuid::uuid_null(UUID).
     UUID = '00000000-0000-0000-0000-000000000000'
     yes


File: TheLogtalkHandbook-3.96.0.info,  Node: zippers,  Prev: uuid,  Up: Libraries

6.58 ‘zippers’
==============

This library implements zippers over lists.

* Menu:

* API documentation: API documentation<71>.
* Loading: Loading<72>.
* Testing: Testing<63>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<71>,  Next: Loading<72>,  Up: zippers

6.58.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#zippers’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<72>,  Next: Testing<63>,  Prev: API documentation<71>,  Up: zippers

6.58.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(zippers(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<63>,  Prev: Loading<72>,  Up: zippers

6.58.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(zippers(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Ports,  Next: Contributions,  Prev: Libraries,  Up: Top

7 Ports
*******

The documentation of each port can also be found in the port directory
in the ‘NOTES.md’ file.

* Menu:

* fcube::
* metagol::
* toychr::


File: TheLogtalkHandbook-3.96.0.info,  Node: fcube,  Next: metagol,  Up: Ports

7.1 ‘fcube’
===========

This folder contains a Logtalk port of FCube: An Efficient Prover for
Intuitionistic Propositional Logic available from:

     https://www.vidal-rosset.net/fCube/

The port includes portability changes (notably, operator names) plus
changes to use an ordered representation for sets.  Also some code
formatting changes for Logtalk coding guidelines.

The port tests are adapted from the examples available from the web page
above.

To load this port and for sample queries, please see the ‘SCRIPT.txt’
file.

For more information about FCube, see the following paper:

     @InProceedings{10.1007/978-3-642-16242-8_21,
         author="Ferrari, Mauro and Fiorentini, Camillo and Fiorino, Guido",
         editor="Ferm{\"u}ller, Christian G. and Voronkov, Andrei",
         title="fCube: An Efficient Prover for Intuitionistic Propositional Logic",
         booktitle="Logic for Programming, Artificial Intelligence, and Reasoning",
         year="2010",
         publisher="Springer Berlin Heidelberg",
         address="Berlin, Heidelberg",
         pages="294--301",
         isbn="978-3-642-16242-8"
     }

For sample queries, please see the ‘SCRIPT.txt’ file.

* Menu:

* API documentation: API documentation<72>.
* Loading: Loading<73>.
* Testing: Testing<64>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<72>,  Next: Loading<73>,  Up: fcube

7.1.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#fcube’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<73>,  Next: Testing<64>,  Prev: API documentation<72>,  Up: fcube

7.1.2 Loading
-------------

To load all entities in this port, load the ‘loader.lgt’ file:

     | ?- logtalk_load(fcube(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<64>,  Prev: Loading<73>,  Up: fcube

7.1.3 Testing
-------------

To test this port predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(fcube(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: metagol,  Next: toychr,  Prev: fcube,  Up: Ports

7.2 ‘metagol’
=============

This folder contains a Logtalk port of ‘metagol’, an inductive logic
programming (ILP) system based on meta-interpretive learning available
from:

     https://github.com/metagol/metagol

See the original code git repo for details and bibliography on Metagol
and ILP.

The port allows any number of datasets to be loaded simultaneously with
per-dataset learning options.  A dataset is simply wrapped in an object
that extends and is expanded by the ‘metagol’ object as illustrated by
the ported examples.

Both the original code and the port requires the coroutining ‘when/2’
predicate, which is only available in some backend Prolog systems.  The
port currently supports ECLiPSe, XVM, SICStus Prolog, SWI-Prolog, and
YAP. It can be used on both POSIX and Windows operating-systems.

The examples are ported from the original Metagol distribution.  Some of
the examples are taken from the following paper (with the original
Prolog examples source code files made available by MystikNinja):

     @article{DBLP:journals/jair/EvansG18,
         author    = {Richard Evans and Edward Grefenstette},
         title     = {Learning Explanatory Rules from Noisy Data},
         journal   = {J. Artif. Intell. Res.},
         volume    = {61},
         pages     = {1--64},
         year      = {2018},
         url       = {https://doi.org/10.1613/jair.5714},
         doi       = {10.1613/jair.5714},
         timestamp = {Mon, 21 Jan 2019 15:01:17 +0100},
         biburl    = {https://dblp.org/rec/bib/journals/jair/EvansG18},
         bibsource = {dblp computer science bibliography, https://dblp.org}
     }

The paper can be downloaded at

     https://arxiv.org/pdf/1711.04574.pdf

For sample queries, please see the ‘SCRIPT.txt’ file.

* Menu:

* API documentation: API documentation<73>.
* Loading: Loading<74>.
* Testing: Testing<65>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<73>,  Next: Loading<74>,  Up: metagol

7.2.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#metagol’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<74>,  Next: Testing<65>,  Prev: API documentation<73>,  Up: metagol

7.2.2 Loading
-------------

To load all entities in this port, load the ‘loader.lgt’ file:

     | ?- logtalk_load(metagol(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<65>,  Prev: Loading<74>,  Up: metagol

7.2.3 Testing
-------------

To test this port predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(metagol(tester)).

There are three lengthy tests that only run when the tests are being run
manually instead of automatically.


File: TheLogtalkHandbook-3.96.0.info,  Node: toychr,  Prev: metagol,  Up: Ports

7.3 ‘toychr’
============

This folder contains a Logtalk port of ToyCHR, a reference
implementation of Constraint Handling Rules (CHR) available from:

     https://www.comp.nus.edu.sg/~gregory/toychr/

The port is work in progress and includes significant modifications to
the original code:

   - Instead of compiling ‘.chr’ files, it uses the term-expansion
     mechanism, by defining ‘toychrdb’ as a hook object, to support
     writing rules inside objects and categories.  As a consequence, the
     original ‘chr_compile/1’ is not available.

   - The port is portable and should run on all supported backends.

The port also includes examples ported from the SWI-Prolog CHR package
examples and documentation.  These examples are ported using the same
license of the original code (BSD-2-Clause).

For sample queries, please see the ‘SCRIPT.txt’ file.

* Menu:

* API documentation: API documentation<74>.
* Loading: Loading<75>.
* Testing: Testing<66>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<74>,  Next: Loading<75>,  Up: toychr

7.3.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#toychr’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<75>,  Next: Testing<66>,  Prev: API documentation<74>,  Up: toychr

7.3.2 Loading
-------------

To load all entities in this port, load the ‘loader.lgt’ file:

     | ?- logtalk_load(toychr(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<66>,  Prev: Loading<75>,  Up: toychr

7.3.3 Testing
-------------

To test this port predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(toychr(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Contributions,  Next: Glossary,  Prev: Ports,  Up: Top

8 Contributions
***************

The documentation of contribution can also be found in the contribution
directory in the ‘NOTES.md’ file.

* Menu:

* flags::
* iso8601::
* pddl_parser::
* verdi_neruda::
* xml_parser::


File: TheLogtalkHandbook-3.96.0.info,  Node: flags,  Next: iso8601,  Up: Contributions

8.1 ‘flags’
===========

Flags was developed at Katholieke Universiteit Leuven

SPDX-FileCopyrightText: 2010 Katholieke Universiteit Leuven
SPDX-License-Identifier: Artistic-2.0

     Contributions to this file:
     Author: Theofrastos Mantadelis
     Suggestions: Paulo Moura
     Version: 1
     Date: 27/11/2010

* Menu:

* API documentation: API documentation<75>.
* Loading: Loading<76>.
* Testing: Testing<67>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<75>,  Next: Loading<76>,  Up: flags

8.1.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#flags’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<76>,  Next: Testing<67>,  Prev: API documentation<75>,  Up: flags

8.1.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     ?- logtalk_load(flags(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<67>,  Prev: Loading<76>,  Up: flags

8.1.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(flags(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: iso8601,  Next: pddl_parser,  Prev: flags,  Up: Contributions

8.2 ‘iso8601’
=============

ISO 8601 (and European civil calendar) compliant library of date and
time (clock) related predicates.  That is, an ISO 8601 handler.

Author: Daniel L. Dudley Created: 2004-02-18

Modified: 2014-09-26 (to use the library “os” object to get the current
date)

* Menu:

* API documentation: API documentation<76>.
* Loading: Loading<77>.
* Testing: Testing<68>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<76>,  Next: Loading<77>,  Up: iso8601

8.2.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#iso8601’ link in a web browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<77>,  Next: Testing<68>,  Prev: API documentation<76>,  Up: iso8601

8.2.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(iso8601(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<68>,  Prev: Loading<77>,  Up: iso8601

8.2.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(iso8601(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: pddl_parser,  Next: verdi_neruda,  Prev: iso8601,  Up: Contributions

8.3 ‘pddl_parser’
=================

     PDDL 3.0 parser
     Release 1.0

Copyright (c) 2011 Robert Sasak.  All Rights Reserved.  This is free
software.  You can redistribute it and/or modify it under the terms of
the “Artistic License 2.0” as published by The Perl Foundation.  Consult
the “LICENSE.txt” file for details.

This PDDL 3.0 file parser converts PDDL files to Logtalk/Prolog friendly
syntax.  For example:

     PDDL         Prolog
     (on ?x ?y)   on(?x, ?y)

Syntax sugar: op(200, fy, ?).

For whole example check the “pddl.lgt” file for usage and example
output.

* Menu:

* API documentation: API documentation<77>.
* Loading: Loading<78>.
* Testing: Testing<69>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<77>,  Next: Loading<78>,  Up: pddl_parser

8.3.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#pddl_parser’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<78>,  Next: Testing<69>,  Prev: API documentation<77>,  Up: pddl_parser

8.3.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     ?- logtalk_load(pddl_parser(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<69>,  Prev: Loading<78>,  Up: pddl_parser

8.3.3 Testing
-------------

The provided unit tests are based on a collection of problem set files
from International Planning Competition 2008.  In order to run all unit
tests from the parser’s directory type:

     ?- logtalk_load(tester).

Or from any directory by typing:

     ?- logtalk_load(pddl_parser(tester)).

Some of the unit tests fail in some Prolog compilers due to limitations
to the maximum arity of a term.


File: TheLogtalkHandbook-3.96.0.info,  Node: verdi_neruda,  Next: xml_parser,  Prev: pddl_parser,  Up: Contributions

8.4 ‘verdi_neruda’
==================

     Verdi Neruda - Meta-interpreter collection for Prolog.
     Release 1.0

Copyright (c) 2010 Victor Lagerkvist.  All Rights Reserved.  Verdi
Neruda is free software.  You can redistribute it and/or modify it under
the terms of the simplified BSD license.

CONTENTS

  1. License

  2. About

  3. Verdi Neruda web site

  4. Installation and running

  5. Examples

  6. Authors

  7. LICENSE

Copyright 2010 Victor Lagerkvist.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the
     distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ‘’AS IS’’ AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation
are those of the authors and should not be interpreted as representing
official policies, either expressed or implied, of the copyright
holders.

  2. ABOUT

Verdi Neruda is a meta-interpreter collection for Prolog.  Or, to be
more precise, for a Prolog like language.  Or, to be pedantically
precise to the point that you are annoying people, it’s not really a
meta-interpreter collection at all since the interpreters themselves
aren’t interpreting the language that they are written in.  Let’s just
say that it is a collection of interpreters for a logic programming
language very much like pure Prolog with negation as finite failure.

Verdi Neruda is written entirely in Logtalk and compatible with most
major Prolog systems.  The name is sadly not a subtle wordplay or an
acronym, but was generated by a computer with the help of a soundex
algorithm.  The purpose of the interpreter suite was to compare top-down
methods to bottom-up methods and how resolution tree search rules
affected performance and completeness.  In the top-down family we find
such interpreters as the long-time standing champion depth-first, its
slow but orderly brother breadth-first and the youngster iterative
deepening.  A best-first framework can be found a stone throw away.
With it it’s possible to define interpreters that use greedy best-first
search as well as A* search.

In the bottom-up camp we find an interpreter that uses a semi naive
fixpoint construction.  Since bottom-up interpreters by their very
nature are not goal oriented a transformation technique called magic
transformation is used on logic programs before any inferences are made.
This technique allows the interpreter to only generate the facts that a
top-down interpreter would have used on the same logic program.

A shell akin to a Prolog top loop is also included.  It has commands
both for proving goals with an interpreter of choice and for
benchmarking logical inferences.  If Verdi Neruda is run with a Prolog
system that supports statistics/2 it’s possible to obtain statistics
such as CPU-time as well.

  3. VERDI NERUDA WEB SITE

Visit the Verdi Neruda GitHub www-page at:

‘https://github.com/Joelbyte/verdi-neruda’

  4. INSTALLATION AND RUNNING

Verdi Neruda requires Logtalk 2.40.0 or a later version.

To use the snapshot of Verdi Neruda bundled with Logtalk:

   - Start Logtalk.

   - Type ‘{verdi_neruda(loader)}.’ (Including ‘.’).

To use the latest version of Verdi Neruda, fetch the latest source code,
either as an archive or from the git repository, extract it to a
directory of your choice, and:

   - Start Logtalk from that directory.

   - Type ‘{loader}.’ (Including ‘.’).  If everything went according to
     the plan you should be greeted by the welcoming message.  If you
     replace the bundled version with the new one, you can use in
     alternative the steps above.

  5. EXAMPLES

Follow the previous instructions to get everything up and running.
First we’re going to run some predefined programs in the included
databases.  Begin by typing ‘databases.’ from the shell - this should
print a list of the currently loaded databases.  The demo database
‘demodb’ should be included in the list.  Next type ‘listing(demodb).’
to print the contents of the database.  The output should look something
like:

     append([],A,A) if
         true.
     append([A|B],C,[A|D]) if
         append(B,C,D).
     .
     .
     .

Which means that the ‘append/3’ program is loaded and ready for action.
Next we need to decide which interpreter to use.  Fortunately the shell
does not leave much to the imagination - as might be expected, the
‘interpreters.’ command prints the currently loaded interpreters.  The
list should look like:

     dfs_interpreter
     bfs_interpreter
     iddfs_interpreter(A)
     bup_interpreter
     a_star_interpreter(A)

The variables means that the interpreters are parametric objects and
that additional information is needed in order to run them.  The
iddfs-interpreter needs to know the increment and the A*-interpreter
needs to know what weight should be used when calculating the cost of
nodes.  To start with let’s use the dfs-interpreter and do something
exciting, namely appending two lists!

     prove(dfs_interpreter, append([a,b], [c,d], Xs), demodb).

The prove command takes three arguments.  The first is a interpreter,
the second the goal that shall be proved and the last the database that
the clauses are derived from.

To accomplish the same thing with the iddfs-interpreter with an
increment of 1 we need only type

     prove(iddfs_interpreter(1), append([a,b], [c,d], Xs), demodb).

The shell also has support for counting logical inferences.  To compare
the dfs- and iddfs-interpreter with the append program we could write:

     benchmark(dfs_interpreter, append([a,b,c,d],[e,f], Xs), demodb).  ->
     dfs_interpreter inferences: 5

     benchmark(iddfs_interpreter(1), append([a,b,c,d],[e,f], Xs), demodb).
     -> iddfs_interpreter(1) inferences: 15

For more information regarding the built in shell commands consult the
‘help.’ command.

  6. AUTHORS

The bulk of Verdi Neruda was written by Victor Lagerkvist during his
bachelor thesis at Linköping university in the spring of 2010.  Paulo
Moura also helped a great deal during the later stages of development,
especially with regards to compatibility between various Prolog systems.


File: TheLogtalkHandbook-3.96.0.info,  Node: xml_parser,  Prev: verdi_neruda,  Up: Contributions

8.5 ‘xml_parser’
================

This folder contains a Logtalk version of John Fletcher’s Prolog XML
parser:

‘https://binding-time.co.uk/index.php/Parsing_XML_with_Prolog’

For a detailed description of this XML parser, please see the comments
in the ‘xml.lgt’ source file or convert the automatically generated
documentation to HTML or PDF. For sample queries, please see the
‘SCRIPT.txt’ file.

See the copyright and license information on the contributed files for
usage and distributions conditions.

* Menu:

* API documentation: API documentation<78>.
* Loading: Loading<79>.
* Testing: Testing<70>.
* Known issues: Known issues<18>.


File: TheLogtalkHandbook-3.96.0.info,  Node: API documentation<78>,  Next: Loading<79>,  Up: xml_parser

8.5.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#xml_parser’ link in a web
browser.


File: TheLogtalkHandbook-3.96.0.info,  Node: Loading<79>,  Next: Testing<70>,  Prev: API documentation<78>,  Up: xml_parser

8.5.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(xml_parser(loader)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Testing<70>,  Next: Known issues<18>,  Prev: Loading<79>,  Up: xml_parser

8.5.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(xml_parser(tester)).


File: TheLogtalkHandbook-3.96.0.info,  Node: Known issues<18>,  Prev: Testing<70>,  Up: xml_parser

8.5.4 Known issues
------------------

When using GNU Prolog as the backend compiler, you may need to to use a
larger default global stack size (see the GNU Prolog documentation on
the environment variable ‘GLOBALSZ’).


File: TheLogtalkHandbook-3.96.0.info,  Node: Glossary,  Next: Index<2>,  Prev: Contributions,  Up: Top

9 Glossary
**********

abstract class

     A *note class: bd1. that cannot be instantiated by sending it a
     message.  Usually used to contain common predicates that are
     inherited by other classes.

abstract method

     A *note method: bd3. implementing an algorithm whose step
     corresponds to calls to methods defined in the descendants of the
     object (or *note category: bd4.) containing it.

adapter file

     A Prolog source file defining a minimal abstraction layer between
     the Logtalk compiler/runtime and a specific *note backend Prolog
     compiler: 34.

after method

     The *note predicate definition: 58. used to answer an ‘after’
     event.

ancestor

     A *note class: bd1. or a parent *note prototype: bd7. that
     contributes (via inheritance) to the definition of an object.  For
     class-based hierarchies, the ancestors of an instance are its
     class(es) and all the superclasses of its class(es).  For
     prototype-based hierarchies, the ancestors of a prototype are its
     parent(s) and the ancestors of its parent(s).

around method

     An overriding definition for a predicate that calls additional
     goals before and after a call to the overriden predicate
     definition.

backend Prolog compiler

     The Prolog compiler that is used to host and run Logtalk and that
     is called for compiling the intermediate Prolog code generated by
     the Logtalk compiler when compiling source files.

before method

     The *note predicate definition: 58. used to answer a ‘before’
     event.

built-in method

     A predefined *note method: bd3. that can be called from within any
     object or *note category: bd4.  I.e.  built-in methods are built-in
     object and category predicates.  Built-in methods cannot be
     redefined.

built-in predicate

     A predefined predicate that can be called from anywhere.  Built-in
     predicates can be redefined within *note objects: 533. and *note
     categories: bd4.

category

     A set of *note predicates directives: bdc. and clauses that can be
     (virtually) imported by any object.  Categories support composing
     objects using fine-grained units of code reuse and also *note hot
     patching: 10b. of existing objects.  A category should be
     functionally-cohesive, defining a single functionality.

class

     An *note object: 533. that specializes another object, interpreted
     as its *note superclass: 60.  A class defines the common predicates
     of a set of objects that instantiate it.  An object can also be
     interpreted as a class when it instantiates itself.

clause reference

     An opaque term that uniquely identifies a clause.  Provided by some
     backends via alternative database built-in predicates.

closed-world assumption

     The assumption that what cannot be proved true is false.
     Therefore, sending a *note message: 43. corresponding to a
     'declared' but not 'defined' predicate, or calling a declared
     predicate with no clauses, fails.  But messages or calls to
     undeclared predicates generate an error.

closure

     A callable term (i.e., an atom or a compound term) passed to a
     *note meta-predicate: 52. call where it is extended with additional
     arguments to form a goal called by the meta-predicate.

coinductive predicate

     A predicate whose calls are proved using greatest fixed point
     semantics.  Coinductive predicates allows reasoning about infinite
     rational entities such as cyclic terms and ω-automata.

complementing category

     A category used for *note hot patching: 10b. an existing object (or
     a set of objects).

component

     A unique atom or compound term template identifying a library,
     tool, application, or application sub-system.  Component names are
     notably used by the message printing and question asking
     mechanisms.  Compound terms are used instead of atoms when
     parameterization is required.

debug handler

     An object or category that defines clauses for the multifile
     predicates that handle the trace and debug events generated by the
     runtime.

directive

     A source file term that affects the interpretation of source code.
     Directives use the ‘(:-)/1’ prefix operator as functor.

discontiguous predicate

     A predicate whose clauses are not contiguous in a *note source
     file: 61c.  I.e.  a predicate whose clauses are mixed with clauses
     for other predicates.

doclet file

     A *note source file: 61c. whose main purpose is to generate
     documentation for a *note library: 6e. or an application.

doclet object

     An object specifying the steps necessary to (re)generate the API
     documentation for a project.  See the *note doclet: 32d. and *note
     lgtdoc: 322. tools for details.

dynamic binding

     Runtime lookup of a *note predicate declaration: 57. and *note
     predicate definition: 58. to verify the validity of a *note
     message: 43. (or a *note super call: 115.) and find the predicate
     definition that will be used to answer the message (or the super
     call).  Also known as 'late binding'.  See also *note static
     binding: 35.

dynamic entity

     See *note entity: be1.

dynamic predicate

     A predicate whose clauses can be dynamically added or retracted at
     runtime.

early binding

     See *note static binding: 35.

encapsulation

     The hiding of an object implementation.  This promotes software
     reuse by isolating the object clients from its implementation
     details.  Encapsulation is enforced in Logtalk by using *note
     predicate scope directives: 1e4.

entity

     Generic name for Logtalk compilation units: *note objects: 533,
     *note categories: bd4, and *note protocols: 59.  Entities share a
     single namespace (i.e., entity *note identifiers: be4. must be
     unique) and can be static (the default) or dynamic.  Static
     entities are defined in source files.  Dynamic entities can also be
     defined in source files but are usually created and abolished at
     runtime using the language built-in predicates.

entity alias

     An alternative name for an entity.  Entity aliases can be defined
     using the *note uses/1: 4a. and *note use_module/1: 4c. directives.
     Entity aliases can be used to improve code clarity by using
     alternative names that are more meaningful in the calling context,
     to bind parametric entity parameters, and to simplify experimenting
     with alternative entities implementing the same protocol.

entity directive

     A directive that affects how Logtalk *note entities: be1. are used
     or compiled.

event

     The sending of a *note message: 43. to an object.  An event can be
     expressed as an ordered tuple: ‘(Event, Object, Message, Sender)’.
     Logtalk distinguishes between the sending of a message — ‘before’
     event — and the return of control to the sender — ‘after’ event.

expansion workflow

     A sequence of *note term-expansion: be8. or *note goal-expansion:
     be9. steps where each step is usually defined using a *note hook
     object: 39e. or a combination of hook objects.

flaky test

     A test that can unpredictably succeed, fail, or throw an error and
     thus can yield different results when repeated without any code
     changes.  Can result from, e.g., race conditions or dependencies on
     external resources outside user control.

goal-expansion

     The transformation of a goal into another goal, defined by clauses
     for the *note goal_expansion/2: fd. predicate that is declared by
     the expanding(1) built-in protocol.  Goal-expansion is usually
     recursively applied at compile time until a fixed-point is reached
     (i.e., until the result of an expansion cannot be further
     expanded).  See also *note term-expansion: be8. and *note expansion
     workflow: be7.

grammar rule

     An alternative notation for predicates used to parse or generate
     sentences in some language.  This notation hides the arguments used
     to pass the sequences of tokens being processed, thus simplifying
     the representation of grammars.  Grammar rules are represented
     using as functor the infix operator ‘(-->)/2’ instead of the
     ‘(:-)/2’ operator used with predicate clauses.

grammar rule non-terminal

     A syntactic category of words or phrases.  A non-terminal is
     identified by its 'non-terminal indicator', i.e.  by its name and
     number of arguments using the notation ‘Name//Arity’.

grammar rule terminal

     A word or basic symbol of a language.

homoiconic

     A property of programming languages where 'code' and 'data' use the
     same representation.  Logtalk (and Prolog) are examples of
     homoiconic programming languages.  A Logtalk program is a set of
     terms (clauses and directives) that can be handled as 'data' by
     e.g.  the *note term-expansion: be8. mechanism.

hook object

     An object, implementing the expanding(2) built-in protocol,
     defining *note term-expansion: be8. and *note goal-expansion: be9.
     predicates, used in the compilation of Logtalk or Prolog source
     files.  A hook object can be specified using the *note hook: fe.
     flag.  It can also be specified using a *note set_logtalk_flag/2:
     50. directive in the source files to be expanded.

hook predicate

     A predicate, usually declared *note multifile: 16b, that allows the
     user to customize another predicate or provide alternative
     definitions for a default predicate definition.

hot patching

     The act of fixing *note entity directives: be5. and predicates or
     adding new entity directives and predicates to loaded *note
     entities: be1. in a running application without requiring access to
     the entities source code or restarting the application.  Achieved
     using *note complementing categories: bdd.

identity

     Property of an *note entity: be1. that distinguishes it from every
     other entity.  The identifier of an entity is its functor (i.e.,
     its name and arity), which must be unique.  Object and *note
     category: bd4. identifiers can be atoms or compound terms.
     Protocol identities must be atoms.  All Logtalk entities (objects,
     protocols, and categories) share the same namespace.

inheritance

     An *note entity: be1. inherits *note predicates directives: bdc.
     and clauses from related entities.  In the particular case of
     objects, when an object extends other object, we have
     prototype-based inheritance.  When an object specializes or
     instantiates another object, we have class-based inheritance.  See
     also *note public inheritance: bee, *note protected inheritance:
     bef, and *note private inheritance: bf0.

instance

     An *note object: 533. that instantiates another object, interpreted
     as its *note class: bd1.  An object may instantiate multiple
     objects (also known as multiple instantiation).

instantiation

     The process of creating a new *note class: bd1. *note instance:
     bf1.  In Logtalk, this does not necessarily imply dynamic creation
     of an object at runtime; an instance may also be defined as a
     static object in a source file.

interface

     See *note protocol: 59.

lambda expression

     A compound term that can be used in place of a goal or *note
     closure: 14f. meta-argument and that abstracts a *note predicate
     definition: 58. by listing its variables and a callable term that
     implements the definition.  Lambda expressions help avoid the need
     of naming and defining auxiliary predicates.

lambda free variable

     A variable that is global to a *note lambda expression: 182.  All
     used global variables must be explicitly listed in a lambda
     expression for well-defined semantics.

lambda parameter

     A term (usually a variable or a non-ground compound term) that is
     local to a *note lambda expression: 182.  All lambda parameters
     must be explicitly enumerated in a lambda expression for
     well-defined semantics.

late binding

     See *note dynamic binding: 36.

library

     A directory containing source files.  See also *note library alias:
     bf5. and *note library notation: 2a8.

library alias

     An atom that can be used as an alias for a *note library: 6e. full
     path.  Library aliases and their corresponding paths can be defined
     using the *note logtalk_library_path/2: 2a7. predicate.  See also
     *note library notation: 2a8.

library notation

     A compound term where the name is a *note library alias: bf5. and
     the single argument is a *note source file: 61c. relative path.
     Use of library notation simplifies compiling and loading source
     files and can make an application easily relocatable by defining an
     alias for the root directory of the application files.

loader file

     A *note source file: 61c. whose main purpose is to load a set of
     source files (possibly with specific compiler flags) and any
     library dependencies.

local predicate

     A predicate that is defined in an object (or in a *note category:
     bd4.) but that is not listed in a *note scope directive: 1e4.
     These predicates behave like private predicates but are invisible
     to the reflection *note built-in methods: bda.  Local predicates
     are usually auxiliary predicates and only relevant to the entity
     where they are defined.

message

     A query sent to an object.  In logical terms, a message can be
     interpreted as a request for proof construction using an object
     database and the databases of related entities.

message lookup

     Sending a message to an object requires a lookup for the *note
     predicate declaration: 57, to check if the message is within the
     scope of the sender, and a lookup for the *note predicate
     definition: 58. that is going to be called to answer the message.
     Message lookup can occur at *note compile: 35. time or at *note
     runtime: 36.

message to self

     A message sent to the object that received the original message
     under processing.  Messages to self require *note dynamic binding:
     36. as the value of self is only know at runtime.

meta-argument

     A predicate argument that is called as a goal, used as a *note
     closure: 14f. to construct a goal that will be called, or that is
     handled in a way that requires awareness of the predicate calling
     context.

meta-interpreter

     A program capable of running other programs written in the same
     language.

meta-predicate

     A predicate with one or more *note meta-arguments: bf6.  For
     example, *note call/1-N: 181. and *note findall/3: 1c0. are
     built-in meta-predicates.

meta-variable

     A variable in a *note meta-argument: bf6. position that is expected
     to be unified with a goal or a closure at runtime.

metaclass

     The *note class: bd1. of a class, when interpreted as an *note
     instance: bf1.  Metaclass instances are themselves classes.
     Metaclasses are optional, except for the root class, and can be
     shared by several classes.

method

     The *note predicate definition: 58. used to answer a *note message:
     43. sent to an object.  Logtalk supports both *note static binding:
     35. and *note dynamic binding: 36. to find which method to run to
     answer a message.  See also *note built-in method: bda.

mocking

     Techniques used to replace dependencies in the code being tested
     with controlled substitutes, simplifying testing.  Can be
     accomplished using, e.g., *note term-expansion: be8, hot patching,
     or message interception.

module

     A Prolog entity characterized by an identity and a set of *note
     predicates directives: bdc. and clauses.  Prolog modules are
     usually static although some Prolog systems allow the creation of
     dynamic modules at runtime.  Prolog modules can be interpreted as
     *note prototypes: bd7.

monitor

     Any object, implementing the monitoring(3) built-in protocol, that
     is notified by the runtime when a spied event occurs.  The spied
     *note events: be6. can be set by the monitor itself or by any other
     object.

multifile predicate

     A predicate whose clauses can be defined in multiple *note
     entities: be1. and *note source files: 61c.  The object or category
     holding the directive without an entity prefix qualifying the
     predicate holds the multifile predicate 'primary declaration',
     which consists of both a *note scope directive: 1e4. and a *note
     multifile/1: 16c. directive for the predicate.

naked meta-variable

     A *note meta-variable: 183. used as the body of a predicate clause
     or grammar rule or used in a cut-transparent argument of a control
     construct.  The “naked” designation highlights that the
     meta-variable is not wrapped by ‘call/1’ or ‘phrase//1’ goals.

object

     An entity characterized by an *note identity: be4. and a set of
     *note predicates directives: bdc. and clauses.  Logtalk objects can
     be either static or dynamic.  Logtalk objects can play the 'role'
     of classes, instances, or prototypes.  The role or roles an object
     plays are a function of its relations with other objects.

object database

     The set of predicates locally defined inside an object.

parameter

     An argument of a parametric object or a parametric category
     identifier.  Parameters are 'logical variables' implicitly shared
     by all the entity directives and predicate clauses.

parameter variable

     A variable used as parameter in a parametric object or a parametric
     category using the syntax ‘_ParameterName_’ (i.e., a variable whose
     name stars and ends with an underscore).  Parameter variables are
     'logical variables' shared by all entity terms.  Occurrences of
     parameter variables in *note entity directives: be5. and clauses
     are implicitly unified with the corresponding entity parameters.

parametric category

     See *note parametric entity: 6a0.

parametric entity

     An *note object: 533. or *note category: bd4. whose *note
     identifier: be4. is a compound term possibly containing free
     variables that can be used to parameterize the entity predicates.
     Parameters are 'logical variables' implicitly shared by all the
     entity clauses.  Note that the identifier of a parametric entity is
     its functor, irrespective of the possible values of its arguments
     (e.g., ‘foo(bar)’ and ‘foo(baz)’ are different parameterizations of
     the same parametric entity, ‘foo/1’).

parametric object

     See *note parametric entity: 6a0.

parametric object proxy

     A compound term (usually represented as a plain Prolog fact) with
     the same name and number of arguments as the identifier of a
     parametric object.

parent

     A *note prototype: bd7. that is extended by another prototype.

polymorphism

     Different objects (and categories) can provide different
     implementations of the same predicate.  The predicate declaration
     can be inherited from a common ancestor, also known as 'subtype
     polymorphism'.  Logtalk implements 'single dispatch' on the
     receiver of a message, which can be described as 'single-argument
     polymorphism'.  As *note message lookup: 37. only uses the
     predicate functor, multiple predicate implementations for different
     types of arguments are possible, also known as 'ad hoc
     polymorphism'.  *note Parametric objects and categories: 6a0.
     enable implementation of 'parametric polymorphism' by using one or
     more parameters to pass object identifiers that can be used to
     parameterize generic predicate definitions.

predicate

     Predicates describe what is true about the application domain.  A
     predicate is identified by its 'predicate indicator', i.e.  by its
     name and number of arguments using the notation ‘Name/Arity’.  See
     also *note built-in predicate: bdb. and *note method: bd3.

predicate alias

     An alternative functor (‘Name/Arity’) for a predicate.  Predicate
     aliases can be defined for any inherited predicate using the *note
     alias/2: 165. directive and for predicates listed in *note uses/2:
     4b. and *note use_module/2: 4d. directives.  Predicate aliases can
     be used to solve inheritance conflicts, to improve code clarity by
     using alternative names that are more meaningful in the calling
     context, and to use a different order of the predicate arguments.

predicate calling context

     The object or category from within a predicate is called (either
     directly or using a control construct such as a message-sending
     control construct).

predicate declaration

     A predicate declaration is composed by a set of *note predicates
     directives: bdc, which must include at least a *note scope
     directive: 1e4.

predicate definition

     The set of clauses for a predicate, contained in an object or
     category.  Predicate definitions can be overridden or specialized
     in descendant entities.

predicate definition context

     The object or category that contains the definition (i.e., clauses)
     for a predicate.

predicate directive

     A directive that specifies a predicate property that affects how
     predicates are called or compiled.

predicate execution context

     The implicit arguments (including *note sender: 399, *note self:
     69, and *note this: 114.) required for the correct execution of a
     predicate call.

predicate scope container

     The object that inherits a *note predicate declaration: 57. from an
     imported *note category: bd4. or an implemented *note protocol: 59.

predicate scope directive

     A directive that declares a predicate by specifying its visibility
     as 'public', 'protected', or 'private'.

predicate shorthand

     A *note predicate alias: ca. that defines a call template, possibly
     using a different name, with a reduced number of arguments by
     hard-coding the value of the omitted arguments in the original call
     template.  Predicate shorthands can be defined using *note uses/2:
     4b. and *note use_module/2: 4d. directives.  They can be used to
     simplify predicate calls and to ensure consistent call patterns
     when some of the arguments always use the same fixed values in the
     calling context.

primary predicate declaration

     See *note multifile predicate: 16b.

private inheritance

     All public and protected predicates are inherited as private
     predicates.  See also *note public inheritance: bee. and *note
     protected inheritance: bef.

private predicate

     A predicate that can only be called from the object that contains
     its *note scope directive: 1e4.

profiler

     A program that collects data about other program performance.

protected inheritance

     All public predicates are inherited as protected.  No scope change
     for protected or private predicates.  See also *note public
     inheritance: bee. and *note private inheritance: bf0.

protected predicate

     A predicate that can only be called from the object containing its
     *note scope directive: 1e4. or from an object that inherits the
     predicate.

protocol

     An entity that contains *note predicate declarations: 57.  A
     predicate is declared using a *note scope directive: 1e4.  It may
     be further specified by additional predicate directives.  Protocols
     support the separation between interface and implementation, can be
     implemented by both objects and categories, and can be extended by
     other protocols.  A protocol should be functionally-cohesive,
     specifying a single functionality.  Also known as 'interface'.

prototype

     A self-describing *note object: 533. that may extend or be extended
     by other objects.  A prototype typically describes a concrete
     object instead of an abstraction of a set of objects.  An object
     with no instantiation or specialization relations with other
     objects is always interpreted as a prototype.

public inheritance

     All inherited predicates maintain their declared scope.  See also
     *note protected inheritance: bef. and *note private inheritance:
     bf0.

public predicate

     A predicate that can be called from any object.

scratch directory

     The directory used to save the intermediate Prolog files generated
     by the compiler when compiling *note source files: 61c.

self

     The object that received the *note message: 43. under processing.

sender

     An object that sends a *note message: 43. to other object.  When a
     message is sent from within a *note category: bd4, the 'sender' is
     the object importing the category on which behalf the message was
     sent.

settings file

     A *note source file: 61c, compiled and loaded automatically by
     default at Logtalk startup, mainly defining default values for
     compiler flags that override the defaults found on the backend
     Prolog compiler *note adapter files: 154.

singleton method

     A *note method: bd3. defined in an *note instance: bf1. itself.
     Singleton methods are supported in Logtalk and can also be found in
     other object-oriented programming languages.

source file

     A text file defining Logtalk and/or Prolog code.  Multiple Logtalk
     entities may be defined in a single source file.  Plain Prolog code
     may be intermixed with Logtalk entity definitions.  Depending on
     the used *note backend Prolog compiler: 34, the text encoding may
     be specified using an *note encoding/1: 298. directive as the first
     term in the first line in the file.

source file directive

     A *note directive: bde. that affects how a *note source file: 61c.
     is compiled.

specialization

     A *note class: bd1. is specialized by defining a new class that
     inherits its predicates and possibly adds new ones.

static binding

     Compile time lookup of a *note predicate declaration: 57. and *note
     predicate definition: 58. when compiling a *note message: 43.
     sending call (or a *note super call: 115.).  Dynamic binding is
     used whenever static binding is not possible (e.g., due to the
     predicate being dynamic or due to lack of enough information at
     compilation time).  Also known as 'early binding'.  See also *note
     dynamic binding: 36.

static entity

     See *note entity: be1.

steadfastness

     A predicate definition is 'steadfast' when it still generates only
     correct answers when called with unexpectedly bound arguments
     (notably, bound output arguments).  Typically, a predicate may not
     be steadfast when output argument unifications can occur before a
     cut in a predicate clause body.

subclass

     A *note class: bd1. that is a specialization, direct or indirectly,
     of another class.  A class may have multiple subclasses.

super call

     Call of an inherited (or imported) *note predicate definition: 58.
     Mainly used when redefining an inherited (or imported) predicate to
     call the overridden definition while making additional calls.
     Super calls preserve *note self: 69. and may require *note dynamic
     binding: 36. if the predicate is dynamic.

superclass

     A *note class: bd1. from which another class is a specialization
     (directly or indirectly via another class).  A class may have
     multiple superclasses.

synchronized predicate

     A synchronized predicate is protected by a mutex ensuring that, in
     a multi-threaded application, it can only be called by a single
     thread at a time.

template method

     See *note abstract method: bd2.

term-expansion

     The transformation of a term (usually a directive or a clause) into
     another term or a list of terms, defined by clauses for the *note
     term_expansion/2: fc. predicate that is declared by the
     expanding(4) built-in protocol.  Term-expansion is usually applied
     at compile time once (i.e., the result of an expansion is not
     further expanded).  See also *note goal-expansion: be9. and *note
     expansion workflow: be7.

test dialect

     Predicate syntax for defining a test.  I.e., the predicate name;
     the number, syntax, and semantics of the predicate arguments; and
     the syntax and semantics of any options.

test outcome

     The expected result of a test goal.  E.g., success, failure, an
     error, deterministic success, success with bindings that subsume or
     are a variant of specific terms.

tester file

     A *note source file: 61c. whose main purpose is to load and a run a
     set of unit tests.

this

     The object that contains the predicate clause under execution.
     When the predicate clause is contained in a *note category: bd4,
     'this' is a reference to the object importing the category on which
     behalf the predicate clause is being used to prove the current
     goal.

threaded engine

     A computing thread running a goal whose solutions can be lazily and
     concurrently computed and retrieved.  A threaded engine also
     supports a term queue that allows passing arbitrary terms to the
     engine.  This queue can be used to pass e.g.  data and new goals to
     the engine.

top-level interpreter shorthand

     Aliases for frequently used built-in predicates such as *note
     logtalk_load/1: 46. and *note logtalk_make/1: 2a0.  These
     shorthands are 'not' part of the Logtalk language and must only be
     used at the top-level interpreter.

visible predicate

     A predicate that is within scope, a locally defined predicate, a
     *note built-in method: bda, a Logtalk built-in predicate, or a
     Prolog built-in predicate.

(Alexiev93) Mutable Object State for Object-Oriented Logic Programming:
A Survey Alexiev, V. Technical Report TR 93-15, Department of Computing
Science, University of Alberta, Canada

(Belli_et_al_92) Object-oriented programming in Prolog: rationale and a
case study Belli, F., Jack, O., Naish, L. Technical Report 92/2,
Department of Electrical and Electronics Engineering, University of
Paderborn, Germany URL:
‘https://lee-naish.github.io/papers/oolp/index.html’

(Block89) An Extended Frame Language Block, F. P., Chan, N. C.
Proceedings OOPLSLA 89(10):151-157, ACM

(Bobrow_et_al_88) Common Lisp Object System Specification Bobrow, D. G.,
Michiel, L. G., Gabriel, R. P., Keene, S. E., Kiczales, G., Moon, D. A.
ACM SIGPLAN Notices(23)

(Bratko90) Prolog Programming for Artificial Intelligence Bratko, I.
Addison Wesley, 2º edition, 1990

(Champaux92) A comparative Study of Object-Oriented Analysis Methods
Champaux, D., Faure, P. Journal of Object-Oriented Programming, Vol.  5,
N.1, 1992

(Clocksin87) Programming in Prolog Clocksin, W.F., Mellish, C.S.
Springer-Verlag, New York, 1987

(Cointe87) Metaclasses are First Class: the ObjVlisp Model Cointe, P.
Proceedings OOPLSLA 87(10):156-167, ACM

(Cordes91) The Literate Programming Paradigm Cordes, D., Brown, M. IEEE
Computer, June 1991:52-61

(Covington94) ISO Prolog: A Summary of the Draft Proposed Standard
Covington, M. A. URL: ‘ftp://ai.uga.edu/pub/prolog.standard/’

(Cox86) Object-Oriented Programming: An Evolutionary Approach Cox, Brad
J. Addison-Wesley Publishing Company, Don Mills, Ontario

(Davison89) Polka: A Parlog Object oriented language Davison, A. Ph.D.
Thesis, Imperial College, London, 1989

(Davison92) A survey of logic programming-based object oriented
languages Davison, A. Tech Report 92/3, Dept.  of Computer Science,
University of Melbourne, Australia URL:
‘https://catalogue.nla.gov.au/catalog/772526’

(Davison93) The deductive and object oriented features of BeBOP Davison,
A. Tech Report 93/6, Dept.  of Computer Science, University of
Melbourne, Australia URL: ‘https://catalogue.nla.gov.au/catalog/1273317’

(Delzanno97) Logic and Object-Oriented Programming in Linear Logic
Delzanno, G. Ph.D. Thesis, University of Pisa, Italy URL:
‘https://opac.bncf.firenze.sbn.it/Record/BVE0136144?uri=BVE0136144’

(Dony90) Exception Handling and Object-Oriented Programming: Towards a
Synthesis Dony, C. Proceedings OOPLSLA 90:322-330, ACM

(Fornarino_et_al_89) An Original Object-Oriented Approach for Relation
Management Fornarino, M., Pinna, A.-M.,Trousse, B. Proceedings of the
4th Portuguese Conference on Artificial Intelligence Lecture Notes in
Artificial Intelligence, Springer-Verlag (390):13-26

(Fromherz93) OL(P): Object Layer for Prolog Fromherz, M. URL:
‘ftp://parcftp.xerox.com/ftp/pub/ol/’

(Fukunaga86) An Experience with a Prolog-based Object-Oriented Language
Fukunaga, K., Hirose, S. Proceedings OOPLSLA 86, 21(11):224-231, ACM

(Goldberg83) Smalltalk-80 The language and its implementation Goldberg,
A., Robson, D. Addison-Wesley Series in Computer Science

(Joy_et_al_00) The Java Language Specification, Second Edition Joy, B.,
Steele, G., Gosling, J., Bracha, G. Addison-Wesley, 2000

(ISO95) ISO/IEC DIS 13211-1 - Programming Language Prolog Part 1:
General Core Joint Technical Committee ISO/IEC JTC 1 URL:
‘https://www.iso.org/standard/21413.html’

(Knuth84) Literate Programming Knuth, D. E. Computer Journal, May 84,
27(2):97-111

(Lieberman86) Using Prototypical Objects to Implement Shared Behaviour
in Object Oriented Systems Lieberman, H. Proceedings OOPLSLA 86:189-214,
ACM

(Maes87) Concepts and Experiments in Computational Reflection Maes, P.
Proceedings OOPLSLA 87, ACM

(McCabe92) Logic and Objects McCabe, F. G. Prentice Hall Series in
Computer Science

(Moon86) Object-Oriented Programming in Flavors Moon, D. Proceedings
OOPLSLA 86:1-8, ACM

(Moss94) Prolog++ The Power of Object-Oriented and Logic Programming
Moss, C. Addison-Wesley International Series in Logic Programming, 1994

(Moura94) Logtalk: Programação Orientada para Objectos em Prolog Moura,
P., Costa, E. 2ª Conferência e Exposição Portuguesa de Tecnologia
Orientada por Objectos 3i Consultores, Lisboa

(Moura99) Porting Prolog: Notes on porting a Prolog program to 22 Prolog
compilers or the relevance of the ISO Prolog standard Moura, P. ALP
Newsletter, Vol.  12/2, May 1999

(Moura00) Logtalk 2.6 Documentation Moura, P. Technical Report DMI
2000/1 University of Beira Interior, Portugal

(Razek92) Combining Objects and Relations Razek, G. Communications of
the ACM, 27(12):66-70

(Rumbaugh87) Relations as Semantic Constructs in an Object-Oriented
Language Rumbaugh, J. Proceedings OOPLSLA 87:466-481, ACM

(Rumbaugh88) Controlling Propagation of Operations using Attributes on
Relations Rumbaugh, J. Proceedings OOPLSLA 88:285-296, ACM

(Schachte95) Efficient Object-Oriented Programming in Prolog Schachte,
P., Saab, G. Logic Programming: Formal Methods and Pratical Applications
Studies in Computer Science and Artificial Intelligence, 11 Elsevier
Science B.V. North-Holland, Amsterdam, 1995

(SICStus95) SICStus Prolog Manual SICStus URL: ‘https://sicstus.sics.se’

(Shan_et_al_93) Is Multiple Inheritance Essential to OOP? (Panel) Shan,
Y., Cargill, T., Cox, B., Cook, W., Loomis, M., Snyder, A. Proceedings
OOPLSLA 93:360-363

(Stefik_et_al_86) Integrating Acess-Oriented Programming into a
Multiparadigm Environment Stefik, M. J., Bobrow, D. G. , Kahn, K. M.
IEEE Software, January 1986:10-18

(Stroustrup86) The C++ Programming Language Stroustrup, B.
Addison-Wesley Series in Computer Science

(Taenzer89) Problems in Object-Oriented Software Reuse Taenzer, D.,
Ganti, M., Podar, S. Proceedings of ECOOP 89 British Computer Society
Workshop Series, Cambridge University Press

(Tanzer95) Remarks on Object-Oriented Modeling of Associations Tanzer,
C. Journal of Object-Oriented Programming, February 1995, SIGS
Publications

(Tanenbaum87) Operating Systems - Design and Implementation Tanenbaum,
A. Prentice-Hall Software Series, 1987

(Welsch89) Reasoning Objects with Dynamic Knowledge Bases Welsch, C.,
Barth, G. Proceedings of the 4th Portuguese Conference on Artificial
Intelligence(390):257-268 Lecture Notes in Artificial Intelligence,
Springer-Verlag, 1989

   ---------- Footnotes ----------

   (1) ../apis/expanding_0.html#expanding-0

   (2) ../apis/expanding_0.html#expanding-0

   (3) ../apis/monitoring_0.html#monitoring-0

   (4) ../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.96.0.info,  Node: Index<2>,  Next: Index,  Prev: Glossary,  Up: Top

10 Index
********


File: TheLogtalkHandbook-3.96.0.info,  Node: Index,  Prev: Index<2>,  Up: Top

Index
*****

[index]
* Menu:

* !/0; Built-in method:                  Logic and control.   (line   8)
* (;;)/1; Control construct:             Examples<2>.         (line  19)
* (;;)/2; Control construct:             Message sending<2>.  (line   8)
* (@)/1; Control construct:              Calling predicates in this.
                                                              (line   8)
* (\+)/1; Built-in method:               Examples<122>.       (line  19)
* (^^)/1; Control construct:             Calling imported and inherited predicates<2>.
                                                              (line   8)
* (<<)/2; Control construct:             Context switching calls.
                                                              (line   8)
* []/1; Control construct:               Message delegation.  (line   8)
* {}/1; Control construct:               Calling external predicates.
                                                              (line   8)
* abolish_category/1; Built-in predicate: Abolishing objects categories and protocols.
                                                              (line   8)
* abolish_events/5; Built-in predicate:  Event handling<2>.   (line   8)
* abolish_object/1; Built-in predicate:  Examples<55>.        (line  16)
* abolish_protocol/1; Built-in predicate: Examples<56>.       (line  17)
* abolish/1; Built-in method:            Database.            (line   8)
* abstract class:                        Glossary.            (line   6)
* abstract method:                       Glossary.            (line  10)
* adapter file:                          Glossary.            (line  16)
* after method:                          Glossary.            (line  22)
* after/3; Built-in method:              Examples<143>.       (line  22)
* alias/2; Directive:                    Predicate directives<2>.
                                                              (line   8)
* always_true_or_false_goals; Flag:      Lint flags.          (line  83)
* ancestor:                              Glossary.            (line  27)
* arithmetic_expressions; Flag:          Lint flags.          (line  96)
* around method:                         Glossary.            (line  36)
* ask_question/5; Built-in method:       Question asking.     (line   8)
* asserta/1; Built-in method:            Examples<114>.       (line  21)
* assertz/1; Built-in method:            Examples<115>.       (line  60)
* backend Prolog compiler:               Glossary.            (line  42)
* bagof/3; Built-in method:              All solutions.       (line   8)
* before method:                         Glossary.            (line  48)
* before/3; Built-in method:             Event handling<3>.   (line   8)
* begin_of_file:                         Hook objects.        (line  89)
* behavioral reflection:                 Black-box view.      (line  18)
* black-box view:                        Transparent-box view.
                                                              (line  30)
* built_in/0; Directive:                 Entity directives.   (line   8)
* built-in method:                       Glossary.            (line  53)
* built-in predicate:                    Glossary.            (line  60)
* call//1-N; Built-in method:            Definite clause grammar rules<2>.
                                                              (line   8)
* call/1-N; Built-in method:             Meta-calls.          (line   8)
* catch/3; Built-in method:              Error handling<2>.   (line   8)
* catchall_catch; Flag:                  Lint flags.          (line 171)
* category:                              Glossary.            (line  66)
* category_property/2; Built-in predicate: Enumerating objects categories and protocols properties.
                                                              (line   8)
* category/1-4; Directive:               Examples<18>.        (line   9)
* class:                                 Glossary.            (line  74)
* clause reference:                      Glossary.            (line  81)
* clause/2; Built-in method:             Examples<116>.       (line  60)
* clean; Flag:                           Other flags.         (line 108)
* closed-world assumption:               Glossary.            (line  86)
* closure:                               Glossary.            (line  94)
* code_prefix; Flag:                     Other flags.         (line  29)
* coinduction; Flag:                     Read-only flags.     (line  88)
* coinductive predicate:                 Glossary.            (line 100)
* coinductive_success_hook/1-2; Built-in method: Coinduction hooks.
                                                              (line   8)
* coinductive/1; Directive:              Examples<30>.        (line  19)
* complementing category:                Glossary.            (line 106)
* complements_object/2; Built-in predicate: Examples<62>.     (line  25)
* complements; Flag:                     Optional features compilation flags.
                                                              (line   6)
* component:                             Glossary.            (line 111)
* conditionals; Flag:                    Lint flags.          (line 163)
* conforms_to_protocol/2-3; Built-in predicate: Examples<61>. (line  25)
* consistency_error/3; Built-in method:  Examples<129>.       (line  23)
* context_switching_calls; Flag:         Optional features compilation flags.
                                                              (line  41)
* context/1; Built-in method:            Execution context.   (line   8)
* create_category/4; Built-in predicate: Creating new objects categories and protocols.
                                                              (line   8)
* create_logtalk_flag/3; Built-in predicate: Examples<98>.    (line  16)
* create_object/4; Built-in predicate:   Examples<52>.        (line  21)
* create_protocol/3; Built-in predicate: Examples<53>.        (line  63)
* current_category/1; Built-in predicate: Enumerating objects categories and protocols.
                                                              (line   8)
* current_event/5; Built-in predicate:   Examples<67>.        (line  17)
* current_logtalk_flag/2; Built-in predicate: Flags.          (line   8)
* current_object/1; Built-in predicate:  Examples<46>.        (line  20)
* current_op/3; Built-in method:         Reflection<2>.       (line   8)
* current_predicate/1; Built-in method:  Examples<111>.       (line  20)
* current_protocol/1; Built-in predicate: Examples<47>.       (line  22)
* debug handler:                         Glossary.            (line 119)
* debug; Flag:                           Other flags.         (line  73)
* define_events/5; Built-in predicate:   Examples<68>.        (line  16)
* deprecated; Flag:                      Lint flags.          (line  58)
* directive:                             Glossary.            (line 125)
* discontiguous predicate:               Glossary.            (line 130)
* discontiguous/1; Directive:            Examples<31>.        (line  17)
* disjunctions; Flag:                    Lint flags.          (line 155)
* doclet file:                           Glossary.            (line 136)
* doclet object:                         Glossary.            (line 141)
* domain_error/2; Built-in method:       Examples<128>.       (line  22)
* duplicated_clauses; Flag:              Lint flags.          (line 146)
* duplicated_directives; Flag:           Lint flags.          (line  69)
* dynamic binding:                       Glossary.            (line 147)
* dynamic entity:                        Glossary.            (line 156)
* dynamic predicate:                     Glossary.            (line 160)
* dynamic_declarations; Flag:            Optional features compilation flags.
                                                              (line  19)
* dynamic/0; Directive:                  Examples<19>.        (line  27)
* dynamic/1; Directive:                  Examples<32>.        (line  13)
* early binding:                         Glossary.            (line 165)
* elif/1; Directive:                     Examples<14>.        (line  42)
* else/0; Directive:                     Examples<15>.        (line  26)
* encapsulation:                         Glossary.            (line 169)
* encoding_directive; Flag:              Read-only flags.     (line  52)
* encoding/1; Directive:                 Source file directives<2>.
                                                              (line   8)
* encodings; Flag:                       Lint flags.          (line 195)
* end_category/0; Directive:             Examples<20>.        (line  15)
* end_object/0; Directive:               Examples<21>.        (line  14)
* end_of_file:                           Hook objects.        (line  88)
* end_protocol/0; Directive:             Examples<22>.        (line  14)
* endif/0; Directive:                    Examples<16>.        (line  30)
* engines; Flag:                         Read-only flags.     (line  67)
* entity:                                Glossary.            (line 176)
* entity alias:                          Glossary.            (line 186)
* entity directive:                      Glossary.            (line 195)
* eos//0; Built-in method:               Examples<146>.       (line  22)
* evaluation_error/1; Built-in method:   Examples<133>.       (line  21)
* event:                                 Glossary.            (line 200)
* events; Flag:                          Optional features compilation flags.
                                                              (line  30)
* existence_error/2; Built-in method:    Examples<130>.       (line  33)
* expand_goal/2; Built-in method:        Examples<152>.       (line  16)
* expand_term/2; Built-in method:        Term and goal expansion<2>.
                                                              (line   8)
* expansion workflow:                    Glossary.            (line 207)
* extends_category/2-3; Built-in predicate: Examples<59>.     (line  19)
* extends_object/2-3; Built-in predicate: Objects categories and protocols relations.
                                                              (line   8)
* extends_protocol/2-3; Built-in predicate: Examples<58>.     (line  19)
* fail/0; Built-in method:               Examples<102>.       (line  15)
* false/0; Built-in method:              Examples<103>.       (line  15)
* findall/3; Built-in method:            Examples<138>.       (line  20)
* findall/4; Built-in method:            Examples<139>.       (line  20)
* flaky test:                            Glossary.            (line 213)
* forall/2; Built-in method:             Examples<140>.       (line  20)
* forward/1; Built-in method:            Message forwarding.  (line   8)
* general; Flag:                         Lint flags.          (line 200)
* goal_expansion/2; Built-in method:     Examples<153>.       (line  15)
* goal-expansion:                        Glossary.            (line 220)
* grammar rule:                          Glossary.            (line 230)
* grammar rule non-terminal:             Glossary.            (line 239)
* grammar rule terminal:                 Glossary.            (line 245)
* grammar_rules; Flag:                   Lint flags.          (line  90)
* homoiconic:                            Glossary.            (line 249)
* hook object:                           Glossary.            (line 257)
* hook predicate:                        Glossary.            (line 266)
* hook; Flag:                            Other flags.         (line  99)
* hot patching:                          Glossary.            (line 272)
* identity:                              Glossary.            (line 280)
* if/1; Directive:                       Conditional compilation directives<2>.
                                                              (line   8)
* ignore/1; Built-in method:             Examples<120>.       (line  19)
* implements_protocol/2-3; Built-in predicate: Examples<60>.  (line  19)
* imports_category/2-3; Built-in predicate: Examples<63>.     (line  15)
* include/1; Directive:                  Examples<9>.         (line   9)
* info/1; Directive:                     Examples<23>.        (line  14)
* info/2; Directive:                     Examples<33>.        (line  18)
* inheritance:                           Glossary.            (line 289)
* initialization/1; Directive:           Examples<10>.        (line  22)
* instance:                              Glossary.            (line 299)
* instantiates_class/2-3; Built-in predicate: Examples<64>.   (line  18)
* instantiation:                         Glossary.            (line 305)
* instantiation_error/0; Built-in method: Examples<125>.      (line  20)
* interface:                             Glossary.            (line 312)
* lambda expression:                     Glossary.            (line 316)
* lambda free variable:                  Glossary.            (line 324)
* lambda parameter:                      Glossary.            (line 330)
* lambda_variables; Flag:                Lint flags.          (line 102)
* late binding:                          Glossary.            (line 337)
* left_recursion; Flag:                  Lint flags.          (line 179)
* library:                               Glossary.            (line 341)
* library alias:                         Glossary.            (line 346)
* library notation:                      Glossary.            (line 353)
* linter; Flag:                          Lint flags.          (line   6)
* loader file:                           Glossary.            (line 361)
* local predicate:                       Glossary.            (line 367)
* logtalk_compile/1; Built-in predicate: Compiling and loading source files.
                                                              (line   8)
* logtalk_compile/2; Built-in predicate: Examples<88>.        (line  26)
* logtalk_library_path/2; Built-in predicate: Examples<94>.   (line  20)
* logtalk_linter_hook/7; Built-in predicate: Linter.          (line   8)
* logtalk_load_context/2; Built-in predicate: Examples<95>.   (line  54)
* logtalk_load/1; Built-in predicate:    Examples<89>.        (line  26)
* logtalk_load/2; Built-in predicate:    Examples<90>.        (line  26)
* logtalk_make_target_action/1; Built-in predicate: Examples<93>.
                                                              (line  24)
* logtalk_make/0; Built-in predicate:    Examples<91>.        (line  26)
* logtalk_make/1; Built-in predicate:    Examples<92>.        (line  17)
* message:                               Glossary.            (line 376)
* message lookup:                        Glossary.            (line 382)
* message to self:                       Glossary.            (line 391)
* message_hook/4; Built-in method:       Examples<157>.       (line  21)
* message_prefix_file/6; Built-in method: Examples<159>.      (line  21)
* message_prefix_stream/4; Built-in method: Examples<158>.    (line  23)
* message_tokens//2; Built-in method:    Examples<156>.       (line  17)
* meta_non_terminal/1; Directive:        Examples<35>.        (line  23)
* meta_predicate/1; Directive:           Examples<34>.        (line  21)
* meta-argument:                         Glossary.            (line 397)
* meta-interpreter:                      Glossary.            (line 404)
* meta-predicate:                        Glossary.            (line 409)
* meta-variable:                         Glossary.            (line 415)
* metaclass:                             Glossary.            (line 420)
* method:                                Glossary.            (line 427)
* missing_directives; Flag:              Lint flags.          (line  63)
* mocking:                               Glossary.            (line 434)
* mode_non_terminal/2; Directive:        Examples<37>.        (line  20)
* mode/2; Directive:                     Examples<36>.        (line  15)
* module:                                Glossary.            (line 441)
* modules; Flag:                         Read-only flags.     (line  81)
* monitor:                               Glossary.            (line 449)
* multifile predicate:                   Glossary.            (line 456)
* multifile/1; Directive:                Examples<38>.        (line  14)
* naked meta-variable:                   Glossary.            (line 465)
* naming; Flag:                          Lint flags.          (line 136)
* object:                                Glossary.            (line 472)
* object database:                       Glossary.            (line 480)
* object_property/2; Built-in predicate: Examples<49>.        (line  22)
* object/1-5; Directive:                 Examples<24>.        (line  20)
* once/1; Built-in method:               Examples<121>.       (line  19)
* op/3; Directive:                       Examples<11>.        (line  30)
* optimize; Flag:                        Other flags.         (line  44)
* parameter:                             Glossary.            (line 484)
* parameter variable:                    Glossary.            (line 490)
* parameter/2; Built-in method:          Examples<106>.       (line  21)
* parametric category:                   Glossary.            (line 499)
* parametric entity:                     Glossary.            (line 503)
* parametric object:                     Glossary.            (line 514)
* parametric object proxy:               Glossary.            (line 518)
* parent:                                Glossary.            (line 524)
* permission_error/3; Built-in method:   Examples<131>.       (line  21)
* phrase//1; Built-in method:            Examples<147>.       (line  15)
* phrase/2; Built-in method:             Examples<148>.       (line  14)
* phrase/3; Built-in method:             Examples<149>.       (line  19)
* polymorphism:                          Glossary.            (line 528)
* portability; Flag:                     Lint flags.          (line  50)
* predicate:                             Glossary.            (line 543)
* predicate alias:                       Glossary.            (line 550)
* predicate calling context:             Glossary.            (line 560)
* predicate declaration:                 Glossary.            (line 566)
* predicate definition:                  Glossary.            (line 572)
* predicate definition context:          Glossary.            (line 578)
* predicate directive:                   Glossary.            (line 583)
* predicate execution context:           Glossary.            (line 588)
* predicate scope container:             Glossary.            (line 594)
* predicate scope directive:             Glossary.            (line 600)
* predicate shorthand:                   Glossary.            (line 604)
* predicate_property/2; Built-in method: Examples<112>.       (line  42)
* primary predicate declaration:         Glossary.            (line 615)
* print_message_token/4; Built-in method: Examples<161>.      (line  19)
* print_message_tokens/3; Built-in method: Examples<160>.     (line  21)
* print_message/3; Built-in method:      Message printing.    (line   8)
* private inheritance:                   Glossary.            (line 619)
* private predicate:                     Glossary.            (line 625)
* private/1; Directive:                  Examples<39>.        (line  16)
* profiler:                              Glossary.            (line 630)
* prolog_compatible_version; Flag:       Read-only flags.     (line  36)
* prolog_compiler; Flag:                 Backend Prolog compiler and loader flags.
                                                              (line  16)
* prolog_dialect; Flag:                  Read-only flags.     (line  22)
* prolog_loader; Flag:                   Backend Prolog compiler and loader flags.
                                                              (line  26)
* prolog_version; Flag:                  Read-only flags.     (line  28)
* protected inheritance:                 Glossary.            (line 634)
* protected predicate:                   Glossary.            (line 640)
* protected/1; Directive:                Examples<40>.        (line  19)
* protocol:                              Glossary.            (line 646)
* protocol_property/2; Built-in predicate: Examples<50>.      (line  25)
* protocol/1-2; Directive:               Examples<25>.        (line  35)
* prototype:                             Glossary.            (line 656)
* public inheritance:                    Glossary.            (line 664)
* public predicate:                      Glossary.            (line 670)
* public/1; Directive:                   Examples<41>.        (line  19)
* question_hook/6; Built-in method:      Examples<163>.       (line  19)
* question_prompt_stream/4; Built-in method: Examples<164>.   (line  21)
* redefined_built_ins; Flag:             Lint flags.          (line 114)
* redefined_operators; Flag:             Lint flags.          (line 123)
* reflection:                            Message sending.     (line  26)
* relative_to; Flag:                     Other flags.         (line  93)
* reload; Flag:                          Other flags.         (line  82)
* repeat/0; Built-in method:             Examples<104>.       (line  15)
* report; Flag:                          Other flags.         (line  21)
* representation_error/1; Built-in method: Examples<132>.     (line  21)
* resource_error/1; Built-in method:     Examples<134>.       (line  21)
* retract/1; Built-in method:            Examples<117>.       (line  21)
* retractall/1; Built-in method:         Examples<118>.       (line  21)
* scratch directory:                     Glossary.            (line 674)
* scratch_directory; Flag:               Other flags.         (line   6)
* self:                                  Glossary.            (line 679)
* self/1; Built-in method:               Examples<107>.       (line  42)
* sender:                                Glossary.            (line 683)
* sender/1; Built-in method:             Examples<108>.       (line  20)
* set_logtalk_flag/2; Built-in predicate: Examples<97>.       (line  15)
* set_logtalk_flag/2; Directive:         Examples<12>.        (line  61)
* setof/3; Built-in method:              Examples<141>.       (line  20)
* settings file:                         Glossary.            (line 690)
* settings_file; Flag:                   Read-only flags.     (line  10)
* singleton method:                      Glossary.            (line 697)
* singleton_variables; Flag:             Lint flags.          (line 131)
* source file:                           Glossary.            (line 703)
* source file directive:                 Glossary.            (line 712)
* source_data; Flag:                     Other flags.         (line  61)
* specialization:                        Glossary.            (line 717)
* specializes_class/2-3; Built-in predicate: Examples<65>.    (line  20)
* static binding:                        Glossary.            (line 722)
* static entity:                         Glossary.            (line 732)
* steadfastness:                         Glossary.            (line 736)
* steadfastness; Flag:                   Lint flags.          (line  42)
* structural reflection:                 Reflection.          (line  13)
* subclass:                              Glossary.            (line 744)
* super call:                            Glossary.            (line 749)
* superclass:                            Glossary.            (line 757)
* suspicious_calls; Flag:                Lint flags.          (line 108)
* synchronized predicate:                Glossary.            (line 763)
* synchronized/1; Directive:             Examples<42>.        (line  19)
* syntax_error/1; Built-in method:       Examples<135>.       (line  21)
* system_error/0; Built-in method:       Examples<136>.       (line  19)
* tabling; Flag:                         Read-only flags.     (line  61)
* tail_recursive; Flag:                  Lint flags.          (line 186)
* template method:                       Glossary.            (line 769)
* term_expansion/2; Built-in method:     Examples<151>.       (line  15)
* term-expansion:                        Glossary.            (line 773)
* test dialect:                          Glossary.            (line 783)
* test outcome:                          Glossary.            (line 789)
* tester file:                           Glossary.            (line 795)
* this:                                  Glossary.            (line 800)
* this/1; Built-in method:               Examples<109>.       (line  20)
* threaded engine:                       Glossary.            (line 808)
* threaded_call/1-2; Built-in predicate: Examples<70>.        (line  18)
* threaded_cancel/1; Built-in predicate: Examples<75>.        (line  21)
* threaded_engine_create/3; Built-in predicate: Multi-threading engines.
                                                              (line   8)
* threaded_engine_destroy/1; Built-in predicate: Examples<79>.
                                                              (line  17)
* threaded_engine_fetch/1; Built-in predicate: Examples<86>.  (line  15)
* threaded_engine_next_reified/2; Built-in predicate: Examples<83>.
                                                              (line  16)
* threaded_engine_next/2; Built-in predicate: Examples<82>.   (line  19)
* threaded_engine_post/2; Built-in predicate: Examples<85>.   (line  16)
* threaded_engine_self/1; Built-in predicate: Examples<81>.   (line  22)
* threaded_engine_yield/1; Built-in predicate: Examples<84>.  (line  16)
* threaded_engine/1; Built-in predicate: Examples<80>.        (line  22)
* threaded_exit/1-2; Built-in predicate: Examples<73>.        (line  21)
* threaded_ignore/1; Built-in predicate: Examples<72>.        (line  21)
* threaded_notify/1; Built-in predicate: Examples<77>.        (line  15)
* threaded_once/1-2; Built-in predicate: Examples<71>.        (line  21)
* threaded_peek/1-2; Built-in predicate: Examples<74>.        (line  21)
* threaded_wait/1; Built-in predicate:   Examples<76>.        (line  16)
* threaded/0; Directive:                 Examples<26>.        (line  20)
* threaded/1; Built-in predicate:        Multi-threading.     (line   8)
* threads; Flag:                         Read-only flags.     (line  74)
* throw/1; Built-in method:              Examples<124>.       (line  20)
* top-level interpreter shorthand:       Glossary.            (line 816)
* transparent-box view:                  Structural reflection.
                                                              (line  11)
* trivial_goal_fails; Flag:              Lint flags.          (line  77)
* true/0; Built-in method:               Examples<101>.       (line  15)
* type_error/2; Built-in method:         Examples<127>.       (line  22)
* undefined_predicates; Flag:            Lint flags.          (line  34)
* underscore_variables; Flag:            Backend Prolog compiler and loader flags.
                                                              (line   6)
* unicode; Flag:                         Read-only flags.     (line  45)
* unknown_entities; Flag:                Lint flags.          (line  16)
* unknown_predicates; Flag:              Lint flags.          (line  24)
* ununinstantiation_error/1; Built-in method: Examples<126>.  (line  22)
* use_module/1; Directive:               Examples<28>.        (line  33)
* use_module/2; Directive:               Examples<44>.        (line  68)
* uses/1; Directive:                     Examples<27>.        (line  14)
* uses/2; Directive:                     Examples<43>.        (line  18)
* version_data; Flag:                    Version flags.       (line   6)
* visible predicate:                     Glossary.            (line 823)


Tag Table:
Node: Top470
Ref: index doc706
Ref: 0706
Node: User Manual66769
Ref: userman/index doc66876
Ref: 166876
Ref: userman/index the-logtalk-handbook66876
Ref: 266876
Ref: userman/index user-manual66876
Ref: 366876
Node: Declarative object-oriented programming67403
Ref: userman/declarative doc67531
Ref: 467531
Ref: userman/declarative declarative-declarative67531
Ref: 567531
Ref: userman/declarative declarative-object-oriented-programming67531
Ref: 667531
Node: Main features71382
Ref: userman/features doc71531
Ref: 971531
Ref: userman/features features-features71531
Ref: a71531
Ref: userman/features main-features71531
Ref: b71531
Node: Integration of logic and object-oriented programming73477
Ref: userman/features features-logic73666
Ref: c73666
Ref: userman/features integration-of-logic-and-object-oriented-programming73666
Ref: d73666
Node: Integration of event-driven and object-oriented programming74717
Ref: userman/features features-events74954
Ref: e74954
Ref: userman/features integration-of-event-driven-and-object-oriented-programming74954
Ref: f74954
Node: Support for component-based programming76226
Ref: userman/features features-categories76461
Ref: 1576461
Ref: userman/features support-for-component-based-programming76461
Ref: 1676461
Node: Support for both prototype and class-based systems77294
Ref: userman/features features-both77509
Ref: 1777509
Ref: userman/features support-for-both-prototype-and-class-based-systems77509
Ref: 1877509
Node: Support for multiple object hierarchies78518
Ref: userman/features features-multiple78741
Ref: 1a78741
Ref: userman/features support-for-multiple-object-hierarchies78741
Ref: 1b78741
Node: Separation between interface and implementation79562
Ref: userman/features features-interface79775
Ref: 1f79775
Ref: userman/features separation-between-interface-and-implementation79775
Ref: 2079775
Node: Private protected and public inheritance80275
Ref: userman/features features-inheritance80495
Ref: 2180495
Ref: userman/features private-protected-and-public-inheritance80495
Ref: 2280495
Node: Private protected and public object predicates80841
Ref: userman/features features-predicates81032
Ref: 2481032
Ref: userman/features private-protected-and-public-object-predicates81032
Ref: 2581032
Node: Parametric objects81524
Ref: userman/features features-parametric81721
Ref: 2681721
Ref: userman/features parametric-objects81721
Ref: 2781721
Node: High level multi-threading programming support82465
Ref: userman/features features-threading82637
Ref: 2b82637
Ref: userman/features high-level-multi-threading-programming-support82637
Ref: 2c82637
Node: Smooth learning curve83193
Ref: userman/features features-learning83406
Ref: 2d83406
Ref: userman/features smooth-learning-curve83406
Ref: 2e83406
Node: Compatibility with most Prolog systems and the ISO standard83626
Ref: userman/features compatibility-with-most-prolog-systems-and-the-iso-standard83804
Ref: 2f83804
Ref: userman/features features-compatibility83804
Ref: 3083804
Node: Performance84179
Ref: userman/features features-performance84349
Ref: 3284349
Ref: userman/features performance84349
Ref: 3384349
Node: Logtalk scope85667
Ref: userman/features features-scope85769
Ref: 3985769
Ref: userman/features logtalk-scope85769
Ref: 3a85769
Node: Nomenclature88442
Ref: userman/nomenclature doc88560
Ref: 3b88560
Ref: userman/nomenclature nomenclature88560
Ref: 3c88560
Ref: userman/nomenclature nomenclature-nomenclature88560
Ref: 3d88560
Node: Prolog nomenclature90258
Ref: userman/nomenclature nomenclature-prolog90376
Ref: 4090376
Ref: userman/nomenclature prolog-nomenclature90376
Ref: 4190376
Node: Smalltalk nomenclature97400
Ref: userman/nomenclature nomenclature-smalltalk97543
Ref: 5a97543
Ref: userman/nomenclature smalltalk-nomenclature97543
Ref: 5b97543
Node: C++ nomenclature102814
Ref: userman/nomenclature c-nomenclature102955
Ref: 5e102955
Ref: userman/nomenclature nomenclature-cpp102955
Ref: 5f102955
Node: Java nomenclature106207
Ref: userman/nomenclature java-nomenclature106345
Ref: 6b106345
Ref: userman/nomenclature nomenclature-java106345
Ref: 6c106345
Node: Python nomenclature111320
Ref: userman/nomenclature nomenclature-python111433
Ref: 75111433
Ref: userman/nomenclature python-nomenclature111433
Ref: 76111433
Node: Messages115513
Ref: userman/messages doc115625
Ref: 77115625
Ref: userman/messages messages115625
Ref: 78115625
Ref: userman/messages messages-messages115625
Ref: 79115625
Node: Operators used in message-sending117323
Ref: userman/messages messages-operators117459
Ref: 7a117459
Ref: userman/messages operators-used-in-message-sending117459
Ref: 7b117459
Node: Sending a message to an object118014
Ref: userman/messages messages-sending118192
Ref: 7c118192
Ref: userman/messages sending-a-message-to-an-object118192
Ref: 7d118192
Node: Delegating a message to an object118720
Ref: userman/messages delegating-a-message-to-an-object118890
Ref: 7f118890
Ref: userman/messages messages-delegating118890
Ref: 80118890
Node: Sending a message to self119448
Ref: userman/messages sending-a-message-to-self119600
Ref: 82119600
Node: Broadcasting120366
Ref: userman/messages broadcasting120526
Ref: 83120526
Ref: userman/messages messages-broadcasting120526
Ref: 84120526
Node: Calling imported and inherited predicates121405
Ref: userman/messages calling-imported-and-inherited-predicates121576
Ref: 85121576
Ref: userman/messages messages-super121576
Ref: 86121576
Node: Message sending and event generation122748
Ref: userman/messages message-sending-and-event-generation122938
Ref: 87122938
Ref: userman/messages messages-events122938
Ref: 88122938
Node: Sending a message from a module124639
Ref: userman/messages messages-from-module124815
Ref: 8a124815
Ref: userman/messages sending-a-message-from-a-module124815
Ref: 8b124815
Node: Message sending performance125816
Ref: userman/messages message-sending-performance125947
Ref: 8d125947
Ref: userman/messages messages-performance125947
Ref: 8e125947
Node: Objects126115
Ref: userman/objects doc126224
Ref: 8f126224
Ref: userman/objects objects126224
Ref: 90126224
Ref: userman/objects objects-objects126224
Ref: 91126224
Ref: Objects-Footnote-1127199
Ref: Objects-Footnote-2127237
Node: Objects prototypes classes and instances127281
Ref: userman/objects objects-prototypes-classes-and-instances127414
Ref: 92127414
Ref: userman/objects objects-roles127414
Ref: 93127414
Node: Prototypes129046
Ref: userman/objects objects-prototypes129168
Ref: 94129168
Ref: userman/objects prototypes129168
Ref: 95129168
Node: Classes129787
Ref: userman/objects classes129909
Ref: 96129909
Ref: userman/objects objects-classes129909
Ref: 97129909
Node: Defining a new object130466
Ref: userman/objects defining-a-new-object130629
Ref: 98130629
Ref: userman/objects objects-defining130629
Ref: 99130629
Node: Parametric objects<2>136483
Ref: userman/objects objects-parametric136629
Ref: 66136629
Ref: userman/objects parametric-objects136629
Ref: 9f136629
Node: Accessing object parameters137409
Ref: userman/objects accessing-object-parameters137547
Ref: a0137547
Node: Parametric object proxies139830
Ref: userman/objects parametric-object-proxies139968
Ref: a3139968
Node: Finding defined objects141491
Ref: userman/objects finding-defined-objects141648
Ref: a4141648
Ref: userman/objects objects-finding141648
Ref: a5141648
Node: Creating a new object at runtime142077
Ref: userman/objects creating-a-new-object-at-runtime142242
Ref: a7142242
Ref: userman/objects objects-creating142242
Ref: a8142242
Node: Abolishing an existing object143500
Ref: userman/objects abolishing-an-existing-object143659
Ref: a9143659
Ref: userman/objects objects-abolishing143659
Ref: aa143659
Node: Object directives143959
Ref: userman/objects object-directives144106
Ref: ab144106
Ref: userman/objects objects-directives144106
Ref: ac144106
Node: Object initialization144487
Ref: userman/objects object-initialization144605
Ref: ad144605
Ref: userman/objects objects-initialization144605
Ref: ae144605
Node: Dynamic objects145827
Ref: userman/objects dynamic-objects145974
Ref: af145974
Ref: userman/objects objects-dynamic145974
Ref: b0145974
Node: Object documentation146700
Ref: userman/objects object-documentation146854
Ref: b2146854
Ref: userman/objects objects-documentation146854
Ref: b3146854
Node: Loading files into an object147084
Ref: userman/objects loading-files-into-an-object147247
Ref: b6147247
Ref: userman/objects objects-include147247
Ref: b7147247
Node: Declaring object aliases147994
Ref: userman/objects declaring-object-aliases148128
Ref: b9148128
Ref: userman/objects objects-object-aliases148128
Ref: ba148128
Node: Object relationships148542
Ref: userman/objects object-relationships148677
Ref: bb148677
Ref: userman/objects objects-relationships148677
Ref: bc148677
Node: Object properties150777
Ref: userman/objects object-properties150911
Ref: c4150911
Ref: userman/objects objects-properties150911
Ref: c5150911
Node: Built-in objects159604
Ref: userman/objects built-in-objects159746
Ref: cd159746
Ref: userman/objects objects-built-in159746
Ref: ce159746
Node: The built-in pseudo-object user159959
Ref: userman/objects objects-user160098
Ref: cf160098
Ref: userman/objects the-built-in-pseudo-object-user160098
Ref: d0160098
Ref: The built-in pseudo-object user-Footnote-1161088
Node: The built-in object logtalk161126
Ref: userman/objects objects-logtalk161265
Ref: d1161265
Ref: userman/objects the-built-in-object-logtalk161265
Ref: d2161265
Ref: The built-in object logtalk-Footnote-1161767
Node: Multi-threading applications161811
Ref: userman/objects multi-threading-applications161927
Ref: d6161927
Node: Protocols162225
Ref: userman/protocols doc162336
Ref: d7162336
Ref: userman/protocols protocols162336
Ref: d8162336
Ref: userman/protocols protocols-protocols162336
Ref: d9162336
Ref: Protocols-Footnote-1163298
Ref: Protocols-Footnote-2163348
Ref: Protocols-Footnote-3163396
Node: Defining a new protocol163446
Ref: userman/protocols defining-a-new-protocol163568
Ref: da163568
Ref: userman/protocols protocols-defining163568
Ref: db163568
Node: Finding defined protocols165657
Ref: userman/protocols finding-defined-protocols165822
Ref: de165822
Ref: userman/protocols protocols-finding165822
Ref: df165822
Node: Creating a new protocol at runtime166190
Ref: userman/protocols creating-a-new-protocol-at-runtime166363
Ref: e1166363
Ref: userman/protocols protocols-creating166363
Ref: e2166363
Node: Abolishing an existing protocol167409
Ref: userman/protocols abolishing-an-existing-protocol167576
Ref: e4167576
Ref: userman/protocols protocols-abolishing167576
Ref: e5167576
Node: Protocol directives167890
Ref: userman/protocols protocol-directives168045
Ref: e7168045
Node: Dynamic protocols168270
Ref: userman/protocols dynamic-protocols168393
Ref: e8168393
Ref: userman/protocols protocols-dynamic168393
Ref: e9168393
Node: Protocol documentation169036
Ref: userman/protocols protocol-documentation169197
Ref: ea169197
Ref: userman/protocols protocols-documentation169197
Ref: eb169197
Node: Loading files into a protocol169432
Ref: userman/protocols loading-files-into-a-protocol169567
Ref: ec169567
Ref: userman/protocols protocols-include169567
Ref: ed169567
Node: Protocol relationships169816
Ref: userman/protocols protocol-relationships169959
Ref: ee169959
Ref: userman/protocols protocols-relationships169959
Ref: ef169959
Node: Protocol properties170994
Ref: userman/protocols protocol-properties171140
Ref: f2171140
Ref: userman/protocols protocols-properties171140
Ref: f3171140
Node: Implementing protocols173524
Ref: userman/protocols implementing-protocols173666
Ref: f6173666
Ref: userman/protocols protocols-implementing173666
Ref: f7173666
Node: Built-in protocols174658
Ref: userman/protocols built-in-protocols174812
Ref: f8174812
Ref: userman/protocols protocols-built-in174812
Ref: f9174812
Node: The built-in protocol expanding175075
Ref: userman/protocols protocols-expanding175221
Ref: fa175221
Ref: userman/protocols the-built-in-protocol-expanding175221
Ref: fb175221
Ref: The built-in protocol expanding-Footnote-1175543
Node: The built-in protocol monitoring175591
Ref: userman/protocols protocols-monitoring175778
Ref: ff175778
Ref: userman/protocols the-built-in-protocol-monitoring175778
Ref: 100175778
Ref: The built-in protocol monitoring-Footnote-1176104
Node: The built-in protocol forwarding176154
Ref: userman/protocols protocols-forwarding176301
Ref: 103176301
Ref: userman/protocols the-built-in-protocol-forwarding176301
Ref: 104176301
Ref: The built-in protocol forwarding-Footnote-1176711
Node: Multi-threading applications<2>176761
Ref: userman/protocols multi-threading-applications176884
Ref: 106176884
Node: Categories177186
Ref: userman/categories doc177300
Ref: 107177300
Ref: userman/categories categories177300
Ref: 108177300
Ref: userman/categories categories-categories177300
Ref: 109177300
Ref: Categories-Footnote-1178806
Node: Defining a new category178862
Ref: userman/categories categories-defining178972
Ref: 10c178972
Ref: userman/categories defining-a-new-category178972
Ref: 10d178972
Node: Hot patching184383
Ref: userman/categories categories-patching184528
Ref: 110184528
Ref: userman/categories hot-patching184528
Ref: 111184528
Node: Finding defined categories188072
Ref: userman/categories categories-finding188228
Ref: 116188228
Ref: userman/categories finding-defined-categories188228
Ref: 117188228
Node: Creating a new category at runtime188619
Ref: userman/categories categories-creating188794
Ref: 118188794
Ref: userman/categories creating-a-new-category-at-runtime188794
Ref: 119188794
Node: Abolishing an existing category190045
Ref: userman/categories abolishing-an-existing-category190213
Ref: 11b190213
Ref: userman/categories categories-abolishing190213
Ref: 11c190213
Node: Category directives190529
Ref: userman/categories categories-directives190685
Ref: 11d190685
Ref: userman/categories category-directives190685
Ref: 11e190685
Node: Dynamic categories191056
Ref: userman/categories categories-dynamic191180
Ref: 11f191180
Ref: userman/categories dynamic-categories191180
Ref: 120191180
Node: Category documentation191838
Ref: userman/categories categories-documentation192000
Ref: 121192000
Ref: userman/categories category-documentation192000
Ref: 122192000
Node: Loading files into a category192235
Ref: userman/categories categories-include192406
Ref: 123192406
Ref: userman/categories loading-files-into-a-category192406
Ref: 124192406
Node: Declaring object aliases<2>192655
Ref: userman/categories categories-object-aliases192795
Ref: 125192795
Ref: userman/categories declaring-object-aliases192795
Ref: 126192795
Node: Category relationships193128
Ref: userman/categories categories-relationships193272
Ref: 127193272
Ref: userman/categories category-relationships193272
Ref: 128193272
Node: Category properties194918
Ref: userman/categories categories-properties195063
Ref: 12a195063
Ref: userman/categories category-properties195063
Ref: 12b195063
Node: Importing categories202896
Ref: userman/categories categories-importing203046
Ref: 12d203046
Ref: userman/categories importing-categories203046
Ref: 12e203046
Node: Calling category predicates203872
Ref: userman/categories calling-category-predicates204024
Ref: 12f204024
Ref: userman/categories categories-predicates204024
Ref: 130204024
Node: Parametric categories205818
Ref: userman/categories categories-parametric205969
Ref: 131205969
Ref: userman/categories parametric-categories205969
Ref: 132205969
Node: Built-in categories206923
Ref: userman/categories built-in-categories207078
Ref: 133207078
Ref: userman/categories categories-built-in207078
Ref: 134207078
Node: The built-in category core_messages207266
Ref: userman/categories categories-core-messages207376
Ref: 135207376
Ref: userman/categories the-built-in-category-core-messages207376
Ref: 136207376
Ref: The built-in category core_messages-Footnote-1207699
Node: Multi-threading applications<3>207755
Ref: userman/categories multi-threading-applications207880
Ref: 137207880
Node: Predicates208182
Ref: userman/predicates doc208298
Ref: 138208298
Ref: userman/predicates predicates208298
Ref: 139208298
Ref: userman/predicates predicates-predicates208298
Ref: 13a208298
Node: Reserved predicate names209092
Ref: userman/predicates predicates-reserved209211
Ref: 13b209211
Ref: userman/predicates reserved-predicate-names209211
Ref: 13c209211
Ref: Reserved predicate names-Footnote-1209886
Ref: Reserved predicate names-Footnote-2209934
Ref: Reserved predicate names-Footnote-3209984
Node: Declaring predicates210034
Ref: userman/predicates declaring-predicates210181
Ref: 13d210181
Ref: userman/predicates predicates-declaring210181
Ref: 13e210181
Node: Scope directives211292
Ref: userman/predicates predicates-scope211407
Ref: 13f211407
Ref: userman/predicates scope-directives211407
Ref: 140211407
Node: Mode directive214496
Ref: userman/predicates mode-directive214644
Ref: 147214644
Ref: userman/predicates predicates-mode214644
Ref: 148214644
Ref: userman/predicates predicates-mode-instantiation215040
Ref: 14b215040
Ref: userman/predicates predicates-mode-number-of-proofs217105
Ref: 14d217105
Node: Meta-predicate directive221146
Ref: userman/predicates meta-predicate-directive221301
Ref: 14e221301
Ref: userman/predicates predicates-meta221301
Ref: 65221301
Node: Discontiguous directive225248
Ref: userman/predicates discontiguous-directive225406
Ref: 155225406
Ref: userman/predicates predicates-discontiguous225406
Ref: 156225406
Node: Dynamic directive226105
Ref: userman/predicates dynamic-directive226257
Ref: 158226257
Ref: userman/predicates predicates-dynamic226257
Ref: 159226257
Node: Operator directive227491
Ref: userman/predicates operator-directive227634
Ref: 15b227634
Ref: userman/predicates predicates-op227634
Ref: 15c227634
Node: Uses directive229186
Ref: userman/predicates predicates-uses229327
Ref: 15f229327
Ref: userman/predicates uses-directive229327
Ref: 160229327
Node: Alias directive233175
Ref: userman/predicates alias-directive233319
Ref: 163233319
Ref: userman/predicates predicates-alias233319
Ref: 164233319
Node: Documenting directive237465
Ref: userman/predicates documenting-directive237614
Ref: 166237614
Ref: userman/predicates predicates-info237614
Ref: 167237614
Node: Multifile directive237935
Ref: userman/predicates multifile-directive238090
Ref: 169238090
Ref: userman/predicates predicates-multifile238090
Ref: 16a238090
Node: Coinductive directive242084
Ref: userman/predicates coinductive-directive242240
Ref: 16e242240
Ref: userman/predicates predicates-coinductive242240
Ref: 16f242240
Node: Synchronized directive242743
Ref: userman/predicates predicates-synchronized242871
Ref: 173242871
Ref: userman/predicates synchronized-directive242871
Ref: 174242871
Node: Defining predicates243211
Ref: userman/predicates defining-predicates243363
Ref: 177243363
Ref: userman/predicates predicates-defining243363
Ref: 178243363
Node: Object predicates243550
Ref: userman/predicates object-predicates243670
Ref: 179243670
Ref: userman/predicates predicates-objects243670
Ref: 17a243670
Node: Category predicates244846
Ref: userman/predicates category-predicates244990
Ref: 17b244990
Ref: userman/predicates predicates-categories244990
Ref: 17c244990
Node: Meta-predicates246782
Ref: userman/predicates meta-predicates246927
Ref: 17e246927
Ref: userman/predicates predicates-metadef246927
Ref: 17f246927
Node: Lambda expressions250066
Ref: userman/predicates lambda-expressions250222
Ref: 184250222
Ref: userman/predicates predicates-lambdas250222
Ref: 162250222
Ref: Lambda expressions-Footnote-1256818
Node: Redefining built-in predicates256872
Ref: userman/predicates predicates-redefining257004
Ref: 187257004
Ref: userman/predicates redefining-built-in-predicates257004
Ref: 188257004
Node: Definite clause grammar rules259348
Ref: userman/predicates definite-clause-grammar-rules259496
Ref: 18c259496
Ref: userman/predicates predicates-dcgs259496
Ref: 18d259496
Node: Built-in methods267294
Ref: userman/predicates built-in-methods267443
Ref: 192267443
Ref: userman/predicates predicates-methods267443
Ref: 193267443
Node: Logic and control methods268193
Ref: userman/predicates logic-and-control-methods268324
Ref: 194268324
Ref: userman/predicates predicates-logic268324
Ref: 195268324
Node: Execution context methods268786
Ref: userman/predicates execution-context-methods268961
Ref: 19b268961
Ref: userman/predicates predicates-context268961
Ref: 19c268961
Node: Error handling and throwing methods273410
Ref: userman/predicates error-handling-and-throwing-methods273576
Ref: 19f273576
Ref: userman/predicates predicates-errors273576
Ref: 1a0273576
Node: Database methods274369
Ref: userman/predicates database-methods274527
Ref: 1ae274527
Ref: userman/predicates predicates-database274527
Ref: 1af274527
Node: Meta-call methods275930
Ref: userman/predicates meta-call-methods276074
Ref: 1b9276074
Ref: userman/predicates predicates-metacalls276074
Ref: 1ba276074
Node: All solutions methods276527
Ref: userman/predicates all-solutions-methods276673
Ref: 1bd276673
Ref: userman/predicates predicates-solutions276673
Ref: 1be276673
Node: Reflection methods277044
Ref: userman/predicates predicates-reflection277230
Ref: 1c4277230
Ref: userman/predicates reflection-methods277230
Ref: 1c5277230
Node: Definite clause grammar parsing methods and non-terminals278461
Ref: userman/predicates definite-clause-grammar-parsing-methods-and-non-terminals278617
Ref: 1c6278617
Ref: userman/predicates predicates-parsing278617
Ref: 1c7278617
Node: Predicate properties279419
Ref: userman/predicates predicate-properties279566
Ref: 1cb279566
Ref: userman/predicates predicates-properties279566
Ref: 1cc279566
Node: Finding declared predicates285071
Ref: userman/predicates finding-declared-predicates285227
Ref: 1cd285227
Ref: userman/predicates predicates-finding285227
Ref: 1ce285227
Node: Calling Prolog predicates286119
Ref: userman/predicates calling-prolog-predicates286291
Ref: 1cf286291
Ref: userman/predicates predicates-prolog286291
Ref: 3e286291
Node: Calling Prolog built-in predicates287371
Ref: userman/predicates calling-prolog-built-in-predicates287547
Ref: 1d0287547
Node: Calling Prolog non-standard built-in meta-predicates289507
Ref: userman/predicates calling-prolog-non-standard-built-in-meta-predicates289725
Ref: 1d2289725
Ref: userman/predicates predicates-prolog-meta289725
Ref: 1d3289725
Node: Calling Prolog foreign predicates290961
Ref: userman/predicates calling-prolog-foreign-predicates291189
Ref: 1d4291189
Ref: userman/predicates predicates-prolog-foreign291189
Ref: 1d5291189
Node: Calling Prolog user-defined plain predicates292463
Ref: userman/predicates calling-prolog-user-defined-plain-predicates292671
Ref: 1d6292671
Ref: userman/predicates predicates-prolog-user292671
Ref: 1d7292671
Node: Calling Prolog module predicates293762
Ref: userman/predicates calling-prolog-module-predicates293974
Ref: 1d8293974
Ref: userman/predicates predicates-prolog-module293974
Ref: 1d9293974
Node: Calling Prolog module meta-predicates297518
Ref: userman/predicates calling-prolog-module-meta-predicates297677
Ref: 1da297677
Ref: userman/predicates predicates-prolog-module-meta-predicates297677
Ref: 1db297677
Node: Defining Prolog multifile predicates300461
Ref: userman/predicates defining-prolog-multifile-predicates300648
Ref: 1dc300648
Ref: userman/predicates predicates-prolog-multifile300648
Ref: 1dd300648
Node: Asserting and retracting Prolog predicates301829
Ref: userman/predicates asserting-and-retracting-prolog-predicates301982
Ref: 1de301982
Ref: userman/predicates predicates-prolog-dynamic301982
Ref: 1df301982
Node: Inheritance303827
Ref: userman/inheritance doc303957
Ref: 1e0303957
Ref: userman/inheritance inheritance303957
Ref: 1e1303957
Ref: userman/inheritance inheritance-inheritance303957
Ref: 8303957
Node: Protocol inheritance305965
Ref: userman/inheritance inheritance-protocol306087
Ref: 1e2306087
Ref: userman/inheritance protocol-inheritance306087
Ref: 1e3306087
Node: Lookup order for prototype hierarchies306565
Ref: userman/inheritance inheritance-protocol-prototype306722
Ref: 1e5306722
Ref: userman/inheritance lookup-order-for-prototype-hierarchies306722
Ref: 1e6306722
Node: Lookup order for class hierarchies307294
Ref: userman/inheritance inheritance-protocol-class307451
Ref: 1e7307451
Ref: userman/inheritance lookup-order-for-class-hierarchies307451
Ref: 1e8307451
Node: Implementation inheritance308041
Ref: userman/inheritance implementation-inheritance308212
Ref: 1e9308212
Ref: userman/inheritance inheritance-implementation308212
Ref: 1ea308212
Node: Lookup order for prototype hierarchies<2>308935
Ref: userman/inheritance id1309104
Ref: 1eb309104
Ref: userman/inheritance inheritance-implementation-prototype309104
Ref: 1ec309104
Node: Lookup order for class hierarchies<2>309391
Ref: userman/inheritance id2309611
Ref: 1ed309611
Ref: userman/inheritance inheritance-implementation-class309611
Ref: 1ee309611
Node: Redefining inherited predicate definitions310109
Ref: userman/inheritance inheritance-implementation-redefinition310332
Ref: 1ef310332
Ref: userman/inheritance redefining-inherited-predicate-definitions310332
Ref: 1f0310332
Node: Specializing inherited predicate definitions311357
Ref: userman/inheritance inheritance-specialization311593
Ref: 1f1311593
Ref: userman/inheritance specializing-inherited-predicate-definitions311593
Ref: 1f2311593
Node: Union of inherited and local predicate definitions312409
Ref: userman/inheritance inheritance-union312649
Ref: 1f3312649
Ref: userman/inheritance union-of-inherited-and-local-predicate-definitions312649
Ref: 1f4312649
Node: Selective inheritance of predicate definitions313550
Ref: userman/inheritance inheritance-selective313737
Ref: 1f5313737
Ref: userman/inheritance selective-inheritance-of-predicate-definitions313737
Ref: 1f6313737
Node: Public protected and private inheritance314568
Ref: userman/inheritance inheritance-scope314739
Ref: 9e314739
Ref: userman/inheritance public-protected-and-private-inheritance314739
Ref: 1f7314739
Node: Multiple inheritance316036
Ref: userman/inheritance inheritance-multiple316220
Ref: 1f8316220
Ref: userman/inheritance multiple-inheritance316220
Ref: 1f9316220
Node: Composition versus multiple inheritance317109
Ref: userman/inheritance composition-versus-multiple-inheritance317244
Ref: 1fa317244
Ref: userman/inheritance inheritance-composition317244
Ref: 1fb317244
Node: Event-driven programming318950
Ref: userman/events doc319097
Ref: 200319097
Ref: userman/events event-driven-programming319097
Ref: 201319097
Ref: userman/events events-events319097
Ref: 6d319097
Node: Definitions320905
Ref: userman/events definitions321021
Ref: 204321021
Ref: userman/events events-definitions321021
Ref: 205321021
Node: Event321248
Ref: userman/events event321336
Ref: 206321336
Ref: userman/events events-event321336
Ref: 207321336
Node: Monitor323203
Ref: userman/events events-monitor323291
Ref: 208323291
Ref: userman/events monitor323291
Ref: 209323291
Ref: Monitor-Footnote-1324793
Node: Event generation324843
Ref: userman/events event-generation325000
Ref: 20a325000
Ref: userman/events events-generation325000
Ref: 20b325000
Node: Communicating events to monitors325651
Ref: userman/events communicating-events-to-monitors325817
Ref: 20c325817
Ref: userman/events events-communicating325817
Ref: 20d325817
Ref: Communicating events to monitors-Footnote-1326347
Node: Performance concerns326397
Ref: userman/events events-performance326564
Ref: 20e326564
Ref: userman/events performance-concerns326564
Ref: 20f326564
Node: Monitor semantics327471
Ref: userman/events events-semantics327634
Ref: 210327634
Ref: userman/events monitor-semantics327634
Ref: 211327634
Node: Activation order of monitors328528
Ref: userman/events activation-order-of-monitors328685
Ref: 212328685
Ref: userman/events events-order328685
Ref: 213328685
Node: Event handling329855
Ref: userman/events event-handling329986
Ref: 214329986
Ref: userman/events events-handling329986
Ref: 215329986
Node: Defining new events330453
Ref: userman/events defining-new-events330576
Ref: 216330576
Ref: userman/events events-defining330576
Ref: 217330576
Node: Abolishing defined events330978
Ref: userman/events abolishing-defined-events331132
Ref: 219331132
Ref: userman/events events-abolishing331132
Ref: 21a331132
Node: Finding defined events331456
Ref: userman/events events-finding331614
Ref: 21c331614
Ref: userman/events finding-defined-events331614
Ref: 21d331614
Node: Defining event handlers332004
Ref: userman/events defining-event-handlers332128
Ref: 21f332128
Ref: userman/events events-handlers332128
Ref: 220332128
Ref: Defining event handlers-Footnote-1335247
Ref: Defining event handlers-Footnote-2335297
Node: Multi-threading programming335347
Ref: userman/threads doc335497
Ref: 221335497
Ref: userman/threads multi-threading-programming335497
Ref: 222335497
Ref: userman/threads threads-threads335497
Ref: 73335497
Node: Enabling multi-threading support336680
Ref: userman/threads enabling-multi-threading-support336850
Ref: 223336850
Ref: userman/threads threads-enabling336850
Ref: 224336850
Node: Enabling objects to make multi-threading calls337133
Ref: userman/threads enabling-objects-to-make-multi-threading-calls337347
Ref: 226337347
Ref: userman/threads threads-directive337347
Ref: 227337347
Node: Multi-threading built-in predicates337579
Ref: userman/threads multi-threading-built-in-predicates337787
Ref: 229337787
Ref: userman/threads threads-predicates337787
Ref: 22a337787
Node: Proving goals concurrently using threads338550
Ref: userman/threads proving-goals-concurrently-using-threads338732
Ref: 22c338732
Ref: userman/threads threads-threaded338732
Ref: 22d338732
Node: Proving goals asynchronously using threads341093
Ref: userman/threads proving-goals-asynchronously-using-threads341275
Ref: 22e341275
Ref: userman/threads threads-call341275
Ref: 22f341275
Node: One-way asynchronous calls345762
Ref: userman/threads one-way-asynchronous-calls345970
Ref: 235345970
Ref: userman/threads threads-ignore345970
Ref: 236345970
Node: Asynchronous calls and synchronized predicates346644
Ref: userman/threads asynchronous-calls-and-synchronized-predicates346860
Ref: 238346860
Ref: userman/threads threads-synchronized-predicates346860
Ref: 176346860
Node: Synchronizing threads through notifications350270
Ref: userman/threads synchronizing-threads-through-notifications350476
Ref: 239350476
Ref: userman/threads threads-notifications350476
Ref: 23a350476
Node: Threaded engines351893
Ref: userman/threads threaded-engines352080
Ref: 23d352080
Ref: userman/threads threads-engines352080
Ref: 23e352080
Node: Multi-threading performance355955
Ref: userman/threads multi-threading-performance356090
Ref: 246356090
Ref: userman/threads threads-performance356090
Ref: 247356090
Node: Error handling357145
Ref: userman/errors doc357281
Ref: 248357281
Ref: userman/errors error-handling357281
Ref: 249357281
Ref: userman/errors errors-errors357281
Ref: 24a357281
Ref: Error handling-Footnote-1358504
Node: Raising Exceptions358568
Ref: userman/errors raising-exceptions358678
Ref: 24b358678
Node: Type-checking359236
Ref: userman/errors type-checking359369
Ref: 24d359369
Ref: Type-checking-Footnote-1362008
Ref: Type-checking-Footnote-2362046
Ref: Type-checking-Footnote-3362092
Ref: Type-checking-Footnote-4362138
Node: Expected terms362184
Ref: userman/errors expected-terms362327
Ref: 24e362327
Node: Compiler warnings and errors362616
Ref: userman/errors compiler-warnings-and-errors362760
Ref: 250362760
Node: Unknown entities364199
Ref: userman/errors errors-unknown364327
Ref: 252364327
Ref: userman/errors unknown-entities364327
Ref: 253364327
Node: Singleton variables364712
Ref: userman/errors errors-singletons364891
Ref: 254364891
Ref: userman/errors singleton-variables364891
Ref: 255364891
Node: Redefinition of Prolog built-in predicates365327
Ref: userman/errors errors-prolog365533
Ref: 256365533
Ref: userman/errors redefinition-of-prolog-built-in-predicates365533
Ref: 257365533
Node: Redefinition of Logtalk built-in predicates366063
Ref: userman/errors errors-redefinition-predicates366290
Ref: 258366290
Ref: userman/errors redefinition-of-logtalk-built-in-predicates366290
Ref: 259366290
Node: Redefinition of Logtalk built-in methods366609
Ref: userman/errors errors-redefinition-methods366828
Ref: 25a366828
Ref: userman/errors redefinition-of-logtalk-built-in-methods366828
Ref: 25b366828
Node: Misspell calls of local predicates367120
Ref: userman/errors errors-misspell367316
Ref: 25c367316
Ref: userman/errors misspell-calls-of-local-predicates367316
Ref: 25d367316
Node: Portability warnings367657
Ref: userman/errors errors-portability367832
Ref: 25e367832
Ref: userman/errors portability-warnings367832
Ref: 25f367832
Node: Deprecated elements368192
Ref: userman/errors deprecated-elements368351
Ref: 260368351
Ref: userman/errors errors-deprecated368351
Ref: 261368351
Node: Missing directives368646
Ref: userman/errors errors-missing-directives368806
Ref: 262368806
Ref: userman/errors missing-directives368806
Ref: 263368806
Node: Duplicated directives368979
Ref: userman/errors duplicated-directives369138
Ref: 264369138
Ref: userman/errors errors-duplicated-directives369138
Ref: 265369138
Node: Duplicated clauses369460
Ref: userman/errors duplicated-clauses369636
Ref: 266369636
Ref: userman/errors errors-duplicated-clauses369636
Ref: 267369636
Node: Goals that are always true or false369840
Ref: userman/errors errors-always-true-or-false-goals370008
Ref: 268370008
Ref: userman/errors goals-that-are-always-true-or-false370008
Ref: 269370008
Node: Trivial fails370277
Ref: userman/errors errors-trivial-fails370443
Ref: 26a370443
Ref: userman/errors trivial-fails370443
Ref: 26b370443
Node: Suspicious calls370586
Ref: userman/errors errors-suspicious-calls370733
Ref: 26c370733
Ref: userman/errors suspicious-calls370733
Ref: 26d370733
Node: Lambda variables371080
Ref: userman/errors errors-lambda-variables371286
Ref: 26e371286
Ref: userman/errors lambda-variables371286
Ref: 26f371286
Node: Redefinition of predicates declared in uses/2 or use_module/2 directives371664
Ref: userman/errors errors-predicate-redefinition371879
Ref: 272371879
Ref: userman/errors redefinition-of-predicates-declared-in-uses-2-or-use-module-2-directives371879
Ref: 273371879
Node: Other warnings and errors372221
Ref: userman/errors errors-others372411
Ref: 274372411
Ref: userman/errors other-warnings-and-errors372411
Ref: 275372411
Node: Runtime errors372667
Ref: userman/errors errors-runtime372788
Ref: 276372788
Ref: userman/errors runtime-errors372788
Ref: 277372788
Node: Logtalk built-in predicates373166
Ref: userman/errors errors-predicates373296
Ref: 278373296
Ref: userman/errors logtalk-built-in-predicates373296
Ref: 279373296
Node: Logtalk built-in methods373496
Ref: userman/errors errors-methods373650
Ref: 27a373650
Ref: userman/errors logtalk-built-in-methods373650
Ref: 27b373650
Node: Message sending373840
Ref: userman/errors errors-sending373958
Ref: 27c373958
Ref: userman/errors message-sending373958
Ref: 27d373958
Ref: Message sending-Footnote-1374875
Node: Reflection374925
Ref: userman/reflection doc375066
Ref: 27e375066
Ref: userman/reflection reflection375066
Ref: 27f375066
Ref: userman/reflection reflection-reflection375066
Ref: 48375066
Node: Structural reflection375531
Ref: userman/reflection reflection-structural375648
Ref: 281375648
Ref: userman/reflection structural-reflection375648
Ref: 282375648
Node: Transparent-box view375996
Ref: userman/reflection transparent-box-view376116
Ref: 283376116
Ref: Transparent-box view-Footnote-1377541
Node: Black-box view377585
Ref: userman/reflection black-box-view377705
Ref: 286377705
Node: Behavioral reflection378431
Ref: userman/reflection behavioral-reflection378548
Ref: 287378548
Ref: userman/reflection reflection-behavioral378548
Ref: 288378548
Ref: Behavioral reflection-Footnote-1379161
Node: Writing and running applications379205
Ref: userman/programming doc379370
Ref: 28a379370
Ref: userman/programming programming-programming379370
Ref: 28b379370
Ref: userman/programming writing-and-running-applications379370
Ref: 28c379370
Node: Starting Logtalk381091
Ref: userman/programming programming-starting381238
Ref: 28e381238
Ref: userman/programming starting-logtalk381238
Ref: 28f381238
Node: Running parallel Logtalk processes382325
Ref: userman/programming programming-parallel-processes382493
Ref: 290382493
Ref: userman/programming running-parallel-logtalk-processes382493
Ref: 291382493
Node: Source files384669
Ref: userman/programming programming-source-files384840
Ref: 294384840
Ref: userman/programming source-files384840
Ref: 295384840
Ref: Source files-Footnote-1387866
Ref: Source files-Footnote-2387943
Node: Naming conventions388020
Ref: userman/programming naming-conventions388140
Ref: 296388140
Node: Source file text encoding388732
Ref: userman/programming source-file-text-encoding388852
Ref: 297388852
Node: Multi-pass compiler389199
Ref: userman/programming multi-pass-compiler389375
Ref: 29a389375
Ref: userman/programming programming-multi-pass-compiler389375
Ref: 29b389375
Node: Compiling and loading your applications391653
Ref: userman/programming compiling-and-loading-your-applications391854
Ref: 29c391854
Ref: userman/programming programming-compiling391854
Ref: 29d391854
Node: Compiler errors warnings and comments394856
Ref: userman/programming compiler-errors-warnings-and-comments395050
Ref: 2a1395050
Ref: userman/programming programming-errors-warnings-comments395050
Ref: 2a2395050
Node: Loader files395959
Ref: userman/programming loader-files396139
Ref: 2a3396139
Ref: userman/programming programming-loaders396139
Ref: 2a4396139
Node: Libraries of source files399698
Ref: userman/programming libraries-of-source-files399855
Ref: 2a5399855
Ref: userman/programming programming-libraries399855
Ref: 2a6399855
Node: Settings files402726
Ref: userman/programming programming-settings402886
Ref: 2a9402886
Ref: userman/programming settings-files402886
Ref: 2aa402886
Node: Compiler linter405635
Ref: userman/programming compiler-linter405784
Ref: 2ad405784
Ref: userman/programming programming-linter405784
Ref: 2ae405784
Node: Compiler flags406556
Ref: userman/programming compiler-flags406713
Ref: 2b1406713
Ref: userman/programming programming-flags406713
Ref: 251406713
Node: Read-only flags409311
Ref: userman/programming read-only-flags409418
Ref: 2b4409418
Ref: userman/programming flag-settings-file409628
Ref: 2ab409628
Ref: userman/programming flag-prolog-dialect410299
Ref: 2ac410299
Ref: userman/programming flag-prolog-version410497
Ref: 2b5410497
Ref: userman/programming flag-prolog-compatible-version410839
Ref: 2b6410839
Ref: userman/programming flag-unicode411237
Ref: 2b7411237
Ref: userman/programming flag-encoding-directive411510
Ref: 299411510
Ref: userman/programming flag-tabling411942
Ref: 2b8411942
Ref: userman/programming flag-engines412134
Ref: 2b9412134
Ref: userman/programming flag-threads412394
Ref: 225412394
Ref: userman/programming flag-modules412676
Ref: 2bb412676
Ref: userman/programming flag-coinduction412972
Ref: 172412972
Node: Version flags413252
Ref: userman/programming version-flags413378
Ref: 2bc413378
Ref: userman/programming flag-version-data413427
Ref: 2bd413427
Node: Lint flags413944
Ref: userman/programming lint-flags414090
Ref: 2be414090
Ref: userman/programming programming-flags-lint414090
Ref: 2b0414090
Ref: userman/programming flag-linter414133
Ref: 2bf414133
Ref: userman/programming flag-unknown-entities414661
Ref: 2c0414661
Ref: userman/programming flag-unknown-predicates415054
Ref: 2c1415054
Ref: userman/programming flag-undefined-predicates415530
Ref: 2c2415530
Ref: userman/programming flag-steadfastness415888
Ref: 2c3415888
Ref: userman/programming flag-portability416220
Ref: 1d1416220
Ref: userman/programming flag-deprecated416540
Ref: 2c5416540
Ref: userman/programming flag-missing-directives416701
Ref: 2c6416701
Ref: userman/programming flag-duplicated-directives416900
Ref: 2c7416900
Ref: userman/programming flag-trivial-goal-fails417233
Ref: 2c8417233
Ref: userman/programming flag-always-true-or-false-goals417478
Ref: 2c9417478
Ref: userman/programming flag-grammar-rules417782
Ref: 190417782
Ref: userman/programming flag-arithmetic-expressions417982
Ref: 2ca417982
Ref: userman/programming flag-lambda-variables418199
Ref: 186418199
Ref: userman/programming flag-suspicious-calls418403
Ref: 2cb418403
Ref: userman/programming flag-redefined-built-ins418600
Ref: 189418600
Ref: userman/programming flag-redefined-operators419020
Ref: 2cc419020
Ref: userman/programming flag-singleton-variables419389
Ref: 2cd419389
Ref: userman/programming flag-naming419575
Ref: 2ce419575
Ref: userman/programming flag-duplicated-clauses420051
Ref: 2cf420051
Ref: userman/programming flag-disjunctions420483
Ref: 2d0420483
Ref: userman/programming flag-conditionals420820
Ref: 2d1420820
Ref: userman/programming flag-catchall-catch421154
Ref: 2d2421154
Ref: userman/programming flag-left-recursion421487
Ref: 2d3421487
Ref: userman/programming flag-tail-recursive421783
Ref: 2d4421783
Ref: userman/programming flag-encodings422232
Ref: 2d5422232
Ref: userman/programming flag-general422397
Ref: 2d6422397
Node: Optional features compilation flags422577
Ref: userman/programming optional-features-compilation-flags422750
Ref: 2d7422750
Ref: userman/programming flag-complements422843
Ref: 112422843
Ref: userman/programming flag-dynamic-declarations423531
Ref: 2d8423531
Ref: userman/programming flag-events424136
Ref: 89424136
Ref: userman/programming flag-context-switching-calls424692
Ref: 2d9424692
Node: Backend Prolog compiler and loader flags425020
Ref: userman/programming backend-prolog-compiler-and-loader-flags425194
Ref: 2da425194
Ref: userman/programming flag-underscore-variables425297
Ref: 2db425297
Ref: userman/programming flag-prolog-compiler425787
Ref: 2dc425787
Ref: userman/programming flag-prolog-loader426289
Ref: 2dd426289
Node: Other flags426633
Ref: userman/programming other-flags426790
Ref: 2de426790
Ref: userman/programming flag-scratch-directory426835
Ref: 2df426835
Ref: userman/programming flag-report427721
Ref: 2e0427721
Ref: userman/programming flag-code-prefix428099
Ref: 2e1428099
Ref: userman/programming flag-optimize428967
Ref: 8c428967
Ref: userman/programming flag-source-data429915
Ref: cc429915
Ref: userman/programming flag-debug430563
Ref: 2e2430563
Ref: userman/programming flag-reload430986
Ref: 2e3430986
Ref: userman/programming flag-relative-to431543
Ref: 2e4431543
Ref: userman/programming flag-hook431726
Ref: fe431726
Ref: userman/programming flag-clean432151
Ref: 292432151
Ref: Other flags-Footnote-1433183
Ref: Other flags-Footnote-2433221
Node: User-defined flags433269
Ref: userman/programming user-defined-flags433377
Ref: 2e5433377
Node: Reloading source files433541
Ref: userman/programming programming-reloading433699
Ref: 2e7433699
Ref: userman/programming reloading-source-files433699
Ref: 2e8433699
Node: Batch processing436188
Ref: userman/programming batch-processing436354
Ref: 2e9436354
Ref: userman/programming programming-batch436354
Ref: 2ea436354
Node: Optimizing performance436741
Ref: userman/programming optimizing-performance436906
Ref: 2eb436906
Ref: userman/programming programming-performance436906
Ref: 2ec436906
Node: Portable applications438957
Ref: userman/programming portable-applications439129
Ref: 2ee439129
Ref: userman/programming programming-portability439129
Ref: 2ef439129
Node: Conditional compilation440069
Ref: userman/programming conditional-compilation440241
Ref: 2f0440241
Ref: userman/programming programming-cc440241
Ref: 2f1440241
Node: Avoiding common errors440612
Ref: userman/programming avoiding-common-errors440786
Ref: 2f6440786
Ref: userman/programming programming-errors440786
Ref: 2f7440786
Node: Coding style guidelines442504
Ref: userman/programming coding-style-guidelines442646
Ref: 2f8442646
Ref: userman/programming programming-style442646
Ref: 2f9442646
Node: Printing messages and asking questions443445
Ref: userman/printing doc443623
Ref: 2fa443623
Ref: userman/printing printing-messages-and-asking-questions443623
Ref: 2fb443623
Ref: userman/printing printing-printing443623
Ref: 18b443623
Ref: Printing messages and asking questions-Footnote-1446949
Node: Printing messages446993
Ref: userman/printing id1447133
Ref: 2fd447133
Ref: userman/printing printing-messages447133
Ref: d3447133
Node: Message tokenization450852
Ref: userman/printing message-tokenization451014
Ref: 2ff451014
Node: Meta-messages453329
Ref: userman/printing meta-messages453518
Ref: 301453518
Ref: Meta-messages-Footnote-1453956
Node: Defining message prefixes and output streams454000
Ref: userman/printing defining-message-prefixes-and-output-streams454211
Ref: 303454211
Node: Defining message prefixes and output files455904
Ref: userman/printing defining-message-prefixes-and-output-files456123
Ref: 305456123
Node: Intercepting messages457761
Ref: userman/printing id2457952
Ref: 308457952
Ref: userman/printing intercepting-messages457952
Ref: 309457952
Node: Asking questions459602
Ref: userman/printing asking-questions459773
Ref: 30a459773
Ref: userman/printing printing-questions459773
Ref: d4459773
Node: Intercepting questions462641
Ref: userman/printing intercepting-questions462822
Ref: 30c462822
Node: Multi-threading applications<4>464348
Ref: userman/printing multi-threading-applications464504
Ref: 30e464504
Node: Term and goal expansion464787
Ref: userman/expansion doc464944
Ref: 30f464944
Ref: userman/expansion expansion-expansion464944
Ref: cb464944
Ref: userman/expansion term-and-goal-expansion464944
Ref: 310464944
Node: Defining expansions466403
Ref: userman/expansion defining-expansions466533
Ref: 311466533
Ref: Defining expansions-Footnote-1470343
Node: Expanding grammar rules470391
Ref: userman/expansion expanding-grammar-rules470550
Ref: 313470550
Node: Bypassing expansions471151
Ref: userman/expansion bypassing-expansions471303
Ref: 314471303
Node: Hook objects471713
Ref: userman/expansion hook-objects471887
Ref: 315471887
Ref: Hook objects-Footnote-1474310
Node: Virtual source file terms and loading context474358
Ref: userman/expansion virtual-source-file-terms-and-loading-context474547
Ref: 316474547
Node: Default compiler expansion workflow476523
Ref: userman/expansion default-compiler-expansion-workflow476732
Ref: 318476732
Node: User defined expansion workflows477478
Ref: userman/expansion user-defined-expansion-workflows477673
Ref: 319477673
Ref: User defined expansion workflows-Footnote-1479392
Ref: User defined expansion workflows-Footnote-2479448
Ref: User defined expansion workflows-Footnote-3479494
Ref: User defined expansion workflows-Footnote-4479564
Node: Using Prolog defined expansions479620
Ref: userman/expansion using-prolog-defined-expansions479800
Ref: 31c479800
Ref: Using Prolog defined expansions-Footnote-1481553
Node: Debugging expansions481619
Ref: userman/expansion debugging-expansions481758
Ref: 31d481758
Node: Documenting484781
Ref: userman/documenting doc484909
Ref: 320484909
Ref: userman/documenting documenting484909
Ref: 321484909
Ref: userman/documenting documenting-documenting484909
Ref: b5484909
Node: Entity documenting directives486409
Ref: userman/documenting documenting-entity486546
Ref: 323486546
Ref: userman/documenting entity-documenting-directives486546
Ref: 324486546
Ref: Entity documenting directives-Footnote-1489610
Ref: Entity documenting directives-Footnote-2489637
Node: Predicate documenting directives489672
Ref: userman/documenting documenting-predicate489839
Ref: 325489839
Ref: userman/documenting predicate-documenting-directives489839
Ref: 326489839
Node: Describing predicates493526
Ref: userman/documenting describing-predicates493696
Ref: 327493696
Ref: userman/documenting documenting-descriptions493696
Ref: 328493696
Node: Documenting predicate exceptions494955
Ref: userman/documenting documenting-exceptions495133
Ref: 329495133
Ref: userman/documenting documenting-predicate-exceptions495133
Ref: 32a495133
Node: Processing and viewing documenting files497939
Ref: userman/documenting documenting-processing498130
Ref: 32b498130
Ref: userman/documenting processing-and-viewing-documenting-files498130
Ref: 32c498130
Node: Inline formatting in comments text501881
Ref: userman/documenting documenting-formatting502048
Ref: 32e502048
Ref: userman/documenting inline-formatting-in-comments-text502048
Ref: 32f502048
Node: Diagrams503090
Ref: userman/documenting diagrams503208
Ref: 330503208
Node: Debugging503842
Ref: userman/debugging doc503961
Ref: 331503961
Ref: userman/debugging debugging503961
Ref: 332503961
Ref: userman/debugging debugging-debugging503961
Ref: 47503961
Node: Compiling source files in debug mode505749
Ref: userman/debugging compiling-source-files-in-debug-mode505878
Ref: 333505878
Ref: userman/debugging debugging-debug-mode505878
Ref: 334505878
Node: Procedure box model507808
Ref: userman/debugging debugging-box-model507969
Ref: 335507969
Ref: userman/debugging procedure-box-model507969
Ref: 336507969
Node: Activating the debugger509903
Ref: userman/debugging activating-the-debugger510048
Ref: 337510048
Ref: Activating the debugger-Footnote-1510587
Ref: Activating the debugger-Footnote-2510643
Ref: Activating the debugger-Footnote-3510699
Node: Defining breakpoints510757
Ref: userman/debugging defining-breakpoints510902
Ref: 339510902
Node: Defining predicate and clause breakpoints512621
Ref: userman/debugging defining-predicate-and-clause-breakpoints512779
Ref: 33a512779
Node: Defining conditional breakpoints514135
Ref: userman/debugging defining-conditional-breakpoints514332
Ref: 33b514332
Node: Defining hit count breakpoints515542
Ref: userman/debugging defining-hit-count-breakpoints515728
Ref: 33c515728
Node: Defining triggered breakpoints516748
Ref: userman/debugging defining-triggered-breakpoints516930
Ref: 33d516930
Node: Defining context breakpoints517792
Ref: userman/debugging defining-context-breakpoints517968
Ref: 33e517968
Node: Removing all breakpoints519160
Ref: userman/debugging removing-all-breakpoints519297
Ref: 33f519297
Node: Defining log points519674
Ref: userman/debugging defining-log-points519821
Ref: 340519821
Node: Tracing program execution521689
Ref: userman/debugging programming-trace521843
Ref: 341521843
Ref: userman/debugging tracing-program-execution521843
Ref: 342521843
Node: Debugging using breakpoints524003
Ref: userman/debugging debugging-debug524156
Ref: 343524156
Ref: userman/debugging debugging-using-breakpoints524156
Ref: 344524156
Node: Debugging commands524838
Ref: userman/debugging debugging-commands524990
Ref: 345524990
Ref: userman/debugging id1524990
Ref: 346524990
Node: Customizing term writing528110
Ref: userman/debugging customizing-term-writing528258
Ref: 347528258
Ref: userman/debugging debugging-term-write528258
Ref: 348528258
Node: Term write depth528809
Ref: userman/debugging debugging-term-write-depth528933
Ref: 349528933
Ref: userman/debugging term-write-depth528933
Ref: 34a528933
Ref: Term write depth-Footnote-1529988
Ref: Term write depth-Footnote-2530054
Node: Custom term writing530124
Ref: userman/debugging custom-term-writing530248
Ref: 34b530248
Ref: userman/debugging debugging-custom-term-writing530248
Ref: 34c530248
Node: Context-switching calls530871
Ref: userman/debugging context-switching-calls531019
Ref: 34d531019
Ref: userman/debugging debugging-context531019
Ref: 34e531019
Node: Debugging messages532984
Ref: userman/debugging debugging-messages533156
Ref: 302533156
Ref: userman/debugging id2533156
Ref: 34f533156
Node: Meta-messages<2>533768
Ref: userman/debugging meta-messages533903
Ref: 350533903
Node: Selective printing of debug messages537028
Ref: userman/debugging selective-printing-of-debug-messages537163
Ref: 351537163
Node: Using the term-expansion mechanism for debugging538240
Ref: userman/debugging debugging-hooks538404
Ref: 354538404
Ref: userman/debugging using-the-term-expansion-mechanism-for-debugging538404
Ref: 355538404
Ref: Using the term-expansion mechanism for debugging-Footnote-1539002
Node: Ports profiling539062
Ref: userman/debugging debugging-ports-profiling539230
Ref: 356539230
Ref: userman/debugging ports-profiling539230
Ref: 357539230
Node: Debug and trace events539571
Ref: userman/debugging debug-and-trace-events539712
Ref: 359539712
Ref: userman/debugging debugging-events539712
Ref: d5539712
Ref: Debug and trace events-Footnote-1542241
Ref: Debug and trace events-Footnote-2542299
Ref: Debug and trace events-Footnote-3542359
Ref: Debug and trace events-Footnote-4542419
Ref: Debug and trace events-Footnote-5542488
Ref: Debug and trace events-Footnote-6542559
Node: Source-level debugger542617
Ref: userman/debugging debugging-source-level-debugger542734
Ref: 35a542734
Ref: userman/debugging source-level-debugger542734
Ref: 35b542734
Node: Performance<2>543126
Ref: userman/performance doc543252
Ref: 35c543252
Ref: userman/performance performance543252
Ref: 35d543252
Ref: userman/performance performance-performance543252
Ref: 38543252
Node: Source code compilation modes544903
Ref: userman/performance source-code-compilation-modes545040
Ref: 361545040
Node: Source code compilation order545774
Ref: userman/performance source-code-compilation-order545941
Ref: 362545941
Ref: Source code compilation order-Footnote-1546673
Ref: Source code compilation order-Footnote-2546750
Node: Local predicate calls546827
Ref: userman/performance local-predicate-calls547006
Ref: 363547006
Node: Calls to imported or inherited predicates547217
Ref: userman/performance calls-to-imported-or-inherited-predicates547393
Ref: 364547393
Node: Calls to module predicates547645
Ref: userman/performance calls-to-module-predicates547811
Ref: 365547811
Node: Messages<2>548035
Ref: userman/performance messages548207
Ref: 366548207
Node: Automatic expansion of built-in meta-predicates550840
Ref: userman/performance automatic-expansion-of-built-in-meta-predicates550994
Ref: 367550994
Node: Inlining551537
Ref: userman/performance inlining551727
Ref: 368551727
Node: Generated code simplification and optimizations552260
Ref: userman/performance generated-code-simplification-and-optimizations552429
Ref: 369552429
Node: Size of the generated code553040
Ref: userman/performance size-of-the-generated-code553220
Ref: 36b553220
Node: Circular references554390
Ref: userman/performance circular-references554542
Ref: 36c554542
Node: Debug mode overhead554978
Ref: userman/performance debug-mode-overhead555124
Ref: 36d555124
Ref: Debug mode overhead-Footnote-1556489
Ref: Debug mode overhead-Footnote-2556547
Node: Other considerations556607
Ref: userman/performance other-considerations556725
Ref: 36e556725
Ref: Other considerations-Footnote-1557339
Ref: Other considerations-Footnote-2557417
Ref: Other considerations-Footnote-3557500
Node: Installing Logtalk557545
Ref: userman/installing doc557694
Ref: 36f557694
Ref: userman/installing installing-installing557694
Ref: 370557694
Ref: userman/installing installing-logtalk557694
Ref: 371557694
Node: Hardware and software requirements559659
Ref: userman/installing hardware-and-software-requirements559794
Ref: 372559794
Ref: userman/installing installing-requirements559794
Ref: 373559794
Node: Computer and operating system559943
Ref: userman/installing computer-and-operating-system560086
Ref: 374560086
Ref: userman/installing installing-computer560086
Ref: 375560086
Node: Prolog compiler560293
Ref: userman/installing installing-compiler560436
Ref: 376560436
Ref: userman/installing prolog-compiler560436
Ref: 377560436
Node: Logtalk installers561718
Ref: userman/installing installing-installers561881
Ref: 378561881
Ref: userman/installing logtalk-installers561881
Ref: 379561881
Node: Source distribution562179
Ref: userman/installing installing-sources562329
Ref: 37a562329
Ref: userman/installing source-distribution562329
Ref: 37b562329
Node: Distribution overview562977
Ref: userman/installing distribution-overview563100
Ref: 37c563100
Ref: userman/installing installing-organization563100
Ref: 37d563100
Node: Adapter files567430
Ref: userman/installing adapter-files567549
Ref: 37e567549
Ref: userman/installing installing-adapters567549
Ref: 37f567549
Node: Compiler and runtime569041
Ref: userman/installing compiler-and-runtime569176
Ref: 380569176
Ref: userman/installing installing-runtime569176
Ref: 381569176
Node: Library569538
Ref: userman/installing installing-library569668
Ref: 382569668
Ref: userman/installing library569668
Ref: 383569668
Node: Examples569887
Ref: userman/installing examples570017
Ref: 384570017
Ref: userman/installing installing-examples570017
Ref: 385570017
Node: Logtalk source files570527
Ref: userman/installing installing-entities570641
Ref: 386570641
Ref: userman/installing logtalk-source-files570641
Ref: 387570641
Node: Prolog integration and migration571293
Ref: userman/migration doc571419
Ref: 388571419
Ref: userman/migration migration-migration571419
Ref: 389571419
Ref: userman/migration prolog-integration-and-migration571419
Ref: 38a571419
Node: Source files with both Prolog code and Logtalk code572441
Ref: userman/migration migration-hybrid572631
Ref: 38c572631
Ref: userman/migration source-files-with-both-prolog-code-and-logtalk-code572631
Ref: 38d572631
Node: Encapsulating plain Prolog code in objects573498
Ref: userman/migration encapsulating-plain-prolog-code-in-objects573735
Ref: 38e573735
Ref: userman/migration migration-encapsulating573735
Ref: 38f573735
Node: Prolog multifile predicates575746
Ref: userman/migration migration-multifile575871
Ref: 390575871
Ref: userman/migration prolog-multifile-predicates575871
Ref: 391575871
Node: Converting Prolog modules into objects577563
Ref: userman/migration converting-prolog-modules-into-objects577784
Ref: 393577784
Ref: userman/migration migration-converting577784
Ref: 394577784
Node: Compiling Prolog modules as objects582662
Ref: userman/migration compiling-prolog-modules-as-objects582898
Ref: 395582898
Ref: userman/migration migration-compiling582898
Ref: 396582898
Node: Supported module directives584807
Ref: userman/migration migration-compatibility584963
Ref: 397584963
Ref: userman/migration supported-module-directives584963
Ref: 398584963
Node: Unsupported module directives589037
Ref: userman/migration migration-unsupported-module-directives589242
Ref: 39a589242
Ref: userman/migration unsupported-module-directives589242
Ref: 39b589242
Node: Modules using a term-expansion mechanism590411
Ref: userman/migration migration-module-expansions590606
Ref: 39c590606
Ref: userman/migration modules-using-a-term-expansion-mechanism590606
Ref: 39d590606
Node: File search paths592819
Ref: userman/migration file-search-paths592976
Ref: 39f592976
Ref: userman/migration migration-file-search-paths592976
Ref: 3a0592976
Node: Dealing with proprietary Prolog directives and predicates593587
Ref: userman/migration dealing-with-proprietary-prolog-directives-and-predicates593820
Ref: 3a1593820
Ref: userman/migration migration-proprietary593820
Ref: 3a2593820
Node: Calling Prolog module predicates<2>596185
Ref: userman/migration calling-prolog-module-predicates596420
Ref: 3a3596420
Ref: userman/migration migration-calling596420
Ref: 3a4596420
Node: Loading converted Prolog applications598917
Ref: userman/migration loading-converted-prolog-applications599086
Ref: 3a5599086
Ref: userman/migration migration-loading599086
Ref: 3a6599086
Node: Reference Manual600549
Ref: refman/index doc600661
Ref: 3a7600661
Ref: refman/index reference-manual600661
Ref: 3a8600661
Node: Grammar600839
Ref: refman/grammar doc600945
Ref: 3a9600945
Ref: refman/grammar grammar600945
Ref: 3aa600945
Ref: refman/grammar grammar-grammar600945
Ref: 3ab600945
Node: Entities601593
Ref: refman/grammar entities601690
Ref: 3ac601690
Ref: refman/grammar grammar-entities601690
Ref: 3ad601690
Node: Object definition601791
Ref: refman/grammar grammar-object-definition601916
Ref: 3ae601916
Ref: refman/grammar object-definition601916
Ref: 3af601916
Node: Category definition602800
Ref: refman/grammar category-definition602936
Ref: 3b0602936
Ref: refman/grammar grammar-category-definition602936
Ref: 3b1602936
Node: Protocol definition603477
Ref: refman/grammar grammar-protocol-definition603612
Ref: 3b2603612
Ref: refman/grammar protocol-definition603612
Ref: 3b3603612
Node: Entity relations603934
Ref: refman/grammar entity-relations604068
Ref: 3b4604068
Ref: refman/grammar grammar-entity-relations604068
Ref: 3b5604068
Node: Implemented protocols604942
Ref: refman/grammar grammar-implemented-protocols605062
Ref: 3b6605062
Ref: refman/grammar implemented-protocols605062
Ref: 3b7605062
Node: Extended protocols605576
Ref: refman/grammar extended-protocols605724
Ref: 3b8605724
Ref: refman/grammar grammar-extended-protocols605724
Ref: 3b9605724
Node: Imported categories606198
Ref: refman/grammar grammar-imported-categories606341
Ref: 3ba606341
Ref: refman/grammar imported-categories606341
Ref: 3bb606341
Node: Extended objects606819
Ref: refman/grammar extended-objects606963
Ref: 3bc606963
Ref: refman/grammar grammar-extended-objects606963
Ref: 3bd606963
Node: Extended categories607408
Ref: refman/grammar extended-categories607553
Ref: 3be607553
Ref: refman/grammar grammar-extended-categories607553
Ref: 3bf607553
Node: Instantiated objects608031
Ref: refman/grammar grammar-instantiated-objects608179
Ref: 3c0608179
Ref: refman/grammar instantiated-objects608179
Ref: 3c1608179
Node: Specialized objects608676
Ref: refman/grammar grammar-specialized-objects608825
Ref: 3c2608825
Ref: refman/grammar specialized-objects608825
Ref: 3c3608825
Node: Complemented objects609309
Ref: refman/grammar complemented-objects609464
Ref: 3c4609464
Ref: refman/grammar grammar-complemented-objects609464
Ref: 3c5609464
Node: Entity and predicate scope609860
Ref: refman/grammar entity-and-predicate-scope609987
Ref: 3c6609987
Ref: refman/grammar grammar-scope609987
Ref: 3c7609987
Node: Entity identifiers610133
Ref: refman/grammar entity-identifiers610263
Ref: 3c8610263
Ref: refman/grammar grammar-entity-identifiers610263
Ref: 3c9610263
Node: Object identifiers610534
Ref: refman/grammar grammar-object-identifiers610655
Ref: 3ca610655
Ref: refman/grammar object-identifiers610655
Ref: 3cb610655
Node: Category identifiers610770
Ref: refman/grammar category-identifiers610920
Ref: 3cc610920
Ref: refman/grammar grammar-category-identifiers610920
Ref: 3cd610920
Node: Protocol identifiers611041
Ref: refman/grammar grammar-protocol-identifiers611191
Ref: 3ce611191
Ref: refman/grammar protocol-identifiers611191
Ref: 3cf611191
Node: Module identifiers611293
Ref: refman/grammar grammar-module-identifiers611414
Ref: 3d0611414
Ref: refman/grammar module-identifiers611414
Ref: 3d1611414
Node: Source files<2>611510
Ref: refman/grammar grammar-source-files611641
Ref: 3d2611641
Ref: refman/grammar source-files611641
Ref: 3d3611641
Node: Source file names611852
Ref: refman/grammar grammar-source-file-names611970
Ref: 3d4611970
Ref: refman/grammar source-file-names611970
Ref: 3d5611970
Node: Terms612199
Ref: refman/grammar grammar-terms612312
Ref: 3d6612312
Ref: refman/grammar terms612312
Ref: 3d7612312
Node: Object terms612383
Ref: refman/grammar grammar-object-terms612479
Ref: 3d8612479
Ref: refman/grammar object-terms612479
Ref: 3d9612479
Node: Category terms612609
Ref: refman/grammar category-terms612705
Ref: 3da612705
Ref: refman/grammar grammar-category-terms612705
Ref: 3db612705
Node: Directives612843
Ref: refman/grammar directives612956
Ref: 3dc612956
Ref: refman/grammar grammar-directives612956
Ref: 3dd612956
Node: Source file directives613231
Ref: refman/grammar grammar-source-file-directives613362
Ref: 3de613362
Ref: refman/grammar source-file-directives613362
Ref: 3df613362
Node: Conditional compilation directives613619
Ref: refman/grammar conditional-compilation-directives613779
Ref: 3e0613779
Ref: refman/grammar grammar-conditional-compilation-directives613779
Ref: 3e1613779
Node: Object directives<2>614021
Ref: refman/grammar grammar-object-directives614181
Ref: 3e2614181
Ref: refman/grammar object-directives614181
Ref: 3e3614181
Node: Category directives<2>614691
Ref: refman/grammar category-directives614839
Ref: 3e4614839
Ref: refman/grammar grammar-category-directives614839
Ref: 3e5614839
Node: Protocol directives<2>615285
Ref: refman/grammar grammar-protocol-directives615433
Ref: 3e6615433
Ref: refman/grammar protocol-directives615433
Ref: 3e7615433
Node: Predicate directives615785
Ref: refman/grammar grammar-predicate-directives615902
Ref: 3e8615902
Ref: refman/grammar predicate-directives615902
Ref: 3e9615902
Node: Clauses and goals626274
Ref: refman/grammar clauses-and-goals626403
Ref: 3ea626403
Ref: refman/grammar grammar-clauses626403
Ref: 3eb626403
Node: Lambda expressions<2>627554
Ref: refman/grammar grammar-lambdas627690
Ref: 185627690
Ref: refman/grammar lambda-expressions627690
Ref: 3ec627690
Node: Entity properties628158
Ref: refman/grammar entity-properties628300
Ref: 3ed628300
Ref: refman/grammar grammar-entity-properties628300
Ref: c8628300
Node: Predicate properties<2>635780
Ref: refman/grammar grammar-predicate-properties635918
Ref: 3ee635918
Ref: refman/grammar predicate-properties635918
Ref: 3ef635918
Node: Compiler flags<2>637270
Ref: refman/grammar compiler-flags637382
Ref: 3f0637382
Ref: refman/grammar grammar-compiler-flags637382
Ref: 3f1637382
Node: Control constructs637483
Ref: refman/control/index doc637611
Ref: 3f2637611
Ref: refman/control/index control-constructs637611
Ref: 3f3637611
Node: Message sending<2>637912
Ref: refman/control/message_sending doc638031
Ref: 3f4638031
Ref: refman/control/message_sending id1638031
Ref: 3f5638031
Ref: refman/control/message_sending message-sending638031
Ref: 360638031
Node: /2638135
Ref: refman/control/send_to_object_2 doc638222
Ref: 3f6638222
Ref: refman/control/send_to_object_2 control-send-to-object-2638222
Ref: 7e638222
Ref: refman/control/send_to_object_2 id1638222
Ref: 3f7638222
Node: Description638354
Ref: refman/control/send_to_object_2 description638458
Ref: 3f8638458
Node: Modes and number of proofs640128
Ref: refman/control/send_to_object_2 modes-and-number-of-proofs640247
Ref: 3fb640247
Node: Errors640421
Ref: refman/control/send_to_object_2 errors640540
Ref: 3fc640540
Node: Examples<2>641790
Ref: refman/control/send_to_object_2 examples641874
Ref: 3fd641874
Node: /1642088
Ref: refman/control/send_to_self_1 doc642175
Ref: 3fe642175
Ref: refman/control/send_to_self_1 control-send-to-self-1642175
Ref: 5c642175
Ref: refman/control/send_to_self_1 id1642175
Ref: 3ff642175
Node: Description<2>642362
Ref: refman/control/send_to_self_1 description642472
Ref: 400642472
Node: Modes and number of proofs<2>643600
Ref: refman/control/send_to_self_1 modes-and-number-of-proofs643728
Ref: 401643728
Node: Errors<2>643832
Ref: refman/control/send_to_self_1 errors643957
Ref: 402643957
Node: Examples<3>644470
Ref: refman/control/send_to_self_1 examples644557
Ref: 403644557
Node: Message delegation644771
Ref: refman/control/message_delegation doc644943
Ref: 404644943
Ref: refman/control/message_delegation id1644943
Ref: 405644943
Ref: refman/control/message_delegation message-delegation644943
Ref: 406644943
Node: []/1645034
Ref: refman/control/delegate_message_1 doc645112
Ref: 407645112
Ref: refman/control/delegate_message_1 control-delegate-message-1645112
Ref: 81645112
Ref: refman/control/delegate_message_1 id1645112
Ref: 408645112
Node: Description<3>645295
Ref: refman/control/delegate_message_1 description645407
Ref: 409645407
Node: Modes and number of proofs<3>646335
Ref: refman/control/delegate_message_1 modes-and-number-of-proofs646465
Ref: 40a646465
Node: Errors<3>646643
Ref: refman/control/delegate_message_1 errors646770
Ref: 40b646770
Node: Examples<4>648202
Ref: refman/control/delegate_message_1 examples648291
Ref: 40c648291
Node: Calling imported and inherited predicates<2>648533
Ref: refman/control/super_calls doc648713
Ref: 40d648713
Ref: refman/control/super_calls calling-imported-and-inherited-predicates648713
Ref: 40e648713
Ref: refman/control/super_calls super-calls648713
Ref: 40f648713
Node: ^^ /1648858
Ref: refman/control/call_super_1 doc648963
Ref: 410648963
Ref: refman/control/call_super_1 control-call-super-1648963
Ref: 5d648963
Ref: refman/control/call_super_1 id1648963
Ref: 411648963
Node: Description<4>649150
Ref: refman/control/call_super_1 description649263
Ref: 412649263
Node: Modes and number of proofs<4>651233
Ref: refman/control/call_super_1 modes-and-number-of-proofs651364
Ref: 413651364
Node: Errors<4>651468
Ref: refman/control/call_super_1 errors651596
Ref: 414651596
Node: Examples<5>652119
Ref: refman/control/call_super_1 examples652209
Ref: 415652209
Node: Calling predicates in this652452
Ref: refman/control/call_in_this doc652641
Ref: 416652641
Ref: refman/control/call_in_this call-in-this652641
Ref: 417652641
Ref: refman/control/call_in_this calling-predicates-in-this652641
Ref: 418652641
Node: @ /1652758
Ref: refman/control/call_in_this_1 doc652844
Ref: 419652844
Ref: refman/control/call_in_this_1 call-in-this-1652844
Ref: 113652844
Ref: refman/control/call_in_this_1 id1652844
Ref: 41a652844
Node: Description<5>653029
Ref: refman/control/call_in_this_1 description653141
Ref: 41b653141
Node: Modes and number of proofs<5>653805
Ref: refman/control/call_in_this_1 modes-and-number-of-proofs653935
Ref: 41c653935
Node: Errors<5>654039
Ref: refman/control/call_in_this_1 errors654166
Ref: 41d654166
Node: Examples<6>654347
Ref: refman/control/call_in_this_1 examples654436
Ref: 41e654436
Node: Calling external predicates654799
Ref: refman/control/external_calls doc654967
Ref: 41f654967
Ref: refman/control/external_calls calling-external-predicates654967
Ref: 420654967
Ref: refman/control/external_calls external-calls654967
Ref: 421654967
Node: {}/1655076
Ref: refman/control/external_call_1 doc655163
Ref: 422655163
Ref: refman/control/external_call_1 control-external-call-1655163
Ref: 191655163
Ref: refman/control/external_call_1 id1655163
Ref: 423655163
Node: Description<6>655346
Ref: refman/control/external_call_1 description655458
Ref: 424655458
Node: Modes and number of proofs<6>656959
Ref: refman/control/external_call_1 modes-and-number-of-proofs657089
Ref: 426657089
Node: Errors<6>657193
Ref: refman/control/external_call_1 errors657320
Ref: 427657320
Node: Examples<7>657890
Ref: refman/control/external_call_1 examples657979
Ref: 428657979
Node: Context switching calls658600
Ref: refman/control/context_switching_calls doc658733
Ref: 429658733
Ref: refman/control/context_switching_calls context-switching-calls658733
Ref: 42a658733
Ref: refman/control/context_switching_calls id1658733
Ref: 42b658733
Node: << /2658842
Ref: refman/control/context_switch_2 doc658926
Ref: 42c658926
Ref: refman/control/context_switch_2 control-context-switch-2658926
Ref: c7658926
Ref: refman/control/context_switch_2 id1658926
Ref: 42d658926
Node: Description<7>659113
Ref: refman/control/context_switch_2 description659226
Ref: 42e659226
Node: Modes and number of proofs<7>660769
Ref: refman/control/context_switch_2 modes-and-number-of-proofs660900
Ref: 42f660900
Node: Errors<7>661074
Ref: refman/control/context_switch_2 errors661202
Ref: 430661202
Node: Examples<8>662310
Ref: refman/control/context_switch_2 examples662400
Ref: 431662400
Node: Directives<2>662569
Ref: refman/directives/index doc662709
Ref: 432662709
Ref: refman/directives/index directives662709
Ref: 433662709
Node: Source file directives<2>662951
Ref: refman/directives/source_file_directives doc663091
Ref: 434663091
Ref: refman/directives/source_file_directives id1663091
Ref: 435663091
Ref: refman/directives/source_file_directives source-file-directives663091
Ref: 436663091
Node: encoding/1663255
Ref: refman/directives/encoding_1 doc663364
Ref: 437663364
Ref: refman/directives/encoding_1 directives-encoding-1663364
Ref: 298663364
Ref: refman/directives/encoding_1 encoding-1663364
Ref: 438663364
Node: Description<8>663500
Ref: refman/directives/encoding_1 description663607
Ref: 439663607
Ref: Description<8>-Footnote-1665080
Node: Template and modes665157
Ref: refman/directives/encoding_1 template-and-modes665284
Ref: 43a665284
Node: Examples<9>665361
Ref: refman/directives/encoding_1 examples665465
Ref: 43b665465
Node: include/1665541
Ref: refman/directives/include_1 doc665675
Ref: 43c665675
Ref: refman/directives/include_1 directives-include-1665675
Ref: b8665675
Ref: refman/directives/include_1 include-1665675
Ref: 43d665675
Node: Description<9>665832
Ref: refman/directives/include_1 description665941
Ref: 43e665941
Node: Template and modes<2>667844
Ref: refman/directives/include_1 template-and-modes667974
Ref: 43f667974
Node: Examples<10>668062
Ref: refman/directives/include_1 examples668169
Ref: 440668169
Node: initialization/1668775
Ref: refman/directives/initialization_1 doc668903
Ref: 441668903
Ref: refman/directives/initialization_1 directives-initialization-1668903
Ref: 42668903
Ref: refman/directives/initialization_1 initialization-1668903
Ref: 442668903
Node: Description<10>669075
Ref: refman/directives/initialization_1 description669192
Ref: 443669192
Node: Template and modes<3>670816
Ref: refman/directives/initialization_1 template-and-modes670954
Ref: 444670954
Node: Examples<11>671043
Ref: refman/directives/initialization_1 examples671157
Ref: 445671157
Node: op/3671737
Ref: refman/directives/op_3 doc671874
Ref: 446671874
Ref: refman/directives/op_3 directives-op-3671874
Ref: 15d671874
Ref: refman/directives/op_3 op-3671874
Ref: 447671874
Node: Description<11>672024
Ref: refman/directives/op_3 description672129
Ref: 448672129
Node: Template and modes<4>672580
Ref: refman/directives/op_3 template-and-modes672706
Ref: 449672706
Node: Examples<12>672818
Ref: refman/directives/op_3 examples672920
Ref: 44a672920
Node: set_logtalk_flag/2674000
Ref: refman/directives/set_logtalk_flag_2 doc674112
Ref: 44b674112
Ref: refman/directives/set_logtalk_flag_2 directives-set-logtalk-flag-2674112
Ref: 50674112
Ref: refman/directives/set_logtalk_flag_2 set-logtalk-flag-2674112
Ref: 44c674112
Node: Description<12>674311
Ref: refman/directives/set_logtalk_flag_2 description674430
Ref: 44d674430
Node: Template and modes<5>674977
Ref: refman/directives/set_logtalk_flag_2 template-and-modes675114
Ref: 44e675114
Node: Errors<8>675210
Ref: refman/directives/set_logtalk_flag_2 errors675344
Ref: 44f675344
Node: Examples<13>675843
Ref: refman/directives/set_logtalk_flag_2 examples675947
Ref: 450675947
Node: Conditional compilation directives<2>676518
Ref: refman/directives/conditional_compilation_directives doc676684
Ref: 451676684
Ref: refman/directives/conditional_compilation_directives conditional-compilation-directives676684
Ref: 18a676684
Ref: refman/directives/conditional_compilation_directives id1676684
Ref: 452676684
Node: if/1676833
Ref: refman/directives/if_1 doc676945
Ref: 453676945
Ref: refman/directives/if_1 directives-if-1676945
Ref: 2f2676945
Ref: refman/directives/if_1 if-1676945
Ref: 454676945
Node: Description<13>677093
Ref: refman/directives/if_1 description677198
Ref: 455677198
Node: Template and modes<6>677982
Ref: refman/directives/if_1 template-and-modes678108
Ref: 456678108
Node: Examples<14>678183
Ref: refman/directives/if_1 examples678285
Ref: 457678285
Node: elif/1679177
Ref: refman/directives/elif_1 doc679304
Ref: 458679304
Ref: refman/directives/elif_1 directives-elif-1679304
Ref: 2f3679304
Ref: refman/directives/elif_1 elif-1679304
Ref: 459679304
Node: Description<14>679456
Ref: refman/directives/elif_1 description679563
Ref: 45a679563
Node: Template and modes<7>680301
Ref: refman/directives/elif_1 template-and-modes680429
Ref: 45b680429
Node: Examples<15>680506
Ref: refman/directives/elif_1 examples680610
Ref: 45c680610
Node: else/0680963
Ref: refman/directives/else_0 doc681093
Ref: 45d681093
Ref: refman/directives/else_0 directives-else-0681093
Ref: 2f4681093
Ref: refman/directives/else_0 else-0681093
Ref: 45e681093
Node: Description<15>681245
Ref: refman/directives/else_0 description681352
Ref: 45f681352
Node: Template and modes<8>681607
Ref: refman/directives/else_0 template-and-modes681735
Ref: 460681735
Node: Examples<16>681803
Ref: refman/directives/else_0 examples681907
Ref: 461681907
Node: endif/0682511
Ref: refman/directives/endif_0 doc682626
Ref: 462682626
Ref: refman/directives/endif_0 directives-endif-0682626
Ref: 2f5682626
Ref: refman/directives/endif_0 endif-0682626
Ref: 463682626
Node: Description<16>682782
Ref: refman/directives/endif_0 description682890
Ref: 464682890
Node: Template and modes<9>683020
Ref: refman/directives/endif_0 template-and-modes683149
Ref: 465683149
Node: Examples<17>683218
Ref: refman/directives/endif_0 examples683323
Ref: 466683323
Node: Entity directives683543
Ref: refman/directives/entity_directives doc683707
Ref: 467683707
Ref: refman/directives/entity_directives entity-directives683707
Ref: 468683707
Ref: refman/directives/entity_directives id1683707
Ref: 469683707
Node: built_in/0683966
Ref: refman/directives/built_in_0 doc684070
Ref: 46a684070
Ref: refman/directives/built_in_0 built-in-0684070
Ref: 46b684070
Ref: refman/directives/built_in_0 directives-built-in-0684070
Ref: 46c684070
Node: Description<17>684231
Ref: refman/directives/built_in_0 description684343
Ref: 46d684343
Node: Template and modes<10>684623
Ref: refman/directives/built_in_0 template-and-modes684756
Ref: 46e684756
Node: Examples<18>684826
Ref: refman/directives/built_in_0 examples684935
Ref: 46f684935
Node: category/1-4685002
Ref: refman/directives/category_1_4 doc685124
Ref: 470685124
Ref: refman/directives/category_1_4 category-1-4685124
Ref: 471685124
Ref: refman/directives/category_1_4 directives-category-1-4685124
Ref: 10e685124
Node: Description<18>685289
Ref: refman/directives/category_1_4 description685403
Ref: 472685403
Node: Template and modes<11>686046
Ref: refman/directives/category_1_4 template-and-modes686181
Ref: 473686181
Node: Examples<19>687052
Ref: refman/directives/category_1_4 examples687163
Ref: 474687163
Node: dynamic/0687577
Ref: refman/directives/dynamic_0 doc687703
Ref: 475687703
Ref: refman/directives/dynamic_0 directives-dynamic-0687703
Ref: b1687703
Ref: refman/directives/dynamic_0 dynamic-0687703
Ref: 476687703
Node: Description<19>687862
Ref: refman/directives/dynamic_0 description687973
Ref: 477687973
Node: Template and modes<12>688605
Ref: refman/directives/dynamic_0 template-and-modes688737
Ref: 478688737
Node: Examples<20>688808
Ref: refman/directives/dynamic_0 examples688916
Ref: 479688916
Node: end_category/0689118
Ref: refman/directives/end_category_0 doc689244
Ref: 47a689244
Ref: refman/directives/end_category_0 directives-end-category-0689244
Ref: 10f689244
Ref: refman/directives/end_category_0 end-category-0689244
Ref: 47b689244
Node: Description<20>689415
Ref: refman/directives/end_category_0 description689531
Ref: 47c689531
Node: Template and modes<13>689621
Ref: refman/directives/end_category_0 template-and-modes689758
Ref: 47d689758
Node: Examples<21>689834
Ref: refman/directives/end_category_0 examples689947
Ref: 47e689947
Node: end_object/0690065
Ref: refman/directives/end_object_0 doc690196
Ref: 47f690196
Ref: refman/directives/end_object_0 directives-end-object-0690196
Ref: 9b690196
Ref: refman/directives/end_object_0 end-object-0690196
Ref: 480690196
Node: Description<21>690363
Ref: refman/directives/end_object_0 description690477
Ref: 481690477
Node: Template and modes<14>690563
Ref: refman/directives/end_object_0 template-and-modes690698
Ref: 482690698
Node: Examples<22>690772
Ref: refman/directives/end_object_0 examples690883
Ref: 483690883
Node: end_protocol/0690996
Ref: refman/directives/end_protocol_0 doc691119
Ref: 484691119
Ref: refman/directives/end_protocol_0 directives-end-protocol-0691119
Ref: dd691119
Ref: refman/directives/end_protocol_0 end-protocol-0691119
Ref: 485691119
Node: Description<22>691290
Ref: refman/directives/end_protocol_0 description691406
Ref: 486691406
Node: Template and modes<15>691496
Ref: refman/directives/end_protocol_0 template-and-modes691633
Ref: 487691633
Node: Examples<23>691709
Ref: refman/directives/end_protocol_0 examples691822
Ref: 488691822
Node: info/1691939
Ref: refman/directives/info_1 doc692060
Ref: 489692060
Ref: refman/directives/info_1 directives-info-1692060
Ref: b4692060
Ref: refman/directives/info_1 info-1692060
Ref: 48a692060
Node: Description<23>692215
Ref: refman/directives/info_1 description692323
Ref: 48b692323
Node: Template and modes<16>692636
Ref: refman/directives/info_1 template-and-modes692765
Ref: 48c692765
Node: Examples<24>692852
Ref: refman/directives/info_1 examples692957
Ref: 48d692957
Node: object/1-5693290
Ref: refman/directives/object_1_5 doc693409
Ref: 48e693409
Ref: refman/directives/object_1_5 directives-object-1-5693409
Ref: 9a693409
Ref: refman/directives/object_1_5 object-1-5693409
Ref: 48f693409
Node: Description<24>693572
Ref: refman/directives/object_1_5 description693684
Ref: 490693684
Node: Template and modes<17>695525
Ref: refman/directives/object_1_5 template-and-modes695658
Ref: 491695658
Node: Examples<25>698209
Ref: refman/directives/object_1_5 examples698318
Ref: 492698318
Node: protocol/1-2698861
Ref: refman/directives/protocol_1_2 doc698984
Ref: 493698984
Ref: refman/directives/protocol_1_2 directives-protocol-1-2698984
Ref: dc698984
Ref: refman/directives/protocol_1_2 protocol-1-2698984
Ref: 494698984
Node: Description<25>699151
Ref: refman/directives/protocol_1_2 description699265
Ref: 495699265
Node: Template and modes<18>699417
Ref: refman/directives/protocol_1_2 template-and-modes699552
Ref: 496699552
Node: Examples<26>699722
Ref: refman/directives/protocol_1_2 examples699833
Ref: 497699833
Node: threaded/0700073
Ref: refman/directives/threaded_0 doc700192
Ref: 498700192
Ref: refman/directives/threaded_0 directives-threaded-0700192
Ref: 228700192
Ref: refman/directives/threaded_0 threaded-0700192
Ref: 499700192
Node: Description<26>700355
Ref: refman/directives/threaded_0 description700467
Ref: 49a700467
Node: Template and modes<19>701546
Ref: refman/directives/threaded_0 template-and-modes701679
Ref: 49b701679
Node: Examples<27>701751
Ref: refman/directives/threaded_0 examples701860
Ref: 49c701860
Node: uses/1702004
Ref: refman/directives/uses_1 doc702123
Ref: 49d702123
Ref: refman/directives/uses_1 directives-uses-1702123
Ref: 4a702123
Ref: refman/directives/uses_1 uses-1702123
Ref: 49e702123
Node: Description<27>702278
Ref: refman/directives/uses_1 description702386
Ref: 49f702386
Node: Template and modes<20>703494
Ref: refman/directives/uses_1 template-and-modes703623
Ref: 4a0703623
Node: Examples<28>703711
Ref: refman/directives/uses_1 examples703816
Ref: 4a1703816
Node: use_module/1704583
Ref: refman/directives/use_module_1 doc704683
Ref: 4a2704683
Ref: refman/directives/use_module_1 directives-use-module-1704683
Ref: 4c704683
Ref: refman/directives/use_module_1 use-module-1704683
Ref: 4a3704683
Node: Description<28>704850
Ref: refman/directives/use_module_1 description704964
Ref: 4a4704964
Node: Template and modes<21>706128
Ref: refman/directives/use_module_1 template-and-modes706263
Ref: 4a5706263
Node: Examples<29>706357
Ref: refman/directives/use_module_1 examples706468
Ref: 4a6706468
Node: Predicate directives<2>706964
Ref: refman/directives/predicate_directives doc707082
Ref: 4a7707082
Ref: refman/directives/predicate_directives id1707082
Ref: 4a8707082
Ref: refman/directives/predicate_directives predicate-directives707082
Ref: 4a9707082
Node: alias/2707421
Ref: refman/directives/alias_2 doc707529
Ref: 4aa707529
Ref: refman/directives/alias_2 alias-2707529
Ref: 4ab707529
Ref: refman/directives/alias_2 directives-alias-2707529
Ref: 165707529
Node: Description<29>707684
Ref: refman/directives/alias_2 description707793
Ref: 4ac707793
Node: Template and modes<22>708904
Ref: refman/directives/alias_2 template-and-modes709034
Ref: 4ad709034
Node: Examples<30>709223
Ref: refman/directives/alias_2 examples709329
Ref: 4ae709329
Node: coinductive/1709706
Ref: refman/directives/coinductive_1 doc709838
Ref: 4af709838
Ref: refman/directives/coinductive_1 coinductive-1709838
Ref: 4b0709838
Ref: refman/directives/coinductive_1 directives-coinductive-1709838
Ref: 171709838
Node: Description<30>710005
Ref: refman/directives/coinductive_1 description710120
Ref: 4b1710120
Node: Template and modes<23>711749
Ref: refman/directives/coinductive_1 template-and-modes711885
Ref: 4b3711885
Node: Examples<31>712087
Ref: refman/directives/coinductive_1 examples712199
Ref: 4b4712199
Node: discontiguous/1712459
Ref: refman/directives/discontiguous_1 doc712593
Ref: 4b5712593
Ref: refman/directives/discontiguous_1 directives-discontiguous-1712593
Ref: 157712593
Ref: refman/directives/discontiguous_1 discontiguous-1712593
Ref: 4b6712593
Node: Description<31>712764
Ref: refman/directives/discontiguous_1 description712881
Ref: 4b7712881
Node: Template and modes<24>714104
Ref: refman/directives/discontiguous_1 template-and-modes714242
Ref: 4b9714242
Node: Examples<32>714395
Ref: refman/directives/discontiguous_1 examples714509
Ref: 4ba714509
Node: dynamic/1714685
Ref: refman/directives/dynamic_1 doc714812
Ref: 4bb714812
Ref: refman/directives/dynamic_1 directives-dynamic-1714812
Ref: 15a714812
Ref: refman/directives/dynamic_1 dynamic-1714812
Ref: 4bc714812
Node: Description<32>714973
Ref: refman/directives/dynamic_1 description715084
Ref: 4bd715084
Node: Template and modes<25>716835
Ref: refman/directives/dynamic_1 template-and-modes716967
Ref: 4bf716967
Node: Examples<33>717128
Ref: refman/directives/dynamic_1 examples717236
Ref: 4c0717236
Node: info/2717468
Ref: refman/directives/info_2 doc717596
Ref: 4c1717596
Ref: refman/directives/info_2 directives-info-2717596
Ref: 168717596
Ref: refman/directives/info_2 info-2717596
Ref: 4c2717596
Node: Description<33>717751
Ref: refman/directives/info_2 description717859
Ref: 4c3717859
Node: Template and modes<26>718329
Ref: refman/directives/info_2 template-and-modes718458
Ref: 4c4718458
Node: Examples<34>718627
Ref: refman/directives/info_2 examples718732
Ref: 4c5718732
Node: meta_predicate/1719116
Ref: refman/directives/meta_predicate_1 doc719254
Ref: 4c6719254
Ref: refman/directives/meta_predicate_1 directives-meta-predicate-1719254
Ref: 152719254
Ref: refman/directives/meta_predicate_1 meta-predicate-1719254
Ref: 4c7719254
Node: Description<34>719429
Ref: refman/directives/meta_predicate_1 description719547
Ref: 4c8719547
Node: Template and modes<27>721707
Ref: refman/directives/meta_predicate_1 template-and-modes721846
Ref: 4c9721846
Node: Examples<35>722171
Ref: refman/directives/meta_predicate_1 examples722286
Ref: 4ca722286
Node: meta_non_terminal/1722796
Ref: refman/directives/meta_non_terminal_1 doc722934
Ref: 4cb722934
Ref: refman/directives/meta_non_terminal_1 directives-meta-non-terminal-1722934
Ref: 153722934
Ref: refman/directives/meta_non_terminal_1 meta-non-terminal-1722934
Ref: 4cc722934
Node: Description<35>723115
Ref: refman/directives/meta_non_terminal_1 description723236
Ref: 4cd723236
Node: Template and modes<28>724548
Ref: refman/directives/meta_non_terminal_1 template-and-modes724690
Ref: 4ce724690
Node: Examples<36>725039
Ref: refman/directives/meta_non_terminal_1 examples725157
Ref: 4cf725157
Node: mode/2725365
Ref: refman/directives/mode_2 doc725506
Ref: 4d0725506
Ref: refman/directives/mode_2 directives-mode-2725506
Ref: 149725506
Ref: refman/directives/mode_2 mode-2725506
Ref: 4d1725506
Node: Description<36>725661
Ref: refman/directives/mode_2 description725769
Ref: 4d2725769
Node: Template and modes<29>726154
Ref: refman/directives/mode_2 template-and-modes726283
Ref: 4d3726283
Node: Examples<37>726446
Ref: refman/directives/mode_2 examples726551
Ref: 4d4726551
Node: mode_non_terminal/2726919
Ref: refman/directives/mode_non_terminal_2 doc727052
Ref: 4d5727052
Ref: refman/directives/mode_non_terminal_2 directives-mode-non-terminal-2727052
Ref: 14a727052
Ref: refman/directives/mode_non_terminal_2 mode-non-terminal-2727052
Ref: 4d6727052
Node: Description<37>727233
Ref: refman/directives/mode_non_terminal_2 description727354
Ref: 4d7727354
Node: Template and modes<30>727755
Ref: refman/directives/mode_non_terminal_2 template-and-modes727897
Ref: 4d8727897
Node: Examples<38>728086
Ref: refman/directives/mode_non_terminal_2 examples728204
Ref: 4d9728204
Node: multifile/1728407
Ref: refman/directives/multifile_1 doc728543
Ref: 4da728543
Ref: refman/directives/multifile_1 directives-multifile-1728543
Ref: 16c728543
Ref: refman/directives/multifile_1 multifile-1728543
Ref: 4db728543
Node: Description<38>728708
Ref: refman/directives/multifile_1 description728821
Ref: 4dc728821
Node: Template and modes<31>730425
Ref: refman/directives/multifile_1 template-and-modes730559
Ref: 4dd730559
Node: Examples<39>730724
Ref: refman/directives/multifile_1 examples730834
Ref: 4de730834
Node: private/1731066
Ref: refman/directives/private_1 doc731194
Ref: 4df731194
Ref: refman/directives/private_1 directives-private-1731194
Ref: 145731194
Ref: refman/directives/private_1 private-1731194
Ref: 4e0731194
Node: Description<39>731355
Ref: refman/directives/private_1 description731466
Ref: 4e1731466
Node: Template and modes<32>732216
Ref: refman/directives/private_1 template-and-modes732348
Ref: 4e2732348
Node: Examples<40>732525
Ref: refman/directives/private_1 examples732633
Ref: 4e3732633
Node: protected/1732889
Ref: refman/directives/protected_1 doc733014
Ref: 4e4733014
Ref: refman/directives/protected_1 directives-protected-1733014
Ref: 144733014
Ref: refman/directives/protected_1 protected-1733014
Ref: 4e5733014
Node: Description<40>733179
Ref: refman/directives/protected_1 description733292
Ref: 4e6733292
Node: Template and modes<33>734313
Ref: refman/directives/protected_1 template-and-modes734447
Ref: 4e7734447
Node: Examples<41>734630
Ref: refman/directives/protected_1 examples734740
Ref: 4e8734740
Node: public/1734994
Ref: refman/directives/public_1 doc735124
Ref: 4e9735124
Ref: refman/directives/public_1 directives-public-1735124
Ref: 143735124
Ref: refman/directives/public_1 public-1735124
Ref: 4ea735124
Node: Description<41>735283
Ref: refman/directives/public_1 description735393
Ref: 4eb735393
Node: Template and modes<34>736347
Ref: refman/directives/public_1 template-and-modes736478
Ref: 4ec736478
Node: Examples<42>736652
Ref: refman/directives/public_1 examples736759
Ref: 4ed736759
Node: synchronized/1737018
Ref: refman/directives/synchronized_1 doc737143
Ref: 4ee737143
Ref: refman/directives/synchronized_1 directives-synchronized-1737143
Ref: 74737143
Ref: refman/directives/synchronized_1 synchronized-1737143
Ref: 4ef737143
Node: Description<42>737314
Ref: refman/directives/synchronized_1 description737430
Ref: 4f0737430
Node: Template and modes<35>738818
Ref: refman/directives/synchronized_1 template-and-modes738955
Ref: 4f1738955
Node: Examples<43>739106
Ref: refman/directives/synchronized_1 examples739219
Ref: 4f2739219
Node: uses/2739476
Ref: refman/directives/uses_2 doc739605
Ref: 4f3739605
Ref: refman/directives/uses_2 directives-uses-2739605
Ref: 4b739605
Ref: refman/directives/uses_2 uses-2739605
Ref: 4f4739605
Node: Description<43>739760
Ref: refman/directives/uses_2 description739868
Ref: 4f5739868
Node: Template and modes<36>742315
Ref: refman/directives/uses_2 template-and-modes742444
Ref: 4f6742444
Node: Examples<44>742859
Ref: refman/directives/uses_2 examples742964
Ref: 4f7742964
Node: use_module/2744758
Ref: refman/directives/use_module_2 doc744864
Ref: 4f8744864
Ref: refman/directives/use_module_2 directives-use-module-2744864
Ref: 4d744864
Ref: refman/directives/use_module_2 use-module-2744864
Ref: 4f9744864
Node: Description<44>745031
Ref: refman/directives/use_module_2 description745145
Ref: 4fa745145
Node: Template and modes<37>748501
Ref: refman/directives/use_module_2 template-and-modes748636
Ref: 4fb748636
Node: Examples<45>749101
Ref: refman/directives/use_module_2 examples749212
Ref: 4fc749212
Node: Built-in predicates750579
Ref: refman/predicates/index doc750720
Ref: 4fd750720
Ref: refman/predicates/index built-in-predicates750720
Ref: 4fe750720
Node: Enumerating objects categories and protocols751418
Ref: refman/predicates/enumerating_entity_predicates doc751601
Ref: 4ff751601
Ref: refman/predicates/enumerating_entity_predicates enumerating-entity-predicates751601
Ref: 284751601
Ref: refman/predicates/enumerating_entity_predicates enumerating-objects-categories-and-protocols751601
Ref: 500751601
Node: current_category/1751805
Ref: refman/predicates/current_category_1 doc751948
Ref: 501751948
Ref: refman/predicates/current_category_1 current-category-1751948
Ref: 502751948
Ref: refman/predicates/current_category_1 predicates-current-category-1751948
Ref: f1751948
Node: Description<45>752161
Ref: refman/predicates/current_category_1 description752288
Ref: 503752288
Node: Modes and number of proofs<8>752490
Ref: refman/predicates/current_category_1 modes-and-number-of-proofs752635
Ref: 504752635
Node: Errors<9>752766
Ref: refman/predicates/current_category_1 errors752908
Ref: 505752908
Node: Examples<46>753073
Ref: refman/predicates/current_category_1 examples753177
Ref: 506753177
Node: current_object/1753565
Ref: refman/predicates/current_object_1 doc753735
Ref: 507753735
Ref: refman/predicates/current_object_1 current-object-1753735
Ref: 508753735
Ref: refman/predicates/current_object_1 predicates-current-object-1753735
Ref: a6753735
Node: Description<46>753945
Ref: refman/predicates/current_object_1 description754070
Ref: 509754070
Node: Modes and number of proofs<9>754261
Ref: refman/predicates/current_object_1 modes-and-number-of-proofs754405
Ref: 50a754405
Node: Errors<10>754532
Ref: refman/predicates/current_object_1 errors754673
Ref: 50b754673
Node: Examples<47>754830
Ref: refman/predicates/current_object_1 examples754933
Ref: 50c754933
Node: current_protocol/1755353
Ref: refman/predicates/current_protocol_1 doc755496
Ref: 50d755496
Ref: refman/predicates/current_protocol_1 current-protocol-1755496
Ref: 50e755496
Ref: refman/predicates/current_protocol_1 predicates-current-protocol-1755496
Ref: e0755496
Node: Description<47>755713
Ref: refman/predicates/current_protocol_1 description755841
Ref: 50f755841
Node: Modes and number of proofs<10>756043
Ref: refman/predicates/current_protocol_1 modes-and-number-of-proofs756190
Ref: 510756190
Node: Errors<11>756323
Ref: refman/predicates/current_protocol_1 errors756467
Ref: 511756467
Node: Examples<48>756634
Ref: refman/predicates/current_protocol_1 examples756739
Ref: 512756739
Node: Enumerating objects categories and protocols properties757164
Ref: refman/predicates/enumerating_entity_property_predicates doc757401
Ref: 513757401
Ref: refman/predicates/enumerating_entity_property_predicates enumerating-entity-property-predicates757401
Ref: 6f757401
Ref: refman/predicates/enumerating_entity_property_predicates enumerating-objects-categories-and-protocols-properties757401
Ref: 514757401
Node: category_property/2757630
Ref: refman/predicates/category_property_2 doc757786
Ref: 515757786
Ref: refman/predicates/category_property_2 category-property-2757786
Ref: 516757786
Ref: refman/predicates/category_property_2 predicates-category-property-2757786
Ref: 12c757786
Node: Description<48>758003
Ref: refman/predicates/category_property_2 description758132
Ref: 517758132
Node: Modes and number of proofs<11>758475
Ref: refman/predicates/category_property_2 modes-and-number-of-proofs758623
Ref: 518758623
Node: Errors<12>758775
Ref: refman/predicates/category_property_2 errors758920
Ref: 519758920
Node: Examples<49>759338
Ref: refman/predicates/category_property_2 examples759444
Ref: 51a759444
Node: object_property/2759927
Ref: refman/predicates/object_property_2 doc760111
Ref: 51b760111
Ref: refman/predicates/object_property_2 object-property-2760111
Ref: 51c760111
Ref: refman/predicates/object_property_2 predicates-object-property-2760111
Ref: c6760111
Node: Description<49>760324
Ref: refman/predicates/object_property_2 description760451
Ref: 51d760451
Node: Modes and number of proofs<12>760784
Ref: refman/predicates/object_property_2 modes-and-number-of-proofs760930
Ref: 51e760930
Node: Errors<13>761076
Ref: refman/predicates/object_property_2 errors761219
Ref: 51f761219
Node: Examples<50>761614
Ref: refman/predicates/object_property_2 examples761718
Ref: 520761718
Node: protocol_property/2762281
Ref: refman/predicates/protocol_property_2 doc762437
Ref: 521762437
Ref: refman/predicates/protocol_property_2 predicates-protocol-property-2762437
Ref: f4762437
Ref: refman/predicates/protocol_property_2 protocol-property-2762437
Ref: 522762437
Node: Description<50>762656
Ref: refman/predicates/protocol_property_2 description762785
Ref: 523762785
Node: Modes and number of proofs<13>763138
Ref: refman/predicates/protocol_property_2 modes-and-number-of-proofs763286
Ref: 524763286
Node: Errors<14>763440
Ref: refman/predicates/protocol_property_2 errors763585
Ref: 525763585
Node: Examples<51>763994
Ref: refman/predicates/protocol_property_2 examples764100
Ref: 526764100
Node: Creating new objects categories and protocols764562
Ref: refman/predicates/creating_entity_predicates doc764798
Ref: 527764798
Ref: refman/predicates/creating_entity_predicates creating-entity-predicates764798
Ref: 528764798
Ref: refman/predicates/creating_entity_predicates creating-new-objects-categories-and-protocols764798
Ref: 529764798
Node: create_category/4765001
Ref: refman/predicates/create_category_4 doc765143
Ref: 52a765143
Ref: refman/predicates/create_category_4 create-category-4765143
Ref: 52b765143
Ref: refman/predicates/create_category_4 predicates-create-category-4765143
Ref: 11a765143
Node: Description<51>765356
Ref: refman/predicates/create_category_4 description765483
Ref: 52c765483
Node: Modes and number of proofs<14>766378
Ref: refman/predicates/create_category_4 modes-and-number-of-proofs766524
Ref: 52d766524
Node: Errors<15>766713
Ref: refman/predicates/create_category_4 errors766856
Ref: 52e766856
Node: Examples<52>767929
Ref: refman/predicates/create_category_4 examples768033
Ref: 52f768033
Node: create_object/4768494
Ref: refman/predicates/create_object_4 doc768662
Ref: 530768662
Ref: refman/predicates/create_object_4 create-object-4768662
Ref: 531768662
Ref: refman/predicates/create_object_4 predicates-create-object-4768662
Ref: 62768662
Node: Description<52>768871
Ref: refman/predicates/create_object_4 description768996
Ref: 532768996
Node: Modes and number of proofs<15>770134
Ref: refman/predicates/create_object_4 modes-and-number-of-proofs770278
Ref: 534770278
Node: Errors<16>770459
Ref: refman/predicates/create_object_4 errors770600
Ref: 535770600
Node: Examples<53>771812
Ref: refman/predicates/create_object_4 examples771914
Ref: 536771914
Node: create_protocol/3773458
Ref: refman/predicates/create_protocol_3 doc773600
Ref: 537773600
Ref: refman/predicates/create_protocol_3 create-protocol-3773600
Ref: 538773600
Ref: refman/predicates/create_protocol_3 predicates-create-protocol-3773600
Ref: e3773600
Node: Description<53>773815
Ref: refman/predicates/create_protocol_3 description773942
Ref: 539773942
Node: Modes and number of proofs<16>774677
Ref: refman/predicates/create_protocol_3 modes-and-number-of-proofs774823
Ref: 53a774823
Node: Errors<17>774999
Ref: refman/predicates/create_protocol_3 errors775142
Ref: 53b775142
Node: Examples<54>775961
Ref: refman/predicates/create_protocol_3 examples776065
Ref: 53c776065
Node: Abolishing objects categories and protocols776472
Ref: refman/predicates/abolishing_entity_predicates doc776695
Ref: 53d776695
Ref: refman/predicates/abolishing_entity_predicates abolishing-entity-predicates776695
Ref: 53e776695
Ref: refman/predicates/abolishing_entity_predicates abolishing-objects-categories-and-protocols776695
Ref: 53f776695
Node: abolish_category/1776897
Ref: refman/predicates/abolish_category_1 doc777039
Ref: 540777039
Ref: refman/predicates/abolish_category_1 abolish-category-1777039
Ref: 541777039
Ref: refman/predicates/abolish_category_1 predicates-abolish-category-1777039
Ref: f5777039
Node: Description<54>777254
Ref: refman/predicates/abolish_category_1 description777382
Ref: 542777382
Node: Modes and number of proofs<17>777561
Ref: refman/predicates/abolish_category_1 modes-and-number-of-proofs777708
Ref: 543777708
Node: Errors<18>777830
Ref: refman/predicates/abolish_category_1 errors777974
Ref: 544777974
Node: Examples<55>778425
Ref: refman/predicates/abolish_category_1 examples778530
Ref: 545778530
Node: abolish_object/1778837
Ref: refman/predicates/abolish_object_1 doc779006
Ref: 546779006
Ref: refman/predicates/abolish_object_1 abolish-object-1779006
Ref: 547779006
Ref: refman/predicates/abolish_object_1 predicates-abolish-object-1779006
Ref: 64779006
Node: Description<55>779217
Ref: refman/predicates/abolish_object_1 description779343
Ref: 548779343
Node: Modes and number of proofs<18>779512
Ref: refman/predicates/abolish_object_1 modes-and-number-of-proofs779657
Ref: 549779657
Node: Errors<19>779775
Ref: refman/predicates/abolish_object_1 errors779917
Ref: 54a779917
Node: Examples<56>780344
Ref: refman/predicates/abolish_object_1 examples780447
Ref: 54b780447
Node: abolish_protocol/1780772
Ref: refman/predicates/abolish_protocol_1 doc780914
Ref: 54c780914
Ref: refman/predicates/abolish_protocol_1 abolish-protocol-1780914
Ref: 54d780914
Ref: refman/predicates/abolish_protocol_1 predicates-abolish-protocol-1780914
Ref: e6780914
Node: Description<56>781131
Ref: refman/predicates/abolish_protocol_1 description781259
Ref: 54e781259
Node: Modes and number of proofs<19>781440
Ref: refman/predicates/abolish_protocol_1 modes-and-number-of-proofs781587
Ref: 54f781587
Node: Errors<20>781711
Ref: refman/predicates/abolish_protocol_1 errors781855
Ref: 550781855
Node: Examples<57>782308
Ref: refman/predicates/abolish_protocol_1 examples782413
Ref: 551782413
Node: Objects categories and protocols relations782699
Ref: refman/predicates/entity_relation_predicates doc782894
Ref: 552782894
Ref: refman/predicates/entity_relation_predicates entity-relation-predicates782894
Ref: 285782894
Ref: refman/predicates/entity_relation_predicates objects-categories-and-protocols-relations782894
Ref: 553782894
Node: extends_object/2-3783262
Ref: refman/predicates/extends_object_2_3 doc783407
Ref: 554783407
Ref: refman/predicates/extends_object_2_3 extends-object-2-3783407
Ref: 555783407
Ref: refman/predicates/extends_object_2_3 predicates-extends-object-2-3783407
Ref: bf783407
Node: Description<57>783622
Ref: refman/predicates/extends_object_2_3 description783750
Ref: 556783750
Node: Modes and number of proofs<20>784070
Ref: refman/predicates/extends_object_2_3 modes-and-number-of-proofs784217
Ref: 557784217
Node: Errors<21>784447
Ref: refman/predicates/extends_object_2_3 errors784591
Ref: 558784591
Node: Examples<58>785071
Ref: refman/predicates/extends_object_2_3 examples785176
Ref: 559785176
Node: extends_protocol/2-3785577
Ref: refman/predicates/extends_protocol_2_3 doc785751
Ref: 55a785751
Ref: refman/predicates/extends_protocol_2_3 extends-protocol-2-3785751
Ref: 55b785751
Ref: refman/predicates/extends_protocol_2_3 predicates-extends-protocol-2-3785751
Ref: f0785751
Node: Description<58>785970
Ref: refman/predicates/extends_protocol_2_3 description786100
Ref: 55c786100
Node: Modes and number of proofs<21>786440
Ref: refman/predicates/extends_protocol_2_3 modes-and-number-of-proofs786589
Ref: 55d786589
Node: Errors<22>786831
Ref: refman/predicates/extends_protocol_2_3 errors786977
Ref: 55e786977
Node: Examples<59>787479
Ref: refman/predicates/extends_protocol_2_3 examples787586
Ref: 55f787586
Node: extends_category/2-3787999
Ref: refman/predicates/extends_category_2_3 doc788178
Ref: 560788178
Ref: refman/predicates/extends_category_2_3 extends-category-2-3788178
Ref: 561788178
Ref: refman/predicates/extends_category_2_3 predicates-extends-category-2-3788178
Ref: 129788178
Node: Description<59>788399
Ref: refman/predicates/extends_category_2_3 description788529
Ref: 562788529
Node: Modes and number of proofs<22>788872
Ref: refman/predicates/extends_category_2_3 modes-and-number-of-proofs789021
Ref: 563789021
Node: Errors<23>789265
Ref: refman/predicates/extends_category_2_3 errors789411
Ref: 564789411
Node: Examples<60>789915
Ref: refman/predicates/extends_category_2_3 examples790022
Ref: 565790022
Node: implements_protocol/2-3790442
Ref: refman/predicates/implements_protocol_2_3 doc790625
Ref: 566790625
Ref: refman/predicates/implements_protocol_2_3 implements-protocol-2-3790625
Ref: 567790625
Ref: refman/predicates/implements_protocol_2_3 predicates-implements-protocol-2-3790625
Ref: c1790625
Node: Description<60>790852
Ref: refman/predicates/implements_protocol_2_3 description790985
Ref: 568790985
Node: Modes and number of proofs<23>791571
Ref: refman/predicates/implements_protocol_2_3 modes-and-number-of-proofs791723
Ref: 569791723
Node: Errors<24>792146
Ref: refman/predicates/implements_protocol_2_3 errors792295
Ref: 56a792295
Node: Examples<61>792912
Ref: refman/predicates/implements_protocol_2_3 examples793022
Ref: 56b793022
Node: conforms_to_protocol/2-3793759
Ref: refman/predicates/conforms_to_protocol_2_3 doc793942
Ref: 56c793942
Ref: refman/predicates/conforms_to_protocol_2_3 conforms-to-protocol-2-3793942
Ref: 56d793942
Ref: refman/predicates/conforms_to_protocol_2_3 predicates-conforms-to-protocol-2-3793942
Ref: c2793942
Node: Description<61>794171
Ref: refman/predicates/conforms_to_protocol_2_3 description794305
Ref: 56e794305
Node: Modes and number of proofs<24>794842
Ref: refman/predicates/conforms_to_protocol_2_3 modes-and-number-of-proofs794995
Ref: 56f794995
Node: Errors<25>795422
Ref: refman/predicates/conforms_to_protocol_2_3 errors795572
Ref: 570795572
Node: Examples<62>796189
Ref: refman/predicates/conforms_to_protocol_2_3 examples796300
Ref: 571796300
Node: complements_object/2797070
Ref: refman/predicates/complements_object_2 doc797250
Ref: 572797250
Ref: refman/predicates/complements_object_2 complements-object-2797250
Ref: 573797250
Ref: refman/predicates/complements_object_2 predicates-complements-object-2797250
Ref: c3797250
Node: Description<62>797471
Ref: refman/predicates/complements_object_2 description797601
Ref: 574797601
Node: Modes and number of proofs<25>797803
Ref: refman/predicates/complements_object_2 modes-and-number-of-proofs797952
Ref: 575797952
Node: Errors<26>798107
Ref: refman/predicates/complements_object_2 errors798253
Ref: 576798253
Node: Examples<63>798546
Ref: refman/predicates/complements_object_2 examples798653
Ref: 577798653
Node: imports_category/2-3798916
Ref: refman/predicates/imports_category_2_3 doc799094
Ref: 578799094
Ref: refman/predicates/imports_category_2_3 imports-category-2-3799094
Ref: 579799094
Ref: refman/predicates/imports_category_2_3 predicates-imports-category-2-3799094
Ref: c0799094
Node: Description<63>799315
Ref: refman/predicates/imports_category_2_3 description799445
Ref: 57a799445
Node: Modes and number of proofs<26>799759
Ref: refman/predicates/imports_category_2_3 modes-and-number-of-proofs799908
Ref: 57b799908
Node: Errors<27>800148
Ref: refman/predicates/imports_category_2_3 errors800294
Ref: 57c800294
Node: Examples<64>800778
Ref: refman/predicates/imports_category_2_3 examples800885
Ref: 57d800885
Node: instantiates_class/2-3801278
Ref: refman/predicates/instantiates_class_2_3 doc801457
Ref: 57e801457
Ref: refman/predicates/instantiates_class_2_3 instantiates-class-2-3801457
Ref: 57f801457
Ref: refman/predicates/instantiates_class_2_3 predicates-instantiates-class-2-3801457
Ref: bd801457
Node: Description<64>801682
Ref: refman/predicates/instantiates_class_2_3 description801814
Ref: 580801814
Node: Modes and number of proofs<27>802145
Ref: refman/predicates/instantiates_class_2_3 modes-and-number-of-proofs802296
Ref: 581802296
Node: Errors<28>802536
Ref: refman/predicates/instantiates_class_2_3 errors802684
Ref: 582802684
Node: Examples<65>803162
Ref: refman/predicates/instantiates_class_2_3 examples803271
Ref: 583803271
Node: specializes_class/2-3803712
Ref: refman/predicates/specializes_class_2_3 doc803862
Ref: 584803862
Ref: refman/predicates/specializes_class_2_3 predicates-specializes-class-2-3803862
Ref: be803862
Ref: refman/predicates/specializes_class_2_3 specializes-class-2-3803862
Ref: 585803862
Node: Description<65>804085
Ref: refman/predicates/specializes_class_2_3 description804216
Ref: 586804216
Node: Modes and number of proofs<28>804548
Ref: refman/predicates/specializes_class_2_3 modes-and-number-of-proofs804698
Ref: 587804698
Node: Errors<29>804936
Ref: refman/predicates/specializes_class_2_3 errors805083
Ref: 588805083
Node: Examples<66>805565
Ref: refman/predicates/specializes_class_2_3 examples805673
Ref: 589805673
Node: Event handling<2>806077
Ref: refman/predicates/event_handling_predicates doc806244
Ref: 58a806244
Ref: refman/predicates/event_handling_predicates event-handling806244
Ref: 58b806244
Ref: refman/predicates/event_handling_predicates event-handling-predicates806244
Ref: 71806244
Node: abolish_events/5806380
Ref: refman/predicates/abolish_events_5 doc806493
Ref: 58c806493
Ref: refman/predicates/abolish_events_5 abolish-events-5806493
Ref: 58d806493
Ref: refman/predicates/abolish_events_5 predicates-abolish-events-5806493
Ref: 21b806493
Node: Description<66>806704
Ref: refman/predicates/abolish_events_5 description806830
Ref: 58e806830
Node: Modes and number of proofs<29>807148
Ref: refman/predicates/abolish_events_5 modes-and-number-of-proofs807293
Ref: 58f807293
Node: Errors<30>807426
Ref: refman/predicates/abolish_events_5 errors807568
Ref: 590807568
Node: Examples<67>808195
Ref: refman/predicates/abolish_events_5 examples808298
Ref: 591808298
Node: current_event/5808638
Ref: refman/predicates/current_event_5 doc808775
Ref: 592808775
Ref: refman/predicates/current_event_5 current-event-5808775
Ref: 593808775
Ref: refman/predicates/current_event_5 predicates-current-event-5808775
Ref: 21e808775
Node: Description<67>808984
Ref: refman/predicates/current_event_5 description809109
Ref: 594809109
Node: Modes and number of proofs<30>809345
Ref: refman/predicates/current_event_5 modes-and-number-of-proofs809489
Ref: 595809489
Node: Errors<31>809644
Ref: refman/predicates/current_event_5 errors809785
Ref: 596809785
Node: Examples<68>810412
Ref: refman/predicates/current_event_5 examples810514
Ref: 597810514
Node: define_events/5810823
Ref: refman/predicates/define_events_5 doc810935
Ref: 598810935
Ref: refman/predicates/define_events_5 define-events-5810935
Ref: 599810935
Ref: refman/predicates/define_events_5 predicates-define-events-5810935
Ref: 218810935
Node: Description<68>811146
Ref: refman/predicates/define_events_5 description811271
Ref: 59a811271
Node: Modes and number of proofs<31>811688
Ref: refman/predicates/define_events_5 modes-and-number-of-proofs811832
Ref: 59b811832
Node: Errors<32>811979
Ref: refman/predicates/define_events_5 errors812120
Ref: 59c812120
Node: Examples<69>813065
Ref: refman/predicates/define_events_5 examples813167
Ref: 59d813167
Node: Multi-threading813479
Ref: refman/predicates/multi_threading_predicates doc813627
Ref: 59e813627
Ref: refman/predicates/multi_threading_predicates multi-threading813627
Ref: 59f813627
Ref: refman/predicates/multi_threading_predicates multi-threading-predicates813627
Ref: 5a0813627
Node: threaded/1813893
Ref: refman/predicates/threaded_1 doc814000
Ref: 5a1814000
Ref: refman/predicates/threaded_1 predicates-threaded-1814000
Ref: 22b814000
Ref: refman/predicates/threaded_1 threaded-1814000
Ref: 5a2814000
Node: Description<69>814227
Ref: refman/predicates/threaded_1 description814340
Ref: 5a3814340
Node: Meta-predicate template816106
Ref: refman/predicates/threaded_1 meta-predicate-template816258
Ref: 5a4816258
Node: Modes and number of proofs<32>816341
Ref: refman/predicates/threaded_1 modes-and-number-of-proofs816488
Ref: 5a5816488
Node: Errors<33>816599
Ref: refman/predicates/threaded_1 errors816735
Ref: 5a6816735
Node: Examples<70>817141
Ref: refman/predicates/threaded_1 examples817238
Ref: 5a7817238
Node: threaded_call/1-2817638
Ref: refman/predicates/threaded_call_1_2 doc817771
Ref: 5a8817771
Ref: refman/predicates/threaded_call_1_2 predicates-threaded-call-1-2817771
Ref: 230817771
Ref: refman/predicates/threaded_call_1_2 threaded-call-1-2817771
Ref: 5a9817771
Node: Description<70>818039
Ref: refman/predicates/threaded_call_1_2 description818162
Ref: 5aa818162
Node: Meta-predicate template<2>819121
Ref: refman/predicates/threaded_call_1_2 meta-predicate-template819283
Ref: 5ab819283
Node: Modes and number of proofs<33>819396
Ref: refman/predicates/threaded_call_1_2 modes-and-number-of-proofs819553
Ref: 5ac819553
Node: Errors<34>819709
Ref: refman/predicates/threaded_call_1_2 errors819852
Ref: 5ad819852
Node: Examples<71>820132
Ref: refman/predicates/threaded_call_1_2 examples820236
Ref: 5ae820236
Node: threaded_once/1-2820817
Ref: refman/predicates/threaded_once_1_2 doc820957
Ref: 5af820957
Ref: refman/predicates/threaded_once_1_2 predicates-threaded-once-1-2820957
Ref: 232820957
Ref: refman/predicates/threaded_once_1_2 threaded-once-1-2820957
Ref: 5b0820957
Node: Description<71>821227
Ref: refman/predicates/threaded_once_1_2 description821350
Ref: 5b1821350
Node: Meta-predicate template<3>822239
Ref: refman/predicates/threaded_once_1_2 meta-predicate-template822401
Ref: 5b2822401
Node: Modes and number of proofs<34>822516
Ref: refman/predicates/threaded_once_1_2 modes-and-number-of-proofs822673
Ref: 5b3822673
Node: Errors<35>822829
Ref: refman/predicates/threaded_once_1_2 errors822972
Ref: 5b4822972
Node: Examples<72>823234
Ref: refman/predicates/threaded_once_1_2 examples823338
Ref: 5b5823338
Node: threaded_ignore/1823919
Ref: refman/predicates/threaded_ignore_1 doc824059
Ref: 5b6824059
Ref: refman/predicates/threaded_ignore_1 predicates-threaded-ignore-1824059
Ref: 237824059
Ref: refman/predicates/threaded_ignore_1 threaded-ignore-1824059
Ref: 5b7824059
Node: Description<72>824329
Ref: refman/predicates/threaded_ignore_1 description824452
Ref: 5b8824452
Node: Meta-predicate template<4>825119
Ref: refman/predicates/threaded_ignore_1 meta-predicate-template825281
Ref: 5b9825281
Node: Modes and number of proofs<35>825373
Ref: refman/predicates/threaded_ignore_1 modes-and-number-of-proofs825530
Ref: 5ba825530
Node: Errors<36>825642
Ref: refman/predicates/threaded_ignore_1 errors825785
Ref: 5bb825785
Node: Examples<73>825988
Ref: refman/predicates/threaded_ignore_1 examples826092
Ref: 5bc826092
Node: threaded_exit/1-2826649
Ref: refman/predicates/threaded_exit_1_2 doc826789
Ref: 5bd826789
Ref: refman/predicates/threaded_exit_1_2 predicates-threaded-exit-1-2826789
Ref: 231826789
Ref: refman/predicates/threaded_exit_1_2 threaded-exit-1-2826789
Ref: 5be826789
Node: Description<73>827004
Ref: refman/predicates/threaded_exit_1_2 description827131
Ref: 5bf827131
Node: Modes and number of proofs<36>828465
Ref: refman/predicates/threaded_exit_1_2 modes-and-number-of-proofs828611
Ref: 5c0828611
Node: Errors<37>828784
Ref: refman/predicates/threaded_exit_1_2 errors828927
Ref: 5c1828927
Node: Examples<74>829330
Ref: refman/predicates/threaded_exit_1_2 examples829434
Ref: 5c2829434
Node: threaded_peek/1-2829965
Ref: refman/predicates/threaded_peek_1_2 doc830105
Ref: 5c3830105
Ref: refman/predicates/threaded_peek_1_2 predicates-threaded-peek-1-2830105
Ref: 233830105
Ref: refman/predicates/threaded_peek_1_2 threaded-peek-1-2830105
Ref: 5c4830105
Node: Description<74>830320
Ref: refman/predicates/threaded_peek_1_2 description830447
Ref: 5c5830447
Node: Modes and number of proofs<37>831694
Ref: refman/predicates/threaded_peek_1_2 modes-and-number-of-proofs831840
Ref: 5c6831840
Node: Errors<38>832011
Ref: refman/predicates/threaded_peek_1_2 errors832154
Ref: 5c7832154
Node: Examples<75>832557
Ref: refman/predicates/threaded_peek_1_2 examples832661
Ref: 5c8832661
Node: threaded_cancel/1833195
Ref: refman/predicates/threaded_cancel_1 doc833333
Ref: 5c9833333
Ref: refman/predicates/threaded_cancel_1 predicates-threaded-cancel-1833333
Ref: 234833333
Ref: refman/predicates/threaded_cancel_1 threaded-cancel-1833333
Ref: 5ca833333
Node: Description<75>833548
Ref: refman/predicates/threaded_cancel_1 description833675
Ref: 5cb833675
Node: Modes and number of proofs<38>834386
Ref: refman/predicates/threaded_cancel_1 modes-and-number-of-proofs834532
Ref: 5cc834532
Node: Errors<39>834642
Ref: refman/predicates/threaded_cancel_1 errors834785
Ref: 5cd834785
Node: Examples<76>834885
Ref: refman/predicates/threaded_cancel_1 examples834989
Ref: 5ce834989
Node: threaded_wait/1835219
Ref: refman/predicates/threaded_wait_1 doc835357
Ref: 5cf835357
Ref: refman/predicates/threaded_wait_1 predicates-threaded-wait-1835357
Ref: 23b835357
Ref: refman/predicates/threaded_wait_1 threaded-wait-1835357
Ref: 5d0835357
Node: Description<76>835568
Ref: refman/predicates/threaded_wait_1 description835693
Ref: 5d1835693
Node: Modes and number of proofs<39>836489
Ref: refman/predicates/threaded_wait_1 modes-and-number-of-proofs836633
Ref: 5d2836633
Node: Errors<40>836777
Ref: refman/predicates/threaded_wait_1 errors836918
Ref: 5d3836918
Node: Examples<77>836959
Ref: refman/predicates/threaded_wait_1 examples837061
Ref: 5d4837061
Node: threaded_notify/1837281
Ref: refman/predicates/threaded_notify_1 doc837393
Ref: 5d5837393
Ref: refman/predicates/threaded_notify_1 predicates-threaded-notify-1837393
Ref: 23c837393
Ref: refman/predicates/threaded_notify_1 threaded-notify-1837393
Ref: 5d6837393
Node: Description<77>837608
Ref: refman/predicates/threaded_notify_1 description837735
Ref: 5d7837735
Node: Modes and number of proofs<40>838531
Ref: refman/predicates/threaded_notify_1 modes-and-number-of-proofs838677
Ref: 5d8838677
Node: Errors<41>838825
Ref: refman/predicates/threaded_notify_1 errors838968
Ref: 5d9838968
Node: Examples<78>839009
Ref: refman/predicates/threaded_notify_1 examples839113
Ref: 5da839113
Node: Multi-threading engines839291
Ref: refman/predicates/engine_predicates doc839456
Ref: 5db839456
Ref: refman/predicates/engine_predicates engine-predicates839456
Ref: 5dc839456
Ref: refman/predicates/engine_predicates multi-threading-engines839456
Ref: 5dd839456
Node: threaded_engine_create/3839802
Ref: refman/predicates/threaded_engine_create_3 doc839939
Ref: 5de839939
Ref: refman/predicates/threaded_engine_create_3 predicates-threaded-engine-create-3839939
Ref: 23f839939
Ref: refman/predicates/threaded_engine_create_3 threaded-engine-create-3839939
Ref: 5df839939
Node: Description<78>840221
Ref: refman/predicates/threaded_engine_create_3 description840351
Ref: 5e0840351
Node: Meta-predicate template<5>841054
Ref: refman/predicates/threaded_engine_create_3 meta-predicate-template841223
Ref: 5e1841223
Node: Modes and number of proofs<41>841326
Ref: refman/predicates/threaded_engine_create_3 modes-and-number-of-proofs841490
Ref: 5e2841490
Node: Errors<42>841685
Ref: refman/predicates/threaded_engine_create_3 errors841835
Ref: 5e3841835
Node: Examples<79>842146
Ref: refman/predicates/threaded_engine_create_3 examples842257
Ref: 5e4842257
Node: threaded_engine_destroy/1842638
Ref: refman/predicates/threaded_engine_destroy_1 doc842801
Ref: 5e7842801
Ref: refman/predicates/threaded_engine_destroy_1 predicates-threaded-engine-destroy-1842801
Ref: 242842801
Ref: refman/predicates/threaded_engine_destroy_1 threaded-engine-destroy-1842801
Ref: 5e8842801
Node: Description<79>843030
Ref: refman/predicates/threaded_engine_destroy_1 description843165
Ref: 5e9843165
Node: Modes and number of proofs<42>843514
Ref: refman/predicates/threaded_engine_destroy_1 modes-and-number-of-proofs843668
Ref: 5ea843668
Node: Errors<43>843784
Ref: refman/predicates/threaded_engine_destroy_1 errors843935
Ref: 5eb843935
Node: Examples<80>844162
Ref: refman/predicates/threaded_engine_destroy_1 examples844274
Ref: 5ec844274
Node: threaded_engine/1844676
Ref: refman/predicates/threaded_engine_1 doc844837
Ref: 5ed844837
Ref: refman/predicates/threaded_engine_1 predicates-threaded-engine-1844837
Ref: 5e6844837
Ref: refman/predicates/threaded_engine_1 threaded-engine-1844837
Ref: 5ee844837
Node: Description<80>845052
Ref: refman/predicates/threaded_engine_1 description845179
Ref: 5ef845179
Node: Modes and number of proofs<43>845628
Ref: refman/predicates/threaded_engine_1 modes-and-number-of-proofs845774
Ref: 5f0845774
Node: Errors<44>845893
Ref: refman/predicates/threaded_engine_1 errors846036
Ref: 5f1846036
Node: Examples<81>846077
Ref: refman/predicates/threaded_engine_1 examples846181
Ref: 5f2846181
Node: threaded_engine_self/1846608
Ref: refman/predicates/threaded_engine_self_1 doc846766
Ref: 5f3846766
Ref: refman/predicates/threaded_engine_self_1 predicates-threaded-engine-self-1846766
Ref: 5e5846766
Ref: refman/predicates/threaded_engine_self_1 threaded-engine-self-1846766
Ref: 5f4846766
Node: Description<81>846991
Ref: refman/predicates/threaded_engine_self_1 description847123
Ref: 5f5847123
Node: Modes and number of proofs<44>847591
Ref: refman/predicates/threaded_engine_self_1 modes-and-number-of-proofs847742
Ref: 5f6847742
Node: Errors<45>847865
Ref: refman/predicates/threaded_engine_self_1 errors848013
Ref: 5f7848013
Node: Examples<82>848054
Ref: refman/predicates/threaded_engine_self_1 examples848163
Ref: 5f8848163
Node: threaded_engine_next/2848553
Ref: refman/predicates/threaded_engine_next_2 doc848724
Ref: 5f9848724
Ref: refman/predicates/threaded_engine_next_2 predicates-threaded-engine-next-2848724
Ref: 240848724
Ref: refman/predicates/threaded_engine_next_2 threaded-engine-next-2848724
Ref: 5fa848724
Node: Description<82>848949
Ref: refman/predicates/threaded_engine_next_2 description849081
Ref: 5fb849081
Node: Modes and number of proofs<45>849747
Ref: refman/predicates/threaded_engine_next_2 modes-and-number-of-proofs849898
Ref: 5fc849898
Node: Errors<46>850028
Ref: refman/predicates/threaded_engine_next_2 errors850176
Ref: 5fd850176
Node: Examples<83>850403
Ref: refman/predicates/threaded_engine_next_2 examples850512
Ref: 5fe850512
Node: threaded_engine_next_reified/2850811
Ref: refman/predicates/threaded_engine_next_reified_2 doc850983
Ref: 5ff850983
Ref: refman/predicates/threaded_engine_next_reified_2 predicates-threaded-engine-next-reified-2850983
Ref: 241850983
Ref: refman/predicates/threaded_engine_next_reified_2 threaded-engine-next-reified-2850983
Ref: 600850983
Node: Description<83>851224
Ref: refman/predicates/threaded_engine_next_reified_2 description851364
Ref: 601851364
Node: Modes and number of proofs<46>851957
Ref: refman/predicates/threaded_engine_next_reified_2 modes-and-number-of-proofs852116
Ref: 602852116
Node: Errors<47>852248
Ref: refman/predicates/threaded_engine_next_reified_2 errors852404
Ref: 603852404
Node: Examples<84>852631
Ref: refman/predicates/threaded_engine_next_reified_2 examples852748
Ref: 604852748
Node: threaded_engine_yield/1853055
Ref: refman/predicates/threaded_engine_yield_1 doc853227
Ref: 605853227
Ref: refman/predicates/threaded_engine_yield_1 predicates-threaded-engine-yield-1853227
Ref: 245853227
Ref: refman/predicates/threaded_engine_yield_1 threaded-engine-yield-1853227
Ref: 606853227
Node: Description<84>853454
Ref: refman/predicates/threaded_engine_yield_1 description853587
Ref: 607853587
Node: Modes and number of proofs<47>854506
Ref: refman/predicates/threaded_engine_yield_1 modes-and-number-of-proofs854658
Ref: 608854658
Node: Errors<48>854780
Ref: refman/predicates/threaded_engine_yield_1 errors854929
Ref: 609854929
Node: Examples<85>854970
Ref: refman/predicates/threaded_engine_yield_1 examples855080
Ref: 60a855080
Node: threaded_engine_post/2855372
Ref: refman/predicates/threaded_engine_post_2 doc855537
Ref: 60b855537
Ref: refman/predicates/threaded_engine_post_2 predicates-threaded-engine-post-2855537
Ref: 244855537
Ref: refman/predicates/threaded_engine_post_2 threaded-engine-post-2855537
Ref: 60c855537
Node: Description<85>855762
Ref: refman/predicates/threaded_engine_post_2 description855894
Ref: 60d855894
Node: Modes and number of proofs<48>856257
Ref: refman/predicates/threaded_engine_post_2 modes-and-number-of-proofs856408
Ref: 60e856408
Node: Errors<49>856530
Ref: refman/predicates/threaded_engine_post_2 errors856678
Ref: 60f856678
Node: Examples<86>856905
Ref: refman/predicates/threaded_engine_post_2 examples857014
Ref: 610857014
Node: threaded_engine_fetch/1857238
Ref: refman/predicates/threaded_engine_fetch_1 doc857371
Ref: 611857371
Ref: refman/predicates/threaded_engine_fetch_1 predicates-threaded-engine-fetch-1857371
Ref: 243857371
Ref: refman/predicates/threaded_engine_fetch_1 threaded-engine-fetch-1857371
Ref: 612857371
Node: Description<86>857598
Ref: refman/predicates/threaded_engine_fetch_1 description857731
Ref: 613857731
Node: Modes and number of proofs<49>858170
Ref: refman/predicates/threaded_engine_fetch_1 modes-and-number-of-proofs858322
Ref: 614858322
Node: Errors<50>858444
Ref: refman/predicates/threaded_engine_fetch_1 errors858593
Ref: 615858593
Node: Examples<87>858634
Ref: refman/predicates/threaded_engine_fetch_1 examples858744
Ref: 616858744
Node: Compiling and loading source files858928
Ref: refman/predicates/compiling_predicates doc859083
Ref: 617859083
Ref: refman/predicates/compiling_predicates compiling-and-loading-source-files859083
Ref: 618859083
Ref: refman/predicates/compiling_predicates compiling-predicates859083
Ref: 45859083
Node: logtalk_compile/1859405
Ref: refman/predicates/logtalk_compile_1 doc859538
Ref: 619859538
Ref: refman/predicates/logtalk_compile_1 logtalk-compile-1859538
Ref: 61a859538
Ref: refman/predicates/logtalk_compile_1 predicates-logtalk-compile-1859538
Ref: 29e859538
Node: Description<87>859751
Ref: refman/predicates/logtalk_compile_1 description859878
Ref: 61b859878
Node: Modes and number of proofs<50>861400
Ref: refman/predicates/logtalk_compile_1 modes-and-number-of-proofs861546
Ref: 61d861546
Node: Errors<51>861732
Ref: refman/predicates/logtalk_compile_1 errors861875
Ref: 61e861875
Node: Examples<88>862548
Ref: refman/predicates/logtalk_compile_1 examples862652
Ref: 61f862652
Node: logtalk_compile/2863271
Ref: refman/predicates/logtalk_compile_2 doc863427
Ref: 620863427
Ref: refman/predicates/logtalk_compile_2 logtalk-compile-2863427
Ref: 621863427
Ref: refman/predicates/logtalk_compile_2 predicates-logtalk-compile-2863427
Ref: 2b2863427
Node: Description<88>863640
Ref: refman/predicates/logtalk_compile_2 description863767
Ref: 622863767
Node: Modes and number of proofs<51>865767
Ref: refman/predicates/logtalk_compile_2 modes-and-number-of-proofs865913
Ref: 623865913
Node: Errors<52>866143
Ref: refman/predicates/logtalk_compile_2 errors866286
Ref: 624866286
Node: Examples<89>867604
Ref: refman/predicates/logtalk_compile_2 examples867708
Ref: 625867708
Node: logtalk_load/1868474
Ref: refman/predicates/logtalk_load_1 doc868627
Ref: 626868627
Ref: refman/predicates/logtalk_load_1 logtalk-load-1868627
Ref: 627868627
Ref: refman/predicates/logtalk_load_1 predicates-logtalk-load-1868627
Ref: 46868627
Node: Description<89>868836
Ref: refman/predicates/logtalk_load_1 description868960
Ref: 628868960
Node: Modes and number of proofs<52>870590
Ref: refman/predicates/logtalk_load_1 modes-and-number-of-proofs870733
Ref: 629870733
Node: Errors<53>870915
Ref: refman/predicates/logtalk_load_1 errors871055
Ref: 62a871055
Node: Examples<90>871731
Ref: refman/predicates/logtalk_load_1 examples871832
Ref: 62b871832
Node: logtalk_load/2872454
Ref: refman/predicates/logtalk_load_2 doc872604
Ref: 62c872604
Ref: refman/predicates/logtalk_load_2 logtalk-load-2872604
Ref: 62d872604
Ref: refman/predicates/logtalk_load_2 predicates-logtalk-load-2872604
Ref: 4e872604
Node: Description<90>872813
Ref: refman/predicates/logtalk_load_2 description872937
Ref: 62e872937
Node: Modes and number of proofs<53>874942
Ref: refman/predicates/logtalk_load_2 modes-and-number-of-proofs875085
Ref: 62f875085
Node: Errors<54>875311
Ref: refman/predicates/logtalk_load_2 errors875451
Ref: 630875451
Node: Examples<91>876760
Ref: refman/predicates/logtalk_load_2 examples876861
Ref: 631876861
Node: logtalk_make/0877606
Ref: refman/predicates/logtalk_make_0 doc877756
Ref: 632877756
Ref: refman/predicates/logtalk_make_0 logtalk-make-0877756
Ref: 633877756
Ref: refman/predicates/logtalk_make_0 predicates-logtalk-make-0877756
Ref: 29f877756
Node: Description<91>877965
Ref: refman/predicates/logtalk_make_0 description878089
Ref: 634878089
Node: Modes and number of proofs<54>879470
Ref: refman/predicates/logtalk_make_0 modes-and-number-of-proofs879613
Ref: 636879613
Node: Errors<55>879711
Ref: refman/predicates/logtalk_make_0 errors879851
Ref: 637879851
Node: Examples<92>879892
Ref: refman/predicates/logtalk_make_0 examples879993
Ref: 638879993
Node: logtalk_make/1880329
Ref: refman/predicates/logtalk_make_1 doc880493
Ref: 639880493
Ref: refman/predicates/logtalk_make_1 logtalk-make-1880493
Ref: 63a880493
Ref: refman/predicates/logtalk_make_1 predicates-logtalk-make-1880493
Ref: 2a0880493
Node: Description<92>880702
Ref: refman/predicates/logtalk_make_1 description880826
Ref: 63b880826
Ref: Description<92>-Footnote-1885007
Node: Modes and number of proofs<55>885060
Ref: refman/predicates/logtalk_make_1 modes-and-number-of-proofs885203
Ref: 63d885203
Node: Errors<56>885316
Ref: refman/predicates/logtalk_make_1 errors885456
Ref: 63e885456
Node: Examples<93>885497
Ref: refman/predicates/logtalk_make_1 examples885598
Ref: 63f885598
Node: logtalk_make_target_action/1886157
Ref: refman/predicates/logtalk_make_target_action_1 doc886329
Ref: 640886329
Ref: refman/predicates/logtalk_make_target_action_1 logtalk-make-target-action-1886329
Ref: 641886329
Ref: refman/predicates/logtalk_make_target_action_1 predicates-logtalk-make-target-action-1886329
Ref: 635886329
Node: Description<93>886566
Ref: refman/predicates/logtalk_make_target_action_1 description886704
Ref: 642886704
Node: Modes and number of proofs<56>887077
Ref: refman/predicates/logtalk_make_target_action_1 modes-and-number-of-proofs887234
Ref: 643887234
Node: Errors<57>887362
Ref: refman/predicates/logtalk_make_target_action_1 errors887516
Ref: 644887516
Node: Examples<94>887557
Ref: refman/predicates/logtalk_make_target_action_1 examples887672
Ref: 645887672
Node: logtalk_library_path/2888043
Ref: refman/predicates/logtalk_library_path_2 doc888223
Ref: 646888223
Ref: refman/predicates/logtalk_library_path_2 logtalk-library-path-2888223
Ref: 647888223
Ref: refman/predicates/logtalk_library_path_2 predicates-logtalk-library-path-2888223
Ref: 2a7888223
Node: Description<94>888448
Ref: refman/predicates/logtalk_library_path_2 description888580
Ref: 648888580
Ref: Description<94>-Footnote-1891438
Node: Modes and number of proofs<57>891507
Ref: refman/predicates/logtalk_library_path_2 modes-and-number-of-proofs891658
Ref: 64a891658
Node: Errors<58>891846
Ref: refman/predicates/logtalk_library_path_2 errors891994
Ref: 64b891994
Node: Examples<95>892035
Ref: refman/predicates/logtalk_library_path_2 examples892144
Ref: 64c892144
Node: logtalk_load_context/2893279
Ref: refman/predicates/logtalk_load_context_2 doc893422
Ref: 64d893422
Ref: refman/predicates/logtalk_load_context_2 logtalk-load-context-2893422
Ref: 64e893422
Ref: refman/predicates/logtalk_load_context_2 predicates-logtalk-load-context-2893422
Ref: 317893422
Node: Description<95>893647
Ref: refman/predicates/logtalk_load_context_2 description893779
Ref: 64f893779
Node: Modes and number of proofs<58>897315
Ref: refman/predicates/logtalk_load_context_2 modes-and-number-of-proofs897466
Ref: 650897466
Node: Errors<59>897601
Ref: refman/predicates/logtalk_load_context_2 errors897749
Ref: 651897749
Node: Examples<96>897998
Ref: refman/predicates/logtalk_load_context_2 examples898107
Ref: 652898107
Node: Flags898821
Ref: refman/predicates/flag_predicates doc898959
Ref: 653898959
Ref: refman/predicates/flag_predicates flag-predicates898959
Ref: 654898959
Ref: refman/predicates/flag_predicates flags898959
Ref: 655898959
Node: current_logtalk_flag/2899116
Ref: refman/predicates/current_logtalk_flag_2 doc899229
Ref: 656899229
Ref: refman/predicates/current_logtalk_flag_2 current-logtalk-flag-2899229
Ref: 657899229
Ref: refman/predicates/current_logtalk_flag_2 predicates-current-logtalk-flag-2899229
Ref: 2b3899229
Node: Description<96>899454
Ref: refman/predicates/current_logtalk_flag_2 description899586
Ref: 658899586
Node: Modes and number of proofs<59>899855
Ref: refman/predicates/current_logtalk_flag_2 modes-and-number-of-proofs900006
Ref: 659900006
Node: Errors<60>900135
Ref: refman/predicates/current_logtalk_flag_2 errors900283
Ref: 65a900283
Node: Examples<97>900497
Ref: refman/predicates/current_logtalk_flag_2 examples900606
Ref: 65b900606
Node: set_logtalk_flag/2<2>900856
Ref: refman/predicates/set_logtalk_flag_2 doc900999
Ref: 65c900999
Ref: refman/predicates/set_logtalk_flag_2 predicates-set-logtalk-flag-2900999
Ref: 51900999
Ref: refman/predicates/set_logtalk_flag_2 set-logtalk-flag-2900999
Ref: 65d900999
Node: Description<97>901216
Ref: refman/predicates/set_logtalk_flag_2 description901347
Ref: 65e901347
Node: Modes and number of proofs<60>901829
Ref: refman/predicates/set_logtalk_flag_2 modes-and-number-of-proofs901979
Ref: 65f901979
Node: Errors<61>902097
Ref: refman/predicates/set_logtalk_flag_2 errors902244
Ref: 660902244
Node: Examples<98>902796
Ref: refman/predicates/set_logtalk_flag_2 examples902904
Ref: 661902904
Node: create_logtalk_flag/3903196
Ref: refman/predicates/create_logtalk_flag_3 doc903308
Ref: 662903308
Ref: refman/predicates/create_logtalk_flag_3 create-logtalk-flag-3903308
Ref: 663903308
Ref: refman/predicates/create_logtalk_flag_3 predicates-create-logtalk-flag-3903308
Ref: 2e6903308
Node: Description<98>903533
Ref: refman/predicates/create_logtalk_flag_3 description903664
Ref: 664903664
Node: Modes and number of proofs<61>904864
Ref: refman/predicates/create_logtalk_flag_3 modes-and-number-of-proofs905014
Ref: 665905014
Node: Errors<62>905152
Ref: refman/predicates/create_logtalk_flag_3 errors905299
Ref: 666905299
Node: Examples<99>906198
Ref: refman/predicates/create_logtalk_flag_3 examples906306
Ref: 667906306
Node: Linter906559
Ref: refman/predicates/linter_predicates doc906654
Ref: 668906654
Ref: refman/predicates/linter_predicates linter906654
Ref: 669906654
Ref: refman/predicates/linter_predicates linter-predicates906654
Ref: 66a906654
Node: logtalk_linter_hook/7906741
Ref: refman/predicates/logtalk_linter_hook_7 doc906824
Ref: 66b906824
Ref: refman/predicates/logtalk_linter_hook_7 logtalk-linter-hook-7906824
Ref: 66c906824
Ref: refman/predicates/logtalk_linter_hook_7 predicates-logtalk-linter-hook-7906824
Ref: 66d906824
Node: Description<99>907048
Ref: refman/predicates/logtalk_linter_hook_7 description907179
Ref: 66e907179
Node: Modes and number of proofs<62>907790
Ref: refman/predicates/logtalk_linter_hook_7 modes-and-number-of-proofs907940
Ref: 66f907940
Node: Errors<63>908133
Ref: refman/predicates/logtalk_linter_hook_7 errors908281
Ref: 670908281
Node: Examples<100>908322
Ref: refman/predicates/logtalk_linter_hook_7 examples908431
Ref: 671908431
Node: Built-in methods<2>908861
Ref: refman/methods/index doc908980
Ref: 672908980
Ref: refman/methods/index built-in-methods908980
Ref: 673908980
Node: Logic and control909434
Ref: refman/methods/logic_and_control_methods doc909552
Ref: 674909552
Ref: refman/methods/logic_and_control_methods logic-and-control909552
Ref: 675909552
Ref: refman/methods/logic_and_control_methods logic-and-control-methods909552
Ref: 676909552
Node: !/0909685
Ref: refman/methods/cut_0 doc909776
Ref: 677909776
Ref: refman/methods/cut_0 id1909776
Ref: 678909776
Ref: refman/methods/cut_0 methods-cut-0909776
Ref: 196909776
Node: Description<100>909963
Ref: refman/methods/cut_0 description910077
Ref: 679910077
Node: Modes and number of proofs<63>910335
Ref: refman/methods/cut_0 modes-and-number-of-proofs910468
Ref: 67a910468
Node: Errors<64>910553
Ref: refman/methods/cut_0 errors910683
Ref: 67b910683
Node: Examples<101>910722
Ref: refman/methods/cut_0 examples910813
Ref: 67c910813
Node: true/0910974
Ref: refman/methods/true_0 doc911080
Ref: 67d911080
Ref: refman/methods/true_0 methods-true-0911080
Ref: 197911080
Ref: refman/methods/true_0 true-0911080
Ref: 67e911080
Node: Description<101>911273
Ref: refman/methods/true_0 description911390
Ref: 67f911390
Node: Modes and number of proofs<64>911602
Ref: refman/methods/true_0 modes-and-number-of-proofs911738
Ref: 680911738
Node: Errors<65>911826
Ref: refman/methods/true_0 errors911959
Ref: 681911959
Node: Examples<102>911998
Ref: refman/methods/true_0 examples912092
Ref: 682912092
Node: fail/0912252
Ref: refman/methods/fail_0 doc912362
Ref: 683912362
Ref: refman/methods/fail_0 fail-0912362
Ref: 684912362
Ref: refman/methods/fail_0 methods-fail-0912362
Ref: 198912362
Node: Description<102>912557
Ref: refman/methods/fail_0 description912674
Ref: 685912674
Node: Modes and number of proofs<65>912885
Ref: refman/methods/fail_0 modes-and-number-of-proofs913021
Ref: 686913021
Node: Errors<66>913111
Ref: refman/methods/fail_0 errors913244
Ref: 687913244
Node: Examples<103>913285
Ref: refman/methods/fail_0 examples913379
Ref: 688913379
Node: false/0913539
Ref: refman/methods/false_0 doc913651
Ref: 689913651
Ref: refman/methods/false_0 false-0913651
Ref: 68a913651
Ref: refman/methods/false_0 methods-false-0913651
Ref: 199913651
Node: Description<103>913848
Ref: refman/methods/false_0 description913966
Ref: 68b913966
Node: Modes and number of proofs<66>914178
Ref: refman/methods/false_0 modes-and-number-of-proofs914315
Ref: 68c914315
Node: Errors<67>914406
Ref: refman/methods/false_0 errors914540
Ref: 68d914540
Node: Examples<104>914581
Ref: refman/methods/false_0 examples914676
Ref: 68e914676
Node: repeat/0914835
Ref: refman/methods/repeat_0 doc914932
Ref: 68f914932
Ref: refman/methods/repeat_0 methods-repeat-0914932
Ref: 19a914932
Ref: refman/methods/repeat_0 repeat-0914932
Ref: 690914932
Node: Description<104>915131
Ref: refman/methods/repeat_0 description915250
Ref: 691915250
Node: Modes and number of proofs<67>915555
Ref: refman/methods/repeat_0 modes-and-number-of-proofs915693
Ref: 692915693
Node: Errors<68>915793
Ref: refman/methods/repeat_0 errors915928
Ref: 693915928
Node: Examples<105>915969
Ref: refman/methods/repeat_0 examples916065
Ref: 694916065
Node: Execution context916204
Ref: refman/methods/context_methods doc916344
Ref: 695916344
Ref: refman/methods/context_methods context-methods916344
Ref: 35f916344
Ref: refman/methods/context_methods execution-context916344
Ref: 696916344
Node: context/1916487
Ref: refman/methods/context_1 doc916589
Ref: 697916589
Ref: refman/methods/context_1 context-1916589
Ref: 698916589
Ref: refman/methods/context_1 methods-context-1916589
Ref: 19e916589
Node: Description<105>916788
Ref: refman/methods/context_1 description916908
Ref: 699916908
Ref: Description<105>-Footnote-1917862
Node: Modes and number of proofs<68>917929
Ref: refman/methods/context_1 modes-and-number-of-proofs918068
Ref: 69a918068
Node: Errors<69>918171
Ref: refman/methods/context_1 errors918307
Ref: 69b918307
Node: Examples<106>918346
Ref: refman/methods/context_1 examples918443
Ref: 69c918443
Node: parameter/2918813
Ref: refman/methods/parameter_2 doc918930
Ref: 69d918930
Ref: refman/methods/parameter_2 methods-parameter-2918930
Ref: a2918930
Ref: refman/methods/parameter_2 parameter-2918930
Ref: 69e918930
Node: Description<106>919133
Ref: refman/methods/parameter_2 description919255
Ref: 69f919255
Node: Modes and number of proofs<69>920299
Ref: refman/methods/parameter_2 modes-and-number-of-proofs920440
Ref: 6a1920440
Node: Errors<70>920558
Ref: refman/methods/parameter_2 errors920696
Ref: 6a2920696
Node: Examples<107>921146
Ref: refman/methods/parameter_2 examples921245
Ref: 6a3921245
Node: self/1921968
Ref: refman/methods/self_1 doc922084
Ref: 6a4922084
Ref: refman/methods/self_1 methods-self-1922084
Ref: 67922084
Ref: refman/methods/self_1 self-1922084
Ref: 6a5922084
Node: Description<107>922279
Ref: refman/methods/self_1 description922396
Ref: 6a6922396
Node: Modes and number of proofs<70>922815
Ref: refman/methods/self_1 modes-and-number-of-proofs922951
Ref: 6a7922951
Node: Errors<71>923069
Ref: refman/methods/self_1 errors923202
Ref: 6a8923202
Node: Examples<108>923243
Ref: refman/methods/self_1 examples923337
Ref: 6a9923337
Node: sender/1923702
Ref: refman/methods/sender_1 doc923813
Ref: 6aa923813
Ref: refman/methods/sender_1 methods-sender-1923813
Ref: 19d923813
Ref: refman/methods/sender_1 sender-1923813
Ref: 6ab923813
Node: Description<108>924012
Ref: refman/methods/sender_1 description924131
Ref: 6ac924131
Node: Modes and number of proofs<71>924552
Ref: refman/methods/sender_1 modes-and-number-of-proofs924690
Ref: 6ad924690
Node: Errors<72>924810
Ref: refman/methods/sender_1 errors924945
Ref: 6ae924945
Node: Examples<109>924986
Ref: refman/methods/sender_1 examples925082
Ref: 6af925082
Node: this/1925466
Ref: refman/methods/this_1 doc925562
Ref: 6b0925562
Ref: refman/methods/this_1 methods-this-1925562
Ref: 68925562
Ref: refman/methods/this_1 this-1925562
Ref: 6b1925562
Node: Description<109>925757
Ref: refman/methods/this_1 description925874
Ref: 6b2925874
Node: Modes and number of proofs<72>926668
Ref: refman/methods/this_1 modes-and-number-of-proofs926804
Ref: 6b3926804
Node: Errors<73>926922
Ref: refman/methods/this_1 errors927055
Ref: 6b4927055
Node: Examples<110>927096
Ref: refman/methods/this_1 examples927190
Ref: 6b5927190
Node: Reflection<2>927543
Ref: refman/methods/reflection_methods doc927674
Ref: 6b6927674
Ref: refman/methods/reflection_methods reflection927674
Ref: 6b7927674
Ref: refman/methods/reflection_methods reflection-methods927674
Ref: 70927674
Node: current_op/3927804
Ref: refman/methods/current_op_3 doc927913
Ref: 6b8927913
Ref: refman/methods/current_op_3 current-op-3927913
Ref: 6b9927913
Ref: refman/methods/current_op_3 methods-current-op-3927913
Ref: 15e927913
Node: Description<110>928118
Ref: refman/methods/current_op_3 description928241
Ref: 6ba928241
Node: Modes and number of proofs<73>928474
Ref: refman/methods/current_op_3 modes-and-number-of-proofs928616
Ref: 6bb928616
Node: Errors<74>928767
Ref: refman/methods/current_op_3 errors928906
Ref: 6bc928906
Node: Examples<111>929495
Ref: refman/methods/current_op_3 examples929595
Ref: 6bd929595
Node: current_predicate/1930226
Ref: refman/methods/current_predicate_1 doc930364
Ref: 6be930364
Ref: refman/methods/current_predicate_1 current-predicate-1930364
Ref: 6bf930364
Ref: refman/methods/current_predicate_1 methods-current-predicate-1930364
Ref: 141930364
Node: Description<111>930583
Ref: refman/methods/current_predicate_1 description930713
Ref: 6c0930713
Node: Modes and number of proofs<74>931257
Ref: refman/methods/current_predicate_1 modes-and-number-of-proofs931406
Ref: 6c1931406
Node: Errors<75>931538
Ref: refman/methods/current_predicate_1 errors931684
Ref: 6c2931684
Node: Examples<112>932279
Ref: refman/methods/current_predicate_1 examples932386
Ref: 6c3932386
Node: predicate_property/2933468
Ref: refman/methods/predicate_property_2 doc933585
Ref: 6c4933585
Ref: refman/methods/predicate_property_2 methods-predicate-property-2933585
Ref: 142933585
Ref: refman/methods/predicate_property_2 predicate-property-2933585
Ref: 6c5933585
Node: Description<112>933808
Ref: refman/methods/predicate_property_2 description933939
Ref: 6c6933939
Node: Modes and number of proofs<75>934744
Ref: refman/methods/predicate_property_2 modes-and-number-of-proofs934894
Ref: 6c7934894
Node: Errors<76>935039
Ref: refman/methods/predicate_property_2 errors935186
Ref: 6c8935186
Node: Examples<113>935537
Ref: refman/methods/predicate_property_2 examples935645
Ref: 6c9935645
Node: Database936870
Ref: refman/methods/database_methods doc936994
Ref: 6ca936994
Ref: refman/methods/database_methods database936994
Ref: 6cb936994
Ref: refman/methods/database_methods database-methods936994
Ref: 6cc936994
Node: abolish/1937140
Ref: refman/methods/abolish_1 doc937231
Ref: 6cd937231
Ref: refman/methods/abolish_1 abolish-1937231
Ref: 6ce937231
Ref: refman/methods/abolish_1 methods-abolish-1937231
Ref: 1b1937231
Node: Description<113>937430
Ref: refman/methods/abolish_1 description937550
Ref: 6cf937550
Node: Modes and number of proofs<76>938150
Ref: refman/methods/abolish_1 modes-and-number-of-proofs938289
Ref: 6d0938289
Node: Errors<77>938402
Ref: refman/methods/abolish_1 errors938538
Ref: 6d1938538
Node: Examples<114>939725
Ref: refman/methods/abolish_1 examples939822
Ref: 6d2939822
Node: asserta/1940437
Ref: refman/methods/asserta_1 doc940546
Ref: 6d3940546
Ref: refman/methods/asserta_1 asserta-1940546
Ref: 6d4940546
Ref: refman/methods/asserta_1 methods-asserta-1940546
Ref: 1b2940546
Node: Description<114>940745
Ref: refman/methods/asserta_1 description940865
Ref: 6d5940865
Node: Modes and number of proofs<77>942258
Ref: refman/methods/asserta_1 modes-and-number-of-proofs942397
Ref: 6d6942397
Node: Errors<78>942497
Ref: refman/methods/asserta_1 errors942633
Ref: 6d7942633
Node: Examples<115>943707
Ref: refman/methods/asserta_1 examples943804
Ref: 6d8943804
Node: assertz/1945505
Ref: refman/methods/assertz_1 doc945613
Ref: 6d9945613
Ref: refman/methods/assertz_1 assertz-1945613
Ref: 6da945613
Ref: refman/methods/assertz_1 methods-assertz-1945613
Ref: 1b3945613
Node: Description<115>945814
Ref: refman/methods/assertz_1 description945934
Ref: 6db945934
Node: Modes and number of proofs<78>947320
Ref: refman/methods/assertz_1 modes-and-number-of-proofs947459
Ref: 6dc947459
Node: Errors<79>947561
Ref: refman/methods/assertz_1 errors947697
Ref: 6dd947697
Node: Examples<116>948770
Ref: refman/methods/assertz_1 examples948867
Ref: 6de948867
Node: clause/2950565
Ref: refman/methods/clause_2 doc950673
Ref: 6df950673
Ref: refman/methods/clause_2 clause-2950673
Ref: 6e0950673
Ref: refman/methods/clause_2 methods-clause-2950673
Ref: 1b4950673
Node: Description<116>950872
Ref: refman/methods/clause_2 description950991
Ref: 6e1950991
Node: Modes and number of proofs<79>951597
Ref: refman/methods/clause_2 modes-and-number-of-proofs951735
Ref: 6e2951735
Node: Errors<80>951854
Ref: refman/methods/clause_2 errors951989
Ref: 6e3951989
Node: Examples<117>952906
Ref: refman/methods/clause_2 examples953002
Ref: 6e4953002
Node: retract/1953686
Ref: refman/methods/retract_1 doc953797
Ref: 6e5953797
Ref: refman/methods/retract_1 methods-retract-1953797
Ref: 1b5953797
Ref: refman/methods/retract_1 retract-1953797
Ref: 6e6953797
Node: Description<117>953998
Ref: refman/methods/retract_1 description954118
Ref: 6e7954118
Node: Modes and number of proofs<80>954789
Ref: refman/methods/retract_1 modes-and-number-of-proofs954928
Ref: 6e8954928
Node: Errors<81>955039
Ref: refman/methods/retract_1 errors955175
Ref: 6e9955175
Node: Examples<118>956024
Ref: refman/methods/retract_1 examples956121
Ref: 6ea956121
Node: retractall/1956763
Ref: refman/methods/retractall_1 doc956857
Ref: 6eb956857
Ref: refman/methods/retractall_1 methods-retractall-1956857
Ref: 1b6956857
Ref: refman/methods/retractall_1 retractall-1956857
Ref: 6ec956857
Node: Description<118>957064
Ref: refman/methods/retractall_1 description957187
Ref: 6ed957187
Node: Modes and number of proofs<81>957793
Ref: refman/methods/retractall_1 modes-and-number-of-proofs957935
Ref: 6ee957935
Node: Errors<82>958042
Ref: refman/methods/retractall_1 errors958181
Ref: 6ef958181
Node: Examples<119>959030
Ref: refman/methods/retractall_1 examples959130
Ref: 6f0959130
Node: Meta-calls959798
Ref: refman/methods/meta_call_methods doc959926
Ref: 6f1959926
Ref: refman/methods/meta_call_methods meta-call-methods959926
Ref: 6f2959926
Ref: refman/methods/meta_call_methods meta-calls959926
Ref: 6f3959926
Node: call/1-N960044
Ref: refman/methods/call_N doc960135
Ref: 6f4960135
Ref: refman/methods/call_N call-1-n960135
Ref: 6f5960135
Ref: refman/methods/call_N methods-call-n960135
Ref: 181960135
Node: Description<119>960387
Ref: refman/methods/call_N description960502
Ref: 6f6960502
Node: Meta-predicate template<6>961209
Ref: refman/methods/call_N meta-predicate-template961363
Ref: 6f7961363
Node: Modes and number of proofs<82>961486
Ref: refman/methods/call_N modes-and-number-of-proofs961634
Ref: 6f8961634
Node: Errors<83>961844
Ref: refman/methods/call_N errors961979
Ref: 6f9961979
Node: Examples<120>962358
Ref: refman/methods/call_N examples962454
Ref: 6fa962454
Node: ignore/1963110
Ref: refman/methods/ignore_1 doc963216
Ref: 6fb963216
Ref: refman/methods/ignore_1 ignore-1963216
Ref: 6fc963216
Ref: refman/methods/ignore_1 methods-ignore-1963216
Ref: 180963216
Node: Description<120>963468
Ref: refman/methods/ignore_1 description963583
Ref: 6fd963583
Node: Meta-predicate template<7>963905
Ref: refman/methods/ignore_1 meta-predicate-template964059
Ref: 6fe964059
Node: Modes and number of proofs<83>964140
Ref: refman/methods/ignore_1 modes-and-number-of-proofs964288
Ref: 6ff964288
Node: Errors<84>964391
Ref: refman/methods/ignore_1 errors964526
Ref: 700964526
Node: Examples<121>964729
Ref: refman/methods/ignore_1 examples964825
Ref: 701964825
Node: once/1965253
Ref: refman/methods/once_1 doc965356
Ref: 702965356
Ref: refman/methods/once_1 methods-once-1965356
Ref: 1bb965356
Ref: refman/methods/once_1 once-1965356
Ref: 703965356
Node: Description<121>965606
Ref: refman/methods/once_1 description965719
Ref: 704965719
Node: Meta-predicate template<8>966020
Ref: refman/methods/once_1 meta-predicate-template966172
Ref: 705966172
Node: Modes and number of proofs<84>966253
Ref: refman/methods/once_1 modes-and-number-of-proofs966399
Ref: 706966399
Node: Errors<85>966508
Ref: refman/methods/once_1 errors966641
Ref: 707966641
Node: Examples<122>966844
Ref: refman/methods/once_1 examples966938
Ref: 708966938
Node: \+ /1967407
Ref: refman/methods/not_1 doc967493
Ref: 709967493
Ref: refman/methods/not_1 id1967493
Ref: 70a967493
Ref: refman/methods/not_1 methods-not-1967493
Ref: 1bc967493
Node: Description<122>967743
Ref: refman/methods/not_1 description967855
Ref: 70b967855
Node: Meta-predicate template<9>968991
Ref: refman/methods/not_1 meta-predicate-template969142
Ref: 70c969142
Node: Modes and number of proofs<85>969220
Ref: refman/methods/not_1 modes-and-number-of-proofs969365
Ref: 70d969365
Node: Errors<86>969471
Ref: refman/methods/not_1 errors969603
Ref: 70e969603
Node: Examples<123>969806
Ref: refman/methods/not_1 examples969899
Ref: 70f969899
Node: Error handling<2>970310
Ref: refman/methods/error_handling_methods doc970443
Ref: 710970443
Ref: refman/methods/error_handling_methods error-handling970443
Ref: 711970443
Ref: refman/methods/error_handling_methods error-handling-methods970443
Ref: 24c970443
Node: catch/3970807
Ref: refman/methods/catch_3 doc970903
Ref: 712970903
Ref: refman/methods/catch_3 catch-3970903
Ref: 713970903
Ref: refman/methods/catch_3 methods-catch-3970903
Ref: 1a1970903
Node: Description<123>971098
Ref: refman/methods/catch_3 description971216
Ref: 714971216
Node: Modes and number of proofs<86>971613
Ref: refman/methods/catch_3 modes-and-number-of-proofs971750
Ref: 715971750
Node: Errors<87>971877
Ref: refman/methods/catch_3 errors972011
Ref: 716972011
Node: Examples<124>972050
Ref: refman/methods/catch_3 examples972145
Ref: 717972145
Node: throw/1972633
Ref: refman/methods/throw_1 doc972759
Ref: 719972759
Ref: refman/methods/throw_1 methods-throw-1972759
Ref: 1a2972759
Ref: refman/methods/throw_1 throw-1972759
Ref: 71a972759
Node: Description<124>972954
Ref: refman/methods/throw_1 description973072
Ref: 71b973072
Node: Modes and number of proofs<87>973297
Ref: refman/methods/throw_1 modes-and-number-of-proofs973434
Ref: 71c973434
Node: Errors<88>973534
Ref: refman/methods/throw_1 errors973668
Ref: 71d973668
Node: Examples<125>973898
Ref: refman/methods/throw_1 examples973993
Ref: 71e973993
Node: instantiation_error/0974483
Ref: refman/methods/instantiation_error_0 doc974625
Ref: 71f974625
Ref: refman/methods/instantiation_error_0 instantiation-error-0974625
Ref: 720974625
Ref: refman/methods/instantiation_error_0 methods-instantiation-error-0974625
Ref: 1a3974625
Node: Description<125>974850
Ref: refman/methods/instantiation_error_0 description974982
Ref: 721974982
Node: Modes and number of proofs<88>975595
Ref: refman/methods/instantiation_error_0 modes-and-number-of-proofs975746
Ref: 722975746
Node: Errors<89>975853
Ref: refman/methods/instantiation_error_0 errors976001
Ref: 723976001
Node: Examples<126>976089
Ref: refman/methods/instantiation_error_0 examples976198
Ref: 724976198
Node: uninstantiation_error/1976722
Ref: refman/methods/uninstantiation_error_1 doc976869
Ref: 725976869
Ref: refman/methods/uninstantiation_error_1 methods-uninstantiation-error-1976869
Ref: 1a4976869
Ref: refman/methods/uninstantiation_error_1 uninstantiation-error-1976869
Ref: 726976869
Node: Description<126>977098
Ref: refman/methods/uninstantiation_error_1 description977232
Ref: 727977232
Node: Modes and number of proofs<89>977842
Ref: refman/methods/uninstantiation_error_1 modes-and-number-of-proofs977995
Ref: 728977995
Node: Errors<90>978113
Ref: refman/methods/uninstantiation_error_1 errors978263
Ref: 729978263
Node: Examples<127>978362
Ref: refman/methods/uninstantiation_error_1 examples978473
Ref: 72a978473
Node: type_error/2979008
Ref: refman/methods/type_error_2 doc979148
Ref: 72b979148
Ref: refman/methods/type_error_2 methods-type-error-2979148
Ref: 1a5979148
Ref: refman/methods/type_error_2 type-error-2979148
Ref: 72c979148
Node: Description<127>979355
Ref: refman/methods/type_error_2 description979478
Ref: 72d979478
Node: Modes and number of proofs<90>980286
Ref: refman/methods/type_error_2 modes-and-number-of-proofs980428
Ref: 72e980428
Node: Errors<91>980542
Ref: refman/methods/type_error_2 errors980681
Ref: 72f980681
Node: Examples<128>980775
Ref: refman/methods/type_error_2 examples980875
Ref: 730980875
Node: domain_error/2981412
Ref: refman/methods/domain_error_2 doc981548
Ref: 731981548
Ref: refman/methods/domain_error_2 domain-error-2981548
Ref: 732981548
Ref: refman/methods/domain_error_2 methods-domain-error-2981548
Ref: 1a6981548
Node: Description<128>981759
Ref: refman/methods/domain_error_2 description981884
Ref: 733981884
Node: Modes and number of proofs<91>983769
Ref: refman/methods/domain_error_2 modes-and-number-of-proofs983913
Ref: 734983913
Node: Errors<92>984029
Ref: refman/methods/domain_error_2 errors984170
Ref: 735984170
Node: Examples<129>984268
Ref: refman/methods/domain_error_2 examples984370
Ref: 736984370
Node: consistency_error/3984929
Ref: refman/methods/consistency_error_3 doc985070
Ref: 737985070
Ref: refman/methods/consistency_error_3 consistency-error-3985070
Ref: 738985070
Ref: refman/methods/consistency_error_3 methods-consistency-error-3985070
Ref: 718985070
Node: Description<129>985291
Ref: refman/methods/consistency_error_3 description985421
Ref: 739985421
Node: Modes and number of proofs<92>986314
Ref: refman/methods/consistency_error_3 modes-and-number-of-proofs986463
Ref: 73a986463
Node: Errors<93>986593
Ref: refman/methods/consistency_error_3 errors986739
Ref: 73b986739
Node: Examples<130>986860
Ref: refman/methods/consistency_error_3 examples986967
Ref: 73c986967
Node: existence_error/2987912
Ref: refman/methods/existence_error_2 doc988057
Ref: 73d988057
Ref: refman/methods/existence_error_2 existence-error-2988057
Ref: 73e988057
Ref: refman/methods/existence_error_2 methods-existence-error-2988057
Ref: 1a7988057
Node: Description<130>988274
Ref: refman/methods/existence_error_2 description988402
Ref: 73f988402
Node: Modes and number of proofs<93>989409
Ref: refman/methods/existence_error_2 modes-and-number-of-proofs989556
Ref: 740989556
Node: Errors<94>989677
Ref: refman/methods/existence_error_2 errors989821
Ref: 741989821
Node: Examples<131>989921
Ref: refman/methods/existence_error_2 examples990026
Ref: 742990026
Node: permission_error/3990581
Ref: refman/methods/permission_error_3 doc990729
Ref: 743990729
Ref: refman/methods/permission_error_3 methods-permission-error-3990729
Ref: 1a8990729
Ref: refman/methods/permission_error_3 permission-error-3990729
Ref: 744990729
Node: Description<131>990948
Ref: refman/methods/permission_error_3 description991077
Ref: 745991077
Node: Modes and number of proofs<94>992614
Ref: refman/methods/permission_error_3 modes-and-number-of-proofs992762
Ref: 746992762
Node: Errors<95>992893
Ref: refman/methods/permission_error_3 errors993038
Ref: 747993038
Node: Examples<132>993159
Ref: refman/methods/permission_error_3 examples993265
Ref: 748993265
Node: representation_error/1993814
Ref: refman/methods/representation_error_1 doc993963
Ref: 749993963
Ref: refman/methods/representation_error_1 methods-representation-error-1993963
Ref: 1a9993963
Ref: refman/methods/representation_error_1 representation-error-1993963
Ref: 74a993963
Node: Description<132>994190
Ref: refman/methods/representation_error_1 description994323
Ref: 74b994323
Node: Modes and number of proofs<95>995211
Ref: refman/methods/representation_error_1 modes-and-number-of-proofs995363
Ref: 74c995363
Node: Errors<96>995478
Ref: refman/methods/representation_error_1 errors995627
Ref: 74d995627
Node: Examples<133>995722
Ref: refman/methods/representation_error_1 examples995832
Ref: 74e995832
Node: evaluation_error/1996370
Ref: refman/methods/evaluation_error_1 doc996517
Ref: 74f996517
Ref: refman/methods/evaluation_error_1 evaluation-error-1996517
Ref: 750996517
Ref: refman/methods/evaluation_error_1 methods-evaluation-error-1996517
Ref: 1aa996517
Node: Description<133>996736
Ref: refman/methods/evaluation_error_1 description996865
Ref: 751996865
Node: Modes and number of proofs<96>997536
Ref: refman/methods/evaluation_error_1 modes-and-number-of-proofs997684
Ref: 752997684
Node: Errors<97>997797
Ref: refman/methods/evaluation_error_1 errors997942
Ref: 753997942
Node: Examples<134>998038
Ref: refman/methods/evaluation_error_1 examples998144
Ref: 754998144
Node: resource_error/1998683
Ref: refman/methods/resource_error_1 doc998822
Ref: 755998822
Ref: refman/methods/resource_error_1 methods-resource-error-1998822
Ref: 1ab998822
Ref: refman/methods/resource_error_1 resource-error-1998822
Ref: 756998822
Node: Description<134>999037
Ref: refman/methods/resource_error_1 description999164
Ref: 757999164
Node: Modes and number of proofs<97>999872
Ref: refman/methods/resource_error_1 modes-and-number-of-proofs1000018
Ref: 7581000018
Node: Errors<98>1000129
Ref: refman/methods/resource_error_1 errors1000272
Ref: 7591000272
Node: Examples<135>1000365
Ref: refman/methods/resource_error_1 examples1000469
Ref: 75a1000469
Node: syntax_error/11000966
Ref: refman/methods/syntax_error_1 doc1001101
Ref: 75b1001101
Ref: refman/methods/syntax_error_1 methods-syntax-error-11001101
Ref: 1ac1001101
Ref: refman/methods/syntax_error_1 syntax-error-11001101
Ref: 75c1001101
Node: Description<135>1001312
Ref: refman/methods/syntax_error_1 description1001437
Ref: 75d1001437
Node: Modes and number of proofs<98>1001951
Ref: refman/methods/syntax_error_1 modes-and-number-of-proofs1002095
Ref: 75e1002095
Node: Errors<99>1002204
Ref: refman/methods/syntax_error_1 errors1002345
Ref: 75f1002345
Node: Examples<136>1002439
Ref: refman/methods/syntax_error_1 examples1002541
Ref: 7601002541
Node: system_error/01002993
Ref: refman/methods/system_error_0 doc1003103
Ref: 7611003103
Ref: refman/methods/system_error_0 methods-system-error-01003103
Ref: 1ad1003103
Ref: refman/methods/system_error_0 system-error-01003103
Ref: 7621003103
Node: Description<136>1003315
Ref: refman/methods/system_error_0 description1003440
Ref: 7631003440
Node: Modes and number of proofs<99>1003965
Ref: refman/methods/system_error_0 modes-and-number-of-proofs1004110
Ref: 7641004110
Node: Errors<100>1004210
Ref: refman/methods/system_error_0 errors1004352
Ref: 7651004352
Node: Examples<137>1004433
Ref: refman/methods/system_error_0 examples1004536
Ref: 7661004536
Node: All solutions1005000
Ref: refman/methods/solution_methods doc1005140
Ref: 7671005140
Ref: refman/methods/solution_methods all-solutions1005140
Ref: 7681005140
Ref: refman/methods/solution_methods solutions-methods1005140
Ref: 7691005140
Node: bagof/31005275
Ref: refman/methods/bagof_3 doc1005369
Ref: 76a1005369
Ref: refman/methods/bagof_3 bagof-31005369
Ref: 76b1005369
Ref: refman/methods/bagof_3 methods-bagof-31005369
Ref: 1bf1005369
Node: Description<137>1005622
Ref: refman/methods/bagof_3 description1005737
Ref: 76c1005737
Node: Meta-predicate template<10>1006635
Ref: refman/methods/bagof_3 meta-predicate-template1006790
Ref: 76d1006790
Node: Modes and number of proofs<100>1006876
Ref: refman/methods/bagof_3 modes-and-number-of-proofs1007026
Ref: 76e1007026
Node: Errors<101>1007149
Ref: refman/methods/bagof_3 errors1007285
Ref: 76f1007285
Node: Examples<138>1007595
Ref: refman/methods/bagof_3 examples1007691
Ref: 7701007691
Node: findall/31008242
Ref: refman/methods/findall_3 doc1008354
Ref: 7711008354
Ref: refman/methods/findall_3 findall-31008354
Ref: 7721008354
Ref: refman/methods/findall_3 methods-findall-31008354
Ref: 1c01008354
Node: Description<138>1008611
Ref: refman/methods/findall_3 description1008728
Ref: 7731008728
Node: Meta-predicate template<11>1009111
Ref: refman/methods/findall_3 meta-predicate-template1009268
Ref: 7741009268
Node: Modes and number of proofs<101>1009356
Ref: refman/methods/findall_3 modes-and-number-of-proofs1009508
Ref: 7751009508
Node: Errors<102>1009634
Ref: refman/methods/findall_3 errors1009772
Ref: 7761009772
Node: Examples<139>1010084
Ref: refman/methods/findall_3 examples1010182
Ref: 7771010182
Node: findall/41010724
Ref: refman/methods/findall_4 doc1010837
Ref: 7781010837
Ref: refman/methods/findall_4 findall-41010837
Ref: 7791010837
Ref: refman/methods/findall_4 methods-findall-41010837
Ref: 1c11010837
Node: Description<139>1011096
Ref: refman/methods/findall_4 description1011213
Ref: 77a1011213
Node: Meta-predicate template<12>1011579
Ref: refman/methods/findall_4 meta-predicate-template1011736
Ref: 77b1011736
Node: Modes and number of proofs<102>1011829
Ref: refman/methods/findall_4 modes-and-number-of-proofs1011981
Ref: 77c1011981
Node: Errors<103>1012114
Ref: refman/methods/findall_4 errors1012252
Ref: 77d1012252
Node: Examples<140>1012564
Ref: refman/methods/findall_4 examples1012662
Ref: 77e1012662
Node: forall/21013222
Ref: refman/methods/forall_2 doc1013333
Ref: 77f1013333
Ref: refman/methods/forall_2 forall-21013333
Ref: 7801013333
Ref: refman/methods/forall_2 methods-forall-21013333
Ref: 1c31013333
Node: Description<140>1013590
Ref: refman/methods/forall_2 description1013706
Ref: 7811013706
Node: Meta-predicate template<13>1014343
Ref: refman/methods/forall_2 meta-predicate-template1014499
Ref: 7821014499
Node: Modes and number of proofs<103>1014585
Ref: refman/methods/forall_2 modes-and-number-of-proofs1014736
Ref: 7831014736
Node: Errors<104>1014858
Ref: refman/methods/forall_2 errors1014995
Ref: 7841014995
Node: Examples<141>1015336
Ref: refman/methods/forall_2 examples1015433
Ref: 7851015433
Node: setof/31015935
Ref: refman/methods/setof_3 doc1016028
Ref: 7861016028
Ref: refman/methods/setof_3 methods-setof-31016028
Ref: 1c21016028
Ref: refman/methods/setof_3 setof-31016028
Ref: 7871016028
Node: Description<141>1016283
Ref: refman/methods/setof_3 description1016398
Ref: 7881016398
Node: Meta-predicate template<14>1017272
Ref: refman/methods/setof_3 meta-predicate-template1017427
Ref: 7891017427
Node: Modes and number of proofs<104>1017515
Ref: refman/methods/setof_3 modes-and-number-of-proofs1017665
Ref: 78a1017665
Node: Errors<105>1017790
Ref: refman/methods/setof_3 errors1017926
Ref: 78b1017926
Node: Examples<142>1018238
Ref: refman/methods/setof_3 examples1018334
Ref: 78c1018334
Node: Event handling<3>1018868
Ref: refman/methods/event_methods doc1019009
Ref: 78d1019009
Ref: refman/methods/event_methods event-handling1019009
Ref: 78e1019009
Ref: refman/methods/event_methods event-methods1019009
Ref: 78f1019009
Node: before/31019106
Ref: refman/methods/before_3 doc1019203
Ref: 7901019203
Ref: refman/methods/before_3 before-31019203
Ref: 7911019203
Ref: refman/methods/before_3 methods-before-31019203
Ref: 1011019203
Node: Description<142>1019402
Ref: refman/methods/before_3 description1019522
Ref: 7921019522
Ref: Description<142>-Footnote-11020142
Node: Modes and number of proofs<105>1020195
Ref: refman/methods/before_3 modes-and-number-of-proofs1020335
Ref: 7931020335
Node: Errors<106>1020485
Ref: refman/methods/before_3 errors1020622
Ref: 7941020622
Node: Examples<143>1020661
Ref: refman/methods/before_3 examples1020758
Ref: 7951020758
Node: after/31021215
Ref: refman/methods/after_3 doc1021312
Ref: 7961021312
Ref: refman/methods/after_3 after-31021312
Ref: 7971021312
Ref: refman/methods/after_3 methods-after-31021312
Ref: 1021021312
Node: Description<143>1021509
Ref: refman/methods/after_3 description1021628
Ref: 7981021628
Ref: Description<143>-Footnote-11022246
Node: Modes and number of proofs<106>1022299
Ref: refman/methods/after_3 modes-and-number-of-proofs1022438
Ref: 7991022438
Node: Errors<107>1022587
Ref: refman/methods/after_3 errors1022723
Ref: 79a1022723
Node: Examples<144>1022762
Ref: refman/methods/after_3 examples1022858
Ref: 79b1022858
Node: Message forwarding1023304
Ref: refman/methods/forwarding_methods doc1023464
Ref: 79c1023464
Ref: refman/methods/forwarding_methods forwarding-methods1023464
Ref: 79d1023464
Ref: refman/methods/forwarding_methods message-forwarding1023464
Ref: 79e1023464
Node: forward/11023558
Ref: refman/methods/forward_1 doc1023641
Ref: 79f1023641
Ref: refman/methods/forward_1 forward-11023641
Ref: 7a01023641
Ref: refman/methods/forward_1 methods-forward-11023641
Ref: 1051023641
Node: Description<144>1023842
Ref: refman/methods/forward_1 description1023963
Ref: 7a11023963
Ref: Description<144>-Footnote-11024492
Node: Modes and number of proofs<107>1024545
Ref: refman/methods/forward_1 modes-and-number-of-proofs1024686
Ref: 7a21024686
Node: Errors<108>1024797
Ref: refman/methods/forward_1 errors1024935
Ref: 7a31024935
Node: Examples<145>1024974
Ref: refman/methods/forward_1 examples1025072
Ref: 7a41025072
Node: Definite clause grammar rules<2>1025336
Ref: refman/methods/dcg_methods doc1025505
Ref: 7a51025505
Ref: refman/methods/dcg_methods dcg-methods1025505
Ref: 7a61025505
Ref: refman/methods/dcg_methods definite-clause-grammar-rules1025505
Ref: 7a71025505
Node: call//1-N1025674
Ref: refman/methods/call_1 doc1025786
Ref: 7a81025786
Ref: refman/methods/call_1 call-1-n1025786
Ref: 7a91025786
Ref: refman/methods/call_1 methods-call-11025786
Ref: 1c91025786
Node: Description<145>1026020
Ref: refman/methods/call_1 description1026136
Ref: 7aa1026136
Node: Meta-non-terminal template1027304
Ref: refman/methods/call_1 meta-non-terminal-template1027460
Ref: 7ab1027460
Node: Modes and number of proofs<108>1027591
Ref: refman/methods/call_1 modes-and-number-of-proofs1027742
Ref: 7ac1027742
Node: Errors<109>1027954
Ref: refman/methods/call_1 errors1028092
Ref: 7ad1028092
Node: Examples<146>1028304
Ref: refman/methods/call_1 examples1028402
Ref: 7ae1028402
Node: eos//01029242
Ref: refman/methods/eos_0 doc1029372
Ref: 7af1029372
Ref: refman/methods/eos_0 eos-01029372
Ref: 7b01029372
Ref: refman/methods/eos_0 methods-eos-01029372
Ref: 1ca1029372
Node: Description<146>1029569
Ref: refman/methods/eos_0 description1029687
Ref: 7b11029687
Node: Modes and number of proofs<109>1029876
Ref: refman/methods/eos_0 modes-and-number-of-proofs1030014
Ref: 7b21030014
Node: Errors<110>1030111
Ref: refman/methods/eos_0 errors1030246
Ref: 7b31030246
Node: Examples<147>1030289
Ref: refman/methods/eos_0 examples1030384
Ref: 7b41030384
Node: phrase//11030576
Ref: refman/methods/phrase_1 doc1030705
Ref: 7b51030705
Ref: refman/methods/phrase_1 methods-phrase-11030705
Ref: 1c81030705
Ref: refman/methods/phrase_1 phrase-11030705
Ref: 7b61030705
Node: Description<147>1030971
Ref: refman/methods/phrase_1 description1031090
Ref: 7b71031090
Node: Meta-non-terminal template<2>1031412
Ref: refman/methods/phrase_1 meta-non-terminal-template1031571
Ref: 7b91031571
Node: Modes and number of proofs<110>1031662
Ref: refman/methods/phrase_1 modes-and-number-of-proofs1031816
Ref: 7ba1031816
Node: Errors<111>1031930
Ref: refman/methods/phrase_1 errors1032068
Ref: 7bb1032068
Node: Examples<148>1032306
Ref: refman/methods/phrase_1 examples1032404
Ref: 7bc1032404
Node: phrase/21032559
Ref: refman/methods/phrase_2 doc1032690
Ref: 7bd1032690
Ref: refman/methods/phrase_2 methods-phrase-21032690
Ref: 18e1032690
Ref: refman/methods/phrase_2 phrase-21032690
Ref: 7be1032690
Node: Description<148>1032949
Ref: refman/methods/phrase_2 description1033065
Ref: 7bf1033065
Node: Meta-predicate template<15>1034029
Ref: refman/methods/phrase_2 meta-predicate-template1034185
Ref: 7c01034185
Node: Modes and number of proofs<111>1034273
Ref: refman/methods/phrase_2 modes-and-number-of-proofs1034424
Ref: 7c11034424
Node: Errors<112>1034545
Ref: refman/methods/phrase_2 errors1034682
Ref: 7c21034682
Node: Examples<149>1034920
Ref: refman/methods/phrase_2 examples1035017
Ref: 7c31035017
Node: phrase/31035530
Ref: refman/methods/phrase_3 doc1035643
Ref: 7c41035643
Ref: refman/methods/phrase_3 methods-phrase-31035643
Ref: 18f1035643
Ref: refman/methods/phrase_3 phrase-31035643
Ref: 7c51035643
Node: Description<149>1035902
Ref: refman/methods/phrase_3 description1036018
Ref: 7c61036018
Node: Meta-predicate template<16>1037035
Ref: refman/methods/phrase_3 meta-predicate-template1037191
Ref: 7c71037191
Node: Modes and number of proofs<112>1037282
Ref: refman/methods/phrase_3 modes-and-number-of-proofs1037433
Ref: 7c81037433
Node: Errors<113>1037561
Ref: refman/methods/phrase_3 errors1037698
Ref: 7c91037698
Node: Examples<150>1037936
Ref: refman/methods/phrase_3 examples1038033
Ref: 7ca1038033
Node: Term and goal expansion<2>1038544
Ref: refman/methods/expansion_methods doc1038712
Ref: 7cb1038712
Ref: refman/methods/expansion_methods expansion-methods1038712
Ref: 7cc1038712
Ref: refman/methods/expansion_methods term-and-goal-expansion1038712
Ref: 7cd1038712
Node: expand_term/21038882
Ref: refman/methods/expand_term_2 doc1039002
Ref: 7ce1039002
Ref: refman/methods/expand_term_2 expand-term-21039002
Ref: 7cf1039002
Ref: refman/methods/expand_term_2 methods-expand-term-21039002
Ref: 1b71039002
Node: Description<150>1039213
Ref: refman/methods/expand_term_2 description1039338
Ref: 7d01039338
Node: Modes and number of proofs<113>1040776
Ref: refman/methods/expand_term_2 modes-and-number-of-proofs1040921
Ref: 7d11040921
Node: Errors<114>1041032
Ref: refman/methods/expand_term_2 errors1041174
Ref: 7d21041174
Node: Examples<151>1041215
Ref: refman/methods/expand_term_2 examples1041317
Ref: 7d31041317
Node: term_expansion/21041483
Ref: refman/methods/term_expansion_2 doc1041625
Ref: 7d41041625
Ref: refman/methods/term_expansion_2 methods-term-expansion-21041625
Ref: fc1041625
Ref: refman/methods/term_expansion_2 term-expansion-21041625
Ref: 7d51041625
Node: Description<151>1041842
Ref: refman/methods/term_expansion_2 description1041970
Ref: 7d61041970
Ref: Description<151>-Footnote-11043391
Node: Modes and number of proofs<114>1043442
Ref: refman/methods/term_expansion_2 modes-and-number-of-proofs1043590
Ref: 7d71043590
Node: Errors<115>1043774
Ref: refman/methods/term_expansion_2 errors1043919
Ref: 7d81043919
Node: Examples<152>1043960
Ref: refman/methods/term_expansion_2 examples1044065
Ref: 7d91044065
Node: expand_goal/21044410
Ref: refman/methods/expand_goal_2 doc1044555
Ref: 7da1044555
Ref: refman/methods/expand_goal_2 expand-goal-21044555
Ref: 7db1044555
Ref: refman/methods/expand_goal_2 methods-expand-goal-21044555
Ref: 3121044555
Node: Description<152>1044768
Ref: refman/methods/expand_goal_2 description1044893
Ref: 7dc1044893
Node: Modes and number of proofs<115>1045785
Ref: refman/methods/expand_goal_2 modes-and-number-of-proofs1045930
Ref: 7dd1045930
Node: Errors<116>1046043
Ref: refman/methods/expand_goal_2 errors1046185
Ref: 7de1046185
Node: Examples<153>1046228
Ref: refman/methods/expand_goal_2 examples1046330
Ref: 7df1046330
Node: goal_expansion/21046498
Ref: refman/methods/goal_expansion_2 doc1046618
Ref: 7e01046618
Ref: refman/methods/goal_expansion_2 goal-expansion-21046618
Ref: 7e11046618
Ref: refman/methods/goal_expansion_2 methods-goal-expansion-21046618
Ref: fd1046618
Node: Description<153>1046837
Ref: refman/methods/goal_expansion_2 description1046965
Ref: 7e21046965
Ref: Description<153>-Footnote-11048431
Node: Modes and number of proofs<116>1048482
Ref: refman/methods/goal_expansion_2 modes-and-number-of-proofs1048630
Ref: 7e31048630
Node: Errors<117>1048762
Ref: refman/methods/goal_expansion_2 errors1048907
Ref: 7e41048907
Node: Examples<154>1048950
Ref: refman/methods/goal_expansion_2 examples1049055
Ref: 7e51049055
Node: Coinduction hooks1049359
Ref: refman/methods/coinduction_methods doc1049511
Ref: 7e61049511
Ref: refman/methods/coinduction_methods coinduction-hooks1049511
Ref: 7e71049511
Ref: refman/methods/coinduction_methods coinduction-methods1049511
Ref: 7e81049511
Node: coinductive_success_hook/1-21049624
Ref: refman/methods/coinductive_success_hook_1_2 doc1049725
Ref: 7e91049725
Ref: refman/methods/coinductive_success_hook_1_2 coinductive-success-hook-1-21049725
Ref: 7ea1049725
Ref: refman/methods/coinductive_success_hook_1_2 methods-coinductive-success-hook-1-21049725
Ref: 4b21049725
Node: Description<154>1049966
Ref: refman/methods/coinductive_success_hook_1_2 description1050106
Ref: 7eb1050106
Node: Modes and number of proofs<117>1050987
Ref: refman/methods/coinductive_success_hook_1_2 modes-and-number-of-proofs1051147
Ref: 7ec1051147
Node: Errors<118>1051342
Ref: refman/methods/coinductive_success_hook_1_2 errors1051499
Ref: 7ed1051499
Node: Examples<155>1051540
Ref: refman/methods/coinductive_success_hook_1_2 examples1051657
Ref: 7ee1051657
Node: Message printing1052234
Ref: refman/methods/printing_methods doc1052375
Ref: 7ef1052375
Ref: refman/methods/printing_methods message-printing1052375
Ref: 7f01052375
Ref: refman/methods/printing_methods printing-methods1052375
Ref: 7f11052375
Node: print_message/31052621
Ref: refman/methods/print_message_3 doc1052734
Ref: 7f21052734
Ref: refman/methods/print_message_3 methods-print-message-31052734
Ref: 2fe1052734
Ref: refman/methods/print_message_3 print-message-31052734
Ref: 7f31052734
Node: Description<155>1052949
Ref: refman/methods/print_message_3 description1053076
Ref: 7f41053076
Ref: Description<155>-Footnote-11054410
Node: Modes and number of proofs<118>1054457
Ref: refman/methods/print_message_3 modes-and-number-of-proofs1054604
Ref: 7f51054604
Node: Errors<119>1054730
Ref: refman/methods/print_message_3 errors1054874
Ref: 7f61054874
Node: Examples<156>1054915
Ref: refman/methods/print_message_3 examples1055019
Ref: 7f71055019
Node: message_tokens//21055439
Ref: refman/methods/message_tokens_2 doc1055575
Ref: 7fb1055575
Ref: refman/methods/message_tokens_2 message-tokens-21055575
Ref: 7fc1055575
Ref: refman/methods/message_tokens_2 methods-message-tokens-21055575
Ref: 3001055575
Node: Description<156>1055794
Ref: refman/methods/message_tokens_2 description1055923
Ref: 7fd1055923
Ref: Description<156>-Footnote-11056409
Node: Modes and number of proofs<119>1056456
Ref: refman/methods/message_tokens_2 modes-and-number-of-proofs1056605
Ref: 7fe1056605
Node: Errors<120>1056732
Ref: refman/methods/message_tokens_2 errors1056878
Ref: 7ff1056878
Node: Examples<157>1056919
Ref: refman/methods/message_tokens_2 examples1057025
Ref: 8001057025
Node: message_hook/41057571
Ref: refman/methods/message_hook_4 doc1057715
Ref: 8011057715
Ref: refman/methods/message_hook_4 message-hook-41057715
Ref: 8021057715
Ref: refman/methods/message_hook_4 methods-message-hook-41057715
Ref: 3061057715
Node: Description<157>1057930
Ref: refman/methods/message_hook_4 description1058056
Ref: 8031058056
Ref: Description<157>-Footnote-11058545
Node: Modes and number of proofs<120>1058592
Ref: refman/methods/message_hook_4 modes-and-number-of-proofs1058738
Ref: 8041058738
Node: Errors<121>1058888
Ref: refman/methods/message_hook_4 errors1059031
Ref: 8051059031
Node: Examples<158>1059074
Ref: refman/methods/message_hook_4 examples1059177
Ref: 8061059177
Node: message_prefix_stream/41059855
Ref: refman/methods/message_prefix_stream_4 doc1060003
Ref: 8071060003
Ref: refman/methods/message_prefix_stream_4 message-prefix-stream-41060003
Ref: 8081060003
Ref: refman/methods/message_prefix_stream_4 methods-message-prefix-stream-41060003
Ref: 3041060003
Node: Description<158>1060236
Ref: refman/methods/message_prefix_stream_4 description1060371
Ref: 8091060371
Ref: Description<158>-Footnote-11060974
Ref: Description<158>-Footnote-21061021
Node: Modes and number of proofs<121>1061068
Ref: refman/methods/message_prefix_stream_4 modes-and-number-of-proofs1061223
Ref: 80a1061223
Node: Errors<122>1061384
Ref: refman/methods/message_prefix_stream_4 errors1061536
Ref: 80b1061536
Node: Examples<159>1061579
Ref: refman/methods/message_prefix_stream_4 examples1061691
Ref: 80c1061691
Node: message_prefix_file/61062230
Ref: refman/methods/message_prefix_file_6 doc1062386
Ref: 80d1062386
Ref: refman/methods/message_prefix_file_6 message-prefix-file-61062386
Ref: 80e1062386
Ref: refman/methods/message_prefix_file_6 methods-message-prefix-file-61062386
Ref: 3071062386
Node: Description<159>1062615
Ref: refman/methods/message_prefix_file_6 description1062748
Ref: 80f1062748
Ref: Description<159>-Footnote-11063502
Ref: Description<159>-Footnote-21063549
Node: Modes and number of proofs<122>1063596
Ref: refman/methods/message_prefix_file_6 modes-and-number-of-proofs1063749
Ref: 8101063749
Node: Errors<123>1063921
Ref: refman/methods/message_prefix_file_6 errors1064071
Ref: 8111064071
Node: Examples<160>1064114
Ref: refman/methods/message_prefix_file_6 examples1064224
Ref: 8121064224
Node: print_message_tokens/31064769
Ref: refman/methods/print_message_tokens_3 doc1064923
Ref: 8131064923
Ref: refman/methods/print_message_tokens_3 methods-print-message-tokens-31064923
Ref: 7f81064923
Ref: refman/methods/print_message_tokens_3 print-message-tokens-31064923
Ref: 8141064923
Node: Description<160>1065154
Ref: refman/methods/print_message_tokens_3 description1065288
Ref: 8151065288
Ref: Description<160>-Footnote-11066048
Node: Modes and number of proofs<123>1066095
Ref: refman/methods/print_message_tokens_3 modes-and-number-of-proofs1066249
Ref: 8161066249
Node: Errors<124>1066405
Ref: refman/methods/print_message_tokens_3 errors1066556
Ref: 8171066556
Node: Examples<161>1066599
Ref: refman/methods/print_message_tokens_3 examples1066710
Ref: 8181066710
Node: print_message_token/41067148
Ref: refman/methods/print_message_token_4 doc1067272
Ref: 8191067272
Ref: refman/methods/print_message_token_4 methods-print-message-token-41067272
Ref: 7f91067272
Ref: refman/methods/print_message_token_4 print-message-token-41067272
Ref: 81a1067272
Node: Description<161>1067501
Ref: refman/methods/print_message_token_4 description1067634
Ref: 81b1067634
Ref: Description<161>-Footnote-11068100
Node: Modes and number of proofs<124>1068147
Ref: refman/methods/print_message_token_4 modes-and-number-of-proofs1068300
Ref: 81c1068300
Node: Errors<125>1068464
Ref: refman/methods/print_message_token_4 errors1068614
Ref: 81d1068614
Node: Examples<162>1068657
Ref: refman/methods/print_message_token_4 examples1068767
Ref: 81e1068767
Node: Question asking1069276
Ref: refman/methods/asking_methods doc1069391
Ref: 81f1069391
Ref: refman/methods/asking_methods asking-methods1069391
Ref: 8201069391
Ref: refman/methods/asking_methods question-asking1069391
Ref: 8211069391
Node: ask_question/51069535
Ref: refman/methods/ask_question_5 doc1069644
Ref: 8221069644
Ref: refman/methods/ask_question_5 ask-question-51069644
Ref: 8231069644
Ref: refman/methods/ask_question_5 methods-ask-question-51069644
Ref: 30b1069644
Node: Description<162>1069913
Ref: refman/methods/ask_question_5 description1070039
Ref: 8241070039
Node: Modes and number of proofs<125>1071128
Ref: refman/methods/ask_question_5 modes-and-number-of-proofs1071290
Ref: 8251071290
Node: Meta-predicate template<17>1071433
Ref: refman/methods/ask_question_5 meta-predicate-template1071590
Ref: 8261071590
Node: Errors<126>1071691
Ref: refman/methods/ask_question_5 errors1071830
Ref: 8271071830
Node: Examples<163>1071871
Ref: refman/methods/ask_question_5 examples1071974
Ref: 8281071974
Node: question_hook/61072396
Ref: refman/methods/question_hook_6 doc1072538
Ref: 8291072538
Ref: refman/methods/question_hook_6 methods-question-hook-61072538
Ref: 30d1072538
Ref: refman/methods/question_hook_6 question-hook-61072538
Ref: 82a1072538
Node: Description<163>1072809
Ref: refman/methods/question_hook_6 description1072936
Ref: 82b1072936
Ref: Description<163>-Footnote-11073446
Node: Modes and number of proofs<126>1073493
Ref: refman/methods/question_hook_6 modes-and-number-of-proofs1073656
Ref: 82c1073656
Node: Meta-predicate template<18>1073823
Ref: refman/methods/question_hook_6 meta-predicate-template1073981
Ref: 82d1073981
Node: Errors<127>1074088
Ref: refman/methods/question_hook_6 errors1074228
Ref: 82e1074228
Node: Examples<164>1074271
Ref: refman/methods/question_hook_6 examples1074375
Ref: 82f1074375
Node: question_prompt_stream/41074927
Ref: refman/methods/question_prompt_stream_4 doc1075046
Ref: 8301075046
Ref: refman/methods/question_prompt_stream_4 methods-question-prompt-stream-41075046
Ref: 7fa1075046
Ref: refman/methods/question_prompt_stream_4 question-prompt-stream-41075046
Ref: 8311075046
Node: Description<164>1075281
Ref: refman/methods/question_prompt_stream_4 description1075417
Ref: 8321075417
Ref: Description<164>-Footnote-11075807
Node: Modes and number of proofs<127>1075854
Ref: refman/methods/question_prompt_stream_4 modes-and-number-of-proofs1076010
Ref: 8331076010
Node: Errors<128>1076172
Ref: refman/methods/question_prompt_stream_4 errors1076325
Ref: 8341076325
Node: Examples<165>1076368
Ref: refman/methods/question_prompt_stream_4 examples1076481
Ref: 8351076481
Node: Tutorial1076973
Ref: tutorial/index doc1077077
Ref: 8361077077
Ref: tutorial/index tutorial1077077
Ref: 8371077077
Node: List predicates1077219
Ref: tutorial/lists doc1077332
Ref: 8381077332
Ref: tutorial/lists list-predicates1077332
Ref: 8391077332
Node: Defining a list object1077572
Ref: tutorial/lists defining-a-list-object1077698
Ref: 83a1077698
Ref: tutorial/lists object1077698
Ref: 83b1077698
Node: Defining a list protocol1080241
Ref: tutorial/lists defining-a-list-protocol1080383
Ref: 83c1080383
Ref: tutorial/lists protocol1080383
Ref: 83d1080383
Node: Summary1082581
Ref: tutorial/lists summary1082692
Ref: 83e1082692
Node: Dynamic object attributes1083144
Ref: tutorial/attributes doc1083297
Ref: 83f1083297
Ref: tutorial/attributes dynamic-object-attributes1083297
Ref: 8401083297
Node: Defining a category1083659
Ref: tutorial/attributes category1083790
Ref: 8411083790
Ref: tutorial/attributes defining-a-category1083790
Ref: 8421083790
Node: Importing the category1087454
Ref: tutorial/attributes importing1087604
Ref: 8431087604
Ref: tutorial/attributes importing-the-category1087604
Ref: 8441087604
Node: Summary<2>1088166
Ref: tutorial/attributes summary1088288
Ref: 8451088288
Node: A reflective class-based system1088921
Ref: tutorial/reflection doc1089077
Ref: 8461089077
Ref: tutorial/reflection a-reflective-class-based-system1089077
Ref: 8471089077
Node: Defining the base classes1090192
Ref: tutorial/reflection classes1090323
Ref: 8481090323
Ref: tutorial/reflection defining-the-base-classes1090323
Ref: 8491090323
Node: Summary<3>1091706
Ref: tutorial/reflection summary1091837
Ref: 84a1091837
Node: Profiling programs1092435
Ref: tutorial/profiling doc1092557
Ref: 84b1092557
Ref: tutorial/profiling profiling-programs1092557
Ref: 84c1092557
Node: Messages as events1092879
Ref: tutorial/profiling messages-as-events1093001
Ref: 84d1093001
Ref: tutorial/profiling profiling-events1093001
Ref: 84e1093001
Node: Profilers as monitors1094133
Ref: tutorial/profiling profilers-as-monitors1094274
Ref: 84f1094274
Ref: tutorial/profiling profiling-monitors1094274
Ref: 8501094274
Node: Summary<4>1097257
Ref: tutorial/profiling summary1097371
Ref: 8511097371
Node: FAQ1098239
Ref: faq/index doc1098342
Ref: 8521098342
Ref: faq/index faq1098342
Ref: 8531098342
Node: General1098550
Ref: faq/general doc1098638
Ref: 8541098638
Ref: faq/general faq-general1098638
Ref: 8551098638
Ref: faq/general general1098638
Ref: 8561098638
Node: Why are all versions of Logtalk numbered 2 x or 3 x?1099230
Ref: faq/general faq-general-versions1099401
Ref: 8571099401
Ref: faq/general why-are-all-versions-of-logtalk-numbered-2-x-or-3-x1099401
Ref: 85b1099401
Node: Why do I need a Prolog compiler to use Logtalk?1100067
Ref: faq/general faq-general-prolog1100301
Ref: 8581100301
Ref: faq/general why-do-i-need-a-prolog-compiler-to-use-logtalk1100301
Ref: 85c1100301
Node: Is the Logtalk implementation based on Prolog modules?1100934
Ref: faq/general faq-general-modules1101167
Ref: 8591101167
Ref: faq/general is-the-logtalk-implementation-based-on-prolog-modules1101167
Ref: 85d1101167
Node: Does the Logtalk implementation use term-expansion?1101821
Ref: faq/general does-the-logtalk-implementation-use-term-expansion1101998
Ref: 85e1101998
Ref: faq/general faq-general-expansion1101998
Ref: 85a1101998
Node: Compatibility1102221
Ref: faq/compatibility doc1102330
Ref: 85f1102330
Ref: faq/compatibility compatibility1102330
Ref: 8601102330
Ref: faq/compatibility faq-compatibility1102330
Ref: 8611102330
Node: What are the backend Prolog compiler requirements to run Logtalk?1102811
Ref: faq/compatibility faq-compatibility-requirements1103003
Ref: 8621103003
Ref: faq/compatibility what-are-the-backend-prolog-compiler-requirements-to-run-logtalk1103003
Ref: 8651103003
Ref: What are the backend Prolog compiler requirements to run Logtalk?-Footnote-11103240
Node: Can I use constraint-based packages with Logtalk?1103294
Ref: faq/compatibility can-i-use-constraint-based-packages-with-logtalk1103557
Ref: 8661103557
Ref: faq/compatibility faq-compatibility-constraints1103557
Ref: 8631103557
Node: Can I use Logtalk objects and Prolog modules at the same time?1104198
Ref: faq/compatibility can-i-use-logtalk-objects-and-prolog-modules-at-the-same-time1104387
Ref: 8671104387
Ref: faq/compatibility faq-compatibility-modules1104387
Ref: 8641104387
Node: Installation1104975
Ref: faq/installation doc1105088
Ref: 8681105088
Ref: faq/installation faq-installation1105088
Ref: 8691105088
Ref: faq/installation installation1105088
Ref: 86a1105088
Node: The integration scripts/shortcuts are not working!1105438
Ref: faq/installation faq-installation-scripts1105641
Ref: 86b1105641
Ref: faq/installation the-integration-scripts-shortcuts-are-not-working1105641
Ref: 86d1105641
Node: I get errors when starting up Logtalk after upgrading to the latest version!1106591
Ref: faq/installation faq-installation-startup-errors1106794
Ref: 86c1106794
Ref: faq/installation i-get-errors-when-starting-up-logtalk-after-upgrading-to-the-latest-version1106794
Ref: 86e1106794
Node: Portability1107363
Ref: faq/portability doc1107474
Ref: 86f1107474
Ref: faq/portability faq-portability1107474
Ref: 8701107474
Ref: faq/portability portability1107474
Ref: 8711107474
Node: Are my Logtalk applications portable across Prolog compilers?1107821
Ref: faq/portability are-my-logtalk-applications-portable-across-prolog-compilers1108020
Ref: 8741108020
Ref: faq/portability faq-portability-prolog1108020
Ref: 8721108020
Node: Are my Logtalk applications portable across operating systems?1108810
Ref: faq/portability are-my-logtalk-applications-portable-across-operating-systems1109009
Ref: 8751109009
Ref: faq/portability faq-portability-os1109009
Ref: 8731109009
Node: Programming1109567
Ref: faq/programming doc1109681
Ref: 8761109681
Ref: faq/programming faq-programming1109681
Ref: 8771109681
Ref: faq/programming programming1109681
Ref: 8781109681
Node: Should I use prototypes or classes in my application?1110630
Ref: faq/programming faq-programming-either-prototypes-classes1110821
Ref: 8791110821
Ref: faq/programming should-i-use-prototypes-or-classes-in-my-application1110821
Ref: 87f1110821
Node: Can I use both classes and prototypes in the same application?1111324
Ref: faq/programming can-i-use-both-classes-and-prototypes-in-the-same-application1111579
Ref: 8801111579
Ref: faq/programming faq-programming-both-prototypes-classes1111579
Ref: 87a1111579
Node: Can I mix classes and prototypes in the same hierarchy?1111815
Ref: faq/programming can-i-mix-classes-and-prototypes-in-the-same-hierarchy1112085
Ref: 8811112085
Ref: faq/programming faq-programming-hierarchy1112085
Ref: 87b1112085
Node: Can I use a protocol or a category with both prototypes and classes?1112335
Ref: faq/programming can-i-use-a-protocol-or-a-category-with-both-prototypes-and-classes1112613
Ref: 8821112613
Ref: faq/programming faq-programming-protocols-categories1112613
Ref: 87c1112613
Node: What support is provided in Logtalk for defining and using components?1112951
Ref: faq/programming faq-programming-components1113237
Ref: 87d1113237
Ref: faq/programming what-support-is-provided-in-logtalk-for-defining-and-using-components1113237
Ref: 8831113237
Node: What support is provided in Logtalk for reflective programming?1113881
Ref: faq/programming faq-programming-reflection1114090
Ref: 87e1114090
Ref: faq/programming what-support-is-provided-in-logtalk-for-reflective-programming1114090
Ref: 8841114090
Node: Troubleshooting1114526
Ref: faq/troubleshooting doc1114638
Ref: 8851114638
Ref: faq/troubleshooting faq-troubleshooting1114638
Ref: 8861114638
Ref: faq/troubleshooting troubleshooting1114638
Ref: 8871114638
Node: Using compiler options on calls to the Logtalk compiling and loading predicates does not work!1115575
Ref: faq/troubleshooting faq-troubleshooting-options1115850
Ref: 8881115850
Ref: faq/troubleshooting using-compiler-options-on-calls-to-the-logtalk-compiling-and-loading-predicates-does-not-work1115850
Ref: 88b1115850
Node: Gecko-based browsers e g Firefox show non-rendered HTML entities when browsing XML documenting files!1116542
Ref: faq/troubleshooting faq-troubleshooting-gecko1116973
Ref: 8891116973
Ref: faq/troubleshooting gecko-based-browsers-e-g-firefox-show-non-rendered-html-entities-when-browsing-xml-documenting-files1116973
Ref: 88c1116973
Node: Compiling a source file results in errors or warnings but the Logtalk compiler reports a successful compilation with zero errors and zero warnings!1117774
Ref: faq/troubleshooting compiling-a-source-file-results-in-errors-or-warnings-but-the-logtalk-compiler-reports-a-successful-compilation-with-zero-errors-and-zero-warnings1118102
Ref: 88d1118102
Ref: faq/troubleshooting faq-troubleshooting-warnings1118102
Ref: 88a1118102
Node: Usability1119132
Ref: faq/usability doc1119243
Ref: 88e1119243
Ref: faq/usability faq-usability1119243
Ref: 88f1119243
Ref: faq/usability usability1119243
Ref: 8901119243
Node: Is there a shortcut for compiling and loading source files?1119722
Ref: faq/usability faq-usability-shortcuts1119928
Ref: 8911119928
Ref: faq/usability is-there-a-shortcut-for-compiling-and-loading-source-files1119928
Ref: 8941119928
Node: Is there an equivalent directive to the ensure_loaded/1 Prolog directive?1120332
Ref: faq/usability faq-usability-ensure-loaded1120594
Ref: 8921120594
Ref: faq/usability is-there-an-equivalent-directive-to-the-ensure-loaded-1-prolog-directive1120594
Ref: 8951120594
Node: Are there shortcuts for the make functionality?1120955
Ref: faq/usability are-there-shortcuts-for-the-make-functionality1121149
Ref: 8961121149
Ref: faq/usability faq-usability-make1121149
Ref: 8931121149
Node: Deployment1121841
Ref: faq/deployment doc1121951
Ref: 8971121951
Ref: faq/deployment deployment1121951
Ref: 8981121951
Ref: faq/deployment faq-deployment1121951
Ref: 8991121951
Node: Can I create standalone applications with Logtalk?1122116
Ref: faq/deployment can-i-create-standalone-applications-with-logtalk1122232
Ref: 89b1122232
Ref: faq/deployment faq-deployment-create1122232
Ref: 89a1122232
Ref: Can I create standalone applications with Logtalk?-Footnote-11122838
Node: Performance<3>1122881
Ref: faq/performance doc1122991
Ref: 89c1122991
Ref: faq/performance id11122991
Ref: 89d1122991
Ref: faq/performance performance1122991
Ref: 89e1122991
Node: Is Logtalk implemented as a meta-interpreter?1123829
Ref: faq/performance is-logtalk-implemented-as-a-meta-interpreter1124039
Ref: 8a31124039
Ref: faq/performance performance-meta-interpreter1124039
Ref: 89f1124039
Node: What kind of code Logtalk generates when compiling objects? Dynamic code? Static code?1124389
Ref: faq/performance performance-code-generated1124698
Ref: 8a01124698
Ref: faq/performance what-kind-of-code-logtalk-generates-when-compiling-objects-dynamic-code-static-code1124698
Ref: 8a41124698
Node: How about message-sending performance? Does Logtalk use static binding or dynamic binding?1125261
Ref: faq/performance how-about-message-sending-performance-does-logtalk-use-static-binding-or-dynamic-binding1125602
Ref: 8a51125602
Ref: faq/performance performance-binding1125602
Ref: 8a11125602
Node: Which Prolog-dependent factors are most crucial for good Logtalk performance?1126657
Ref: faq/performance which-prolog-dependent-factors-are-most-crucial-for-good-logtalk-performance1126991
Ref: 8a61126991
Node: How does Logtalk performance compare with plain Prolog and with Prolog modules?1127756
Ref: faq/performance how-does-logtalk-performance-compare-with-plain-prolog-and-with-prolog-modules1127991
Ref: 8a71127991
Ref: faq/performance performance-prolog1127991
Ref: 8a21127991
Ref: How does Logtalk performance compare with plain Prolog and with Prolog modules?-Footnote-11128796
Node: Licensing1128841
Ref: faq/licensing doc1128948
Ref: 8a81128948
Ref: faq/licensing faq-licensing1128948
Ref: 8a91128948
Ref: faq/licensing licensing1128948
Ref: 8aa1128948
Node: What’s the Logtalk distribution license?1129402
Ref: faq/licensing faq-licensing-license1129565
Ref: 8ab1129565
Ref: faq/licensing what-s-the-logtalk-distribution-license1129565
Ref: 8ae1129565
Ref: What’s the Logtalk distribution license?-Footnote-11129744
Node: Can Logtalk be used in commercial applications?1129818
Ref: faq/licensing can-logtalk-be-used-in-commercial-applications1130069
Ref: 8af1130069
Ref: faq/licensing faq-licensing-commercial1130069
Ref: 8ac1130069
Ref: Can Logtalk be used in commercial applications?-Footnote-11130323
Node: What’s the final license for a combination of Logtalk with a Prolog compiler?1130382
Ref: faq/licensing faq-licensing-combining1130582
Ref: 8ad1130582
Ref: faq/licensing what-s-the-final-license-for-a-combination-of-logtalk-with-a-prolog-compiler1130582
Ref: 8b01130582
Ref: What’s the final license for a combination of Logtalk with a Prolog compiler?-Footnote-11130855
Node: Support1130898
Ref: faq/support doc1130982
Ref: 8b11130982
Ref: faq/support faq-support1130982
Ref: 8b21130982
Ref: faq/support support1130982
Ref: 8b31130982
Node: Are there professional consulting training and supporting services?1131252
Ref: faq/support are-there-professional-consulting-training-and-supporting-services1131382
Ref: 8b51131382
Ref: faq/support faq-support-professional1131382
Ref: 8b41131382
Ref: Are there professional consulting training and supporting services?-Footnote-11131685
Node: Developer Tools1131713
Ref: devtools/index doc1131817
Ref: 2801131817
Ref: devtools/index developer-tools1131817
Ref: 8b61131817
Node: Overview1132240
Ref: devtools/overview doc1132332
Ref: 8b71132332
Ref: devtools/overview overview1132332
Ref: 8b81132332
Node: Loading the developer tools1133121
Ref: devtools/overview loading-the-developer-tools1133240
Ref: 8b91133240
Node: Tools documentation1134304
Ref: devtools/overview tools-documentation1134450
Ref: 8ba1134450
Node: Tools common flags1134743
Ref: devtools/overview tools-common-flags1134880
Ref: 8bb1134880
Node: Tools requirements1135324
Ref: devtools/overview tools-requirements1135433
Ref: 8bc1135433
Node: Tool dependencies for full functionality1136334
Ref: devtools/overview tool-dependencies-for-full-functionality1136498
Ref: 8bd1136498
Node: Python dependencies all operating-systems1137005
Ref: devtools/overview python-dependencies-all-operating-systems1137194
Ref: 8be1137194
Node: macOS - MacPorts1137589
Ref: devtools/overview macos-macports1137754
Ref: 8bf1137754
Node: macOS - Homebrew1138070
Ref: devtools/overview macos-homebrew1138200
Ref: 8c01138200
Node: Ubuntu1138488
Ref: devtools/overview ubuntu1138608
Ref: 8c11138608
Node: RedHat1138892
Ref: devtools/overview redhat1139016
Ref: 8c21139016
Node: Windows - Chocolatey1139215
Ref: devtools/overview windows-chocolatey1139343
Ref: 8c31139343
Node: Installers1139633
Ref: devtools/overview installers1139783
Ref: 8c41139783
Node: Windows - PowerShell add-ons1140154
Ref: devtools/overview windows-powershell-add-ons1140275
Ref: 8c51140275
Node: asdf1140391
Ref: devtools/asdf doc1140502
Ref: 8c61140502
Ref: devtools/asdf asdf1140502
Ref: 8c71140502
Ref: devtools/asdf library-asdf1140502
Ref: 8c81140502
Ref: asdf-Footnote-11140923
Node: assertions1140951
Ref: devtools/assertions doc1141066
Ref: 8c91141066
Ref: devtools/assertions assertions1141066
Ref: 8ca1141066
Ref: devtools/assertions library-assertions1141066
Ref: 8cb1141066
Node: API documentation1141788
Ref: devtools/assertions api-documentation1141887
Ref: 8cc1141887
Node: Loading1142030
Ref: devtools/assertions loading1142145
Ref: 8cd1142145
Node: Testing1142261
Ref: devtools/assertions testing1142396
Ref: 8ce1142396
Node: Adding assertions to your source code1142522
Ref: devtools/assertions adding-assertions-to-your-source-code1142718
Ref: 8cf1142718
Node: Automatically adding file and line context information to assertions1143376
Ref: devtools/assertions automatically-adding-file-and-line-context-information-to-assertions1143609
Ref: 8d01143609
Node: Suppressing assertion calls from source code1144405
Ref: devtools/assertions suppressing-assertion-calls-from-source-code1144639
Ref: 8d11144639
Node: Redirecting assertion failure messages1145135
Ref: devtools/assertions redirecting-assertion-failure-messages1145342
Ref: 8d21145342
Node: Converting assertion failures into errors1145948
Ref: devtools/assertions converting-assertion-failures-into-errors1146102
Ref: 8d31146102
Node: code_metrics1147047
Ref: devtools/code_metrics doc1147175
Ref: 8d41147175
Ref: devtools/code_metrics code-metrics1147175
Ref: 8d51147175
Ref: devtools/code_metrics library-code-metrics1147175
Ref: 8d61147175
Node: API documentation<2>1148294
Ref: devtools/code_metrics api-documentation1148401
Ref: 8d71148401
Node: Loading<2>1148546
Ref: devtools/code_metrics loading1148672
Ref: 8d81148672
Node: Testing<2>1148790
Ref: devtools/code_metrics testing1148913
Ref: 8d91148913
Node: Available metrics1149041
Ref: devtools/code_metrics available-metrics1149170
Ref: 8da1149170
Node: Coupling metrics1149939
Ref: devtools/code_metrics coupling-metrics1150073
Ref: 8db1150073
Node: Halstead metric1152558
Ref: devtools/code_metrics halstead-metric1152685
Ref: 8dc1152685
Node: UPN metric1154452
Ref: devtools/code_metrics upn-metric1154591
Ref: 8dd1154591
Node: Cyclomatic complexity metric1155346
Ref: devtools/code_metrics cyclomatic-complexity-metric1155475
Ref: 8de1155475
Node: Usage1156879
Ref: devtools/code_metrics usage1157026
Ref: 8df1157026
Node: Excluding code from analysis1157394
Ref: devtools/code_metrics excluding-code-from-analysis1157533
Ref: 8e01157533
Node: Defining new metrics1158373
Ref: devtools/code_metrics defining-new-metrics1158524
Ref: 8e11158524
Node: Third-party tools1158833
Ref: devtools/code_metrics third-party-tools1158990
Ref: 8e21158990
Node: Applying metrics to Prolog modules1159396
Ref: devtools/code_metrics applying-metrics-to-prolog-modules1159570
Ref: 8e31159570
Node: Applying metrics to plain Prolog code1160033
Ref: devtools/code_metrics applying-metrics-to-plain-prolog-code1160181
Ref: 8e41160181
Node: dead_code_scanner1161097
Ref: devtools/dead_code_scanner doc1161229
Ref: 8e51161229
Ref: devtools/dead_code_scanner dead-code-scanner1161229
Ref: 8e61161229
Ref: devtools/dead_code_scanner library-dead-code-scanner1161229
Ref: 8e71161229
Node: API documentation<3>1163088
Ref: devtools/dead_code_scanner api-documentation1163200
Ref: 8e81163200
Node: Loading<3>1163431
Ref: devtools/dead_code_scanner loading1163562
Ref: 8e91163562
Node: Testing<3>1163685
Ref: devtools/dead_code_scanner testing1163804
Ref: 8ea1163804
Node: Usage<2>1163937
Ref: devtools/dead_code_scanner usage1164077
Ref: 8eb1164077
Node: Excluding code from analysis<2>1165117
Ref: devtools/dead_code_scanner excluding-code-from-analysis1165277
Ref: 8ec1165277
Node: Integration with the make tool1166143
Ref: devtools/dead_code_scanner integration-with-the-make-tool1166302
Ref: 8ed1166302
Node: Caveats1166589
Ref: devtools/dead_code_scanner caveats1166740
Ref: 8ee1166740
Node: Scanning Prolog modules1167184
Ref: devtools/dead_code_scanner scanning-prolog-modules1167332
Ref: 8ef1167332
Node: Scanning plain Prolog files1167761
Ref: devtools/dead_code_scanner scanning-plain-prolog-files1167893
Ref: 8f01167893
Node: debug_messages1168813
Ref: devtools/debug_messages doc1168941
Ref: 3521168941
Ref: devtools/debug_messages debug-messages1168941
Ref: 8f11168941
Ref: devtools/debug_messages library-debug-messages1168941
Ref: 8f21168941
Node: API documentation<4>1169429
Ref: devtools/debug_messages api-documentation1169538
Ref: 8f31169538
Node: Loading<4>1169864
Ref: devtools/debug_messages loading1169992
Ref: 8f41169992
Node: Testing<4>1170112
Ref: devtools/debug_messages testing1170228
Ref: 8f51170228
Node: Usage<3>1170358
Ref: devtools/debug_messages usage1170455
Ref: 8f61170455
Node: debugger1171998
Ref: devtools/debugger doc1172117
Ref: 2fc1172117
Ref: devtools/debugger debugger1172117
Ref: 8f71172117
Ref: devtools/debugger library-debugger1172117
Ref: 8f81172117
Node: API documentation<5>1172622
Ref: devtools/debugger api-documentation1172725
Ref: 8f91172725
Node: Loading<5>1172866
Ref: devtools/debugger loading1172988
Ref: 8fa1172988
Node: Testing<5>1173260
Ref: devtools/debugger testing1173370
Ref: 8fb1173370
Node: Usage<4>1173494
Ref: devtools/debugger usage1173620
Ref: 8fc1173620
Node: Alternative debugger tools1174823
Ref: devtools/debugger alternative-debugger-tools1174951
Ref: 8fd1174951
Node: Known issues1175796
Ref: devtools/debugger known-issues1175907
Ref: 8fe1175907
Node: diagrams1176908
Ref: devtools/diagrams doc1177019
Ref: 2ed1177019
Ref: devtools/diagrams diagrams1177019
Ref: 8ff1177019
Ref: devtools/diagrams library-diagrams1177019
Ref: 9001177019
Node: Requirements1179142
Ref: devtools/diagrams requirements1179247
Ref: 9011179247
Node: macOS - MacPorts<2>1179731
Ref: devtools/diagrams macos-macports1179846
Ref: 9021179846
Node: macOS - Homebrew<2>1179935
Ref: devtools/diagrams macos-homebrew1180082
Ref: 9031180082
Node: Windows - Chocolatey<2>1180166
Ref: devtools/diagrams windows-chocolatey1180307
Ref: 9041180307
Node: Installers<2>1180400
Ref: devtools/diagrams installers1180513
Ref: 9051180513
Node: API documentation<6>1180643
Ref: devtools/diagrams api-documentation1180767
Ref: 9061180767
Node: Loading<6>1180989
Ref: devtools/diagrams loading1181111
Ref: 9071181111
Node: Testing<6>1181225
Ref: devtools/diagrams testing1181345
Ref: 9081181345
Node: Supported diagrams1181469
Ref: devtools/diagrams supported-diagrams1181593
Ref: 9091181593
Node: Graph elements1183992
Ref: devtools/diagrams graph-elements1184131
Ref: 90a1184131
Node: Supported graph languages1187345
Ref: devtools/diagrams supported-graph-languages1187479
Ref: 90b1187479
Node: Customization1190690
Ref: devtools/diagrams customization1190826
Ref: 90c1190826
Node: Linking diagrams1202300
Ref: devtools/diagrams linking-diagrams1202459
Ref: 90d1202459
Node: Creating diagrams for Prolog module applications1207358
Ref: devtools/diagrams creating-diagrams-for-prolog-module-applications1207544
Ref: 90e1207544
Node: Creating diagrams for plain Prolog files1208178
Ref: devtools/diagrams creating-diagrams-for-plain-prolog-files1208359
Ref: 90f1208359
Node: Other notes1209185
Ref: devtools/diagrams other-notes1209309
Ref: 9101209309
Node: doclet1211556
Ref: devtools/doclet doc1211663
Ref: 32d1211663
Ref: devtools/doclet doclet1211663
Ref: 9111211663
Ref: devtools/doclet library-doclet1211663
Ref: 9121211663
Node: API documentation<7>1212809
Ref: devtools/doclet api-documentation1212910
Ref: 9131212910
Node: Loading<7>1213130
Ref: devtools/doclet loading1213266
Ref: 9141213266
Node: Automating running doclets1213378
Ref: devtools/doclet automating-running-doclets1213527
Ref: 9151213527
Node: Integration with the make tool<2>1213871
Ref: devtools/doclet integration-with-the-make-tool1214001
Ref: 9161214001
Node: help1214283
Ref: devtools/help doc1214395
Ref: 9171214395
Ref: devtools/help help1214395
Ref: 9181214395
Ref: devtools/help library-help1214395
Ref: 9191214395
Node: Requirements<2>1214867
Ref: devtools/help requirements1214971
Ref: 91a1214971
Node: API documentation<8>1215377
Ref: devtools/help api-documentation1215500
Ref: 91b1215500
Node: Loading<8>1215720
Ref: devtools/help loading1215838
Ref: 91c1215838
Node: Testing<7>1215908
Ref: devtools/help testing1216033
Ref: 91d1216033
Node: Supported operating-systems1216155
Ref: devtools/help supported-operating-systems1216278
Ref: 91e1216278
Node: Usage<5>1216489
Ref: devtools/help usage1216623
Ref: 91f1216623
Node: Experimental features1216722
Ref: devtools/help experimental-features1216844
Ref: 9201216844
Node: Known issues<2>1219082
Ref: devtools/help known-issues1219187
Ref: 9211219187
Node: issue_creator1219819
Ref: devtools/issue_creator doc1219931
Ref: 9221219931
Ref: devtools/issue_creator issue-creator1219931
Ref: 9231219931
Ref: devtools/issue_creator library-issue-creator1219931
Ref: 9241219931
Node: Requirements<3>1220244
Ref: devtools/issue_creator requirements1220347
Ref: 9251220347
Node: Loading<9>1220605
Ref: devtools/issue_creator loading1220725
Ref: 9261220725
Node: Usage<6>1220968
Ref: devtools/issue_creator usage1221088
Ref: 9271221088
Node: Known issues<3>1223947
Ref: devtools/issue_creator known-issues1224048
Ref: 9281224048
Node: lgtdoc1224448
Ref: devtools/lgtdoc doc1224563
Ref: 3221224563
Ref: devtools/lgtdoc lgtdoc1224563
Ref: 9291224563
Ref: devtools/lgtdoc library-lgtdoc1224563
Ref: 92a1224563
Node: Requirements<4>1225575
Ref: devtools/lgtdoc requirements1225681
Ref: 92b1225681
Node: API documentation<9>1227130
Ref: devtools/lgtdoc api-documentation1227256
Ref: 92c1227256
Node: Loading<10>1227397
Ref: devtools/lgtdoc loading1227518
Ref: 92d1227518
Node: Testing<8>1227632
Ref: devtools/lgtdoc testing1227756
Ref: 92e1227756
Node: Documenting source code1227880
Ref: devtools/lgtdoc documenting-source-code1228017
Ref: 92f1228017
Node: Generating documentation1229000
Ref: devtools/lgtdoc generating-documentation1229154
Ref: 9301229154
Ref: Generating documentation-Footnote-11231017
Node: Documentation linter checks1231067
Ref: devtools/lgtdoc documentation-linter-checks1231189
Ref: 9311231189
Node: lgtunit1232776
Ref: devtools/lgtunit doc1232884
Ref: 1461232884
Ref: devtools/lgtunit lgtunit1232884
Ref: 9321232884
Ref: devtools/lgtunit library-lgtunit1232884
Ref: 9331232884
Node: Main files1234882
Ref: devtools/lgtunit main-files1234985
Ref: 9341234985
Node: API documentation<10>1235548
Ref: devtools/lgtunit api-documentation1235671
Ref: 9351235671
Node: Loading<11>1235813
Ref: devtools/lgtunit loading1235936
Ref: 9361235936
Node: Testing<9>1236051
Ref: devtools/lgtunit testing1236178
Ref: 9371236178
Node: Writing and running tests1236303
Ref: devtools/lgtunit writing-and-running-tests1236443
Ref: 9381236443
Node: Automating running tests1242442
Ref: devtools/lgtunit automating-running-tests1242595
Ref: 93a1242595
Node: Parametric test objects1245743
Ref: devtools/lgtunit parametric-test-objects1245884
Ref: 93b1245884
Node: Test dialects1247007
Ref: devtools/lgtunit test-dialects1247150
Ref: 9391247150
Node: User-defined test dialects1253326
Ref: devtools/lgtunit user-defined-test-dialects1253456
Ref: 93c1253456
Node: QuickCheck1254898
Ref: devtools/lgtunit quickcheck1255029
Ref: 93d1255029
Node: Skipping tests1267799
Ref: devtools/lgtunit skipping-tests1267919
Ref: 93e1267919
Node: Selecting tests1269189
Ref: devtools/lgtunit selecting-tests1269325
Ref: 93f1269325
Node: Checking test goal results1270343
Ref: devtools/lgtunit checking-test-goal-results1270489
Ref: 9401270489
Node: Testing local predicates1273571
Ref: devtools/lgtunit testing-local-predicates1273738
Ref: 9411273738
Node: Testing non-deterministic predicates1274349
Ref: devtools/lgtunit testing-non-deterministic-predicates1274508
Ref: 9421274508
Node: Testing generators1275582
Ref: devtools/lgtunit testing-generators1275748
Ref: 9431275748
Node: Testing input/output predicates1276682
Ref: devtools/lgtunit testing-input-output-predicates1276848
Ref: 9441276848
Node: Suppressing tested predicates output1280440
Ref: devtools/lgtunit suppressing-tested-predicates-output1280613
Ref: 9451280613
Node: Tests with timeout limits1282780
Ref: devtools/lgtunit tests-with-timeout-limits1282945
Ref: 9461282945
Node: Setup and cleanup goals1283879
Ref: devtools/lgtunit setup-and-cleanup-goals1284024
Ref: 9471284024
Node: Test annotations1285012
Ref: devtools/lgtunit test-annotations1285169
Ref: 9481285169
Node: Test execution times and memory usage1286362
Ref: devtools/lgtunit test-execution-times-and-memory-usage1286524
Ref: 9491286524
Node: Working with test data files1288277
Ref: devtools/lgtunit working-with-test-data-files1288434
Ref: 94a1288434
Node: Flaky tests1290047
Ref: devtools/lgtunit flaky-tests1290174
Ref: 94b1290174
Node: Mocking1291015
Ref: devtools/lgtunit mocking1291141
Ref: 94c1291141
Node: Debugging messages in tests1294188
Ref: devtools/lgtunit debugging-messages-in-tests1294325
Ref: 94d1294325
Node: Debugging failed tests1295301
Ref: devtools/lgtunit debugging-failed-tests1295444
Ref: 94e1295444
Node: Code coverage1297349
Ref: devtools/lgtunit code-coverage1297483
Ref: 94f1297483
Node: Utility predicates1301551
Ref: devtools/lgtunit utility-predicates1301705
Ref: 9501301705
Node: Exporting test results in xUnit XML format1305799
Ref: devtools/lgtunit exporting-test-results-in-xunit-xml-format1305987
Ref: 9511305987
Node: Exporting test results in the TAP output format1307761
Ref: devtools/lgtunit exporting-test-results-in-the-tap-output-format1307956
Ref: 9521307956
Node: Generating Allure reports1309348
Ref: devtools/lgtunit generating-allure-reports1309546
Ref: 9531309546
Ref: Generating Allure reports-Footnote-11314319
Node: Exporting code coverage results in XML format1314358
Ref: devtools/lgtunit exporting-code-coverage-results-in-xml-format1314561
Ref: 9541314561
Node: Automatically creating bug reports at issue trackers1317098
Ref: devtools/lgtunit automatically-creating-bug-reports-at-issue-trackers1317306
Ref: 9551317306
Node: Minimizing test results output1317552
Ref: devtools/lgtunit minimizing-test-results-output1317733
Ref: 9561317733
Node: Help with warnings1318039
Ref: devtools/lgtunit help-with-warnings1318183
Ref: 9571318183
Node: Known issues<4>1318335
Ref: devtools/lgtunit known-issues1318440
Ref: 9581318440
Node: linter1319170
Ref: devtools/linter doc1319276
Ref: 2af1319276
Ref: devtools/linter library-linter1319276
Ref: 9591319276
Ref: devtools/linter linter1319276
Ref: 95a1319276
Ref: linter-Footnote-11320687
Ref: linter-Footnote-21320746
Ref: linter-Footnote-31320799
Ref: linter-Footnote-41320852
Node: Main linter checks1320900
Ref: devtools/linter main-linter-checks1321012
Ref: 95b1321012
Node: Help on linter warnings1324569
Ref: devtools/linter help-on-linter-warnings1324710
Ref: 95c1324710
Ref: Help on linter warnings-Footnote-11325008
Node: Extending the linter1325065
Ref: devtools/linter extending-the-linter1325210
Ref: 95d1325210
Ref: Extending the linter-Footnote-11325639
Node: Linting Prolog modules1325695
Ref: devtools/linter linting-prolog-modules1325843
Ref: 95e1325843
Node: Linting plain Prolog files1326272
Ref: devtools/linter linting-plain-prolog-files1326391
Ref: 95f1326391
Node: make1327268
Ref: devtools/make doc1327372
Ref: 9601327372
Ref: devtools/make library-make1327372
Ref: 9611327372
Ref: devtools/make make1327372
Ref: 9621327372
Node: API documentation<11>1327700
Ref: devtools/make api-documentation1327811
Ref: 9631327811
Node: Help with warnings<2>1328364
Ref: devtools/make help-with-warnings1328499
Ref: 9641328499
Node: Known issues<5>1328646
Ref: devtools/make known-issues1328751
Ref: 9651328751
Node: packs1329284
Ref: devtools/packs doc1329396
Ref: 6491329396
Ref: devtools/packs library-packs1329396
Ref: 9661329396
Ref: devtools/packs packs1329396
Ref: 9671329396
Node: Requirements<5>1331309
Ref: devtools/packs requirements1331415
Ref: 9681331415
Ref: Requirements<5>-Footnote-11333616
Node: API documentation<12>1333665
Ref: devtools/packs api-documentation1333791
Ref: 9691333791
Node: Loading<12>1333931
Ref: devtools/packs loading1334053
Ref: 96a1334053
Node: Testing<10>1334166
Ref: devtools/packs testing1334275
Ref: 96b1334275
Node: Usage<7>1334454
Ref: devtools/packs usage1334580
Ref: 96c1334580
Node: Registries and packs storage1335041
Ref: devtools/packs registries-and-packs-storage1335176
Ref: 96d1335176
Node: Virtual environments1336423
Ref: devtools/packs virtual-environments1336572
Ref: 96e1336572
Ref: Virtual environments-Footnote-11340744
Ref: Virtual environments-Footnote-21340794
Ref: Virtual environments-Footnote-31340835
Node: Registry specification1340884
Ref: devtools/packs registry-specification1341022
Ref: 96f1341022
Node: Registry handling1344182
Ref: devtools/packs registry-handling1344320
Ref: 9701344320
Ref: Registry handling-Footnote-11347065
Node: Registry development1347102
Ref: devtools/packs registry-development1347236
Ref: 9711347236
Node: Pack specification1347910
Ref: devtools/packs pack-specification1348042
Ref: 9721348042
Ref: Pack specification-Footnote-11351075
Node: Encrypted packs1351110
Ref: devtools/packs encrypted-packs1351234
Ref: 9731351234
Node: Signed packs1351980
Ref: devtools/packs signed-packs1352114
Ref: 9741352114
Node: Pack URLs and Single Sign-On1353050
Ref: devtools/packs pack-urls-and-single-sign-on1353191
Ref: 9751353191
Node: Multiple pack versions1355388
Ref: devtools/packs multiple-pack-versions1355534
Ref: 9761355534
Node: Pack dependencies1356735
Ref: devtools/packs pack-dependencies1356869
Ref: 9771356869
Node: Pack portability1360015
Ref: devtools/packs pack-portability1360143
Ref: 9781360143
Node: Pack development1360963
Ref: devtools/packs pack-development1361087
Ref: 9791361087
Node: Pack handling1362324
Ref: devtools/packs pack-handling1362450
Ref: 97a1362450
Ref: Pack handling-Footnote-11367908
Node: Pack documentation1367940
Ref: devtools/packs pack-documentation1368078
Ref: 97b1368078
Node: Pinning registries and packs1369766
Ref: devtools/packs pinning-registries-and-packs1369904
Ref: 97c1369904
Node: Testing packs1371083
Ref: devtools/packs testing-packs1371226
Ref: 97d1371226
Node: Security considerations1371992
Ref: devtools/packs security-considerations1372121
Ref: 97e1372121
Node: Best practices1373374
Ref: devtools/packs best-practices1373513
Ref: 97f1373513
Node: Installing Prolog packs1374665
Ref: devtools/packs installing-prolog-packs1374802
Ref: 9801374802
Node: Help with warnings<3>1375842
Ref: devtools/packs help-with-warnings1375980
Ref: 9811375980
Node: Known issues<6>1376130
Ref: devtools/packs known-issues1376236
Ref: 9821376236
Node: ports_profiler1377601
Ref: devtools/ports_profiler doc1377717
Ref: 3581377717
Ref: devtools/ports_profiler library-ports-profiler1377717
Ref: 9831377717
Ref: devtools/ports_profiler ports-profiler1377717
Ref: 9841377717
Node: API documentation<13>1378908
Ref: devtools/ports_profiler api-documentation1379019
Ref: 9851379019
Node: Loading<13>1379249
Ref: devtools/ports_profiler loading1379380
Ref: 9861379380
Node: Testing<11>1379460
Ref: devtools/ports_profiler testing1379611
Ref: 9871379611
Node: Compiling source files for port profiling1379743
Ref: devtools/ports_profiler compiling-source-files-for-port-profiling1379908
Ref: 9881379908
Node: Generating profiling data1380660
Ref: devtools/ports_profiler generating-profiling-data1380845
Ref: 9891380845
Node: Printing profiling data reports1381463
Ref: devtools/ports_profiler printing-profiling-data-reports1381634
Ref: 98a1381634
Node: Interpreting profiling data1384225
Ref: devtools/ports_profiler interpreting-profiling-data1384395
Ref: 98b1384395
Node: Profiling Prolog modules1385206
Ref: devtools/ports_profiler profiling-prolog-modules1385372
Ref: 98c1385372
Node: Profiling plain Prolog code1385816
Ref: devtools/ports_profiler profiling-plain-prolog-code1385970
Ref: 98d1385970
Node: Known issues<7>1387393
Ref: devtools/ports_profiler known-issues1387514
Ref: 98e1387514
Node: profiler1387660
Ref: devtools/profiler doc1387776
Ref: 98f1387776
Ref: devtools/profiler library-profiler1387776
Ref: 9901387776
Ref: devtools/profiler profiler1387776
Ref: 9911387776
Node: Loading<14>1388022
Ref: devtools/profiler loading1388117
Ref: 9921388117
Node: Testing<12>1388312
Ref: devtools/profiler testing1388450
Ref: 9931388450
Node: Supported backend Prolog compilers1388576
Ref: devtools/profiler supported-backend-prolog-compilers1388738
Ref: 9941388738
Node: Compiling source code for profiling1390761
Ref: devtools/profiler compiling-source-code-for-profiling1390903
Ref: 9951390903
Node: tutor1391418
Ref: devtools/tutor doc1391527
Ref: 9961391527
Ref: devtools/tutor library-tutor1391527
Ref: 9971391527
Ref: devtools/tutor tutor1391527
Ref: 9981391527
Node: API documentation<14>1391943
Ref: devtools/tutor api-documentation1392045
Ref: 9991392045
Node: Loading<15>1392185
Ref: devtools/tutor loading1392304
Ref: 99a1392304
Node: Usage<8>1392417
Ref: devtools/tutor usage1392506
Ref: 99b1392506
Node: wrapper1393996
Ref: devtools/wrapper doc1394088
Ref: 38b1394088
Ref: devtools/wrapper library-wrapper1394088
Ref: 99c1394088
Ref: devtools/wrapper wrapper1394088
Ref: 99d1394088
Node: API documentation<15>1395195
Ref: devtools/wrapper api-documentation1395299
Ref: 99e1395299
Node: Loading<16>1395441
Ref: devtools/wrapper loading1395563
Ref: 99f1395563
Node: Workflows1395678
Ref: devtools/wrapper workflows1395795
Ref: 9a01395795
Node: Customization<2>1396056
Ref: devtools/wrapper customization1396181
Ref: 9a11396181
Node: Current limitations1398159
Ref: devtools/wrapper current-limitations1398266
Ref: 9a21398266
Ref: libraries/index library-library1399281
Ref: 9a31399281
Node: Libraries1399282
Ref: libraries/index doc1399388
Ref: 9a41399388
Ref: libraries/index libraries1399388
Ref: 9a51399388
Node: Overview<2>1400268
Ref: libraries/overview doc1400362
Ref: 9a61400362
Ref: libraries/overview overview1400362
Ref: 9a71400362
Node: Library documentation1401354
Ref: libraries/overview library-documentation1401468
Ref: 9a81401468
Node: Loading libraries1401771
Ref: libraries/overview loading-libraries1401911
Ref: 9a91401911
Node: Testing libraries1402730
Ref: libraries/overview testing-libraries1402856
Ref: 9aa1402856
Node: Credits1403512
Ref: libraries/overview credits1403635
Ref: 9ab1403635
Node: Other notes<2>1404402
Ref: libraries/overview other-notes1404499
Ref: 9ac1404499
Node: arbitrary1404661
Ref: libraries/arbitrary doc1404774
Ref: 9ad1404774
Ref: libraries/arbitrary arbitrary1404774
Ref: 9ae1404774
Ref: libraries/arbitrary library-arbitrary1404774
Ref: 9af1404774
Node: API documentation<16>1405675
Ref: libraries/arbitrary api-documentation1405781
Ref: 9b01405781
Node: Loading<17>1405909
Ref: libraries/arbitrary loading1406035
Ref: 9b11406035
Node: Testing<13>1406179
Ref: libraries/arbitrary testing1406301
Ref: 9b21406301
Node: Pre-defined types1406605
Ref: libraries/arbitrary pre-defined-types1406724
Ref: 9b31406724
Ref: Pre-defined types-Footnote-11406969
Node: Usage<9>1407017
Ref: libraries/arbitrary usage1407162
Ref: 9b41407162
Node: Defining new generators and shrinkers1407398
Ref: libraries/arbitrary defining-new-generators-and-shrinkers1407557
Ref: 9b51407557
Node: Scoped generators and shrinkers1413364
Ref: libraries/arbitrary scoped-generators-and-shrinkers1413555
Ref: 9b61413555
Node: Reproducing sequences of arbitrary terms1414977
Ref: libraries/arbitrary reproducing-sequences-of-arbitrary-terms1415162
Ref: 9b71415162
Node: Default size of generated terms1416289
Ref: libraries/arbitrary default-size-of-generated-terms1416458
Ref: 9b81416458
Node: Known issues<8>1417028
Ref: libraries/arbitrary known-issues1417148
Ref: 9b91417148
Node: assignvars1417830
Ref: libraries/assignvars doc1417938
Ref: 9ba1417938
Ref: libraries/assignvars assignvars1417938
Ref: 9bb1417938
Ref: libraries/assignvars library-assignvars1417938
Ref: 9bc1417938
Node: API documentation<17>1418900
Ref: libraries/assignvars api-documentation1419007
Ref: 9bd1419007
Node: Loading<18>1419136
Ref: libraries/assignvars loading1419263
Ref: 9be1419263
Node: Testing<14>1419408
Ref: libraries/assignvars testing1419505
Ref: 9bf1419505
Node: base641419645
Ref: libraries/base64 doc1419755
Ref: 9c01419755
Ref: libraries/base64 base641419755
Ref: 9c11419755
Ref: libraries/base64 library-base641419755
Ref: 9c21419755
Node: API documentation<18>1420109
Ref: libraries/base64 api-documentation1420212
Ref: 9c31420212
Node: Loading<19>1420337
Ref: libraries/base64 loading1420460
Ref: 9c41420460
Node: Testing<15>1420609
Ref: libraries/base64 testing1420719
Ref: 9c51420719
Node: Encoding1420855
Ref: libraries/base64 encoding1420962
Ref: 9c61420962
Node: Decoding1422010
Ref: libraries/base64 decoding1422097
Ref: 9c71422097
Node: basic_types1423128
Ref: libraries/basic_types doc1423232
Ref: 9c81423232
Ref: libraries/basic_types basic-types1423232
Ref: 9c91423232
Ref: libraries/basic_types library-basic-types1423232
Ref: 9ca1423232
Node: API documentation<19>1423674
Ref: libraries/basic_types api-documentation1423782
Ref: 9cb1423782
Node: Loading<20>1423906
Ref: libraries/basic_types loading1424034
Ref: 9cc1424034
Node: Testing<16>1424180
Ref: libraries/basic_types testing1424278
Ref: 9cd1424278
Node: cbor1424441
Ref: libraries/cbor doc1424543
Ref: 9ce1424543
Ref: libraries/cbor cbor1424543
Ref: 9cf1424543
Ref: libraries/cbor library-cbor1424543
Ref: 9d01424543
Node: Representation1425074
Ref: libraries/cbor representation1425168
Ref: 9d11425168
Node: Encoding<2>1427023
Ref: libraries/cbor encoding1427137
Ref: 9d21427137
Node: Decoding<2>1427561
Ref: libraries/cbor decoding1427682
Ref: 9d31427682
Node: API documentation<20>1427902
Ref: libraries/cbor api-documentation1428023
Ref: 9d41428023
Node: Loading<21>1428146
Ref: libraries/cbor loading1428267
Ref: 9d51428267
Node: Testing<17>1428406
Ref: libraries/cbor testing1428497
Ref: 9d61428497
Node: core1428631
Ref: libraries/core doc1428733
Ref: 9d71428733
Ref: libraries/core core1428733
Ref: 9d81428733
Ref: libraries/core library-core1428733
Ref: 9d91428733
Node: API documentation<21>1428907
Ref: libraries/core api-documentation1429008
Ref: 9da1429008
Node: Loading<22>1429139
Ref: libraries/core loading1429260
Ref: 9db1429260
Node: Testing<18>1429364
Ref: libraries/core testing1429455
Ref: 9dc1429455
Node: coroutining1429568
Ref: libraries/coroutining doc1429669
Ref: 9dd1429669
Ref: libraries/coroutining coroutining1429669
Ref: 9de1429669
Ref: libraries/coroutining library-coroutining1429669
Ref: 9df1429669
Node: API documentation<22>1430412
Ref: libraries/coroutining api-documentation1430520
Ref: 9e01430520
Node: Loading<23>1430650
Ref: libraries/coroutining loading1430778
Ref: 9e11430778
Node: Testing<19>1430924
Ref: libraries/coroutining testing1431040
Ref: 9e21431040
Node: Usage<10>1431181
Ref: libraries/coroutining usage1431277
Ref: 9e31431277
Node: csv1431642
Ref: libraries/csv doc1431744
Ref: 9e41431744
Ref: libraries/csv csv1431744
Ref: 9e51431744
Ref: libraries/csv library-csv1431744
Ref: 9e61431744
Node: API documentation<23>1433009
Ref: libraries/csv api-documentation1433109
Ref: 9e71433109
Node: Loading<24>1433231
Ref: libraries/csv loading1433351
Ref: 9e81433351
Node: Testing<20>1433489
Ref: libraries/csv testing1433597
Ref: 9e91433597
Node: Usage<11>1433730
Ref: libraries/csv usage1433818
Ref: 9ea1433818
Node: dates1436276
Ref: libraries/dates doc1436377
Ref: 9eb1436377
Ref: libraries/dates dates1436377
Ref: 9ec1436377
Ref: libraries/dates library-dates1436377
Ref: 9ed1436377
Node: API documentation<24>1436761
Ref: libraries/dates api-documentation1436863
Ref: 9ee1436863
Node: Loading<25>1436989
Ref: libraries/dates loading1437091
Ref: 9ef1437091
Node: dependents1437241
Ref: libraries/dependents doc1437351
Ref: 2891437351
Ref: libraries/dependents dependents1437351
Ref: 9f01437351
Ref: libraries/dependents library-dependents1437351
Ref: 9f11437351
Node: API documentation<25>1437681
Ref: libraries/dependents api-documentation1437788
Ref: 9f21437788
Node: Loading<26>1437919
Ref: libraries/dependents loading1438026
Ref: 9f31438026
Node: dictionaries1438181
Ref: libraries/dictionaries doc1438289
Ref: 9f41438289
Ref: libraries/dictionaries dictionaries1438289
Ref: 9f51438289
Ref: libraries/dictionaries library-dictionaries1438289
Ref: 9f61438289
Node: API documentation<26>1438775
Ref: libraries/dictionaries api-documentation1438884
Ref: 9f71438884
Node: Loading<27>1439017
Ref: libraries/dictionaries loading1439146
Ref: 9f81439146
Node: Testing<21>1439295
Ref: libraries/dictionaries testing1439412
Ref: 9f91439412
Node: Usage<12>1439556
Ref: libraries/dictionaries usage1439672
Ref: 9fa1439672
Node: Credits<2>1441551
Ref: libraries/dictionaries credits1441647
Ref: 9fb1441647
Node: dif1442048
Ref: libraries/dif doc1442150
Ref: 9fc1442150
Ref: libraries/dif dif1442150
Ref: 9fd1442150
Ref: libraries/dif library-dif1442150
Ref: 9fe1442150
Node: API documentation<27>1442781
Ref: libraries/dif api-documentation1442881
Ref: 9ff1442881
Node: Loading<28>1443005
Ref: libraries/dif loading1443125
Ref: a001443125
Node: Testing<22>1443265
Ref: libraries/dif testing1443373
Ref: a011443373
Node: Usage<13>1443508
Ref: libraries/dif usage1443596
Ref: a021443596
Node: edcg1443877
Ref: libraries/edcg doc1443973
Ref: 31f1443973
Ref: libraries/edcg edcg1443973
Ref: a031443973
Ref: libraries/edcg library-edcg1443973
Ref: a041443973
Node: API documentation<28>1445487
Ref: libraries/edcg api-documentation1445588
Ref: a051445588
Node: Loading<29>1445713
Ref: libraries/edcg loading1445834
Ref: a061445834
Node: Testing<23>1445983
Ref: libraries/edcg testing1446092
Ref: a071446092
Node: Usage<14>1446256
Ref: libraries/edcg usage1446366
Ref: a081446366
Node: Introduction1447105
Ref: libraries/edcg introduction1447210
Ref: a091447210
Node: Syntax1447842
Ref: libraries/edcg syntax1447963
Ref: a0a1447963
Node: Declaration of Predicates1449858
Ref: libraries/edcg declaration-of-predicates1449994
Ref: a0b1449994
Node: Declaration of Accumulators1450324
Ref: libraries/edcg declaration-of-accumulators1450485
Ref: a0c1450485
Node: Declaration of Passed Arguments1451871
Ref: libraries/edcg declaration-of-passed-arguments1452031
Ref: a0d1452031
Node: Additional documentation1452690
Ref: libraries/edcg additional-documentation1452814
Ref: a0e1452814
Ref: Additional documentation-Footnote-11453196
Ref: Additional documentation-Footnote-21453251
Ref: Additional documentation-Footnote-31453319
Ref: Additional documentation-Footnote-41453392
Node: events1453465
Ref: libraries/events doc1453584
Ref: a0f1453584
Ref: libraries/events events1453584
Ref: a101453584
Ref: libraries/events library-events1453584
Ref: a111453584
Node: API documentation<29>1454239
Ref: libraries/events api-documentation1454342
Ref: a121454342
Node: Loading<30>1454469
Ref: libraries/events loading1454572
Ref: a131454572
Node: expand_library_alias_paths1454722
Ref: libraries/expand_library_alias_paths doc1454846
Ref: a141454846
Ref: libraries/expand_library_alias_paths expand-library-alias-paths1454846
Ref: a151454846
Ref: libraries/expand_library_alias_paths library-expand-library-alias-paths1454846
Ref: a161454846
Node: API documentation<30>1455255
Ref: libraries/expand_library_alias_paths api-documentation1455378
Ref: a171455378
Node: Loading<31>1455525
Ref: libraries/expand_library_alias_paths loading1455666
Ref: a181455666
Node: Usage<15>1455837
Ref: libraries/expand_library_alias_paths usage1455948
Ref: a191455948
Node: expecteds1456303
Ref: libraries/expecteds doc1456427
Ref: 24f1456427
Ref: libraries/expecteds expecteds1456427
Ref: a1a1456427
Ref: libraries/expecteds library-expecteds1456427
Ref: a1b1456427
Node: API documentation<31>1457268
Ref: libraries/expecteds api-documentation1457374
Ref: a1c1457374
Node: Loading<32>1457504
Ref: libraries/expecteds loading1457630
Ref: a1d1457630
Node: Testing<24>1457776
Ref: libraries/expecteds testing1457890
Ref: a1e1457890
Node: Usage<16>1458031
Ref: libraries/expecteds usage1458142
Ref: a1f1458142
Node: See also1458845
Ref: libraries/expecteds see-also1458936
Ref: a201458936
Node: format1458999
Ref: libraries/format doc1459103
Ref: a211459103
Ref: libraries/format format1459103
Ref: a221459103
Ref: libraries/format library-format1459103
Ref: a231459103
Node: API documentation<32>1460229
Ref: libraries/format api-documentation1460332
Ref: a241460332
Node: Loading<33>1460459
Ref: libraries/format loading1460582
Ref: a251460582
Node: Testing<25>1460725
Ref: libraries/format testing1460836
Ref: a261460836
Node: Usage<17>1461260
Ref: libraries/format usage1461374
Ref: a271461374
Node: Portability<2>1461667
Ref: libraries/format portability1461761
Ref: a281461761
Node: genint1462731
Ref: libraries/genint doc1462832
Ref: a291462832
Ref: libraries/genint genint1462832
Ref: a2a1462832
Ref: libraries/genint library-genint1462832
Ref: a2b1462832
Node: API documentation<33>1463232
Ref: libraries/genint api-documentation1463335
Ref: a2c1463335
Node: Loading<34>1463462
Ref: libraries/genint loading1463585
Ref: a2d1463585
Node: Testing<26>1463728
Ref: libraries/genint testing1463839
Ref: a2e1463839
Node: Usage<18>1463977
Ref: libraries/genint usage1464068
Ref: a2f1464068
Node: gensym1464503
Ref: libraries/gensym doc1464601
Ref: a301464601
Ref: libraries/gensym gensym1464601
Ref: a311464601
Ref: libraries/gensym library-gensym1464601
Ref: a321464601
Node: API documentation<34>1464975
Ref: libraries/gensym api-documentation1465078
Ref: a331465078
Node: Loading<35>1465205
Ref: libraries/gensym loading1465328
Ref: a341465328
Node: Testing<27>1465471
Ref: libraries/gensym testing1465582
Ref: a351465582
Node: Usage<19>1465720
Ref: libraries/gensym usage1465811
Ref: a361465811
Node: git1466406
Ref: libraries/git doc1466506
Ref: a371466506
Ref: libraries/git git1466506
Ref: a381466506
Ref: libraries/git library-git1466506
Ref: a391466506
Node: API documentation<35>1466900
Ref: libraries/git api-documentation1467000
Ref: a3a1467000
Node: Loading<36>1467124
Ref: libraries/git loading1467244
Ref: a3b1467244
Node: Testing<28>1467384
Ref: libraries/git testing1467492
Ref: a3c1467492
Node: Usage<20>1467627
Ref: libraries/git usage1467715
Ref: a3d1467715
Node: grammars1469075
Ref: libraries/grammars doc1469174
Ref: a3e1469174
Ref: libraries/grammars grammars1469174
Ref: a3f1469174
Ref: libraries/grammars library-grammars1469174
Ref: a401469174
Node: API documentation<36>1469805
Ref: libraries/grammars api-documentation1469910
Ref: a411469910
Node: Loading<37>1470039
Ref: libraries/grammars loading1470164
Ref: a421470164
Node: Testing<29>1470309
Ref: libraries/grammars testing1470422
Ref: a431470422
Node: Usage<21>1470588
Ref: libraries/grammars usage1470681
Ref: a441470681
Node: heaps1471019
Ref: libraries/heaps doc1471126
Ref: a451471126
Ref: libraries/heaps heaps1471126
Ref: a461471126
Ref: libraries/heaps library-heaps1471126
Ref: a471471126
Node: API documentation<37>1471334
Ref: libraries/heaps api-documentation1471436
Ref: a481471436
Node: Loading<38>1471562
Ref: libraries/heaps loading1471684
Ref: a491471684
Node: Testing<30>1471826
Ref: libraries/heaps testing1471937
Ref: a4a1471937
Node: Credits<3>1472074
Ref: libraries/heaps credits1472165
Ref: a4b1472165
Node: hierarchies1472294
Ref: libraries/hierarchies doc1472403
Ref: a4c1472403
Ref: libraries/hierarchies hierarchies1472403
Ref: a4d1472403
Ref: libraries/hierarchies library-hierarchies1472403
Ref: a4e1472403
Node: API documentation<38>1472746
Ref: libraries/hierarchies api-documentation1472854
Ref: a4f1472854
Node: Loading<39>1472986
Ref: libraries/hierarchies loading1473114
Ref: a501473114
Node: Testing<31>1473262
Ref: libraries/hierarchies testing1473360
Ref: a511473360
Node: hook_flows1473503
Ref: libraries/hook_flows doc1473619
Ref: 31a1473619
Ref: libraries/hook_flows hook-flows1473619
Ref: a521473619
Ref: libraries/hook_flows library-hook-flows1473619
Ref: a531473619
Node: API documentation<39>1474512
Ref: libraries/hook_flows api-documentation1474619
Ref: a541474619
Node: Loading<40>1474750
Ref: libraries/hook_flows loading1474877
Ref: a551474877
Node: Testing<32>1475024
Ref: libraries/hook_flows testing1475139
Ref: a561475139
Node: Usage<22>1475281
Ref: libraries/hook_flows usage1475376
Ref: a571475376
Node: hook_objects1477157
Ref: libraries/hook_objects doc1477266
Ref: 31b1477266
Ref: libraries/hook_objects hook-objects1477266
Ref: a581477266
Ref: libraries/hook_objects library-hook-objects1477266
Ref: a591477266
Node: API documentation<40>1477772
Ref: libraries/hook_objects api-documentation1477881
Ref: a5a1477881
Node: Loading<41>1478014
Ref: libraries/hook_objects loading1478143
Ref: a5b1478143
Node: Testing<33>1478435
Ref: libraries/hook_objects testing1478552
Ref: a5c1478552
Node: Usage<23>1478698
Ref: libraries/hook_objects usage1478795
Ref: a5d1478795
Node: Using the Prolog backend adapter file expansion rules1479476
Ref: libraries/hook_objects using-the-prolog-backend-adapter-file-expansion-rules1479652
Ref: a5e1479652
Node: Restoring the default compiler expansion workflow1480000
Ref: libraries/hook_objects restoring-the-default-compiler-expansion-workflow1480243
Ref: a5f1480243
Node: Preventing applying any other user-defined expansion rules1480600
Ref: libraries/hook_objects preventing-applying-any-other-user-defined-expansion-rules1480856
Ref: a601480856
Node: Expanding grammar rules into clauses independently of the compiler1481755
Ref: libraries/hook_objects expanding-grammar-rules-into-clauses-independently-of-the-compiler1482014
Ref: a611482014
Node: Using the expansion rules defined in a Prolog module1482412
Ref: libraries/hook_objects using-the-expansion-rules-defined-in-a-prolog-module1482666
Ref: a621482666
Node: Wrap the contents of a plain Prolog file as an object1483070
Ref: libraries/hook_objects wrap-the-contents-of-a-plain-prolog-file-as-an-object1483313
Ref: a631483313
Node: Outputting term-expansion results to a stream or a file1484798
Ref: libraries/hook_objects outputting-term-expansion-results-to-a-stream-or-a-file1485049
Ref: a641485049
Node: Printing entity predicate goals before or after calling them1486175
Ref: libraries/hook_objects printing-entity-predicate-goals-before-or-after-calling-them1486390
Ref: a651486390
Node: Suppressing goals1487001
Ref: libraries/hook_objects suppressing-goals1487152
Ref: a661487152
Node: html1487841
Ref: libraries/html doc1487943
Ref: a671487943
Ref: libraries/html html1487943
Ref: a681487943
Ref: libraries/html library-html1487943
Ref: a691487943
Node: API documentation<41>1489560
Ref: libraries/html api-documentation1489661
Ref: a6a1489661
Node: Loading<42>1489786
Ref: libraries/html loading1489907
Ref: a6b1489907
Node: Testing<34>1490048
Ref: libraries/html testing1490174
Ref: a6c1490174
Node: Generating a HTML document1490310
Ref: libraries/html generating-a-html-document1490451
Ref: a6d1490451
Node: Generating a HTML fragment1491186
Ref: libraries/html generating-a-html-fragment1491358
Ref: a6e1491358
Node: Working with callbacks to generate content1491828
Ref: libraries/html working-with-callbacks-to-generate-content1492002
Ref: a6f1492002
Node: Working with custom elements1492978
Ref: libraries/html working-with-custom-elements1493117
Ref: a701493117
Node: ids1493729
Ref: libraries/ids doc1493828
Ref: a711493828
Ref: libraries/ids ids1493828
Ref: a721493828
Ref: libraries/ids library-ids1493828
Ref: a731493828
Node: API documentation<42>1494550
Ref: libraries/ids api-documentation1494650
Ref: a741494650
Node: Loading<43>1494774
Ref: libraries/ids loading1494894
Ref: a751494894
Node: Testing<35>1495034
Ref: libraries/ids testing1495142
Ref: a761495142
Node: Usage<24>1495277
Ref: libraries/ids usage1495365
Ref: a771495365
Node: intervals1496203
Ref: libraries/intervals doc1496302
Ref: a781496302
Ref: libraries/intervals intervals1496302
Ref: a791496302
Ref: libraries/intervals library-intervals1496302
Ref: a7a1496302
Node: API documentation<43>1496634
Ref: libraries/intervals api-documentation1496740
Ref: a7b1496740
Node: Loading<44>1496870
Ref: libraries/intervals loading1496996
Ref: a7c1496996
Node: Testing<36>1497142
Ref: libraries/intervals testing1497238
Ref: a7d1497238
Node: java1497379
Ref: libraries/java doc1497479
Ref: a7e1497479
Ref: libraries/java java1497479
Ref: a7f1497479
Ref: libraries/java library-java1497479
Ref: a801497479
Node: API documentation<44>1498709
Ref: libraries/java api-documentation1498810
Ref: a811498810
Node: Loading<45>1498935
Ref: libraries/java loading1499056
Ref: a821499056
Node: Testing<37>1499197
Ref: libraries/java testing1499306
Ref: a831499306
Node: Usage<25>1499442
Ref: libraries/java usage1499555
Ref: a841499555
Node: Known issues<9>1500155
Ref: libraries/java known-issues1500248
Ref: a851500248
Node: json1500650
Ref: libraries/json doc1500751
Ref: a861500751
Ref: libraries/json json1500751
Ref: a871500751
Ref: libraries/json library-json1500751
Ref: a881500751
Node: API documentation<45>1501550
Ref: libraries/json api-documentation1501651
Ref: a891501651
Node: Loading<46>1501776
Ref: libraries/json loading1501897
Ref: a8a1501897
Node: Testing<38>1502038
Ref: libraries/json testing1502155
Ref: a8b1502155
Node: Representation<2>1502392
Ref: libraries/json representation1502509
Ref: a8c1502509
Node: Encoding<3>1507953
Ref: libraries/json encoding1508070
Ref: a8d1508070
Node: Decoding<3>1508876
Ref: libraries/json decoding1508992
Ref: a8e1508992
Node: Known issues<10>1509518
Ref: libraries/json known-issues1509614
Ref: a8f1509614
Node: json_lines1509819
Ref: libraries/json_lines doc1509923
Ref: a901509923
Ref: libraries/json_lines json-lines1509923
Ref: a911509923
Ref: libraries/json_lines library-json-lines1509923
Ref: a921509923
Node: API documentation<46>1510610
Ref: libraries/json_lines api-documentation1510717
Ref: a931510717
Node: Loading<47>1510848
Ref: libraries/json_lines loading1510975
Ref: a941510975
Node: Testing<39>1511122
Ref: libraries/json_lines testing1511245
Ref: a951511245
Node: Representation<3>1511489
Ref: libraries/json_lines representation1511612
Ref: a961511612
Node: Encoding<4>1517145
Ref: libraries/json_lines encoding1517268
Ref: a971517268
Node: Decoding<4>1518088
Ref: libraries/json_lines decoding1518210
Ref: a981518210
Node: Known issues<11>1518723
Ref: libraries/json_lines known-issues1518825
Ref: a991518825
Node: listing1518960
Ref: libraries/listing doc1519067
Ref: a9a1519067
Ref: libraries/listing library-listing1519067
Ref: a9b1519067
Ref: libraries/listing listing1519067
Ref: a9c1519067
Node: API documentation<47>1519413
Ref: libraries/listing api-documentation1519517
Ref: a9d1519517
Node: Loading<48>1519645
Ref: libraries/listing loading1519769
Ref: a9e1519769
Node: Testing<40>1519921
Ref: libraries/listing testing1520033
Ref: a9f1520033
Node: Usage<26>1520172
Ref: libraries/listing usage1520264
Ref: aa01520264
Node: logging1522358
Ref: libraries/logging doc1522460
Ref: aa11522460
Ref: libraries/logging library-logging1522460
Ref: aa21522460
Ref: libraries/logging logging1522460
Ref: aa31522460
Node: API documentation<48>1522633
Ref: libraries/logging api-documentation1522737
Ref: aa41522737
Node: Loading<49>1522865
Ref: libraries/logging loading1522969
Ref: aa51522969
Node: loops1523121
Ref: libraries/loops doc1523220
Ref: aa61523220
Ref: libraries/loops library-loops1523220
Ref: aa71523220
Ref: libraries/loops loops1523220
Ref: aa81523220
Node: API documentation<49>1523471
Ref: libraries/loops api-documentation1523573
Ref: aa91523573
Node: Loading<50>1523699
Ref: libraries/loops loading1523821
Ref: aaa1523821
Node: Testing<41>1523968
Ref: libraries/loops testing1524078
Ref: aab1524078
Node: Usage<27>1524215
Ref: libraries/loops usage1524305
Ref: aac1524305
Node: meta1524372
Ref: libraries/meta doc1524477
Ref: aad1524477
Ref: libraries/meta library-meta1524477
Ref: aae1524477
Ref: libraries/meta meta1524477
Ref: aaf1524477
Node: API documentation<50>1524896
Ref: libraries/meta api-documentation1524997
Ref: ab01524997
Node: Loading<51>1525122
Ref: libraries/meta loading1525243
Ref: ab11525243
Node: Testing<42>1525389
Ref: libraries/meta testing1525498
Ref: ab21525498
Node: Usage<28>1525634
Ref: libraries/meta usage1525723
Ref: ab31525723
Node: meta_compiler1525810
Ref: libraries/meta_compiler doc1525919
Ref: ab41525919
Ref: libraries/meta_compiler library-meta-compiler1525919
Ref: 36a1525919
Ref: libraries/meta_compiler meta-compiler1525919
Ref: ab51525919
Node: API documentation<51>1526251
Ref: libraries/meta_compiler api-documentation1526361
Ref: ab61526361
Node: Loading<52>1526495
Ref: libraries/meta_compiler loading1526625
Ref: ab71526625
Node: Testing<43>1526780
Ref: libraries/meta_compiler testing1526898
Ref: ab81526898
Node: Usage<29>1527043
Ref: libraries/meta_compiler usage1527166
Ref: ab91527166
Node: Known issues<12>1527786
Ref: libraries/meta_compiler known-issues1527889
Ref: aba1527889
Node: mutations1528046
Ref: libraries/mutations doc1528170
Ref: abb1528170
Ref: libraries/mutations library-mutations1528170
Ref: abc1528170
Ref: libraries/mutations mutations1528170
Ref: abd1528170
Node: API documentation<52>1529223
Ref: libraries/mutations api-documentation1529329
Ref: abe1529329
Node: Loading<53>1529459
Ref: libraries/mutations loading1529585
Ref: abf1529585
Node: Testing<44>1529731
Ref: libraries/mutations testing1529845
Ref: ac01529845
Node: Usage<30>1529986
Ref: libraries/mutations usage1530080
Ref: ac11530080
Node: nested_dictionaries1531069
Ref: libraries/nested_dictionaries doc1531189
Ref: ac21531189
Ref: libraries/nested_dictionaries library-nested-dictionaries1531189
Ref: ac31531189
Ref: libraries/nested_dictionaries nested-dictionaries1531189
Ref: ac41531189
Node: API documentation<53>1531762
Ref: libraries/nested_dictionaries api-documentation1531878
Ref: ac51531878
Node: Loading<54>1532018
Ref: libraries/nested_dictionaries loading1532154
Ref: ac61532154
Node: Testing<45>1532310
Ref: libraries/nested_dictionaries testing1532434
Ref: ac71532434
Node: Usage<31>1532585
Ref: libraries/nested_dictionaries usage1532723
Ref: ac81532723
Node: Curly term representation1534427
Ref: libraries/nested_dictionaries curly-term-representation1534545
Ref: ac91534545
Node: optionals1535128
Ref: libraries/optionals doc1535246
Ref: aca1535246
Ref: libraries/optionals library-optionals1535246
Ref: acb1535246
Ref: libraries/optionals optionals1535246
Ref: acc1535246
Node: API documentation<54>1536140
Ref: libraries/optionals api-documentation1536246
Ref: acd1536246
Node: Loading<55>1536376
Ref: libraries/optionals loading1536502
Ref: ace1536502
Node: Testing<46>1536648
Ref: libraries/optionals testing1536762
Ref: acf1536762
Node: Usage<32>1536903
Ref: libraries/optionals usage1537017
Ref: ad01537017
Node: See also<2>1537722
Ref: libraries/optionals see-also1537816
Ref: ad11537816
Node: options1537879
Ref: libraries/options doc1537980
Ref: ad21537980
Ref: libraries/options library-options1537980
Ref: ad31537980
Ref: libraries/options options1537980
Ref: ad41537980
Node: API documentation<55>1538231
Ref: libraries/options api-documentation1538335
Ref: ad51538335
Node: Loading<56>1538463
Ref: libraries/options loading1538587
Ref: ad61538587
Node: Testing<47>1538739
Ref: libraries/options testing1538851
Ref: ad71538851
Node: Usage<33>1538990
Ref: libraries/options usage1539082
Ref: ad81539082
Node: os1541070
Ref: libraries/os doc1541168
Ref: ad91541168
Ref: libraries/os library-os1541168
Ref: ada1541168
Ref: libraries/os os1541168
Ref: adb1541168
Node: API documentation<56>1541573
Ref: libraries/os api-documentation1541672
Ref: adc1541672
Node: Loading<57>1541795
Ref: libraries/os loading1541914
Ref: add1541914
Node: Testing<48>1542053
Ref: libraries/os testing1542167
Ref: ade1542167
Node: Known issues<13>1542301
Ref: libraries/os known-issues1542395
Ref: adf1542395
Node: queues1542807
Ref: libraries/queues doc1542904
Ref: ae01542904
Ref: libraries/queues library-queues1542904
Ref: ae11542904
Ref: libraries/queues queues1542904
Ref: ae21542904
Node: API documentation<57>1543203
Ref: libraries/queues api-documentation1543306
Ref: ae31543306
Node: Loading<58>1543433
Ref: libraries/queues loading1543556
Ref: ae41543556
Node: Testing<49>1543699
Ref: libraries/queues testing1543810
Ref: ae51543810
Node: Usage<34>1543948
Ref: libraries/queues usage1544039
Ref: ae61544039
Node: random1544878
Ref: libraries/random doc1544979
Ref: ae71544979
Ref: libraries/random library-random1544979
Ref: ae81544979
Ref: libraries/random random1544979
Ref: ae91544979
Node: API documentation<58>1545663
Ref: libraries/random api-documentation1545766
Ref: aea1545766
Node: Loading<59>1545893
Ref: libraries/random loading1546016
Ref: aeb1546016
Node: Testing<50>1546159
Ref: libraries/random testing1546270
Ref: aec1546270
Node: Usage<35>1546408
Ref: libraries/random usage1546499
Ref: aed1546499
Node: reader1549037
Ref: libraries/reader doc1549149
Ref: aee1549149
Ref: libraries/reader library-reader1549149
Ref: aef1549149
Ref: libraries/reader reader1549149
Ref: af01549149
Node: API documentation<59>1549560
Ref: libraries/reader api-documentation1549663
Ref: af11549663
Node: Loading<60>1549790
Ref: libraries/reader loading1549913
Ref: af21549913
Node: Testing<51>1550056
Ref: libraries/reader testing1550149
Ref: af31550149
Node: recorded_database1550287
Ref: libraries/recorded_database doc1550398
Ref: af41550398
Ref: libraries/recorded_database library-recorded-database1550398
Ref: af51550398
Ref: libraries/recorded_database recorded-database1550398
Ref: af61550398
Node: API documentation<60>1550847
Ref: libraries/recorded_database api-documentation1550961
Ref: af71550961
Node: Loading<61>1551099
Ref: libraries/recorded_database loading1551233
Ref: af81551233
Node: Testing<52>1551387
Ref: libraries/recorded_database testing1551509
Ref: af91551509
Node: Usage<36>1551658
Ref: libraries/recorded_database usage1551785
Ref: afa1551785
Node: Known issues<14>1552402
Ref: libraries/recorded_database known-issues1552509
Ref: afb1552509
Node: redis1552845
Ref: libraries/redis doc1552954
Ref: afc1552954
Ref: libraries/redis library-redis1552954
Ref: afd1552954
Ref: libraries/redis redis1552954
Ref: afe1552954
Node: API documentation<61>1553441
Ref: libraries/redis api-documentation1553543
Ref: aff1553543
Node: Loading<62>1553669
Ref: libraries/redis loading1553791
Ref: b001553791
Node: Testing<53>1553917
Ref: libraries/redis testing1554028
Ref: b011554028
Node: Credits<4>1554660
Ref: libraries/redis credits1554776
Ref: b021554776
Node: Known issues<15>1554886
Ref: libraries/redis known-issues1554982
Ref: b031554982
Node: sets1555396
Ref: libraries/sets doc1555498
Ref: b041555498
Ref: libraries/sets library-sets1555498
Ref: b051555498
Ref: libraries/sets sets1555498
Ref: b061555498
Node: API documentation<62>1556645
Ref: libraries/sets api-documentation1556746
Ref: b071556746
Node: Loading<63>1556871
Ref: libraries/sets loading1556992
Ref: b081556992
Node: Testing<54>1557133
Ref: libraries/sets testing1557242
Ref: b091557242
Node: Usage<37>1557378
Ref: libraries/sets usage1557486
Ref: b0a1557486
Node: Credits<5>1559342
Ref: libraries/sets credits1559430
Ref: b0b1559430
Node: statistics1559527
Ref: libraries/statistics doc1559631
Ref: b0c1559631
Ref: libraries/statistics library-statistics1559631
Ref: b0d1559631
Ref: libraries/statistics statistics1559631
Ref: b0e1559631
Node: API documentation<63>1560060
Ref: libraries/statistics api-documentation1560167
Ref: b0f1560167
Node: Loading<64>1560298
Ref: libraries/statistics loading1560425
Ref: b101560425
Node: Testing<55>1560572
Ref: libraries/statistics testing1560669
Ref: b111560669
Node: term_io1560811
Ref: libraries/term_io doc1560918
Ref: b121560918
Ref: libraries/term_io library-term-io1560918
Ref: b131560918
Ref: libraries/term_io term-io1560918
Ref: b141560918
Node: API documentation<64>1561418
Ref: libraries/term_io api-documentation1561522
Ref: b151561522
Node: Loading<65>1561650
Ref: libraries/term_io loading1561774
Ref: b161561774
Node: Testing<56>1561918
Ref: libraries/term_io testing1562012
Ref: b171562012
Node: timeout1562151
Ref: libraries/timeout doc1562251
Ref: b181562251
Ref: libraries/timeout library-timeout1562251
Ref: b191562251
Ref: libraries/timeout timeout1562251
Ref: b1a1562251
Node: API documentation<65>1562893
Ref: libraries/timeout api-documentation1562997
Ref: b1b1562997
Node: Loading<66>1563125
Ref: libraries/timeout loading1563249
Ref: b1c1563249
Node: Testing<57>1563393
Ref: libraries/timeout testing1563512
Ref: b1d1563512
Node: Known issues<16>1563651
Ref: libraries/timeout known-issues1563750
Ref: b1e1563750
Node: tsv1564193
Ref: libraries/tsv doc1564291
Ref: b1f1564291
Ref: libraries/tsv library-tsv1564291
Ref: b201564291
Ref: libraries/tsv tsv1564291
Ref: b211564291
Node: API documentation<66>1565457
Ref: libraries/tsv api-documentation1565557
Ref: b221565557
Node: Loading<67>1565681
Ref: libraries/tsv loading1565801
Ref: b231565801
Node: Testing<58>1565941
Ref: libraries/tsv testing1566049
Ref: b241566049
Node: Usage<38>1566184
Ref: libraries/tsv usage1566272
Ref: b251566272
Node: types1567066
Ref: libraries/types doc1567161
Ref: b261567161
Ref: libraries/types library-types1567161
Ref: 14c1567161
Ref: libraries/types types1567161
Ref: b271567161
Node: API documentation<67>1568053
Ref: libraries/types api-documentation1568155
Ref: b281568155
Node: Loading<68>1568281
Ref: libraries/types loading1568403
Ref: b291568403
Node: Testing<59>1568748
Ref: libraries/types testing1568865
Ref: b2a1568865
Node: Type-checking<2>1569002
Ref: libraries/types type-checking1569126
Ref: b2b1569126
Node: Defining new types1570096
Ref: libraries/types defining-new-types1570222
Ref: b2c1570222
Node: Examples<166>1571274
Ref: libraries/types examples1571375
Ref: b2d1571375
Node: ulid1571615
Ref: libraries/ulid doc1571719
Ref: b2e1571719
Ref: libraries/ulid library-ulid1571719
Ref: b2f1571719
Ref: libraries/ulid ulid1571719
Ref: b301571719
Node: API documentation<68>1572638
Ref: libraries/ulid api-documentation1572739
Ref: b311572739
Node: Loading<69>1572864
Ref: libraries/ulid loading1572985
Ref: b321572985
Node: Testing<60>1573126
Ref: libraries/ulid testing1573242
Ref: b331573242
Node: Generating ULIDs1573378
Ref: libraries/ulid generating-ulids1573502
Ref: b341573502
Node: Type-checking ULIDs1575376
Ref: libraries/ulid type-checking-ulids1575480
Ref: b351575480
Node: unicode_data1575818
Ref: libraries/unicode_data doc1575927
Ref: b361575927
Ref: libraries/unicode_data library-unicode-data1575927
Ref: b371575927
Ref: libraries/unicode_data unicode-data1575927
Ref: b381575927
Node: Authors1576220
Ref: libraries/unicode_data authors1576311
Ref: b391576311
Node: License1576409
Ref: libraries/unicode_data license1576516
Ref: b3a1576516
Node: Website1576799
Ref: libraries/unicode_data website1576915
Ref: b3b1576915
Node: Description<165>1577215
Ref: libraries/unicode_data description1577339
Ref: b3c1577339
Node: Requirements<6>1577950
Ref: libraries/unicode_data requirements1578076
Ref: b3d1578076
Node: Usage<39>1578486
Ref: libraries/unicode_data usage1578612
Ref: b3e1578612
Node: Known issues<17>1579060
Ref: libraries/unicode_data known-issues1579187
Ref: b3f1579187
Node: Acknowledgements1579849
Ref: libraries/unicode_data acknowledgements1579988
Ref: b401579988
Node: Files and API Summary1580134
Ref: libraries/unicode_data files-and-api-summary1580248
Ref: b411580248
Node: unicode_arabic_shaping pl1583422
Ref: libraries/unicode_data unicode-arabic-shaping-pl1583558
Ref: b421583558
Ref: libraries/unicode_data unicode-arabic-shapingpl1583558
Ref: b431583558
Node: unicode_bidi_mirroring pl1583711
Ref: libraries/unicode_data unicode-bidi-mirroring-pl1583873
Ref: b441583873
Ref: libraries/unicode_data unicode-bidi-mirroringpl1583873
Ref: b451583873
Node: unicode_blocks pl1584026
Ref: libraries/unicode_data unicode-blocks-pl1584186
Ref: b461584186
Ref: libraries/unicode_data unicode-blockspl1584186
Ref: b471584186
Node: unicode_case_folding pl1584316
Ref: libraries/unicode_data unicode-case-folding-pl1584472
Ref: b481584472
Ref: libraries/unicode_data unicode-case-foldingpl1584472
Ref: b491584472
Node: unicode_categories pl1584619
Ref: libraries/unicode_data unicode-categories-pl1584781
Ref: b4a1584781
Ref: libraries/unicode_data unicode-categoriespl1584781
Ref: b4b1584781
Node: unicode_cjk_radicals pl1584961
Ref: libraries/unicode_data unicode-cjk-radicals-pl1585133
Ref: b4c1585133
Ref: libraries/unicode_data unicode-cjk-radicalspl1585133
Ref: b4d1585133
Node: unicode_composition_exclusions pl1585279
Ref: libraries/unicode_data unicode-composition-exclusions-pl1585456
Ref: b4e1585456
Ref: libraries/unicode_data unicode-composition-exclusionspl1585456
Ref: b4f1585456
Node: unicode_core_properties pl1585632
Ref: libraries/unicode_data unicode-core-properties-pl1585815
Ref: b501585815
Ref: libraries/unicode_data unicode-core-propertiespl1585815
Ref: b511585815
Node: unicode_decomposition_type pl1586698
Ref: libraries/unicode_data unicode-decomposition-type-pl1586870
Ref: b521586870
Ref: libraries/unicode_data unicode-decomposition-typepl1586870
Ref: b531586870
Node: unicode_derived_age pl1587500
Ref: libraries/unicode_data unicode-derived-age-pl1587675
Ref: b541587675
Ref: libraries/unicode_data unicode-derived-agepl1587675
Ref: b551587675
Node: unicode_derived_bidi_class pl1587815
Ref: libraries/unicode_data unicode-derived-bidi-class-pl1587995
Ref: b561587995
Ref: libraries/unicode_data unicode-derived-bidi-classpl1587995
Ref: b571587995
Node: unicode_derived_combining_class pl1588156
Ref: libraries/unicode_data unicode-derived-combining-class-pl1588348
Ref: b581588348
Ref: libraries/unicode_data unicode-derived-combining-classpl1588348
Ref: b591588348
Node: unicode_derived_core_properties pl1588524
Ref: libraries/unicode_data unicode-derived-core-properties-pl1588724
Ref: b5a1588724
Ref: libraries/unicode_data unicode-derived-core-propertiespl1588724
Ref: b5b1588724
Node: unicode_derived_decomposition_type pl1588898
Ref: libraries/unicode_data unicode-derived-decomposition-type-pl1589099
Ref: b5c1589099
Ref: libraries/unicode_data unicode-derived-decomposition-typepl1589099
Ref: b5d1589099
Node: unicode_derived_east_asian_width pl1589284
Ref: libraries/unicode_data unicode-derived-east-asian-width-pl1589483
Ref: b5e1589483
Ref: libraries/unicode_data unicode-derived-east-asian-widthpl1589483
Ref: b5f1589483
Node: unicode_derived_joining_group pl1589662
Ref: libraries/unicode_data unicode-derived-joining-group-pl1589855
Ref: b601589855
Ref: libraries/unicode_data unicode-derived-joining-grouppl1589855
Ref: b611589855
Node: unicode_derived_joining_type pl1590025
Ref: libraries/unicode_data unicode-derived-joining-type-pl1590212
Ref: b621590212
Ref: libraries/unicode_data unicode-derived-joining-typepl1590212
Ref: b631590212
Node: unicode_derived_line_break pl1590379
Ref: libraries/unicode_data unicode-derived-line-break-pl1590572
Ref: b641590572
Ref: libraries/unicode_data unicode-derived-line-breakpl1590572
Ref: b651590572
Node: unicode_derived_normalization_props pl1590733
Ref: libraries/unicode_data unicode-derived-normalization-props-pl1590926
Ref: b661590926
Ref: libraries/unicode_data unicode-derived-normalization-propspl1590926
Ref: b671590926
Node: unicode_derived_numeric_type pl1591625
Ref: libraries/unicode_data unicode-derived-numeric-type-pl1591822
Ref: b681591822
Ref: libraries/unicode_data unicode-derived-numeric-typepl1591822
Ref: b691591822
Node: unicode_derived_numeric_values pl1591989
Ref: libraries/unicode_data unicode-derived-numeric-values-pl1592179
Ref: b6a1592179
Ref: libraries/unicode_data unicode-derived-numeric-valuespl1592179
Ref: b6b1592179
Node: unicode_hangul_syllable_type pl1592351
Ref: libraries/unicode_data unicode-hangul-syllable-type-pl1592541
Ref: b6c1592541
Ref: libraries/unicode_data unicode-hangul-syllable-typepl1592541
Ref: b6d1592541
Node: unicode_indic_matra_category pl1592716
Ref: libraries/unicode_data unicode-indic-matra-category-pl1592907
Ref: b6e1592907
Ref: libraries/unicode_data unicode-indic-matra-categorypl1592907
Ref: b6f1592907
Node: unicode_indic_syllabic_category pl1593082
Ref: libraries/unicode_data unicode-indic-syllabic-category-pl1593257
Ref: b701593257
Ref: libraries/unicode_data unicode-indic-syllabic-categorypl1593257
Ref: b711593257
Node: unicode_jamo pl1593441
Ref: libraries/unicode_data unicode-jamo-pl1593608
Ref: b721593608
Ref: libraries/unicode_data unicode-jamopl1593608
Ref: b731593608
Node: unicode_name_aliases pl1593733
Ref: libraries/unicode_data unicode-name-aliases-pl1593882
Ref: b741593882
Ref: libraries/unicode_data unicode-name-aliasespl1593882
Ref: b751593882
Node: unicode_names pl1594029
Ref: libraries/unicode_data unicode-names-pl1594183
Ref: b761594183
Ref: libraries/unicode_data unicode-namespl1594183
Ref: b771594183
Node: unicode_prop_list pl1594346
Ref: libraries/unicode_data unicode-prop-list-pl1594501
Ref: b781594501
Ref: libraries/unicode_data unicode-prop-listpl1594501
Ref: b791594501
Node: unicode_range_scripts pl1595791
Ref: libraries/unicode_data unicode-range-scripts-pl1595958
Ref: b7a1595958
Ref: libraries/unicode_data unicode-range-scriptspl1595958
Ref: b7b1595958
Node: unicode_script_extensions pl1596132
Ref: libraries/unicode_data unicode-script-extensions-pl1596297
Ref: b7c1596297
Ref: libraries/unicode_data unicode-script-extensionspl1596297
Ref: b7d1596297
Node: unicode_scripts pl1596480
Ref: libraries/unicode_data unicode-scripts-pl1596646
Ref: b7e1596646
Ref: libraries/unicode_data unicode-scriptspl1596646
Ref: b7f1596646
Node: unicode_special_casing pl1596811
Ref: libraries/unicode_data unicode-special-casing-pl1596975
Ref: b801596975
Ref: libraries/unicode_data unicode-special-casingpl1596975
Ref: b811596975
Node: unicode_unihan_variants pl1597130
Ref: libraries/unicode_data unicode-unihan-variants-pl1597294
Ref: b821597294
Ref: libraries/unicode_data unicode-unihan-variantspl1597294
Ref: b831597294
Node: unicode_version pl1597453
Ref: libraries/unicode_data unicode-version-pl1597583
Ref: b841597583
Ref: libraries/unicode_data unicode-versionpl1597583
Ref: b851597583
Node: union_find1597717
Ref: libraries/union_find doc1597826
Ref: b861597826
Ref: libraries/union_find library-union-find1597826
Ref: b871597826
Ref: libraries/union_find union-find1597826
Ref: b881597826
Node: API documentation<69>1598922
Ref: libraries/union_find api-documentation1599029
Ref: b891599029
Node: Loading<70>1599160
Ref: libraries/union_find loading1599287
Ref: b8a1599287
Node: Testing<61>1599434
Ref: libraries/union_find testing1599549
Ref: b8b1599549
Node: Usage<40>1599691
Ref: libraries/union_find usage1599786
Ref: b8c1599786
Node: uuid1601242
Ref: libraries/uuid doc1601346
Ref: b8d1601346
Ref: libraries/uuid library-uuid1601346
Ref: b8e1601346
Ref: libraries/uuid uuid1601346
Ref: b8f1601346
Node: API documentation<70>1602406
Ref: libraries/uuid api-documentation1602507
Ref: b901602507
Node: Loading<71>1602632
Ref: libraries/uuid loading1602753
Ref: b911602753
Node: Testing<62>1602894
Ref: libraries/uuid testing1603020
Ref: b921603020
Node: Generating version 1 UUIDs1603156
Ref: libraries/uuid generating-version-1-uuids1603297
Ref: b931603297
Node: Generating version 4 UUIDs1604185
Ref: libraries/uuid generating-version-4-uuids1604339
Ref: b941604339
Node: Generating the null UUID1605131
Ref: libraries/uuid generating-the-null-uuid1605250
Ref: b951605250
Node: zippers1605467
Ref: libraries/zippers doc1605552
Ref: b961605552
Ref: libraries/zippers library-zippers1605552
Ref: b971605552
Ref: libraries/zippers zippers1605552
Ref: b981605552
Node: API documentation<71>1605734
Ref: libraries/zippers api-documentation1605838
Ref: b991605838
Node: Loading<72>1605966
Ref: libraries/zippers loading1606090
Ref: b9a1606090
Node: Testing<63>1606234
Ref: libraries/zippers testing1606328
Ref: b9b1606328
Node: Ports1606467
Ref: ports/index doc1606571
Ref: b9c1606571
Ref: ports/index ports1606571
Ref: b9d1606571
Node: fcube1606731
Ref: ports/fcube doc1606813
Ref: b9e1606813
Ref: ports/fcube fcube1606813
Ref: b9f1606813
Ref: ports/fcube library-fcube1606813
Ref: ba01606813
Node: API documentation<72>1608118
Ref: ports/fcube api-documentation1608220
Ref: ba11608220
Node: Loading<73>1608344
Ref: ports/fcube loading1608466
Ref: ba21608466
Node: Testing<64>1608603
Ref: ports/fcube testing1608695
Ref: ba31608695
Node: metagol1608827
Ref: ports/metagol doc1608924
Ref: ba41608924
Ref: ports/metagol library-metagol1608924
Ref: ba51608924
Ref: ports/metagol metagol1608924
Ref: ba61608924
Node: API documentation<73>1610813
Ref: ports/metagol api-documentation1610917
Ref: ba71610917
Node: Loading<74>1611043
Ref: ports/metagol loading1611167
Ref: ba81611167
Node: Testing<65>1611306
Ref: ports/metagol testing1611400
Ref: ba91611400
Node: toychr1611643
Ref: ports/toychr doc1611726
Ref: baa1611726
Ref: ports/toychr library-toychr1611726
Ref: bab1611726
Ref: ports/toychr toychr1611726
Ref: bac1611726
Node: API documentation<74>1612711
Ref: ports/toychr api-documentation1612814
Ref: bad1612814
Node: Loading<75>1612939
Ref: ports/toychr loading1613062
Ref: bae1613062
Node: Testing<66>1613200
Ref: ports/toychr testing1613293
Ref: baf1613293
Node: Contributions1613426
Ref: contributions/index doc1613529
Ref: bb01613529
Ref: contributions/index contributions1613529
Ref: bb11613529
Node: flags1613753
Ref: contributions/flags doc1613843
Ref: bb21613843
Ref: contributions/flags flags1613843
Ref: bb31613843
Ref: contributions/flags library-flags1613843
Ref: bb41613843
Node: API documentation<75>1614266
Ref: contributions/flags api-documentation1614368
Ref: bb51614368
Node: Loading<76>1614492
Ref: contributions/flags loading1614614
Ref: bb61614614
Node: Testing<67>1614752
Ref: contributions/flags testing1614844
Ref: bb71614844
Node: iso86011614979
Ref: contributions/iso8601 doc1615089
Ref: bb81615089
Ref: contributions/iso8601 iso86011615089
Ref: bb91615089
Ref: contributions/iso8601 library-iso86011615089
Ref: bba1615089
Node: API documentation<76>1615487
Ref: contributions/iso8601 api-documentation1615591
Ref: bbb1615591
Node: Loading<77>1615717
Ref: contributions/iso8601 loading1615841
Ref: bbc1615841
Node: Testing<68>1615983
Ref: contributions/iso8601 testing1616077
Ref: bbd1616077
Node: pddl_parser1616214
Ref: contributions/pddl_parser doc1616331
Ref: bbe1616331
Ref: contributions/pddl_parser library-pddl-parser1616331
Ref: bbf1616331
Ref: contributions/pddl_parser pddl-parser1616331
Ref: bc01616331
Node: API documentation<77>1617032
Ref: contributions/pddl_parser api-documentation1617140
Ref: bc11617140
Node: Loading<78>1617270
Ref: contributions/pddl_parser loading1617398
Ref: bc21617398
Node: Testing<69>1617542
Ref: contributions/pddl_parser testing1617640
Ref: bc31617640
Node: verdi_neruda1618069
Ref: contributions/verdi_neruda doc1618189
Ref: bc41618189
Ref: contributions/verdi_neruda library-verdi-neruda1618189
Ref: bc51618189
Ref: contributions/verdi_neruda verdi-neruda1618189
Ref: bc61618189
Node: xml_parser1625457
Ref: contributions/xml_parser doc1625557
Ref: bc71625557
Ref: contributions/xml_parser library-xml-parser1625557
Ref: bc81625557
Ref: contributions/xml_parser xml-parser1625557
Ref: bc91625557
Node: API documentation<78>1626220
Ref: contributions/xml_parser api-documentation1626327
Ref: bca1626327
Node: Loading<79>1626456
Ref: contributions/xml_parser loading1626583
Ref: bcb1626583
Node: Testing<70>1626728
Ref: contributions/xml_parser testing1626850
Ref: bcc1626850
Node: Known issues<18>1626990
Ref: contributions/xml_parser known-issues1627092
Ref: bcd1627092
Node: Glossary1627316
Ref: glossary doc1627422
Ref: bce1627422
Ref: glossary glossary1627422
Ref: bcf1627422
Ref: glossary id11627445
Ref: 3f1627445
Ref: glossary term-abstract-class1627445
Ref: bd01627445
Ref: glossary term-abstract-method1627628
Ref: bd21627628
Ref: glossary term-adapter-file1627833
Ref: 1541627833
Ref: glossary term-after-method1628008
Ref: bd51628008
Ref: glossary term-ancestor1628106
Ref: bd61628106
Ref: glossary term-around-method1628505
Ref: bd81628505
Ref: glossary term-backend-Prolog-compiler1628668
Ref: 341628668
Ref: glossary term-before-method1628891
Ref: bd91628891
Ref: glossary term-built-in-method1628990
Ref: bda1628990
Ref: glossary term-built-in-predicate1629234
Ref: bdb1629234
Ref: glossary term-category1629419
Ref: bd41629419
Ref: glossary term-class1629768
Ref: bd11629768
Ref: glossary term-clause-reference1630047
Ref: 1b81630047
Ref: glossary term-closed-world-assumption1630199
Ref: 6a1630199
Ref: glossary term-closure1630529
Ref: 14f1630529
Ref: glossary term-coinductive-predicate1630740
Ref: 1701630740
Ref: glossary term-complementing-category1630964
Ref: bdd1630964
Ref: glossary term-component1631086
Ref: 3531631086
Ref: glossary term-debug-handler1631399
Ref: 3381631399
Ref: glossary term-directive1631567
Ref: bde1631567
Ref: glossary term-discontiguous-predicate1631716
Ref: 4b81631716
Ref: glossary term-doclet-file1631909
Ref: bdf1631909
Ref: glossary term-doclet-object1632051
Ref: 63c1632051
Ref: glossary term-dynamic-binding1632246
Ref: 361632246
Ref: glossary term-dynamic-entity1632622
Ref: be01632622
Ref: glossary term-dynamic-predicate1632667
Ref: 4be1632667
Ref: glossary term-early-binding1632773
Ref: be21632773
Ref: glossary term-encapsulation1632824
Ref: be31632824
Ref: glossary term-entity1633081
Ref: be11633081
Ref: glossary term-entity-alias1633559
Ref: c91633559
Ref: glossary term-entity-directive1633991
Ref: be51633991
Ref: glossary term-event1634100
Ref: be61634100
Ref: glossary term-expansion-workflow1634411
Ref: be71634411
Ref: glossary term-flaky-test1634625
Ref: bea1634625
Ref: glossary term-goal-expansion1634898
Ref: be91634898
Ref: glossary term-grammar-rule1635354
Ref: beb1635354
Ref: glossary term-grammar-rule-non-terminal1635777
Ref: bec1635777
Ref: glossary term-grammar-rule-terminal1636005
Ref: bed1636005
Ref: glossary term-homoiconic1636072
Ref: 71636072
Ref: glossary term-hook-object1636414
Ref: 39e1636414
Ref: glossary term-hook-predicate1636830
Ref: 16d1636830
Ref: glossary term-hot-patching1637037
Ref: 10b1637037
Ref: glossary term-identity1637380
Ref: be41637380
Ref: glossary term-inheritance1637793
Ref: 441637793
Ref: glossary term-instance1638256
Ref: bf11638256
Ref: glossary term-instantiation1638459
Ref: bf21638459
Ref: glossary term-interface1638720
Ref: bf31638720
Ref: glossary term-lambda-expression1638761
Ref: 1821638761
Ref: glossary term-lambda-free-variable1639110
Ref: 2701639110
Ref: glossary term-lambda-parameter1639313
Ref: 2711639313
Ref: glossary term-late-binding1639563
Ref: bf41639563
Ref: glossary term-library1639614
Ref: 6e1639614
Ref: glossary term-library-alias1639740
Ref: bf51639740
Ref: glossary term-library-notation1640006
Ref: 2a81640006
Ref: glossary term-loader-file1640367
Ref: 4f1640367
Ref: glossary term-local-predicate1640544
Ref: 561640544
Ref: glossary term-message1640940
Ref: 431640940
Ref: glossary term-message-lookup1641140
Ref: 371641140
Ref: glossary term-message-to-self1641516
Ref: 17d1641516
Ref: glossary term-meta-argument1641730
Ref: bf61641730
Ref: glossary term-meta-interpreter1641970
Ref: bf71641970
Ref: glossary term-meta-predicate1642073
Ref: 521642073
Ref: glossary term-meta-variable1642252
Ref: 1831642252
Ref: glossary term-metaclass1642397
Ref: 721642397
Ref: glossary term-method1642643
Ref: bd31642643
Ref: glossary term-mocking1642930
Ref: bf81642930
Ref: glossary term-module1643175
Ref: bf91643175
Ref: glossary term-monitor1643489
Ref: 31e1643489
Ref: glossary term-multifile-predicate1643727
Ref: 16b1643727
Ref: glossary term-naked-meta-variable1644143
Ref: 7b81644143
Ref: glossary term-object1644450
Ref: 5331644450
Ref: glossary term-object-database1644807
Ref: 1b01644807
Ref: glossary term-parameter1644886
Ref: bfa1644886
Ref: glossary term-parameter-variable1645091
Ref: a11645091
Ref: glossary term-parametric-category1645542
Ref: bfb1645542
Ref: glossary term-parametric-entity1645603
Ref: 6a01645603
Ref: glossary term-parametric-object1646164
Ref: 4251646164
Ref: glossary term-parametric-object-proxy1646223
Ref: 3fa1646223
Ref: glossary term-parent1646410
Ref: bfc1646410
Ref: glossary term-polymorphism1646487
Ref: bfd1646487
Ref: glossary term-predicate1647293
Ref: 611647293
Ref: glossary term-predicate-alias1647588
Ref: ca1647588
Ref: glossary term-predicate-calling-context1648109
Ref: 1501648109
Ref: glossary term-predicate-declaration1648301
Ref: 571648301
Ref: glossary term-predicate-definition1648480
Ref: 581648480
Ref: glossary term-predicate-definition-context1648670
Ref: 1511648670
Ref: glossary term-predicate-directive1648796
Ref: bdc1648796
Ref: glossary term-predicate-execution-context1648928
Ref: 35e1648928
Ref: glossary term-predicate-scope-container1649120
Ref: 3f91649120
Ref: glossary term-predicate-scope-directive1649295
Ref: 1e41649295
Ref: glossary term-predicate-shorthand1649439
Ref: 1611649439
Ref: glossary term-primary-predicate-declaration1649979
Ref: 3921649979
Ref: glossary term-private-inheritance1650052
Ref: bf01650052
Ref: glossary term-private-predicate1650241
Ref: 551650241
Ref: glossary term-profiler1650369
Ref: bfe1650369
Ref: glossary term-protected-inheritance1650447
Ref: bef1650447
Ref: glossary term-protected-predicate1650667
Ref: 541650667
Ref: glossary term-protocol1650846
Ref: 591650846
Ref: glossary term-prototype1651347
Ref: bd71651347
Ref: glossary term-public-inheritance1651686
Ref: bee1651686
Ref: glossary term-public-predicate1651858
Ref: 531651858
Ref: glossary term-scratch-directory1651930
Ref: 2931651930
Ref: glossary term-self1652083
Ref: 691652083
Ref: glossary term-sender1652161
Ref: 3991652161
Ref: glossary term-settings-file1652396
Ref: 491652396
Ref: glossary term-singleton-method1652663
Ref: bff1652663
Ref: glossary term-source-file1652874
Ref: 61c1652874
Ref: glossary term-source-file-directive1653288
Ref: c001653288
Ref: glossary term-specialization1653402
Ref: c011653402
Ref: glossary term-static-binding1653545
Ref: 351653545
Ref: glossary term-static-entity1654006
Ref: c021654006
Ref: glossary term-steadfastness1654050
Ref: 2c41654050
Ref: glossary term-subclass1654385
Ref: 631654385
Ref: glossary term-super-call1654531
Ref: 1151654531
Ref: glossary term-superclass1654875
Ref: 601654875
Ref: glossary term-synchronized-predicate1655053
Ref: 1751655053
Ref: glossary term-template-method1655242
Ref: c031655242
Ref: glossary term-term-expansion1655297
Ref: be81655297
Ref: glossary term-test-dialect1655759
Ref: c041655759
Ref: glossary term-test-outcome1655961
Ref: c051655961
Ref: glossary term-tester-file1656156
Ref: c061656156
Ref: glossary term-this1656267
Ref: 1141656267
Ref: glossary term-threaded-engine1656564
Ref: 2ba1656564
Ref: glossary term-top-level-interpreter-shorthand1656881
Ref: c071656881
Ref: glossary term-visible-predicate1657157
Ref: c081657157
Ref: bibliography alexiev931657349
Ref: c091657349
Ref: bibliography belli-et-al-921657533
Ref: c0a1657533
Ref: bibliography block891657820
Ref: c0b1657820
Ref: bibliography bobrow-et-al-881657924
Ref: 1fd1657924
Ref: bibliography bratko901658094
Ref: c0c1658094
Ref: bibliography champaux921658198
Ref: 28d1658198
Ref: bibliography clocksin871658351
Ref: c0d1658351
Ref: bibliography cointe871658449
Ref: 9c1658449
Ref: bibliography cordes911658560
Ref: c0e1658560
Ref: bibliography covington941658659
Ref: c0f1658659
Ref: bibliography cox861658793
Ref: 1d1658793
Ref: bibliography davison891658923
Ref: c101658923
Ref: bibliography davison921659034
Ref: c111659034
Ref: bibliography davison931659257
Ref: c121659257
Ref: bibliography delzanno971659471
Ref: c131659471
Ref: bibliography dony901659669
Ref: c141659669
Ref: bibliography fornarino-et-al-891659796
Ref: 121659796
Ref: bibliography fromherz931660061
Ref: 291660061
Ref: bibliography fukunaga861660166
Ref: c151660166
Ref: bibliography goldberg831660308
Ref: 1c1660308
Ref: bibliography joy-et-al-001660438
Ref: 1e1660438
Ref: bibliography iso951660568
Ref: 311660568
Ref: bibliography knuth841660739
Ref: c161660739
Ref: bibliography lieberman861660823
Ref: 191660823
Ref: bibliography maes871660972
Ref: 141660972
Ref: bibliography mccabe921661072
Ref: 281661072
Ref: bibliography moon861661157
Ref: 10a1661157
Ref: bibliography moss941661247
Ref: 1fc1661247
Ref: bibliography moura941661389
Ref: 9d1661389
Ref: bibliography moura991661580
Ref: c171661580
Ref: bibliography moura001661755
Ref: c181661755
Ref: bibliography razek921661869
Ref: 131661869
Ref: bibliography rumbaugh871661962
Ref: 101661962
Ref: bibliography rumbaugh881662089
Ref: 111662089
Ref: bibliography schachte951662220
Ref: c191662220
Ref: bibliography sicstus951662478
Ref: 2a1662478
Ref: bibliography shan-et-al-931662556
Ref: 1ff1662556
Ref: bibliography stefik-et-al-861662719
Ref: 2021662719
Ref: bibliography stroustrup861662887
Ref: 231662887
Ref: bibliography taenzer891662989
Ref: 1fe1662989
Ref: bibliography tanzer951663172
Ref: c1a1663172
Ref: bibliography tanenbaum871663320
Ref: 2031663320
Ref: bibliography welsch891663431
Ref: c1b1663431
Ref: Glossary-Footnote-11663697
Ref: Glossary-Footnote-21663742
Ref: Glossary-Footnote-31663787
Ref: Glossary-Footnote-41663834
Node: Index<2>1663879
Ref: genindex doc1663977
Ref: c1c1663977
Ref: genindex index1663977
Ref: c1d1663977
Node: Index1663996

End Tag Table


Local Variables:
coding: utf-8
End:
