This is TheLogtalkHandbook-3.50.0.info, produced by makeinfo version 6.8
from TheLogtalkHandbook-3.50.0.texi.

     The Logtalk Handbook v3.50.0, Aug 31, 2021

     Paulo Moura

     Copyright © 1998-2021, Paulo Moura

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


   Generated by Sphinx 4.1.2.


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

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

     The Logtalk Handbook v3.50.0, Aug 31, 2021

     Paulo Moura

     Copyright © 1998-2021, Paulo Moura

* Menu:

* User Manual::
* Reference Manual::
* Tutorial::
* FAQ::
* Developer Tools::
* Libraries::
* 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 in runtime::
* Abolishing an existing object::
* Object directives::
* Object relationships::
* Object properties::
* Built-in objects::

Objects, prototypes, classes, and instances

* Prototypes::
* Classes::

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 in runtime::
* Abolishing an existing protocol::
* Protocol directives::
* Protocol relationships::
* Protocol properties::
* Implementing protocols::
* Built-in protocols::

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 in runtime::
* Abolishing an existing category::
* Category directives::
* Category relationships::
* Category properties::
* Importing categories::
* Calling category predicates::
* Parametric categories::
* Built-in categories::

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

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

* Search order for prototype hierarchies::
* Search order for class hierarchies::

Implementation inheritance

* Search order for prototype hierarchies: Search order for prototype hierarchies<2>.
* Search order for class hierarchies: Search 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::
* 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::
* Intercepting messages::
* Asking questions::
* Intercepting questions::

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

* Documenting directives::
* Processing and viewing documenting files::
* Inline formatting in comments text::
* Diagrams::

Documenting directives

* Entity directives::
* Predicate directives::

Debugging

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

Defining spy points

* Defining line number and predicate spy points::
* Defining context spy points::
* Removing all spy points::

Debugging messages

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

Performance

* Source code compilation modes::
* 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::
* 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>.

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::

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 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: Predicate directives<2>.

Control constructs

* Message sending: Message sending<2>.
* Message delegation::
* Calling imported and inherited predicates: Calling imported and inherited predicates<2>.
* 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

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

Calling external predicates

* {}/1::

{}/1

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

Context switching calls

* <</2::

<</2

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

Directives

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

Source file directives

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

encoding/1

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

include/1

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

initialization/1

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

op/3

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

set_logtalk_flag/2

* Description: Description<11>.
* Template and modes: Template and modes<5>.
* Errors: Errors<7>.
* Examples: Examples<12>.

Conditional compilation directives

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

if/1

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

elif/1

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

else/0

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

endif/0

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

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<16>.
* Template and modes: Template and modes<10>.
* Examples: Examples<17>.

category/1-4

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

dynamic/0

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

end_category/0

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

end_object/0

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

end_protocol/0

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

info/1

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

object/1-5

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

protocol/1-2

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

threaded/0

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

uses/1

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

use_module/1

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

Predicate directives

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

alias/2

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

coinductive/1

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

discontiguous/1

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

dynamic/1

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

info/2

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

meta_predicate/1

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

meta_non_terminal/1

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

mode/2

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

multifile/1

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

private/1

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

protected/1

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

public/1

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

synchronized/1

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

uses/2

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

use_module/2

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

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<43>.
* Modes and number of proofs: Modes and number of proofs<7>.
* Errors: Errors<8>.
* Examples: Examples<44>.

current_object/1

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

current_protocol/1

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

Enumerating objects, categories and protocols properties

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

category_property/2

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

object_property/2

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

protocol_property/2

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

Creating new objects, categories and protocols

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

create_category/4

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

create_object/4

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

create_protocol/3

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

Abolishing objects, categories and protocols

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

abolish_category/1

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

abolish_object/1

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

abolish_protocol/1

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

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<55>.
* Modes and number of proofs: Modes and number of proofs<19>.
* Errors: Errors<20>.
* Examples: Examples<56>.

extends_protocol/2-3

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

extends_category/2-3

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

implements_protocol/2-3

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

conforms_to_protocol/2-3

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

complements_object/2

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

imports_category/2-3

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

instantiates_class/2-3

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

specializes_class/2-3

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

Event handling

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

abolish_events/5

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

current_event/5

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

define_events/5

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

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<67>.
* Modes and number of proofs: Modes and number of proofs<31>.
* Errors: Errors<32>.
* Examples: Examples<68>.

threaded_call/1-2

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

threaded_once/1-2

* Description: Description<69>.
* Modes and number of proofs: Modes and number of proofs<33>.
* Errors: Errors<34>.
* Examples: Examples<70>.

threaded_ignore/1

* Description: Description<70>.
* Modes and number of proofs: Modes and number of proofs<34>.
* Errors: Errors<35>.
* Examples: Examples<71>.

threaded_exit/1-2

* Description: Description<71>.
* Modes and number of proofs: Modes and number of proofs<35>.
* Errors: Errors<36>.
* Examples: Examples<72>.

threaded_peek/1-2

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

threaded_cancel/1

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

threaded_wait/1

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

threaded_notify/1

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

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<76>.
* Modes and number of proofs: Modes and number of proofs<40>.
* Errors: Errors<41>.
* Examples: Examples<77>.

threaded_engine_destroy/1

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

threaded_engine/1

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

threaded_engine_self/1

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

threaded_engine_next/2

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

threaded_engine_next_reified/2

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

threaded_engine_yield/1

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

threaded_engine_post/2

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

threaded_engine_fetch/1

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

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<85>.
* Modes and number of proofs: Modes and number of proofs<49>.
* Errors: Errors<50>.
* Examples: Examples<86>.

logtalk_compile/2

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

logtalk_load/1

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

logtalk_load/2

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

logtalk_make/0

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

logtalk_make/1

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

logtalk_make_target_action/1

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

logtalk_library_path/2

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

logtalk_load_context/2

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

Flags

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

current_logtalk_flag/2

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

set_logtalk_flag/2

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

create_logtalk_flag/3

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

Linter

* logtalk_linter_hook/7::

logtalk_linter_hook/7

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

Built-in methods

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

Execution context

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

context/1

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

parameter/2

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

self/1

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

sender/1

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

this/1

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

Reflection

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

current_op/3

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

current_predicate/1

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

predicate_property/2

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

Database

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

abolish/1

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

asserta/1

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

assertz/1

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

clause/2

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

retract/1

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

retractall/1

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

Meta-calls

* call/1-N::
* ignore/1::
* once/1::
* \\+/1::

call/1-N

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

ignore/1

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

once/1

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

\\+/1

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

Error handling

* catch/3::
* throw/1::
* instantiation_error/0::
* uninstantiation_error/1::
* type_error/2::
* domain_error/2::
* 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<116>.
* Modes and number of proofs: Modes and number of proofs<80>.
* Errors: Errors<81>.
* Examples: Examples<117>.

throw/1

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

instantiation_error/0

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

uninstantiation_error/1

* Description: Description<119>.
* Modes and number of proofs: Modes and number of proofs<83>.
* Errors: Errors<84>.
* Examples: Examples<120>.

type_error/2

* Description: Description<120>.
* Modes and number of proofs: Modes and number of proofs<84>.
* Errors: Errors<85>.
* Examples: Examples<121>.

domain_error/2

* Description: Description<121>.
* Modes and number of proofs: Modes and number of proofs<85>.
* Errors: Errors<86>.
* Examples: Examples<122>.

existence_error/2

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

permission_error/3

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

representation_error/1

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

evaluation_error/1

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

resource_error/1

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

syntax_error/1

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

system_error/0

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

All solutions

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

bagof/3

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

findall/3

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

findall/4

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

forall/2

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

setof/3

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

Event handling

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

before/3

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

after/3

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

Message forwarding

* forward/1::

forward/1

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

Definite clause grammar rules

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

call//1-N

* Description: Description<137>.
* Modes and number of proofs: Modes and number of proofs<101>.
* Errors: Errors<102>.
* Examples: Examples<138>.

eos//0

* Description: Description<138>.
* Modes and number of proofs: Modes and number of proofs<102>.
* Errors: Errors<103>.
* Examples: Examples<139>.

phrase//1

* Description: Description<139>.
* Modes and number of proofs: Modes and number of proofs<103>.
* Errors: Errors<104>.
* Examples: Examples<140>.

phrase/2

* Description: Description<140>.
* Modes and number of proofs: Modes and number of proofs<104>.
* Errors: Errors<105>.
* Examples: Examples<141>.

phrase/3

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

Term and goal expansion

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

expand_term/2

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

term_expansion/2

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

expand_goal/2

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

goal_expansion/2

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

Coinduction hooks

* coinductive_success_hook/1-2::

coinductive_success_hook/1-2

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

Message printing

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

print_message/3

* Description: Description<147>.
* Modes and number of proofs: Modes and number of proofs<111>.
* Errors: Errors<112>.
* Examples: Examples<148>.

message_tokens//2

* Description: Description<148>.
* Modes and number of proofs: Modes and number of proofs<112>.
* Errors: Errors<113>.
* Examples: Examples<149>.

message_hook/4

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

message_prefix_stream/4

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

print_message_tokens/3

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

print_message_token/4

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

Question asking

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

ask_question/5

* Description: Description<153>.
* Modes and number of proofs: Modes and number of proofs<117>.
* Meta-predicate template::
* Errors: Errors<118>.
* Examples: Examples<154>.

question_hook/6

* Description: Description<154>.
* Modes and number of proofs: Modes and number of proofs<118>.
* Meta-predicate template: Meta-predicate template<2>.
* Errors: Errors<119>.
* Examples: Examples<155>.

question_prompt_stream/4

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

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 do 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::
* lgtdoc::
* lgtunit::
* linter::
* make::
* ports_profiler::
* profiler::
* tutor::
* wrapper::

Overview

* Loading the developer tools::
* Tools documentation::

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

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

doclet

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

help

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

lgtdoc

* API documentation: API documentation<9>.
* Loading: Loading<9>.
* Testing: Testing<8>.
* Documenting source code::
* Generating documentation::

lgtunit

* Main files::
* API documentation: API documentation<10>.
* Loading: Loading<10>.
* Testing: Testing<9>.
* Writing and loading tests::
* Running unit tests::
* Parametric test objects::
* Test dialects::
* User-defined test dialects::
* QuickCheck::
* Skipping 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::
* Flaky tests::
* Debugging failed tests::
* Code coverage::
* Automating running tests::
* 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::
* Minimizing test results output::
* Known issues: Known issues<3>.

make

* API documentation: API documentation<11>.

ports_profiler

* API documentation: API documentation<12>.
* Loading: Loading<11>.
* Testing: Testing<10>.
* 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<4>.

profiler

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

tutor

* API documentation: API documentation<13>.
* Loading: Loading<13>.
* Usage: Usage<6>.

wrapper

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

Libraries

* Overview: Overview<2>.
* arbitrary::
* assignvars::
* base64::
* basic_types::
* coroutining::
* cbor::
* csv::
* dates::
* dependents::
* dictionaries::
* edcg::
* events::
* expand_library_alias_paths::
* expecteds::
* gensym::
* git::
* heaps::
* hierarchies::
* hook_flows::
* hook_objects::
* html::
* intervals::
* java::
* json::
* logging::
* loops::
* meta::
* meta_compiler::
* nested_dictionaries::
* optionals::
* options::
* os::
* queues::
* random::
* reader::
* redis::
* sets::
* statistics::
* term_io::
* timeout::
* types::
* unicode_data::
* uuid::
* zippers::

Overview

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

arbitrary

* API documentation: API documentation<15>.
* Loading: Loading<15>.
* Testing: Testing<12>.
* Usage: Usage<7>.
* Examples: Examples<157>.
* Known issues: Known issues<5>.

assignvars

* API documentation: API documentation<16>.
* Loading: Loading<16>.
* Testing: Testing<13>.

base64

* API documentation: API documentation<17>.
* Loading: Loading<17>.
* Testing: Testing<14>.
* Encoding::
* Decoding::

basic_types

* API documentation: API documentation<18>.
* Loading: Loading<18>.
* Testing: Testing<15>.

coroutining

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

cbor

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

csv

* API documentation: API documentation<21>.
* Loading: Loading<21>.
* Testing: Testing<18>.
* Usage: Usage<8>.

dates

* API documentation: API documentation<22>.
* Loading: Loading<22>.

dependents

* API documentation: API documentation<23>.
* Loading: Loading<23>.

dictionaries

* API documentation: API documentation<24>.
* Loading: Loading<24>.
* Testing: Testing<19>.
* Usage: Usage<9>.
* Credits: Credits<2>.

edcg

* API documentation: API documentation<25>.
* Loading: Loading<25>.
* Testing: Testing<20>.
* Usage: Usage<10>.
* Introduction::
* Syntax::
* Declaration of Predicates::
* Declaration of Accumulators::
* Declaration of Passed Arguments::
* Additional documentation::

events

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

expand_library_alias_paths

* API documentation: API documentation<27>.
* Loading: Loading<27>.
* Usage: Usage<11>.

expecteds

* API documentation: API documentation<28>.
* Loading: Loading<28>.
* Testing: Testing<21>.
* Usage: Usage<12>.
* See also::

gensym

* API documentation: API documentation<29>.
* Loading: Loading<29>.
* Testing: Testing<22>.

git

* API documentation: API documentation<30>.
* Loading: Loading<30>.
* Testing: Testing<23>.
* Usage: Usage<13>.

heaps

* API documentation: API documentation<31>.
* Loading: Loading<31>.
* Testing: Testing<24>.
* Credits: Credits<3>.

hierarchies

* API documentation: API documentation<32>.
* Loading: Loading<32>.
* Testing: Testing<25>.

hook_flows

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

hook_objects

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

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::
* Printing entity predicate goals before or after calling them::
* Suppressing goals::

html

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

intervals

* API documentation: API documentation<36>.
* Loading: Loading<36>.
* Testing: Testing<29>.

java

* API documentation: API documentation<37>.
* Loading: Loading<37>.
* Testing: Testing<30>.
* Usage: Usage<16>.
* Known issues: Known issues<6>.

json

* API documentation: API documentation<38>.
* Loading: Loading<38>.
* Testing: Testing<31>.
* Representation: Representation<2>.
* Encoding: Encoding<3>.
* Decoding: Decoding<3>.

logging

* API documentation: API documentation<39>.
* Loading: Loading<39>.

loops

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

meta

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

meta_compiler

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

nested_dictionaries

* API documentation: API documentation<43>.
* Loading: Loading<43>.
* Testing: Testing<35>.
* Usage: Usage<20>.
* Curly term representation::

optionals

* API documentation: API documentation<44>.
* Loading: Loading<44>.
* Testing: Testing<36>.
* Usage: Usage<21>.
* See also: See also<2>.

options

* API documentation: API documentation<45>.
* Loading: Loading<45>.
* Testing: Testing<37>.
* Usage: Usage<22>.

os

* API documentation: API documentation<46>.
* Loading: Loading<46>.
* Testing: Testing<38>.
* Known issues: Known issues<7>.

queues

* API documentation: API documentation<47>.
* Loading: Loading<47>.
* Testing: Testing<39>.
* Usage: Usage<23>.

random

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

reader

* API documentation: API documentation<49>.
* Loading: Loading<49>.
* Testing: Testing<41>.

redis

* API documentation: API documentation<50>.
* Loading: Loading<50>.
* Testing: Testing<42>.
* Credits: Credits<4>.
* Known issues: Known issues<8>.

sets

* API documentation: API documentation<51>.
* Loading: Loading<51>.
* Testing: Testing<43>.
* Usage: Usage<25>.
* Credits: Credits<5>.

statistics

* API documentation: API documentation<52>.
* Loading: Loading<52>.
* Testing: Testing<44>.

term_io

* API documentation: API documentation<53>.
* Loading: Loading<53>.
* Testing: Testing<45>.

timeout

* API documentation: API documentation<54>.
* Loading: Loading<54>.
* Testing: Testing<46>.

types

* API documentation: API documentation<55>.
* Loading: Loading<55>.
* Testing: Testing<47>.

unicode_data

* Authors::
* License::
* Website::
* Description: Description<156>.
* Requirements::
* Usage: Usage<26>.
* Known issues: Known issues<9>.
* 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.

uuid

* API documentation: API documentation<56>.
* Loading: Loading<56>.
* Testing: Testing<48>.
* Generating version 1 UUIDs::
* Generating version 4 UUIDs::
* Generating the null UUID::

zippers

* API documentation: API documentation<57>.
* Loading: Loading<57>.
* Testing: Testing<49>.



File: TheLogtalkHandbook-3.50.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.50.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 in declarative
object-oriented logic programming.

The first critical 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 forgo a distinction between `data'
and `procedures' that is central to imperative object-oriented languages
but moot in declarative, homoiconic logic languages.

The second critical 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.  Moreover, 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 naturally 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.50.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 come from my frustration with
Prolog shortcomings for writing large applications.  Eventually this
work has led to the Logtalk programming language as its know 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 subsequent work, the name was retained and Logtalk as
created as a full programming language focusing on using object-oriented
concepts for code encapsulation and reuse.  Development started on
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.50.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, turning 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.50.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 specially useful when
     representing relationships between objects that imply constraints
     in the state of participating objects *note [Rumbaugh87]: e, *note
     [Rumbaugh88]: f, *note [Fornarino_et_al_89]: 10, *note [Razek92]:
     11.  Other common uses are reflective applications like code
     debugging or profiling *note [Maes87]: 12.  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 on
     Aspect-Oriented Programming.


File: TheLogtalkHandbook-3.50.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 allows for code reuse between non-related
     objects, independent of hierarchy relations, in the same vein as
     protocols allow for interface reuse.


File: TheLogtalkHandbook-3.50.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]: 17,
     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 solves 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.50.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]: 1a, Objective-C
     *note [Cox86]: 1b. and Java *note [Joy_et_al_00]: 1c. 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.50.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.50.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]: 21, enabling us to
     restrict the scope of inherited, imported or implemented predicates
     (by default inheritance is public).


File: TheLogtalkHandbook-3.50.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]: 21.  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.50.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]: 26, ‘OL(P)’
     *note [Fromherz93]: 27. or ‘SICStus Objects’ *note [SICStus95]: 28.
     (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.50.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.50.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.50.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]: 2f.  It runs in almost any computer system with a
     modern Prolog compiler.


File: TheLogtalkHandbook-3.50.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: 32.  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: 33. and *note dynamic binding: 34. 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: 35. (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: 36.


File: TheLogtalkHandbook-3.50.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.50.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 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: 3c. and an extensive *note glossary: 3d.
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.50.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: 40. directive to wrap those goals.  This ensure
     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: 41. 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.  This is also different from calling a
     Prolog module predicate: a message may result e.g.  in calling a
     predicate *note inherited: 42. 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 apply 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: 43. source files.  It also provides convenient
     top-level interpreter *note shorthands: 44. 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: 45. is a regular application, implemented using a public
     *note reflection: 46. API. This means that the debugger must be
     explicitly loaded (either automatically from a *note settings file:
     47. 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/2: 48. or its own *note use_module/1:
     49. and *note use_module/2: 4a. directives) from `loading' goals,
     which use an explicit and disciplined approach with `loader' files.

`flags scope'

     The *note set_logtalk_flag/2: 4b. `directive' is always local to
     the entity or source file that contains it.  Only calls to the
     *note set_logtalk_flag/2: 4c. `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: 4d. 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 is different from
     explicitly qualified calls.

`operators scope'

     Operators declared inside an entity (object, protocol, or category)
     are local to the entity.

`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: 4e, *note protected: 4f, *note private: 50, or *note
     local: 51.

`predicate declaration'

     Logtalk provides a clear distinction between *note declaring: 52. a
     predicate and *note defining: 53. a predicate.  This is a
     fundamental requirement for the concept of *note protocol: 54. (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 specially 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.50.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 in 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 same 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 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 in 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 includes 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 implicit in the *note
     ;;/1: 57. 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: 58. `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.50.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: 54, which are often a better way to provide
     the functionality of C++ abstract classes.

`base class'

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

`data member'

     Logtalk uses *note predicates: 5c. 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: 5d, which can be used as a building block to
     define more sophisticated object creation predicates.

`derived class'

     Logtalk uses the term *note subclass: 5e. 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: 5f, 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: 60.

`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: 5c.

`member function'

     Logtalk uses *note predicates: 5c. 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 to
     static members can be declared in a class metaclass.

`template'

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

`this'

     Logtalk uses the built-in context method *note self/1: 62. for
     retrieving the instance that received the message being processed.
     Logtalk also provides a *note this/1: 63. method but for returning
     the class containing the method being executed.  Why the name
     clashes?  Well, the notion of *note self: 64. 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: 33. or *note
     dynamic binding: 34. for locating both method declarations and
     method definitions.  Moreover, methods that are declared but not
     defined simply fail when called (as per *note closed-world
     assumption: 65.).


File: TheLogtalkHandbook-3.50.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: 5c.)
     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: 54. with 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: 65.).

`callback method'

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

`constructor'

     There are no special methods for creating new objects in Logtalk.
     Instead, Logtalk provides a built-in predicate, *note
     create_object/4: 5d, 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: 5c. 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: 69. 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: 6a, a `black box' API
     supporting `behavioral' reflection about *note object protocols:
     6b, and an *note events: 6c. 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: 6d. 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 updated 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: 58, for calling overridden methods.

`synchronized'

     Logtalk supports *note multi-threading programming: 6e. in selected
     Prolog compilers, including a *note synchronized/1: 6f. 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: 62. for
     retrieving the instance that received the message being processed.
     Logtalk also provides a *note this/1: 63. method but for returning
     the class containing the method being executed.  Why the name
     clashes?  Well, the notion of *note self: 64. was inherited from
     Smalltalk, which predates C++.


File: TheLogtalkHandbook-3.50.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 being also 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'

     Predicates 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.50.0.info,  Node: Messages,  Next: Objects,  Prev: Nomenclature,  Up: User Manual

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

Messages allows 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 actually 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: 75. section for details on
the predicate declaration and predicate definition lookup procedures.

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

Logtalk uses nomenclature similar to in 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.50.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.50.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:
7a. 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: 65.).


File: TheLogtalkHandbook-3.50.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' by using the *note []/1: 7d. delegation control
construct:

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

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


File: TheLogtalkHandbook-3.50.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: 57. 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: 65.).


File: TheLogtalkHandbook-3.50.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 method 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.  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.50.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: 58. 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: 33, this control construct allows imported and
inherited predicates to be called with the same performance of 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: 65.).


File: TheLogtalkHandbook-3.50.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: 85. flag is set to ‘allow’ for the object (or
category) sending a message using the *note ;;/2: 7a. control construct,
two events are generated, one before and one after the message
execution.  Messages that are sent using the *note ;;/1: 57. (message to
`self') control construct or the *note ^^/1: 58. 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, 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: 68. section for more details).


File: TheLogtalkHandbook-3.50.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 object from within a Prolog module.  Depending
on the backend Prolog system and on the *note optimize: 88. 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.

     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.50.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: 36. section.


File: TheLogtalkHandbook-3.50.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 in 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 in runtime::
* Abolishing an existing object::
* Object directives::
* Object relationships::
* Object properties::
* Built-in objects::

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

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

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


File: TheLogtalkHandbook-3.50.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
other object plays the role of an `instance', while the instantiated
object plays the role of a `class'; an object with a `specialization'
relation with other object plays the role of a `subclass', while the
specialized object plays the role of a `superclass'; an object with an
`extension' relation with other 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 accordingly 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.50.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.50.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 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.


File: TheLogtalkHandbook-3.50.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: 32, 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: 96. and *note
end_object/0: 97.  The most simple 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]: 98, *note [Moura94]: 99.  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
     % predicates common to all objects

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


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

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


     % default metaclass for all abstract classes
     % 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 problems.

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: 9a. section for details.


File: TheLogtalkHandbook-3.50.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, the
`object parameters', can be instantiated when sending or as a
consequence of sending a message to the object, thus acting as object
parameters.  The object predicates can then 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.

In order to give access to an object parameter, Logtalk provides a *note
parameter/2: 9c. built-in local method:

     :- 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: 63.  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: 7a,
*note ;;/1: 57, or *note ^^/1: 58.).

A third alternative to access object parameters is to use *note
parameter variables: 9d.  Although parameter variables introduce a
concept of entity global variables, their unique syntax,
‘_ParameterName_’, avoids conflicts and makes them easily recognizable.
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.

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.

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.  Logtalk provides a convenient notation for accessing
proxies represented as Prolog facts when sending a message:

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

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 retrieving 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.50.0.info,  Node: Finding defined objects,  Next: Creating a new object in 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: a0. built-in predicate with a 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.50.0.info,  Node: Creating a new object in runtime,  Next: Abolishing an existing object,  Prev: Finding defined objects,  Up: Objects

1.5.5 Creating a new object in runtime
--------------------------------------

An object can be dynamically created at runtime by using the *note
create_object/4: 5d. 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 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.50.0.info,  Node: Abolishing an existing object,  Next: Object directives,  Prev: Creating a new object in runtime,  Up: Objects

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

Dynamic objects can be abolished using the *note abolish_object/1: 5f.
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.50.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, to document an object dependencies on other Logtalk
entities, and to 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.50.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: 40. 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.50.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: ab. 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.50.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: ae. entity directive.  See the *note
Documenting: af. section for details.


File: TheLogtalkHandbook-3.50.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: b2. 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.50.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: b5. 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.50.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 possible relationships that an object may have with
other entities.

The *note instantiates_class/2-3: b8. 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: b9. 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 with the *note
extends_object/2-3: ba. 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: bb. 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: bc. and *note conforms_to_protocol/2-3: bd.
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 a unbound first argument, we will need to use the
*note current_object/1: a0. 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: be. 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.50.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: c1.:

     | ?- 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: 5f. 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)

‘context_switching_calls’

     The object supports context switching calls (i.e.  can be used with
     the *note <</2: c2. 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: c3. for a predicate declared by the
     object

‘defines(Predicate, Properties)’

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

‘includes(Predicate, Entity, Properties)’

     List of *note properties: c3. for an object multifile predicate
     that are defined in the specified entity (the properties include
     ‘number_of_clauses(Number)’, ‘number_of_rules(Number)’, and
     ‘line_count(Line)’ with ‘Line’ being the begin line of the first
     multifile predicate clause)

‘provides(Predicate, Entity, Properties)’

     List of *note properties: c3. for other entity multifile predicate
     that are defined in the object (the properties include
     ‘number_of_clauses(Number)’, ‘number_of_rules(Number)’, and
     ‘line_count(Line)’ with ‘Line’ being the begin line of the first
     multifile predicate clause)

‘alias(Predicate, Properties)’

     List of *note properties: c3. for a *note predicate alias: c4.
     declared by the object (the properties include ‘for(Original)’,
     ‘from(Entity)’, ‘non_terminal(NonTerminal)’, and ‘line_count(Line)’
     with ‘Line’ being the begin line of the alias directive)

‘calls(Call, Properties)’

     List of *note properties: c3. 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 know at runtime; the
     properties include ‘caller(Caller)’, ‘alias(Alias)’, and
     ‘line_count(Line)’ with both ‘Caller’ and ‘Alias’ being predicate
     indicators and ‘Line’ being the begin line of the predicate clause
     or directive making the call)

‘updates(Predicate, Properties)’

     List of *note properties: c3. 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)’, and ‘line_count(Line)’ with
     ‘Updater’ being a (possibly multifile) predicate indicator, ‘Alias’
     being a predicate indicator, and ‘Line’ being the begin line 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:
     c5. 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:
     c5. 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: c6.
flag turned on.  Moreover, line numbers are only supported in *note
backend Prolog compilers: 32. 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.50.0.info,  Node: Built-in objects,  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.50.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: 85. flag is set to
‘allow’.  Defining complementing categories for this pseudo-object is
not supported.

With some of the *note backend Prolog compilers: 32. 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) ../../docs/user_0.html#user-0


File: TheLogtalkHandbook-3.50.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: cd.
predicates, *note question asking: ce. predicates, *note debug and trace
event: cf. 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) ../../docs/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.50.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
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 in runtime::
* Abolishing an existing protocol::
* Protocol directives::
* Protocol relationships::
* Protocol properties::
* Implementing protocols::
* Built-in protocols::

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

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

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

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


File: TheLogtalkHandbook-3.50.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: d5. and *note end_protocol/0: d6.  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.50.0.info,  Node: Finding defined protocols,  Next: Creating a new protocol in 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: d9. 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.50.0.info,  Node: Creating a new protocol in runtime,  Next: Abolishing an existing protocol,  Prev: Finding defined protocols,  Up: Protocols

1.6.3 Creating a new protocol in runtime
----------------------------------------

We can create a new (dynamic) protocol at runtime by calling the Logtalk
built-in predicate *note create_protocol/3: dc.:

     | ?- 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 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.50.0.info,  Node: Abolishing an existing protocol,  Next: Protocol directives,  Prev: Creating a new protocol in runtime,  Up: Protocols

1.6.4 Abolishing an existing protocol
-------------------------------------

Dynamic protocols can be abolished using the *note abolish_protocol/1:
df. 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.50.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.50.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: ab.
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.50.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: ae. entity directive.  See the *note
Documenting: af. section for details.


File: TheLogtalkHandbook-3.50.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: b2. directive can be used to load the contents of a
file into a protocol.  See the *note Objects: 8d. section for an example
of using this directive.


File: TheLogtalkHandbook-3.50.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 possible relationships that a protocol have with
other entities.

The *note extends_protocol/2-3: e9. 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: bc. 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: a0. or *note
current_category/1: ea. built-in predicates to identify the kind of
entity returned.


File: TheLogtalkHandbook-3.50.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: ed. 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: df. built-in predicate.  Depending on the *note
backend Prolog compiler: 32, 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: ee. 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)

‘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: c3. for a predicate declared by the
     protocol

‘alias(Predicate, Properties)’

     List of *note properties: c3. for a *note predicate alias: c4.
     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: c6. flag turned on.


File: TheLogtalkHandbook-3.50.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 applies to protocols implemented by categories.


File: TheLogtalkHandbook-3.50.0.info,  Node: Built-in protocols,  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.50.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:
f5. and *note goal_expansion/2: f6. predicates.  See the description of
the *note hook: f7. compiler flag for more details.

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

   (1) ../../docs/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.50.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: fa. and
*note after/3: fb. public event handler predicates.  See the *note
Event-driven programming: 68. section for more details.

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

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


File: TheLogtalkHandbook-3.50.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: fe.
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: 7d. control construct.

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

   (1) ../../docs/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.50.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
in 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]: 1a,
Flavors mix-ins *note [Moon86]: 102. (without necessarily implying
multi-inheritance), and Objective-C categories *note [Cox86]: 1b.
Categories may also `complement' existing objects, thus providing a
*note hot patching: 103. 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 in runtime::
* Abolishing an existing category::
* Category directives::
* Category relationships::
* Category properties::
* Importing categories::
* Calling category predicates::
* Parametric categories::
* Built-in categories::

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

   (1) ../../docs/core_messages_0.html#core-messages-0


File: TheLogtalkHandbook-3.50.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: 32, 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: 106. and *note
end_category/0: 107.  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: 58. 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).  However, categories may contain declarations
for dynamic predicates and they can contain predicates which 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, 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.50.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: 103. 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:
c4. 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: 10a. 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
overriden definition in the object from the new definition in the
category by annoting the goal with the `experimental' ‘@’ prefix
operator.  This goal annotation is only valid in the context of a
complementing category and for compile time bound goals.  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 ‘@’ goal annotation to e.g.  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: 10b. 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: 33. 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: 32. level for replacing static predicate definitions.


File: TheLogtalkHandbook-3.50.0.info,  Node: Finding defined categories,  Next: Creating a new category in 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: ea. built-in predicate with a 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.50.0.info,  Node: Creating a new category in runtime,  Next: Abolishing an existing category,  Prev: Finding defined categories,  Up: Categories

1.7.4 Creating a new category in runtime
----------------------------------------

A category can be dynamically created at runtime by using the *note
create_category/4: 110. 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 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.50.0.info,  Node: Abolishing an existing category,  Next: Category directives,  Prev: Creating a new category in runtime,  Up: Categories

1.7.5 Abolishing an existing category
-------------------------------------

Dynamic categories can be abolished using the *note abolish_category/1:
ee. 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.50.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, to document
a category dependencies on other Logtalk entities, and to 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.50.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: ab.
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.50.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: ae. entity directive.  See the *note
Documenting: af. section for details.


File: TheLogtalkHandbook-3.50.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: b2. directive can be used to load the contents of a
file into a category.  See the *note Objects: 8d. section for an example
of using this directive.


File: TheLogtalkHandbook-3.50.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: b5. directive can be used to declare object aliases.
The typical uses of this directive is 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.50.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 possible relationships that a category can have
with other entities.

The built-in predicates *note implements_protocol/2-3: bc. and *note
conforms_to_protocol/2-3: bd. allows us to find which categories
implements 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 a unbound first argument, we will need to use the
*note current_category/1: ea. 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: bb. 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: 11f. 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: be. built-in predicate:

     | ?- complements_object(Category, Object).

Note that a category may explicitly complement several objects.


File: TheLogtalkHandbook-3.50.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: 122.:

     | ?- 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: ee. 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)

‘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: c3. for a predicate declared by the
     category

‘defines(Predicate, Properties)’

     List of *note properties: c3. for a predicate defined by the
     category

‘includes(Predicate, Entity, Properties)’

     List of *note properties: c3. for an object multifile predicate
     that are defined in the specified entity (the properties include
     ‘number_of_clauses(Number)’, ‘number_of_rules(Number)’, and
     ‘line_count(Line)’ with ‘Line’ being the begin line of the first
     multifile predicate clause)

‘provides(Predicate, Entity, Properties)’

     List of *note properties: c3. for other entity multifile predicate
     that are defined in the category (the properties include
     ‘number_of_clauses(Number)’, ‘number_of_rules(Number)’, and
     ‘line_count(Line)’ with ‘Line’ being the begin line of the first
     multifile predicate clause)

‘alias(Predicate, Properties)’

     List of *note properties: c3. for a *note predicate alias: c4.
     declared by the category (the properties include ‘for(Original)’,
     ‘from(Entity)’, ‘non_terminal(NonTerminal)’, and ‘line_count(Line)’
     with ‘Line’ being the begin line of the alias directive)

‘calls(Call, Properties)’

     List of *note properties: c3. 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)’, and
     ‘line_count(Line)’ with both ‘Caller’ and ‘Alias’ being predicate
     indicators and ‘Line’ being the begin line of the predicate clause
     or directive making the call)

‘updates(Predicate, Properties)’

     List of *note properties: c3. 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)’, and ‘line_count(Line)’ with
     ‘Updater’ being a (possibly multifile) predicate indicator, ‘Alias’
     being a predicate indicator, and ‘Line’ being the begin line 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: c5. 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: c5. 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: c6. flag turned on.  Moreover, line numbers are only
supported in *note backend Prolog compilers: 32. 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.50.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.50.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: 58. 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: 88. flag is turned on, the Logtalk
compiler will try to optimize the calls by using *note static binding:
33.  When *note dynamic binding: 34. 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: 64. (in
both cases a predicate lookup caching mechanism is used).


File: TheLogtalkHandbook-3.50.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:
9c. or *note this/1: 63. built-in local methods in the category
predicate clauses or by using *note parameter variables: 9d.  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: 63. built-in local
method from category predicates always access the importing object
identifier (and thus object parameters, not category parameters).


File: TheLogtalkHandbook-3.50.0.info,  Node: Built-in categories,  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.50.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) ../../docs/core_messages_0.html#core-messages-0


File: TheLogtalkHandbook-3.50.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 allows 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.50.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-protocols.
They are: *note goal_expansion/2: f6. and *note term_expansion/2: f5,
declared in the expanding(1) protocol; *note before/3: fa. and *note
after/3: fb, declared in the monitoring(2) protocol; and *note
forward/1: fe, 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) ../../docs/expanding_0.html#expanding-0

   (2) ../../docs/monitoring_0.html#monitoring-0

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


File: TheLogtalkHandbook-3.50.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: 65.
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: d2.: 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.50.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: 136. and *note predicate_property/2: 137.)
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:
138, *note protected/1: 139, and *note private/1: 13a.  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 breaking when e.g.  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 ‘lgtunit’ 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.50.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 by using the *note mode/2: 13d. 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 *note [ISO95]: 2f.).
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 returned term with the given term).

‘?’

     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.

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

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

‘one’

     Predicate always succeeds once.

‘zero_or_one’

     Predicate either fails or succeeds.

‘zero_or_more’

     Predicate has zero or more proofs.

‘one_or_more’

     Predicate has one or more proofs.

‘one_or_error’

     Predicate either succeeds once or throws an error (see below).

‘error’

     Predicate will throw an error.

Mode declarations can also be used to document that some call modes will
throw an error.  For instance, regarding the ‘arg/3’ and ‘open/3’ ISO
Prolog built-in predicates, we may write:

     :- mode(arg(-, -, +), error).
     :- mode(open(@, @, --), one_or_error).

Note that most predicates have more than one valid mode implying several
mode directives.  For example, to document the possible use modes of the
‘atom_concat/3’ ISO built-in predicate we would write:

     :- mode(atom_concat(?atom, ?atom, +atom), one_or_more).
     :- mode(atom_concat(+atom, +atom, -atom), zero_or_one).

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: 46. (assuming the *note
source_data: c6. flag is turned on).  In any case, the use of mode
directives is a good starting point for documenting your predicates.


File: TheLogtalkHandbook-3.50.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 or
interpreted as *note closures: 13f. that will be used for constructing
goals.  To ensure that these goals will be executed in the correct
context (i.e.  in the *note calling context: 140, not in the
meta-predicate *note definition context: 141.) we need to use the *note
meta_predicate/1: 142. 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: 143. 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 has first introduced on Quintus Prolog for providing
information for predicate cross-reference tools.

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.50.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: 146. 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 compilers.

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


File: TheLogtalkHandbook-3.50.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 object
predicates are static.  To declare a dynamic predicate we use the *note
dynamic/1: 149. directive:

     :- dynamic(foo/1).

This directive may also be used to declare dynamic grammar rule
non-terminals.  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 other object or imported from a category).
If we omit the dynamic declaration then the predicate definition will be
compiled static.  In the case of dynamic objects, static predicates
cannot be redefined using the database built-in methods (despite being
internally compiled to dynamic code).

Dynamic predicates can be used to represent persistent mutable object
state.  Note that static objects may declare and define dynamic
predicates.


File: TheLogtalkHandbook-3.50.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: 14c. 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: 14d. 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.50.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: 48, 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: c4. 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.  It’s also possible to define predicate aliases that are also
*note predicate shorthands: 150.  See the directive documentation for
details and 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) which 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:
9d. when using the directive in a parametric object or a parametric
category.  In this case, *note dynamic binding: 34. 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.


File: TheLogtalkHandbook-3.50.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: 153. 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 as connector.

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, 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 which is masked out by the Logtalk lookup algorithm (see
the *note Inheritance: 75. 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 which 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 which 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.50.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: 156. directive:

     :- info(Name/Arity, List).

The second argument is a list of ‘Key is Value’ terms.  See the *note
Documenting: af. section for details.


File: TheLogtalkHandbook-3.50.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 `multifile' by using the *note multifile/1:
159. 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: 15a.
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 depend 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 for 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 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 own database
instead of the database of the entity holding the multifile predicate
primary declaration.


File: TheLogtalkHandbook-3.50.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 `coinductive' by using the *note
coinductive/1: 15d. directive.  For example:

     :- coinductive(comember/2).

Logtalk support for coinductive predicates is experimental and requires
a *note backend Prolog compiler: 32. with minimal support for cyclic
terms.  The value of the read-only *note coinduction flag: 15e. is set
to ‘supported’ for the backend Prolog compilers providing that support.


File: TheLogtalkHandbook-3.50.0.info,  Node: Synchronized directive,  Prev: Coinductive directive,  Up: Declaring predicates

1.8.2.12 Synchronized directive
...............................

A predicate can be declared `synchronized' by using the *note
synchronized/1: 6f. directive.  For example:

     :- synchronized(write_log_entry/2).
     :- synchronized([produce/1, consume/1]).

See the section on *note synchronized predicates: 161. for details.


File: TheLogtalkHandbook-3.50.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.50.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 be 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).
         :- public(member/2).

         append([], L, L).
         append([H| T], L, [H| T2]) :-
             append(T, L, T2).

         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 enables easy conversion from Prolog code to Logtalk
objects: we just need to add the necessary encapsulation and scope
directives to the old code.


File: TheLogtalkHandbook-3.50.0.info,  Node: Category predicates,  Next: Meta-predicates,  Prev: Object predicates,  Up: Defining predicates

1.8.3.2 Category predicates
...........................

Because a category can be imported by multiple objects, dynamic private
predicates must be called either in the context of *note self: 64, using
the *note message to self: 168. control structure, *note ;;/1: 57, or in
the context of *note this: 169. (i.e.  in the context of the object
importing the category).  For example, if we want to define a category
implementing variables using destructive assignment where the variable
values are stored in `self' we could write:

     :- category(variable).

         :- public(get/2).
         :- public(set/2).

         :- private(value_/2).
         :- dynamic(value_/2).

         get(Var, Value) :-
             ::value_(Var, Value).

         set(Var, Value) :-
             ::retractall(value_(Var, _)),
             ::asserta(value_(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.  The alternative, storing the variable values in `this',
such that each object importing the category will have its own
definition for the ‘value_/2’ private predicate is simple: just omit the
use of the ‘::/1’ control construct in the code above.

A category can only contain clauses for static predicates.
Nevertheless, as the example above illustrates, there are no
restrictions in declaring and calling dynamic predicates from inside a
category.


File: TheLogtalkHandbook-3.50.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: 142. directive as described earlier on 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: 16c. 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 argument will
be called as-is.

Some meta-predicates have meta-arguments which are not goals but *note
closures: 13f.  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: 16d. 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: 16e, or a
control construct.

In some cases, 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 definiton to be a
non-variable term and instructs the compiler to look into the argument
sub-terms for goal and closure meta-variables.


File: TheLogtalkHandbook-3.50.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: 13f. 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.

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.  For example, using
GNU Prolog as the backend compiler, we can write:

     | ?- 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’ 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 the
*note language grammar: 171.

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 expression should be
regarded as a programming error.  The compiler also checks 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: 172. flag.  Note, however,
that the dynamic features of the language and lack of sufficient
information at compile time may prevent the compiler of checking all
uses of lambda expressions.

     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: c5, is provided as a standard
library for practical performance.

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

   (1) https://en.wikipedia.org/wiki/Lambda_calculus


File: TheLogtalkHandbook-3.50.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: 175. 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: 176. 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 list length predicate, ‘length/2’.  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(length(_, _), built_in)).

         length(List, Length) :-
             {length(List, Length)}.

     :- else.

         length(List, Length) :-
             ...

     :- endif.

I.e.  the object will use the built-in predicate when available.
Otherwise, it will use the object provided predicate definition.

The redefinition of built-in predicates can also be accomplished using
*note predicate shorthands: 150.  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: 177. 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.50.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 provide a convenient notation to represent
the 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 mean time, 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.

The predicate *note phrase/2: 17a. called in the definition of predicate
‘parse/2’ above is a Logtalk built-in method, similar to the predicate
with the same name found on most Prolog compilers that support definite
clause grammars.  After compiling and loading this object, we can test
the grammar rules with calls such as the following one:

     | ?- calculator::parse("1+2-3*4", Result).

     Result = -9
     yes

In most cases, the predicates resulting from the translation of the
grammar rules to regular clauses are not declared.  Instead, these
predicates are usually called by using the built-in methods *note
phrase/2: 17a. and *note phrase/3: 17b. 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 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 ‘\+/1’, ‘!/0’, ‘;/2’,
‘->/2’, and ‘{}/1’ in the body of a grammar.  When using a backend
Prolog compiler that supports modules, we may also use the ‘`:/2’
control construct.  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/3’.

You may have noticed that Logtalk defines *note {}/1: 17c. 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.

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: 156. directive,
as in the following example:

     :- public(sentence//0).

     :- info(sentence//0, [
         comment is 'Rewrites sentence into noun and verb phrases.']).


File: TheLogtalkHandbook-3.50.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 not be redefined.

* Menu:

* 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.50.0.info,  Node: Execution context methods,  Next: Error handling and throwing methods,  Up: Built-in methods

1.8.5.1 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: 62. method.  We may also retrieve the object that has
sent the message under execution using the *note sender/1: 181. method.

The method *note this/1: 63. 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 do 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: 9c.
enables us to retrieve current parameter values (see the section on
*note parametric objects: 61. 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: 9d.:

     :- 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: 182. 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.50.0.info,  Node: Error handling and throwing methods,  Next: Database methods,  Prev: Execution context methods,  Up: Built-in methods

1.8.5.2 Error handling and throwing methods
...........................................

Besides the *note catch/3: 185. and *note throw/1: 186. methods
inherited from Prolog, Logtalk also provides a set of convenience
methods to throw standard ‘error/2’ exception terms: *note
instantiation_error/0: 187, *note uninstantiation_error/1: 188, *note
type_error/2: 189, *note domain_error/2: 18a, *note existence_error/2:
18b, *note permission_error/3: 18c, *note representation_error/1: 18d,
*note evaluation_error/1: 18e, *note resource_error/1: 18f, *note
syntax_error/1: 190, and *note system_error/0: 191.


File: TheLogtalkHandbook-3.50.0.info,  Node: Database methods,  Next: Meta-call methods,  Prev: Error handling and throwing methods,  Up: Built-in methods

1.8.5.3 Database methods
........................

Logtalk provides a set of built-in methods for *note object database:
194. handling similar to the usual database Prolog predicates: *note
abolish/1: 195, *note asserta/1: 196, *note assertz/1: 197, *note
clause/2: 198, *note retract/1: 199, and *note retractall/1: 19a.  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: 48. or *note use_module/2: 4a. 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: 19b. convert a grammar rule into a
clause that can then be used with the database methods.


File: TheLogtalkHandbook-3.50.0.info,  Node: Meta-call methods,  Next: All solutions methods,  Prev: Database methods,  Up: Built-in methods

1.8.5.4 Meta-call methods
.........................

Logtalk supports the generalized *note call/1-N: 16d. meta-predicate.
This built-in private meta-predicate must be used in the implementation
of meta-predicates which work with *note closures: 13f. instead of
goals.  In addition, Logtalk supports the built-in private
meta-predicates *note ignore/1: 16c, *note once/1: 19e, and *note \\+/1:
19f.  These methods cannot be used as messages to objects.


File: TheLogtalkHandbook-3.50.0.info,  Node: All solutions methods,  Next: Reflection methods,  Prev: Meta-call methods,  Up: Built-in methods

1.8.5.5 All solutions methods
.............................

The usual all solutions meta-predicates are built-in private methods in
Logtalk: *note bagof/3: 1a2, *note findall/3: 1a3, *note findall/4: 1a4,
and *note setof/3: 1a5.  There is also a *note forall/2: 1a6. method
that implements generate-and-test loops.  These methods cannot be used
as messages to objects.


File: TheLogtalkHandbook-3.50.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.6 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: c6. flag turned on.

The *note reflection API: 46. 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: 14d,
which returns operator specifications, *note predicate_property/2: 137,
which returns predicate properties, and *note current_predicate/1: 136,
which enables us to query about user-defined predicate definitions.  See
below for a more detailed description of these methods.


File: TheLogtalkHandbook-3.50.0.info,  Node: Definite clause grammar parsing methods and non-terminals,  Prev: Reflection methods,  Up: Built-in methods

1.8.5.7 Definite clause grammar parsing methods and non-terminals
.................................................................

Logtalk supports two definite clause grammar parsing built-in private
methods, *note phrase/2: 17a. and *note phrase/3: 17b, 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: 1ab, *note call//1-N: 1ac, and
*note eos//0: 1ad. built-in non-terminals.  The ‘call//1-N’
non-terminals takes a *note closure: 13f. (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.50.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: 137. 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 have 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: 65.)

‘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: c6. flag turned on:

‘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:
     c5.

‘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: c4. 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: c6. flag turned on.  Moreover, line numbers are only
supported in *note backend Prolog compilers: 32. 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.50.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: 136. 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.50.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
rising 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 user-defined plain predicates::
* Calling Prolog module predicates::
* Calling Prolog module meta-predicates::


File: TheLogtalkHandbook-3.50.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: 1b4. to
generate warnings for calls to non-standard predicates and arithmetic
functions.  We can also help document those calls using the *note
uses/2: 48. 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.50.0.info,  Node: Calling Prolog non-standard built-in meta-predicates,  Next: Calling Prolog user-defined plain 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 all 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.50.0.info,  Node: Calling Prolog user-defined plain predicates,  Next: Calling Prolog module predicates,  Prev: Calling Prolog non-standard built-in meta-predicates,  Up: Calling Prolog predicates

1.8.8.3 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: 48. 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: 17c. compiler bypass control construct.  For example:

     foo :-
         ...,
         {bar},
         ...

But note that in this case the *note reflection API: 46. 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.50.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.4 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 in alternative the *note use_module/2: 4a. 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: 1bb.  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
     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:
9d. 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.


File: TheLogtalkHandbook-3.50.0.info,  Node: Calling Prolog module meta-predicates,  Prev: Calling Prolog module predicates,  Up: Calling Prolog predicates

1.8.8.5 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.  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: 17c. 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.50.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.50.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: 4a. 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: 48. 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
know at compile time.  If that is not the case, you must use instead
either an explicitly-qualified argument or the *note {}/1: 17c. control
construct.  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.50.0.info,  Node: Inheritance,  Next: Event-driven programming,  Prev: Predicates,  Up: User Manual

1.9 Inheritance
===============

The inheritance mechanisms found on 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.

Logtalk uses a depth-first search procedure for finding predicate
declarations and predicate definitions, as explained below.  The search
procedures locate the entities holding the *note predicate declaration:
52. and the *note predicate definition: 53. using the predicate name and
arity.  The *note alias/2: 153. 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 search procedure).

The search procedures are used when sending a message (using the *note
;;/2: 7a, *note ;;/1: 57, and *note []/1: 7d. control constructs) and
when making `super' calls (using the *note ^^/1: 58. control construct).
The exact details of the search procedures depend on the role played by
the object receiving the message or making the `super' call, as
explained next.  The search procedures are also used by the *note
current_predicate/1: 136. and *note predicate_property/2: 137.
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.50.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: 1c5.).  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:

* Search order for prototype hierarchies::
* Search order for class hierarchies::


File: TheLogtalkHandbook-3.50.0.info,  Node: Search order for prototype hierarchies,  Next: Search order for class hierarchies,  Up: Protocol inheritance

1.9.1.1 Search order for prototype hierarchies
..............................................

The search 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 last the objects that the object extends.  This search
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.50.0.info,  Node: Search order for class hierarchies,  Prev: Search order for prototype hierarchies,  Up: Protocol inheritance

1.9.1.2 Search order for class hierarchies
..........................................

The search order for predicate declarations starts in the object
classes.  Following the classes declaration order, the search starts in
the classes implemented protocols (and the protocols that these may
extend), second the classes imported categories (and the protocols that
they may implement), and last the superclasses of the object classes.
This search 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.50.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:

* Search order for prototype hierarchies: Search order for prototype hierarchies<2>.
* Search order for class hierarchies: Search 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.50.0.info,  Node: Search order for prototype hierarchies<2>,  Next: Search order for class hierarchies<2>,  Up: Implementation inheritance

1.9.2.1 Search order for prototype hierarchies
..............................................

The search order for predicate definitions is similar to the search for
predicate declarations except that implemented protocols are ignored (as
they can only contain predicate directives).


File: TheLogtalkHandbook-3.50.0.info,  Node: Search order for class hierarchies<2>,  Next: Redefining inherited predicate definitions,  Prev: Search order for prototype hierarchies<2>,  Up: Implementation inheritance

1.9.2.2 Search order for class hierarchies
..........................................

The search order for predicate definitions is similar to the search for
predicate declarations except that implemented protocols are ignored (as
they can only contain predicate directives) and that the search starts
at the instance itself (that received the message) before proceeding, if
no predicate definition is found there, to the instance classes and then
to the class superclasses.


File: TheLogtalkHandbook-3.50.0.info,  Node: Redefining inherited predicate definitions,  Next: Specializing inherited predicate definitions,  Prev: Search 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.50.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: 58. `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.50.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: 58. `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.50.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
......................................................

The 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:
58. `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.50.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: 4e. declared via implemented
protocols, imported categories, or ancestor objects *note protected
predicates: 4f. or to make all public and protected predicates *note
private predicates: 50. 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 are not
used.


File: TheLogtalkHandbook-3.50.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 multi-inheritance by enabling an object to extend,
instantiate, or specialize more than one object.  Likewise, a protocol
may extends multiple protocols and a category may extend multiple
categories.  In this case, the depth-first search 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 search will look first into the parent object ‘bar’ and its related
entities before looking into the parent object ‘baz’.  The *note
alias/2: 153. predicate directive can always be used to solve
multi-inheritance conflicts.  It should also be noted that the
multi-inheritance support does not affect performance when we use
single-inheritance.


File: TheLogtalkHandbook-3.50.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.

Until now, 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 like *note [McCabe92]: 26. or *note [Moss94]: 1dd. and
to the sophisticated algorithms of CLOS *note [Bobrow_et_al_88]: 1de,
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]: 1df.  Multiple
inheritance is best used as an analysis and project abstraction, rather
than as an implementation technique *note [Shan_et_al_93]: 1e0.  Note
that Logtalk provides first-class support for composition using *note
categories: 101.


File: TheLogtalkHandbook-3.50.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]: 99. 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]: 1e3, *note [Moon86]: 102, operative
systems *note [Tanenbaum87]: 1e4, 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: 85.
     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.50.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.50.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 a more precise control over a system
dynamic behavior.  In Logtalk, these two types of events have been named
‘before’ and ‘after’, respectively for sending a message and for
returning of 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 to a message sending 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.50.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 the protocol when defining event handlers.

Unlimited number of monitors for each event

     Several monitors can observe the same event because of 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 in 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) ../../docs/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.50.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: 85. 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: 7a. 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: 57. control construct)
or `super' calls (using the *note ^^/1: 58. control construct) don’t
generate events.


File: TheLogtalkHandbook-3.50.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 bypassing the message sending primitives
in order to avoid potential endless loops.  The event handlers consist
in user definitions for the public predicates declared in the built-in
monitoring(1) protocol (see below for more details).

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

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


File: TheLogtalkHandbook-3.50.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 events representation 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: 85. 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.50.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 monitors actions consists on considering
its success as a necessary condition so that a message can succeed:

   - All actions associated to events of type ‘before’ must succeed, so
     that the message processing can start.

   - All actions associated to events of type ‘after’ also have to
     succeed so that the message itself succeeds.  The failure of any
     action associated to 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 wish 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.50.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 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 changing 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.50.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.50.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: 1f9. 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.50.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: 1fc. 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.50.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: 1ff. 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.50.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: fa. and *note after/3: fb, 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 describing 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:
85. flag to ‘allow’, we can start tracing every message sent to any
object by calling the *note define_events/5: 1f9. 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: 1fc. 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: f0. 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.

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

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

   (2) ../../docs/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.50.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
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.50.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: 206. compiler flag to ‘supported’.


File: TheLogtalkHandbook-3.50.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: 209. object directive is used to enable an object
to make multi-threading calls:

     :- threaded.


File: TheLogtalkHandbook-3.50.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:
20c. built-in predicate.  The remaining predicates allow for
fine-grained control, including postponing retrieving 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.50.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: 20c.  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 in 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 faster than others.  Some
methods will converge into 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.50.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: 211. 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: 212. 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 allow 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: 213. 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 to 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: 214. 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 on 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 in
alternative *note threaded_call/2: 211, *note threaded_once/2: 213, and
*note threaded_exit/2: 212. 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: 215. predicate.


File: TheLogtalkHandbook-3.50.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: 218.  For example, assume that we are
developing a multi-agent application where an agent may send an “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.50.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: 194.  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: 6f. 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 imply 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 to 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 e.g.  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 make calls to the synchronized
predicates deterministic when the objects are used in a single-threaded
application.


File: TheLogtalkHandbook-3.50.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: 21c. 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: 21d.  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.50.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: 220.
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: 221. 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 by 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: 222, 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: 223. 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: 224. built-in predicate fetches a
task for the engine term queue.  The engine clients would use the *note
threaded_engine_post/2: 225. 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: 226. 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.50.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: 32, on the operating-system, and on
the use of *note dynamic binding: 34. 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 used 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.50.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]: 2f. 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),
         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) ../../docs/logtalk_0.html#logtalk-0-execution-context-7


File: TheLogtalkHandbook-3.50.0.info,  Node: Raising Exceptions,  Next: Type-checking,  Up: Error handling

1.12.1 Raising Exceptions
-------------------------

The *note error handling section: 22d. 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.50.0.info,  Node: Type-checking,  Next: Expected terms,  Prev: Raising Exceptions,  Up: Error handling

1.12.2 Type-checking
--------------------

One of the most common case 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 and 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 want just 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: 33. when compiling with the
*note optimize flag: 88. turned on, thus enabling efficient
type-checking.

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

   (1) ../../docs/type_0.html#type-0

   (2) ../../docs/type_0.html#type-0-valid-2

   (3) ../../docs/type_0.html#type-0-check-2

   (4) ../../docs/type_0.html#type-0-check-3


File: TheLogtalkHandbook-3.50.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: 230. library.  Expected terms allows defering
errors to later stages of an application in alternative to raising an
exception as soon as an error is detected.


File: TheLogtalkHandbook-3.50.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: 32. 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: 232. 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.50.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 misspell entity name or just
an entity that it will be loaded later.  Out-of-oder loading should be
avoided when possible as it prevents some code optimizations such as
*note static binding: 33. of messages to methods.


File: TheLogtalkHandbook-3.50.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 misspell variables and, as
such, one of the most common errors when programming in Prolog.
Assuming that the *note backend Prolog compiler: 32. 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.50.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: 32. 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.50.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.50.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.50.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.50.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.50.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.50.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.50.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.50.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.50.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.50.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.50.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: 57. 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.50.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: 16e. with
unclassified variables (not listed as either *note lambda free: 251. or
*note lambda parameter: 252. 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.50.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: 48. or *note use_module/2:
4a. directive.


File: TheLogtalkHandbook-3.50.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.50.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.50.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 checks the type and mode of the calling
arguments, throwing an exception in case of misuse.


File: TheLogtalkHandbook-3.50.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 checks the type and mode of the calling
arguments, throwing an exception in case of misuse.


File: TheLogtalkHandbook-3.50.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: fe, 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) ../../docs/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.50.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 while behavioral reflection computations over what
an application does while running.  The structural and behavioral
reflection APIs are used by all the *note developer tools: 261, which
are regular applications.

* Menu:

* Structural reflection::
* Behavioral reflection::


File: TheLogtalkHandbook-3.50.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.50.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?'

For entities, built-in predicates are provided for *note enumerating
entities: 265, *note enumerating entity properties: 6a. (including
entity declared, defined, called, and updated predicates), and *note
enumerating entity relations: 266.  For a detailed description of the
supported entity properties, see the sections on *note object
properties: c0, *note protocol properties: ec, and *note category
properties: 120.  For examples of querying entity relations, see the
sections on *note object relations: b7, *note protocol relations: e8,
and *note category relations: 11d.

     Note: Some entity and predicate properties are only available when
     the source files are compiled with the *note source_data: c6. flag
     turned on.

The logtalk(1) built-in object provides predicates for querying loaded
source files and their properties.

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

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


File: TheLogtalkHandbook-3.50.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 allow querying about predicates and
operators that are within scope of the entity calling the reflection
methods.  This is the view we use and 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: 136. and for querying
the *note predicate properties: 137.  It is also possible to enumerate
*note entity operators: 14d.  See the sections on *note finding declared
predicates: 1b1. and on *note predicate properties: 1af. for more
details.


File: TheLogtalkHandbook-3.50.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: 68. for details.  There is also a *note dependents: 26a.
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: cf. provided by the
logtalk(1) built-in object.

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

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


File: TheLogtalkHandbook-3.50.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 a 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 enable us to
use the currently available object-oriented methodologies, tools, and
metrics *note [Champaux92]: 26e. 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 in 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::
* 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.50.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, the scripts should be available from the
command-line; scripts are named upon the used backend Prolog compilers.
On Windows, the shortcuts should be available from the Start Menu.  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’.


File: TheLogtalkHandbook-3.50.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: 273. 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 processes identifier in
the names, thus preventing file names 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
‘lgtunit’ tool).

To run parallel Logtalk processes with the ‘clean’ flag turned off, each
process must use its own *note scratch directory: 274.  This is
accomplished by defining the ‘scratch_directory’ library alias to a per
process location.  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 contains support for selected backends.


File: TheLogtalkHandbook-3.50.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: c5.).  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: 40. 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: b2. 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: 32, 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).

* Menu:

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


File: TheLogtalkHandbook-3.50.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.50.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: 279. directive when running Logtalk with backend Prolog
compilers that support multiple encodings (check the *note
encoding_directive: 27a. flag in the adapter file of your Prolog
compiler).


File: TheLogtalkHandbook-3.50.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: 33, 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 remaining 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: c5. 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: 273. flag description for details).


File: TheLogtalkHandbook-3.50.0.info,  Node: Compiling and loading your applications,  Next: Loader files,  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: 27f. 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: 44. built-in predicate:

     | ?- logtalk_load([source_file1, source_file2, ...]).

This predicate works in the same way of 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: 1bb. 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: 32, you can use the shorthands
‘{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: 280. 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: 281, 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.50.0.info,  Node: Loader files,  Next: Libraries of source files,  Prev: Compiling and loading your applications,  Up: Writing and running applications

1.14.6 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: 4c. (e.g.  for setting global,
`project-specific', flag values) and *note logtalk_load/1: 44. or *note
logtalk_load/2: 284. (for loading project files), wrapped inside a
Prolog ‘initialization/1’ directive for portability.  For instance, if
your code is split in 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 using the same set of compiler flags).
For example:

     :- initialization((
         % set project-specific global flags
         set_logtalk_flag(underscore_variables, dont_care),
         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.

Worth mentioning here a common mistake when first starting working with
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.50.0.info,  Node: Libraries of source files,  Next: Settings files,  Prev: Loader files,  Up: Writing and running applications

1.14.7 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: 287.  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: 47, as discussed below).  This allows us to load library
source files or entire libraries without worrying about libraries paths,
improving code portability.  The directory paths on the second argument
should always end with the path directory separator character.  Most
backend Prolog compilers allows 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: 288. 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.50.0.info,  Node: Settings files,  Next: Compiler linter,  Prev: Libraries of source files,  Up: Writing and running applications

1.14.8 Settings files
---------------------

Although is always possible to edit the *note backend Prolog compiler:
32. 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 on 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: 28b. 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 on 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: 4c. Logtalk built-in predicate and
asserting clauses for the *note logtalk_library_path/2: 287. multifile
dynamic predicate.  Note that the *note set_logtalk_flag/2: 4b.
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: 28c. flag we can
write a single settings file that can be used with several *note backend
Prolog compilers: 32.:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Compiler linter,  Next: Compiler flags,  Prev: Settings files,  Up: Writing and running applications

1.14.9 Compiler linter
----------------------

The compiler includes a *note linter: 28f. 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 are 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: 290.  See the next
section for details.


File: TheLogtalkHandbook-3.50.0.info,  Node: Compiler flags,  Next: Reloading source files,  Prev: Compiler linter,  Up: Writing and running applications

1.14.10 Compiler flags
----------------------

The *note logtalk_load/1: 44. and *note logtalk_compile/1: 27f. 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: 4c.
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: 284. or the *note logtalk_compile/2: 292. 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: 4c. 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: 293. built-in predicate:

     | ?- current_logtalk_flag(unknown_entities, Value).

     Value = silent
     yes

Logtalk also implements a *note set_logtalk_flag/2: 4b. 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.50.0.info,  Node: Read-only flags,  Next: Version flags,  Up: Compiler flags

1.14.10.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: 143.
These are:

‘settings_file’

     Allows or disables loading of a *note settings file: 47. 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: 32. (an atom).
     This flag can be used for *note conditional compilation: 176. of
     Prolog compiler specific code.

‘prolog_version’

     Version of the *note backend Prolog compiler: 32. (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: 32. (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: 32. 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: 32. supports
     the *note encoding/1: 279. 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: 32. provides
     tabling programming support.  Possible flag values are
     ‘unsupported’ and ‘supported’.

‘engines’

     Informs if the *note backend Prolog compiler: 32. provides the
     required low level multi-threading programming support for Logtalk
     *note threaded engines: 29a.  Possible flag values are
     ‘unsupported’ and ‘supported’.

‘threads’

     Informs if the *note backend Prolog compiler: 32. provides the
     required low level multi-threading programming support for all
     high-level Logtalk *note multi-threading features: 6e.  Possible
     flag values are ‘unsupported’ and ‘supported’.

‘modules’

     Informs Logtalk if the *note backend Prolog compiler: 32. 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: 32. provides
     the required minimal support for cyclic terms necessary for working
     with *note coinductive predicates: 29c.  Possible flag values are
     ‘unsupported’ and ‘supported’.


File: TheLogtalkHandbook-3.50.0.info,  Node: Version flags,  Next: Lint flags,  Prev: Read-only flags,  Up: Compiler flags

1.14.10.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.50.0.info,  Node: Lint flags,  Next: Optional features compilation flags,  Prev: Version flags,  Up: Compiler flags

1.14.10.3 Lint flags
....................

‘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 calls to unknown predicates (or
     non-terminals) are found.  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: 2a4.
     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 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).

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

‘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’ and ‘singletons’ (the usual
     default).  Note that, depending on your Prolog compiler, the
     ‘read_term/3’ built-in predicate may report variables that start
     with an underscore as singleton variables.  There is no standard
     behavior, hence this option.

‘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 on 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’.

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Optional features compilation flags,  Next: Backend Prolog compiler and loader flags,  Prev: Lint flags,  Up: Compiler flags

1.14.10.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: 196. or *note assertz/1: 197. 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: 68. 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 does 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 vale is ‘allow’.  Note that changing this option is of
     no consequence for objects already compiled and loaded.


File: TheLogtalkHandbook-3.50.0.info,  Node: Backend Prolog compiler and loader flags,  Next: Other flags,  Prev: Optional features compilation flags,  Up: Compiler flags

1.14.10.5 Backend Prolog compiler and loader flags
..................................................

‘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: 2b7. 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.50.0.info,  Node: Other flags,  Next: User-defined flags,  Prev: Backend Prolog compiler and loader flags,  Up: Compiler flags

1.14.10.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: 288.
     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: 32. adapter file can be overriden by defining the
     ‘scratch_directory’ library alias (see the *note
     logtalk_library_path/2: 287. 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 start
     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: 47.), restart with the *note clean:
     273. 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: 33.
     optimizations invalid for code defining in other loaded files.
     Turning on this flag automatically turns off the *note debug: 2bc.
     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: 46. 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: 88. 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: 2bb,
     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) ../../docs/user_0.html#user-0

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


File: TheLogtalkHandbook-3.50.0.info,  Node: User-defined flags,  Prev: Other flags,  Up: Compiler flags

1.14.10.7 User-defined flags
............................

Logtalk provides a *note create_logtalk_flag/3: 2c0. predicate that can
be used for defining new flags.


File: TheLogtalkHandbook-3.50.0.info,  Node: Reloading source files,  Next: Batch processing,  Prev: Compiler flags,  Up: Writing and running applications

1.14.11 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: 2bd. compiler flag to ‘skip’.  For code under
development, you can turn off the *note clean: 273. flag to avoid
recompiling files that have not been modified since last compilation
(assuming that backend Prolog compiler that you are using supports
retrieving of 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.  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 be not 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.50.0.info,  Node: Batch processing,  Next: Optimizing performance,  Prev: Reloading source files,  Up: Writing and running applications

1.14.12 Batch processing
------------------------

When doing batch processing, you probably want to turn off the *note
report: 2ba. 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.50.0.info,  Node: Optimizing performance,  Next: Portable applications,  Prev: Batch processing,  Up: Writing and running applications

1.14.13 Optimizing performance
------------------------------

The default compiler flag settings are appropriated for the
`development' but not necessarily for the `deployment' of applications.
To minimize the generated code size, turn the *note source_data: c6.
flag off.  To optimize runtime performance, turn on the *note optimize:
88. 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 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: 33. optimizations.  For a clear picture of file dependencies,
use the *note diagrams: 2c7. 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: 197. and *note retract/1: 199.) that
modify the predicate.

Sending a *note message to self: 168. implies *note dynamic binding: 34.
but there are often cases where *note ;;/1: 57. 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: 10b, *note ^^/1: 58,
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: 36. for a detailed discussion on
Logtalk performance.


File: TheLogtalkHandbook-3.50.0.info,  Node: Portable applications,  Next: Conditional compilation,  Prev: Optimizing performance,  Up: Writing and running applications

1.14.14 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: 1b4. compiler flag.


File: TheLogtalkHandbook-3.50.0.info,  Node: Conditional compilation,  Next: Avoiding common errors,  Prev: Portable applications,  Up: Writing and running applications

1.14.15 Conditional compilation
-------------------------------

Logtalk supports conditional compilation within source files using the
*note if/1: 2cc, *note elif/1: 2cd, *note else/0: 2ce, and *note
endif/0: 2cf. 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.50.0.info,  Node: Avoiding common errors,  Next: Coding style guidelines,  Prev: Conditional compilation,  Up: Writing and running applications

1.14.16 Avoiding common errors
------------------------------

Try to write objects and protocol documentation `before' writing any
other code; if you are having trouble documenting a predicate perhaps we
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: 101.).
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 misspell variables in your source code.


File: TheLogtalkHandbook-3.50.0.info,  Node: Coding style guidelines,  Prev: Avoiding common errors,  Up: Writing and running applications

1.14.17 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.  Closed related entities can be defined
in the same source file.  However, for 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.50.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, 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 its 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 disturb 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 switched e.g.  from a command-line interface
to a GUI input dialog or even automate providing the data (e.g.  when
automating testing of 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: 2d6. tool.

* Menu:

* Printing messages::
* Message tokenization::
* Meta-messages::
* Intercepting messages::
* Asking questions::
* Intercepting questions::

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

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


File: TheLogtalkHandbook-3.50.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: 2d8.  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: 2ba.
     flag to ‘warnings’ or ‘off’)

‘help’

     messages printed in reply for the user asking for help (mostly for
     helping port existing Prolog code)

‘information’ and ‘information(Group)’

     messages usually printed in reply to a user 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: 2ba. 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: 2ba. 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:
     2bc. flag is turned on; these messages are suppressed by the
     compiler when the *note optimize: 88. 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.  Here `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: 2d9. 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 have 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.50.0.info,  Node: Message tokenization,  Next: Meta-messages,  Prev: Printing messages,  Up: Printing messages and asking questions

1.15.2 Message tokenization
---------------------------

The advantages of using message terms require a solution for generating
the actual messages text.  This is supported by defining grammar rules
for the *note logtalk;;message_tokens//2: 2db. 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

‘flush’

     Flush the output stream (by calling the ‘flush_output/1’ standard
     predicate)

‘nl’

     Change line in the output stream

‘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 stream 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.50.0.info,  Node: Meta-messages,  Next: Intercepting messages,  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 to help developing,
notably debugging messages.  See the *note Debugging messages: 2dd.
section and the logtalk built-in object(1) remarks section for details.

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

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Intercepting messages,  Next: Asking questions,  Prev: Meta-messages,  Up: Printing messages and asking questions

1.15.4 Intercepting messages
----------------------------

Calls to the *note logtalk;;print_message/3: 2d8. predicate can be
intercepted by defining clauses for the *note logtalk;;message_hook/4:
2df. 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 have 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.

This example calls the *note logtalk;;message_prefix_stream/4: 2e0. hook
predicate, which can be used to define a message line prefix and an
output stream for printing messages for a given component.


File: TheLogtalkHandbook-3.50.0.info,  Node: Asking questions,  Next: Intercepting questions,  Prev: Intercepting messages,  Up: Printing messages and asking questions

1.15.5 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: 2e2, is used for ask a question and read 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: 13f. 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.50.0.info,  Node: Intercepting questions,  Prev: Asking questions,  Up: Printing messages and asking questions

1.15.6 Intercepting questions
-----------------------------

Calls to the *note logtalk;;ask_question/5: 2e2. predicate can be
intercepted by defining clauses for the *note logtalk;;question_hook/6:
2e4. 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 followup 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.50.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 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 simply 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 expansions 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.50.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: f5. and *note goal_expansion/2: f6, 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: 2e8. in the protocol.  This
design decision is key to give the programmer full control of the
expansion process and prevent the problems that inflict most Prolog
system providing 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:
19b. and *note expand_goal/2: 2e9. built-in methods or called
automatically by the compiler when compiling a source file (see the
section below on `hook objects').

Clauses for the ‘term_expansion/2’ predicate are called until of them
succeeds.  The returned expansion can be a single term or a list of
terms.  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 does not resulted 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.

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

   (1) ../../docs/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.50.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: f5. predicate.


File: TheLogtalkHandbook-3.50.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: 17c. 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.50.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 be used to expand a source file.

To compile a source file using a hook object, we can use the *note hook:
f7. compiler flag in the second argument of the *note logtalk_compile/2:
292. and *note logtalk_load/2: 284. built-in predicates.  For example:

     | ?- logtalk_load(source_file, [hook(hook_object)]).
     ...

In alternative, we can use a *note set_logtalk_flag/2: 4b. directive in
the source file itself.  For example:

     :- set_logtalk_flag(hook, hook_object).

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: 4c.
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) ../../docs/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.50.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: 2ee. built-in
predicate that can be used to access the compilation/loading context
when performing expansions.  The *note logtalk: cb. built-in object also
provides a set of predicates that can be useful, notably when adding
Logtalk support for languages 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 ‘initialization/1’ directives, where the goal argument
     is expanded to improve code portability across backends).


File: TheLogtalkHandbook-3.50.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: 27c, 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: 143. (which are used to support non-standard Prolog
features).


File: TheLogtalkHandbook-3.50.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: 2f1. library that supports two basic expansion workflows: a
pipeline(1) of hook objects, where the expansion results from a hook
object are feed 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: 2f2. library that provides convenient hook objects
for defining custom expansion workflows.  This library includes an 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 overriden by the directive.

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

   (1) ../../docs/hook_pipeline_1.html#hook-pipeline-1

   (2) ../../docs/hook_set_1.html#hook-set-1

   (3) ../../docs/backend_adapter_hook_0.html#backend-adapter-hook-0

   (4) ../../docs/identity_hook_0.html#identity-hook-0


File: TheLogtalkHandbook-3.50.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: 32. 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.
Specially 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 in some of the supported backend Prolog
     compilers.

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

   (1) ../../docs/prolog_module_hook_1.html#prolog-module-hook-1


File: TheLogtalkHandbook-3.50.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: 45. as any other object predicates.  Note that expansions can
often be manually tested by sending *note expand_term/2: 19b. and *note
expand_goal/2: 2e9. messages to a hook object with the term or goal
whose expansion you want to check as argument.  Another alternative to
the debugging tools is to use a *note monitor: 2f5. 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: 2f6. 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


File: TheLogtalkHandbook-3.50.0.info,  Node: Documenting,  Next: Debugging,  Prev: Term and goal expansion,  Up: User Manual

1.17 Documenting
================

Assuming that the *note source_data: c6. flag is turned on, the compiler
saves all relevant documenting information collected when compiling a
source file.  The provided *note lgtdoc: 2f9. tool can access this
information by using the *note reflection: 46. 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 the two directives
described in the next section.  The ‘lgtdoc’ tool includes POSIX and
Windows scripts for converting the XML documentation files to several
final formats (such as HTML and PDF).

* Menu:

* Documenting directives::
* Processing and viewing documenting files::
* Inline formatting in comments text::
* Diagrams::


File: TheLogtalkHandbook-3.50.0.info,  Node: Documenting directives,  Next: Processing and viewing documenting files,  Up: Documenting

1.17.1 Documenting directives
-----------------------------

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: 13d. and *note
meta_predicate/1: 142. directives.

* Menu:

* Entity directives::
* Predicate directives::


File: TheLogtalkHandbook-3.50.0.info,  Node: Entity directives,  Next: Predicate directives,  Up: Documenting directives

1.17.1.1 Entity directives
..........................

Arbitrary user-defined entity information can be represented using the
*note info/1: ae. 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).  As a style
     guideline, don’t use overly long comments.  If you need to provide
     additional details, use the ‘remarks’ key.

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

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

‘remarks’

     List of general remarks about the entity using ‘Topic-Text’ pairs
     where both the topic and the text must be atoms.

‘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: 46. and
are visible to the *note lgtdoc: 2f9. tool (which includes them in the
generated documentation).

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

   (1) https://semver.org


File: TheLogtalkHandbook-3.50.0.info,  Node: Predicate directives,  Prev: Entity directives,  Up: Documenting directives

1.17.1.2 Predicate directives
.............................

Arbitrary user-defined predicate information can be represented using
the *note info/2: 156. 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 and 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).  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).

‘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 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 throw 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 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 ‘{yes}’ or ‘{no}’,
     respectively.

‘remarks’

     List of general remarks about the predicate using ‘Topic-Text’
     pairs where both the topic and the text must be atoms.

‘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.'
     ]).

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: 46. and are visible to the *note lgtdoc:
2f9. tool (which includes them in the generated documentation).


File: TheLogtalkHandbook-3.50.0.info,  Node: Processing and viewing documenting files,  Next: Inline formatting in comments text,  Prev: Documenting directives,  Up: Documenting

1.17.2 Processing and viewing documenting files
-----------------------------------------------

The *note lgtdoc: 2f9. 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 style-sheet file.  The XML specification
file can be either a DTD file (‘logtalk_entity.dtd’) or an XML Scheme
file (‘logtalk_entity.xsd’).  The XSLT style-sheet 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 style-sheet
file are defined by the *note lgtdoc: 2f9. 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
style-sheet 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

On Windows operating-systems, the JScript scripts can be used.  For
example, assuming that we want to generate HTML documentation, we could
run in a ‘cmd.exe’ window:

     cd xml_docs
     cscript "%LOGTALKHOME%\tools\lgtdoc\xml\lgt2html.js" /p:saxon

Or simply use the ‘.bat’ script alternatives:

     cd xml_docs
     lgt2html /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 string.  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: 2f9. 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: 302. tool that
allows automating the steps required to generate the documentation for
an application.


File: TheLogtalkHandbook-3.50.0.info,  Node: Inline formatting in comments text,  Next: Diagrams,  Prev: Processing and viewing documenting files,  Up: Documenting

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Diagrams,  Prev: Inline formatting in comments text,  Up: Documenting

1.17.4 Diagrams
---------------

The *note diagrams: 2c7. 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: 46. as the
‘lgtdoc’ tool and thus have access to the same source data.  See the
tool documentation for details.


File: TheLogtalkHandbook-3.50.0.info,  Node: Debugging,  Next: Performance<2>,  Prev: Documenting,  Up: User Manual

1.18 Debugging
==============

The Logtalk distribution includes a command-line *note debugger: 2d6.
tool implemented as a Logtalk application.  It can be loaded by typing:

     | ?- logtalk_load(debugger(loader)).

It can also be loaded automatically at startup time by using a *note
settings file: 47.  This tool implements debugging features similar to
those found on most Prolog systems.  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.
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 implementation of spy points allows
the user to specify the *note execution context: 308. for entering the
debugger.  This feature is a consequence of the encapsulation of
predicates inside objects.

* Menu:

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


File: TheLogtalkHandbook-3.50.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: 2bc. compiler flag.  The default value for this flag, usually
‘off’, is defined in the adapter files.  Its default value may be
changed at runtime by calling:

     | ?- set_logtalk_flag(debug, on).

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: 281. built-in predicate can also be used to
recompile all loaded files (that were compiled without using explicit
values for the *note debug: 2bc. and *note optimize: 88. compiler flags
in a ‘logtalk_load/2’ call or in a *note loader file: 1bb. file, if
used) in debug mode:

     | ?- logtalk_make(debug).

With most *note backend Prolog compilers: 32, 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.

The *note clean: 273. compiler flag should be turned on whenever the
*note debug: 2bc. flag is turned on at runtime.  This is necessary
because debug code would not be generated for files previously compiled
in normal 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: 4b. directive inside the entity.


File: TheLogtalkHandbook-3.50.0.info,  Node: Procedure box model,  Next: Defining spy points,  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 
     ‘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.  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.50.0.info,  Node: Defining spy points,  Next: Tracing program execution,  Prev: Procedure box model,  Up: Debugging

1.18.3 Defining spy points
--------------------------

Logtalk spy points can be defined by simply stating which predicates
should be spied, as in most Prolog debuggers, by stating which predicate
clauses to spy given their source file line numbers, or by specifying
the context for activating a spy point.  In the case of line number spy
points (also known as breakpoints), the line number must correspond to
the first line of an entity clause.  To simplify the definition of line
number spy points, 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).

* Menu:

* Defining line number and predicate spy points::
* Defining context spy points::
* Removing all spy points::


File: TheLogtalkHandbook-3.50.0.info,  Node: Defining line number and predicate spy points,  Next: Defining context spy points,  Up: Defining spy points

1.18.3.1 Defining line number and predicate spy points
......................................................

Line number and predicate spy points are specified using the debugger
‘spy/1’ predicate.  The argument can be a breakpoint (expressed as a
‘Entity-Line’ pair), a predicate indicator (‘Name/Arity’), or a list of
spy points.  For example:

     | ?- debugger::spy(person-42).

     Spy points set.
     yes

     | ?- debugger::spy(foo/2).

     Spy points set.
     yes

     | ?- debugger::spy([foo/4, bar/1]).

     Spy points set.
     yes

Line numbers and predicate spy points can be removed by using the
debugger ‘nospy/1’ predicate.  The argument can be a spy point, a list
of spy points, or a non-instantiated variable in which case all spy
points will be removed.  For example:

     | ?- debugger::nospy(_).

     All matching predicate spy points removed.
     yes


File: TheLogtalkHandbook-3.50.0.info,  Node: Defining context spy points,  Next: Removing all spy points,  Prev: Defining line number and predicate spy points,  Up: Defining spy points

1.18.3.2 Defining context spy points
....................................

A context spy point is a tuple describing a message execution context
and a goal:

     (Sender, This, Self, Goal)

The debugger is evoked whenever the spy point goal and the specified
execution context subsumes the goal currently being executed and its
execution context.  The user may establish any number of context spy
points 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 spy point:

     | ?- debugger::spy(_, foo, _, _).

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

     Spy point set.
     yes

The debugger ‘nospy/4’ predicate may be used to remove all matching spy
points.  For example, the call:

     | ?- debugger::nospy(_, _, foo, _).

     All matching context spy points removed.
     yes

will remove all context spy points where the value of *note self: 64.
matches the atom ‘foo’.


File: TheLogtalkHandbook-3.50.0.info,  Node: Removing all spy points,  Prev: Defining context spy points,  Up: Defining spy points

1.18.3.3 Removing all spy points
................................

We may remove all line number, predicate, and context spy points by
using the debugger ‘nospyall/0’ predicate:

     | ?- debugger::nospyall.

     All line number spy points removed.
     All predicate spy points removed.
     All context spy points removed.
     yes


File: TheLogtalkHandbook-3.50.0.info,  Node: Tracing program execution,  Next: Debugging using spy points,  Prev: Defining spy points,  Up: Debugging

1.18.4 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 examples, 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 allows 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, when tracing, spy points will be ignored.  Before the port
number, when a spy point is set for the current clause or goal, the
debugger will print a ‘#’ character for line number spy points, a ‘+’
character for predicate spy points, and a ‘*’ character for context spy
points.  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 and turning off the debugger, write:

     | ?- debugger::notrace.

     yes


File: TheLogtalkHandbook-3.50.0.info,  Node: Debugging using spy points,  Next: Debugging commands,  Prev: Tracing program execution,  Up: Debugging

1.18.5 Debugging using spy points
---------------------------------

Tracing a program execution may generate large amounts of debugging
data.  Debugging using spy points allows the user to concentrate in
specific points of the code.  To start a debugging session using spy
points, write:

     | ?- debugger::debug.

     yes

For example, assuming the spy point 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 spy points.


File: TheLogtalkHandbook-3.50.0.info,  Node: Debugging commands,  Next: Context-switching calls,  Prev: Debugging using spy points,  Up: Debugging

1.18.6 Debugging commands
-------------------------

The debugger pauses at leashed ports when tracing or when finding a spy
point for user interaction.  The commands available are as follows:

‘c’ — creep

     go on; you may use the spacebar, return, or enter keys in
     alternative

‘l’ — leap

     continues execution until the next spy point is found

‘s’ — skip

     skips debugging for the current goal; valid at call, redo, and
     unification ports

‘q’ — quasi-skip

     skips debugging until returning to the current goal or reaching a
     spy point; 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 port name and continues execution until that port is reached
     reads negated port name 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

‘@’ — 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

‘=’ — debugging

     prints debugging information

‘<’ — write depth

     sets the write term depth (set to ‘0’ to reset)

‘*’ — add

     adds a context spy point for the current goal

‘/’ — remove

     removes a context spy point for the current goal

‘+’ — add

     adds a predicate spy point for the current goal

‘-’ — remove

     removes a predicate spy point for the current goal

‘#’ — add

     adds a line number spy point for the current clause

‘|’ — remove

     removes a line number spy point for the current clause

‘h’ — condensed help

     prints list of command options

‘?’ — extended help

     prints list of command options


File: TheLogtalkHandbook-3.50.0.info,  Node: Context-switching calls,  Next: Debugging messages,  Prev: Debugging commands,  Up: Debugging

1.18.7 Context-switching calls
------------------------------

Logtalk provides a control construct, *note <</2: c2, 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 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: 2b4. compiler flag (its default value is
defined in the adapter files of the backend Prolog compilers).


File: TheLogtalkHandbook-3.50.0.info,  Node: Debugging messages,  Next: Using the term-expansion mechanism for debugging,  Prev: Context-switching calls,  Up: Debugging

1.18.8 Debugging messages
-------------------------

Calls to the *note logtalk;;print_message/3: 2d8. predicate where the
message kind is either ‘debug’ or ‘debug(Group)’ are only printed, by
default, when the *note debug: 2bc. flag is turned on.  Moreover, these
calls are suppressed by the compiler when the *note optimize: 88. 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.50.0.info,  Node: Meta-messages<2>,  Next: Selective printing of debug messages,  Up: Debugging messages

1.18.8.1 Meta-messages
......................

To avoid having to define *note message_tokens//2: 2db. grammar rules
for translating each and every debug message, Logtalk provides default
tokenization for five `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.

Some simple examples of using these meta-messages:

     | ?- logtalk::print_message(debug, core, @'Phase 1 completed').
     yes

     | ?- set_logtalk_flag(debug, on).
     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: 2e0.
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).


File: TheLogtalkHandbook-3.50.0.info,  Node: Selective printing of debug messages,  Prev: Meta-messages<2>,  Up: Debugging messages

1.18.8.2 Selective printing of debug messages
.............................................

By default, all debug messages are either printed or skipped, depending
on the *note debug: 2bc. and *note optimize: 88. flags.  When the code
is not compiled in optimal mode, the *note debug_messages: 31c. tool
allows selectively enabling of debug messages per *note component: 31d.
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.50.0.info,  Node: Using the term-expansion mechanism for debugging,  Next: Ports profiling,  Prev: Debugging messages,  Up: Debugging

1.18.9 Using the term-expansion mechanism for debugging
-------------------------------------------------------

Debugging messages only output information by default.  These messages
can, however, be intercepted to perform other actions.  An alternative
is to use instead the *note term-expansion mechanism: c5. for
conditional compilation of debugging goals.  For example, the *note
hook_objects: 2f2. 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) ../../docs/print_goal_hook_0.html#print-goal-hook-0


File: TheLogtalkHandbook-3.50.0.info,  Node: Ports profiling,  Next: Debug and trace events,  Prev: Using the term-expansion mechanism for debugging,  Up: Debugging

1.18.10 Ports profiling
-----------------------

The Logtalk distribution includes a *note ports_profiler: 322. 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.50.0.info,  Node: Debug and trace events,  Prev: Ports profiling,  Up: Debugging

1.18.11 Debug and trace events
------------------------------

The debugging API defines two multifile predicates,
logtalk::trace_event/2(1) and logtalk::debug_handler/2(2) for handiling
trace and debug events.  It also provides a
logtalk::debug_handler_provider/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 thar 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.

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

   (1) ../../docs/logtalk_0.html#logtalk-0-trace-event-2

   (2) ../../docs/logtalk_0.html#logtalk-0-debug-handler-2

   (3) ../../docs/logtalk_0.html#logtalk-0-debug-handler-provider-1


File: TheLogtalkHandbook-3.50.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 mean that
if you know how to write efficient Prolog predicates, you already know
how to write efficient Logtalk predicates.

The Logtalk compiler appends a hidden execution-context argument to all
entity predicate clauses.  In the common case where a predicate makes no
calls to the execution-context predicates and message-sending control
constructs and is neither a meta-predicate nor a coinductive predicate,
the execution-context argument 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 `self' for a *note ;;/1: 57. 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::
* 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::
* Debug mode overhead::
* Other considerations::


File: TheLogtalkHandbook-3.50.0.info,  Node: Source code compilation modes,  Next: Local predicate calls,  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: 88. and *note debug: 2bc. 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 use of *note
static binding: 33. 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: cf. that enable developer
tools such as the *note command-line debugger: 2d6. and the *note ports
profiler: 322.


File: TheLogtalkHandbook-3.50.0.info,  Node: Local predicate calls,  Next: Calls to imported or inherited predicates,  Prev: Source code compilation modes,  Up: Performance<2>

1.19.2 Local predicate calls
----------------------------

Local calls to object (or category) predicates have zero overhead in
terms of number of inferences, as expected, compared with local Prolog
calls.


File: TheLogtalkHandbook-3.50.0.info,  Node: Calls to imported or inherited predicates,  Next: Calls to module predicates,  Prev: Local predicate calls,  Up: Performance<2>

1.19.3 Calls to imported or inherited predicates
------------------------------------------------

Assuming the *note optimize: 88. flag is turned on and a static
predicate, *note ^^/1: 58. calls have zero overhead in terms of number
of inferences.


File: TheLogtalkHandbook-3.50.0.info,  Node: Calls to module predicates,  Next: Messages<2>,  Prev: Calls to imported or inherited predicates,  Up: Performance<2>

1.19.4 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.50.0.info,  Node: Messages<2>,  Next: Automatic expansion of built-in meta-predicates,  Prev: Calls to module predicates,  Up: Performance<2>

1.19.5 Messages
---------------

Logtalk implements *note static binding: 33. and *note dynamic binding:
34. 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 inferences' compared with plain Prolog and Prolog modules.
Note that the number of 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 time): 2

Static binding is the common case with libraries and most application
code; it requires compiling code with the *note optimize: 88. 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: 85. 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 in 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: 32. 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: 57. calls) always use dynamic
binding as the object that receives the message is only know at runtime.

Messages sent from Prolog modules may use static binding depending on
the used backend Prolog compiler when the ‘optimize’ flag is turned on.
Consult the Prolog compiler adapter file notes for details.


File: TheLogtalkHandbook-3.50.0.info,  Node: Automatic expansion of built-in meta-predicates,  Next: Inlining,  Prev: Messages<2>,  Up: Performance<2>

1.19.6 Automatic expansion of built-in meta-predicates
------------------------------------------------------

The compiler always expands calls to the *note forall/2: 1a6, *note
once/1: 19e, and *note ignore/1: 16c. meta-predicates into equivalent
definitions using the negation and conditional control constructs.  It
also expands calls to the *note call/1-N: 16d, *note phrase/2: 17a, and
*note phrase/3: 17b. meta-predicates when the first argument is bound.


File: TheLogtalkHandbook-3.50.0.info,  Node: Inlining,  Next: Generated code simplification and optimizations,  Prev: Automatic expansion of built-in meta-predicates,  Up: Performance<2>

1.19.7 Inlining
---------------

When the *note optimize: 88. 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: 180,
calls are inlined independently of the ‘optimize’ flag value.


File: TheLogtalkHandbook-3.50.0.info,  Node: Generated code simplification and optimizations,  Next: Size of the generated code,  Prev: Inlining,  Up: Performance<2>

1.19.8 Generated code simplification and optimizations
------------------------------------------------------

When the *note optimize: 88. 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’.


File: TheLogtalkHandbook-3.50.0.info,  Node: Size of the generated code,  Next: Debug mode overhead,  Prev: Generated code simplification and optimizations,  Up: Performance<2>

1.19.9 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: c5. 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: 75. and *note reflection: 46.  The size of these tables is
proportional to the number of entities, entity relations, and predicate
declarations and definitions.  When the *note source_data: c6. is turned
on (the default when `developing' an application), the generated code
also includes additional data about the source code such as entity and
predicates 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.50.0.info,  Node: Debug mode overhead,  Next: Other considerations,  Prev: Size of the generated code,  Up: Performance<2>

1.19.10 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:
30b.  These debug events can be intercepted by defined clauses for the
logtalk::trace_event/2(1) and logtalk::debug_handler/2(2) multifile
predicates.  With no application (such as a debugger or a port profiler)
loaded defining clauses for these predicates, each goal have 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 results in one or more inferences per goal (depending
on the number of clauses whose head unify 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) ../../docs/logtalk_0.html#logtalk-0-trace-event-2

   (2) ../../docs/logtalk_0.html#logtalk-0-debug-handler-2


File: TheLogtalkHandbook-3.50.0.info,  Node: Other considerations,  Prev: Debug mode overhead,  Up: Performance<2>

1.19.11 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 and 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.50.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 on 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 preferable be kept outside of the Logtalk user
folder created by the installation process, however, 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.50.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.50.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.50.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: 32. 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 predicates
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]: 2f, it is advisable that you try to use the most recent
version of your favorite Prolog compiler.


File: TheLogtalkHandbook-3.50.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.50.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.50.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:

‘BIBLIOGRAPHY.bib’ – Logtalk bibliography in BibTeX format

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

‘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

‘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’

     ‘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

‘examples’

     ‘NOTES.md’ – short description of the provided examples

     ‘bricks’

          ‘NOTES.md’ – example description and other notes ‘SCRIPT.txt’
          – step by step example tutorial ‘loader.lgt’ – loader utility
          file for the example objects ‘...’ – bricks 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

‘man’

     ‘...’ – POSIX man pages for the shell scripts

‘manuals’

     ‘NOTES.md’ – notes on the provided documentation
     ‘bibliography.html’ – bibliography ‘glossary.html’ – glossary
     ‘index.html’ – root document for all documentation ‘...’ – other
     documentation files

‘paths’

     ‘NOTES.md’ – description on how to setup library and examples paths
     ‘paths.pl’ – default library and example paths

‘ports’

     ‘NOTES.md’ – description of included ports of third-party software
     ‘...’ – ports

‘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.50.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: 232.  They also specify values for read-only flags that
are used to describe Prolog backend specific features.


File: TheLogtalkHandbook-3.50.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 in a single file, depending on the Logtalk release that you are
installing.


File: TheLogtalkHandbook-3.50.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.50.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 programing 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.50.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.50.0.info,  Node: Prolog integration and migration,  Prev: Installing Logtalk,  Up: User Manual

1.21 Prolog integration and migration
=====================================

An application may include plain Prolog files, Prolog modules, and
Logtalk objects.  This is a perfectly valid way of developing a complex
application and, in some cases, it might be the most appropriated
solution.  Modules may be used for legacy code or when a simple
encapsulation mechanism is adequate.  Logtalk objects may be used when
more powerful encapsulation, abstraction, and reuse features are
required.

This section provides tips for integrating and migrating plain Prolog
code and Prolog module code to Logtalk.  Step-by-step 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 which uses modules on a Prolog compiler with no module
system.  The ‘wrapper’ 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>.


File: TheLogtalkHandbook-3.50.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 which would
allowed 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
on 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.50.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.

Encapsulating Prolog code using Logtalk objects is simple.  First, for
each source file, add an opening object directive, *note object/1-5: 96,
to the beginning of the file and an ending object directive, *note
end_object/0: 97, to end of the file.  Choose an object name that
reflects the purpose of source file code (this is a good opportunity for
code refactoring if necessary).  Second, add *note public/1: 138.
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: 48. 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: 48. directives.  The Logtalk ‘wrapper’ tool can also help
in detecting cross predicate calls.  Compiling the resulting objects
with the Logtalk *note unknown_predicates: 2a1. and *note portability:
1b4. flags set to ‘warning’ will help you identify calls to predicates
defined on other converted source files and possible portability issues.

* Menu:

* Prolog multifile predicates::


File: TheLogtalkHandbook-3.50.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, is 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: 353, add a *note predicate scope directive: 134.
and a *note multifile/1: 158. 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 User Manual section 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: 61. for more details.


File: TheLogtalkHandbook-3.50.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 compatibility problems.
Some Prolog compilers don’t support a module system.  Among those Prolog
compilers which support a module system, the lack of standardization
leads to several issues, specially 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 from implementation, inheritance,
parametric objects, and categories.

Converting a Prolog module into an object is easy as long as the
directives used in the module are supported by Logtalk (see below).
Assuming that this is the case, apply the following steps:

  1. Convert the module ‘module/1’ directive into an opening object
     directive, *note object/1-5: 96, using the module name as the
     object name.  For ‘module/2’ directives apply the same conversion
     and convert the list of exported predicates into Logtalk *note
     public/1: 138. predicate directives.

  2. Add a closing object directive, *note end_object/0: 97, at the end
     of the module code.

  3. Convert any ‘export/1’ directives into ‘public/1’ predicate
     directives.

  4. Convert any ‘use_module/1’ directives into ‘use_module/2’
     directives (see next section).

  5. Convert any ‘use_module/2’ directives referencing other modules
     also being converted to objects into Logtalk *note uses/2: 48.
     directives.  If the referenced modules are not being converted into
     objects, keep the ‘use_module/2’ directives but change the first
     argument to be the module name.

  6. Convert each ‘reexport/1’ directive into a *note uses/2: 48.
     directive and ‘public/1’ predicate directives (see next section).

  7. Convert any ‘meta_predicate/1’ directives into Logtalk *note
     meta_predicate/1: 142. directives by replacing the module
     meta-argument indicator, ‘:’, with the Logtalk meta-argument
     indicator, ‘0’.  Closures must be represented using an integer
     denoting the number of additional arguments that will be appended
     to construct a goal.  Arguments which are not meta-arguments are
     represented by the ‘*’ character.

  8. Convert any explicit qualified calls to module predicates to
     messages by replacing the ‘:/2’ operator with the *note ;;/2: 7a.
     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: 17c. Logtalk external call
     control construct.  You can also use instead an *note uses/2: 48.
     directive where the first argument would be the atom ‘user’ and the
     second argument a list of all external predicates.  This
     alternative has the advantage of not requiring changes to the code
     making the predicate calls.

  9. If your module uses the database built-in predicates to implement
     module local mutable state using dynamic predicates, add both *note
     private/1: 13a. and *note dynamic/1: 149. directives for each
     dynamic predicate.

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

  11. Compile the resulting objects with the Logtalk *note
     unknown_predicates: 2a1, and *note portability: 1b4. 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: 27f. 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.50.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 port 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 a 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 bogus claims.  Systems
differences include the set of implemented module directives, the
directive semantics, the handling of operators, the locality of flags,
and on the integration of term-expansion mechanisms (when provided).
Follows a discussion of the limitations of this approach that you should
be aware.

* Menu:

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


File: TheLogtalkHandbook-3.50.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: 48. 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.  Only
     predicate arguments marked as goals or *note closures: 13f. (using
     an integer) are interpreted as meta-arguments.  In addition, 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 `sender'.

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: 2a6. flag to ‘warning’).

When compiling modules as objects, you probably don’t need event support
turned on.  You may use the *note events: 85. compiler flag to ‘deny’
with the Logtalk compiling and loading built-in methods for a small
performance gain for the compiled code.


File: TheLogtalkHandbook-3.50.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 first stage
of its *note term-expansion mechanism: c5.  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 and compile the
file (making sure that the *note unknown_predicates: 2a1. compiler flag
is set to ‘warning’).  Logtalk will print a warning with a list of
predicates that are called but never defined.  Second, use these 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.50.0.info,  Node: Modules using a term-expansion mechanism,  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: c5,
the 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 expansions clauses
and the source files that will be subject to source-to-source expansions
by using *note hook objects: 35e.  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, the default hook object is set to the module containing the
expansion code.  For example, if the expansions stored in a ‘system’
module:

     | ?- set_logtalk_flag(hook, system).
     ...

This, however, may not be enough as some expansions may stored in more
than one module.  A common example is to use a module named ‘prolog’.
It is also common to store the 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.


File: TheLogtalkHandbook-3.50.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 copy 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 ‘'$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, is advisable
to set the *note portability: 1b4. 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.50.0.info,  Node: Calling Prolog module predicates<2>,  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 object 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: 48. 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: 32.  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 supports the declaration of *note predicate aliases: c4. in
‘use_module/2’ directives used within object 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.

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 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: 3c. section.


File: TheLogtalkHandbook-3.50.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.50.0.info,  Node: Grammar,  Next: Control constructs,  Up: Reference Manual

2.1 Grammar
===========

The Logtalk grammar is here described using Backus-Naur Form syntax.
Non-terminal symbols in `italics' have the definition found in the ISO
Prolog Core standard.  Terminal symbols are represented in a ‘fixed
width font’ and between double-quotes.

* Menu:

* Entities::
* Object definition::
* Category definition::
* Protocol definition::
* Entity relations::
* Entity identifiers::
* 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.50.0.info,  Node: Entities,  Next: Object definition,  Up: Grammar

2.1.1 Entities
--------------

     entity ::= 
          object | 
          category | 
          protocol 


File: TheLogtalkHandbook-3.50.0.info,  Node: Object definition,  Next: Category definition,  Prev: Entities,  Up: Grammar

2.1.2 Object definition
-----------------------

     object ::= 
          begin_object_directive [ object_terms ] 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.50.0.info,  Node: Category definition,  Next: Protocol definition,  Prev: Object definition,  Up: Grammar

2.1.3 Category definition
-------------------------

     category ::= 
          begin_category_directive [ category_terms ] 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.50.0.info,  Node: Protocol definition,  Next: Entity relations,  Prev: Category definition,  Up: Grammar

2.1.4 Protocol definition
-------------------------

     protocol ::= 
          begin_protocol_directive [ protocol_directives ] end_protocol_directive. 

     begin_protocol_directive ::= 
          “‘:- protocol(’” protocol_identifier [ “‘,’” extends_protocols ] “‘).’” 

     end_protocol_directive ::= 
          “‘:- end_protocol.’” 


File: TheLogtalkHandbook-3.50.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.50.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.50.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.50.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.50.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.50.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.50.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.50.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.50.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.50.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.50.0.info,  Node: Entity identifiers,  Next: Source file names,  Prev: Entity relations,  Up: Grammar

2.1.6 Entity identifiers
------------------------

     entity_identifiers ::= 
          entity_identifier | 
          entity_identifier_sequence | 
          entity_identifier_list 

     entity_identifier ::= 
          object_identifier | 
          protocol_identifier | 
          category_identifier 

     entity_identifier_sequence ::= 
          entity_identifier | 
          entity_identifier “‘,’” entity_identifier_sequence 

     entity_identifier_list ::= 
          “‘[’” entity_identifier_sequence “‘]’” 

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Object identifiers,  Next: Category identifiers,  Up: Entity identifiers

2.1.6.1 Object identifiers
..........................

     object_identifiers ::= 
          object_identifier | 
          object_identifier_sequence | 
          object_identifier_list 

     object_identifier ::= 
          `atom' | 
          `compound' 

     object_identifier_sequence ::= 
          object_identifier | 
          object_identifier “‘,’” object_identifier_sequence 

     object_identifier_list ::= 
          “‘[’” object_identifier_sequence “‘]’” 


File: TheLogtalkHandbook-3.50.0.info,  Node: Category identifiers,  Next: Protocol identifiers,  Prev: Object identifiers,  Up: Entity identifiers

2.1.6.2 Category identifiers
............................

     category_identifiers ::= 
          category_identifier | 
          category_identifier_sequence | 
          category_identifier_list 

     category_identifier ::= 
          `atom' | 
          `compound' 

     category_identifier_sequence ::= 
          category_identifier | 
          category_identifier “‘,’” category_identifier_sequence 

     category_identifier_list ::= 
          “‘[’” category_identifier_sequence “‘]’” 


File: TheLogtalkHandbook-3.50.0.info,  Node: Protocol identifiers,  Next: Module identifiers,  Prev: Category identifiers,  Up: Entity identifiers

2.1.6.3 Protocol identifiers
............................

     protocol_identifiers ::= 
          protocol_identifier | 
          protocol_identifier_sequence | 
          protocol_identifier_list 
           
     protocol_identifier ::= 
          `atom' 

     protocol_identifier_sequence ::= 
          protocol_identifier | 
          protocol_identifier “‘,’” protocol_identifier_sequence 

     protocol_identifier_list ::= 
          “‘[’” protocol_identifier_sequence “‘]’” 


File: TheLogtalkHandbook-3.50.0.info,  Node: Module identifiers,  Prev: Protocol identifiers,  Up: Entity identifiers

2.1.6.4 Module identifiers
..........................

     module_identifier ::= 
          `atom' 


File: TheLogtalkHandbook-3.50.0.info,  Node: Source file names,  Next: Terms,  Prev: Entity identifiers,  Up: Grammar

2.1.7 Source file names
-----------------------

     source_file_names ::= 
          source_file_name | 
          source_file_name_list 

     source_file_name ::= 
          `atom' | 
          library_source_file_name 

     library_source_file_name ::= 
          library_name “‘(’” `atom' “‘)’” 

     library_name ::= 
          `atom' 

     source_file_name_sequence ::= 
          source_file_name | 
          source_file_name “‘,’” source_file_name_sequence 

     source_file_name_list ::= 
          “‘[’” source_file_name_sequence “‘]’” 


File: TheLogtalkHandbook-3.50.0.info,  Node: Terms,  Next: Directives,  Prev: Source file names,  Up: Grammar

2.1.8 Terms
-----------

* Menu:

* Object terms::
* Category terms::


File: TheLogtalkHandbook-3.50.0.info,  Node: Object terms,  Next: Category terms,  Up: Terms

2.1.8.1 Object terms
....................

     object_terms ::= 
          object_term | 
          object_term object_terms 

     object_term ::= 
          object_directive | 
          clause | 
          grammar_rule 


File: TheLogtalkHandbook-3.50.0.info,  Node: Category terms,  Prev: Object terms,  Up: Terms

2.1.8.2 Category terms
......................

     category_terms ::= 
          category_term | 
          category_term category_terms 

     category_term ::= 
          category_directive | 
          clause | 
          grammar_rule 


File: TheLogtalkHandbook-3.50.0.info,  Node: Directives,  Next: Clauses and goals,  Prev: Terms,  Up: Grammar

2.1.9 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: Predicate directives<2>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Source file directives,  Next: Conditional compilation directives,  Up: Directives

2.1.9.1 Source file directives
..............................

     source_file_directives ::= 
          source_file_directive | 
          source_file_directive source_file_directives 

     source_file_directive ::= 
          “‘:- encoding(’” `atom' “‘).’” | 
          “‘:- set_logtalk_flag(’” `atom' “‘,’” `nonvar' “‘).’” | 
          “‘:- include(’” source_file_name “‘).’” 
          `Prolog directives' 


File: TheLogtalkHandbook-3.50.0.info,  Node: Conditional compilation directives,  Next: Object directives<2>,  Prev: Source file directives,  Up: Directives

2.1.9.2 Conditional compilation directives
..........................................

     conditional_compilation_directives ::= 
          conditional_compilation_directive | 
          conditional_compilation_directive conditional_compilation_directives 

     conditional_compilation_directive ::= 
          “‘:- if(’” `callable' “‘).’” | 
          “‘:- elif(’” `callable' “‘).’” | 
          “‘:- else.’” | 
          “‘:- endif.’” 


File: TheLogtalkHandbook-3.50.0.info,  Node: Object directives<2>,  Next: Category directives<2>,  Prev: Conditional compilation directives,  Up: Directives

2.1.9.3 Object directives
.........................

     object_directives ::= 
          object_directive | 
          object_directive 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 “‘).’” | 
          predicate_directives 


File: TheLogtalkHandbook-3.50.0.info,  Node: Category directives<2>,  Next: Protocol directives<2>,  Prev: Object directives<2>,  Up: Directives

2.1.9.4 Category directives
...........................

     category_directives ::= 
          category_directive | 
          category_directive category_directives 

     category_directive ::= 
          “‘:- built_in.’” | 
          “‘:- dynamic.’” | 
          “‘:- info(’” entity_info_list “‘).’” | 
          “‘:- set_logtalk_flag(’” `atom' “‘,’” `nonvar' “‘).’” | 
          “‘:- include(’” source_file_name “‘).’” | 
          “‘:- uses(’” object_alias_list “‘).’” | 
          predicate_directives 


File: TheLogtalkHandbook-3.50.0.info,  Node: Protocol directives<2>,  Next: Predicate directives<2>,  Prev: Category directives<2>,  Up: Directives

2.1.9.5 Protocol directives
...........................

     protocol_directives ::= 
          protocol_directive | 
          protocol_directive protocol_directives 

     protocol_directive ::= 
          “‘:- built_in.’” | 
          “‘:- dynamic.’” | 
          “‘:- info(’” entity_info_list “‘).’” | 
          “‘:- set_logtalk_flag(’” `atom' “‘,’” `nonvar' “‘).’” | 
          “‘:- include(’” source_file_name “‘).’” | 
          predicate_directives 


File: TheLogtalkHandbook-3.50.0.info,  Node: Predicate directives<2>,  Prev: Protocol directives<2>,  Up: Directives

2.1.9.6 Predicate directives
............................

     predicate_directives ::= 
          predicate_directive | 
          predicate_directive predicate_directives 

     predicate_directive ::= 
          alias_directive | 
          synchronized_directive | 
          uses_directive | 
          use_module_directive | 
          scope_directive | 
          mode_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 “‘,’” 
                    predicate_indicator_alias_list | non_terminal_indicator_alias_list 
               “‘).’” 

     synchronized_directive ::= 
          “‘:- synchronized(’” predicate_indicator_term | non_terminal_indicator_term “‘).’” 

     uses_directive ::= 
          “‘:- uses(’“ 
               object_identifier | parameter_variable “‘,’” 
               predicate_indicator_alias_list | non_terminal_indicator_alias_list | operator_list 
          “‘).’” 

     use_module_directive ::= 
          “‘:- use_module(’“ 
               module_identifier | parameter_variable “‘,’” 
               module_predicate_indicator_alias_list | module_non_terminal_indicator_alias_list | operator_list 
          “‘).’” 

     scope_directive ::= 
          “‘:- public(’” predicate_indicator_term | non_terminal_indicator_term “‘).’” | 
          “‘:- protected(’” predicate_indicator_term | non_terminal_indicator_term “‘).’” | 
          “‘:- private(’” predicate_indicator_term | non_terminal_indicator_term “‘).’” 

     mode_directive ::= 
          “‘:- mode(’“ 
               predicate_mode_term | 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_predicate_indicator_term | qualified_non_terminal_indicator_term “‘).’” 

     discontiguous_directive ::= 
          “‘:- discontiguous(’” predicate_indicator_term | 
          non_terminal_indicator_term “‘).’” 

     multifile_directive ::= 
          “‘:- multifile(’” qualified_predicate_indicator_term | 
          qualified_non_terminal_indicator_term “‘).’” 

     coinductive_directive ::= 
          “‘:- coinductive(’” predicate_indicator_term | 
          coinductive_predicate_template_term “‘).’” 

     parameter_variable ::= 
          `_variable_' 

     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 “‘]’” 

     qualified_predicate_indicator_term ::= 
          qualified_predicate_indicator | 
          qualified_predicate_indicator_sequence | 
          qualified_predicate_indicator_list 

     qualified_predicate_indicator_sequence ::= 
          qualified_predicate_indicator | 
          qualified_predicate_indicator “‘,’” qualified_predicate_indicator_sequence 

     qualified_predicate_indicator_list ::= 
          “‘[’” qualified_predicate_indicator_sequence “‘]’” 

     qualified_predicate_indicator ::= 
          predicate_indicator | 
          object_identifier “‘::’” predicate_indicator | 
          category_identifier “‘::’” predicate_indicator | 
          module_identifier “‘:’” predicate_indicator 

     predicate_indicator_alias ::= 
          `predicate_indicator' | 
          `predicate_indicator' “‘as’” `predicate_indicator' | 
          `predicate_indicator' “‘::’” `predicate_indicator' 

     predicate_indicator_alias_sequence ::= 
          predicate_indicator_alias | 
          predicate_indicator_alias “‘,’” predicate_indicator_alias_sequence 

     predicate_indicator_alias_list ::= 
          “‘[’” predicate_indicator_alias_sequence “‘]’” 

     predicate_template_alias ::= 
          `callable' “‘as’” `callable' | 
          `callable' “‘::’” `callable' 

     predicate_template_alias_sequence ::= 
          predicate_template_alias | 
          predicate_template_alias “‘,’” predicate_template_alias_sequence 

     predicate_template_alias_list ::= 
          “‘[’” predicate_template_alias_sequence “‘]’” 

     module_predicate_indicator_alias ::= 
          `predicate_indicator' | 
          `predicate_indicator' “‘as’” `predicate_indicator' | 
          `predicate_indicator' “‘:’” `predicate_indicator' 

     module_predicate_indicator_alias_sequence ::= 
          module_predicate_indicator_alias | 
          module_predicate_indicator_alias “‘,’” module_predicate_indicator_alias_sequence 

     module_predicate_indicator_alias_list ::= 
          “‘[’” module_predicate_indicator_alias_sequence “‘]’” 

     module_non_terminal_indicator_alias ::= 
          `non_terminal_indicator' | 
          `non_terminal_indicator' “‘as’” `non_terminal_indicator' 
          `non_terminal_indicator' “‘:’” `non_terminal_indicator' 

     module_non_terminal_indicator_alias_sequence ::= 
          module_non_terminal_indicator_alias | 
          module_non_terminal_indicator_alias “‘,’” module_non_terminal_indicator_alias_sequence 

     module_non_terminal_indicator_alias_list ::= 
          “‘[’” module_non_terminal_indicator_alias_sequence “‘]’” 

     non_terminal_indicator_term ::= 
          non_terminal_indicator | 
          non_terminal_indicator_sequence | 
          non_terminal_indicator_list 

     non_terminal_indicator_sequence ::= 
          non_terminal_indicator | 
          non_terminal_indicator “‘,’” non_terminal_indicator_sequence 

     non_terminal_indicator_list ::= 
          “‘[’” non_terminal_indicator_sequence “‘]’” 

     non_terminal_indicator ::= 
          `functor' “‘//’” `arity' 

     qualified_non_terminal_indicator_term ::= 
          qualified_non_terminal_indicator | 
          qualified_non_terminal_indicator_sequence | 
          qualified_non_terminal_indicator_list 

     qualified_non_terminal_indicator_sequence ::= 
          qualified_non_terminal_indicator | 
          qualified_non_terminal_indicator “‘,’ ” qualified_non_terminal_indicator_sequence 

     qualified_non_terminal_indicator_list ::= 
          “‘[’” qualified_non_terminal_indicator_sequence “‘]’” 

     qualified_non_terminal_indicator ::= 
          non_terminal_indicator | 
          object_identifier “‘::’” non_terminal_indicator | 
          category_identifier “‘::’” non_terminal_indicator | 
          module_identifier “‘:’” non_terminal_indicator 

     non_terminal_indicator_alias ::= 
          `non_terminal_indicator' | 
          `non_terminal_indicator' “‘as’” `non_terminal_indicator' 
          `non_terminal_indicator' “‘::’” `non_terminal_indicator' 

     non_terminal_indicator_alias_sequence ::= 
          non_terminal_indicator_alias | 
          non_terminal_indicator_alias “‘,’” 
          non_terminal_indicator_alias_sequence 

     non_terminal_indicator_alias_list ::= 
          “‘[’” non_terminal_indicator_alias_sequence “‘]’” 

     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’” | “‘one_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 “‘)’” | 
          `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_item “‘is’” `nonvar' “‘|’” entity_info_list 
          “‘]’” 

     entity_info_item ::= 
          “‘comment’” | “‘remarks’” | 
          “‘author’” | “‘version’” | “‘date’” | 
          “‘copyright’” | “‘license’” | 
          “‘parameters’” | “‘parnames’” | 
          “‘see_also’” | 
          `atom' 

     predicate_info_list ::= 
          “‘[]’” | 
          “‘[’” predicate_info_item “‘is’” `nonvar' “‘|’” predicate_info_list “‘]’” 

     predicate_info_item ::= 
          “‘comment’” | “‘remarks’” | 
          “‘arguments’” | “‘argnames’” | 
          “‘redefinition’” | “‘allocation’” | 
          “‘examples’” | “‘exceptions’” | 
          `atom' 

     object_alias ::= 
          object_identifier “‘as’” object_identifier 

     object_alias_sequence ::= 
          object_alias | 
          object_alias “‘,’” object_alias_sequence 

     object_alias_list ::= 
          “‘[’” object_alias_sequence “‘]’” 


File: TheLogtalkHandbook-3.50.0.info,  Node: Clauses and goals,  Next: Lambda expressions<2>,  Prev: Directives,  Up: Grammar

2.1.10 Clauses and goals
------------------------

     clause ::= 
          object_identifier “‘::’” `head' “‘:-’” `body' | 
          module_identifier “‘:’” `head' “‘:-’” `body' | 
          `head' :- `body' | 
          `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 “‘<<’” `goal' 


File: TheLogtalkHandbook-3.50.0.info,  Node: Lambda expressions<2>,  Next: Entity properties,  Prev: Clauses and goals,  Up: Grammar

2.1.11 Lambda expressions
-------------------------

     lambda_expression ::= 
          lambda_free_variables “‘/’” lambda_parameters “‘>>’” `callable' | 
          lambda_free_variables “‘/’” `callable' | 
          lambda_parameters “‘>>’” `callable' 

     lambda_free_variables ::= 
          “‘{’” `conjunction of variables' “‘}’” | 
          “‘{’” `variable' “‘}’” | 
          “‘{}’” 

     lambda_parameters ::= 
          `list of terms' | 
          “‘[]’” 


File: TheLogtalkHandbook-3.50.0.info,  Node: Entity properties,  Next: Predicate properties<2>,  Prev: Lambda expressions<2>,  Up: Grammar

2.1.12 Entity properties
------------------------

     category_property ::= 
          “‘static’” | 
          “‘dynamic’” | 
          “‘built_in’” | 
          “‘file(’” `atom' “‘)’” | 
          “‘file(’” `atom' “‘,’” `atom' “‘)’” | 
          “‘lines(’” `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 “‘)’” | 
          “‘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' “‘)’” | 
          “‘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 “‘)’” 
          “‘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' “‘)’” | 
          “‘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' “‘)’” | 
          “‘line_count(’” `integer' “‘)’” | 
          “‘mode(’” predicate_mode_term | non_terminal_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' “‘)’” | 
          “‘line_count(’” `integer' “‘)’” | 
          “‘number_of_clauses(’” `integer' “‘)’” | 
          “‘number_of_rules(’” `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 ::= 
          “‘for(’” predicate_indicator “‘)’” | 
          “‘from(’” entity_identifier “‘)’” | 
          “‘non_terminal(’” non_terminal_indicator “‘)’” | 
          “‘include(’” `atom' “‘)’” | 
          “‘line_count(’” `integer' “‘)’” 

     predicate ::= 
          predicate_indicator | 
          “‘^^’” predicate_indicator | 
          “‘::’” predicate_indicator | 
          `variable' “‘::’” predicate_indicator | 
          object_identifier “‘::’” predicate_indicator | 
          `variable' “‘:’” predicate_indicator | 
          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' “‘)’” | 
          “‘line_count(’” `integer' “‘)’” | 
          “‘as(’” predicate_indicator “‘)’” 


File: TheLogtalkHandbook-3.50.0.info,  Node: Predicate properties<2>,  Next: Compiler flags<2>,  Prev: Entity properties,  Up: Grammar

2.1.13 Predicate properties
---------------------------

     predicate_property ::= 
          “‘static’” | “‘dynamic’” | 
          “‘scope(’” scope “‘)’” | 
          “‘private’” | “‘protected’” | “‘public’” | 
          “‘logtalk’” | “‘prolog’” | “‘foreign’” | 
          “‘coinductive(’” coinductive_predicate_template “‘)’” | 
          “‘multifile’” | 
          “‘synchronized’” | 
          “‘built_in’” | 
          “‘inline’” | 
          “‘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 | non_terminal_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.50.0.info,  Node: Compiler flags<2>,  Prev: Predicate properties<2>,  Up: Grammar

2.1.14 Compiler flags
---------------------

     compiler_flag ::= 
          `flag(flag_value)' 


File: TheLogtalkHandbook-3.50.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 external predicates::
* Context switching calls::


File: TheLogtalkHandbook-3.50.0.info,  Node: Message sending<2>,  Next: Message delegation,  Up: Control constructs

2.2.1 Message sending
---------------------

* Menu:

* ;;/2: /2.
* ;;/1: /1.


File: TheLogtalkHandbook-3.50.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.50.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: 138. predicate of the receiver object.  When the message
corresponds to a *note protected: 139. or *note private: 13a. predicate,
the call is only valid if the *note sender: 3b4. matches the *note
predicate scope container: 3b5.  When the predicate is declared but not
defined, the message simply fails (as per the *note closed-world
assumption: 65.).

The ‘{Proxy}::Message’ syntax allows simplified access to *note
parametric object proxies: 3b6.  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: c9. 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 construct 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: 88. 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
in subsequent messages.  See the User Manual section on *note
performance: 36. for details.


File: TheLogtalkHandbook-3.50.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.50.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.50.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: 57, *note ^^/1: 58, *note []/1: 7d.


File: TheLogtalkHandbook-3.50.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.50.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: 64.  Can only used in the body of a
predicate definition.  The argument should match a *note public: 138. or
*note protected: 139. predicate of `self'.  It may also match a *note
private: 13a. 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: 65.).

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: 34. but a caching mechanism is
used to improve performance in subsequent messages.  See the User Manual
section on *note performance: 36. for details.


File: TheLogtalkHandbook-3.50.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.50.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.50.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: 7a, *note ^^/1: 58, *note []/1: 7d.


File: TheLogtalkHandbook-3.50.0.info,  Node: Message delegation,  Next: Calling imported and inherited predicates<2>,  Prev: Message sending<2>,  Up: Control constructs

2.2.2 Message delegation
------------------------

* Menu:

* []/1::


File: TheLogtalkHandbook-3.50.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.50.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.  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 using 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: 7a. 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.50.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.50.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.50.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: 7a, *note ;;/1: 57, *note ^^/1: 58, *note forward/1: fe.


File: TheLogtalkHandbook-3.50.0.info,  Node: Calling imported and inherited predicates<2>,  Next: Calling external predicates,  Prev: Message delegation,  Up: Control constructs

2.2.3 Calling imported and inherited predicates
-----------------------------------------------

* Menu:

* ^^/1::


File: TheLogtalkHandbook-3.50.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.50.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: 65.).
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: 64. and *note sender: 3b4. 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: 88. 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: 36. 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: 138. or *note
protected: 139.  It may also be declared *note private: 13a. 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.50.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.50.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.50.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: 7a, *note ;;/1: 57, *note []/1: 7d.


File: TheLogtalkHandbook-3.50.0.info,  Node: Calling external predicates,  Next: Context switching calls,  Prev: Calling imported and inherited predicates<2>,  Up: Control constructs

2.2.4 Calling external predicates
---------------------------------

* Menu:

* {}/1::


File: TheLogtalkHandbook-3.50.0.info,  Node: {}/1,  Up: Calling external predicates

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.50.0.info,  Node: Description<5>,  Next: Modes and number of proofs<5>,  Up: {}/1

2.2.4.2 Description
...................

     {Term}
     {Goal}

This control construct allows the programmer to bypass the Logtalk
compiler.  It can also be used to wrap a source file term (either a
clause or a directive) to bypass the *note term-expansion mechanism: c5.
Similarly, it can also be used to wrap a goal to bypass the
goal-expansion mechanism.  When used to wrap a goal, it is opaque to
cuts and the argument is called within the context of the pseudo-object
*note user: c9.  It is also possible to use ‘{Closure}’ as the first
argument of *note call/1-N: 16d. calls.  In this case, ‘Closure’ will be
extended with the remaining arguments of the ‘call/2-N’ call in order to
construct a goal that will be called within the context of ‘user’.  It
can also be used as a message to any object.  This is useful when the
message is e.g.  a conjunction of messages, some of which being calls to
Prolog built-in predicates.

This control construct may also be used in place of an object identifier
when sending a message.  In this case, the result of proving its
argument as a goal (within the context of the pseudo-object ‘user’) is
used as an object identifier in the message sending call.  This feature
is mainly used with *note parametric objects: 3d8. when their
identifiers correspond to predicates defined in ‘user’.


File: TheLogtalkHandbook-3.50.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.50.0.info,  Node: Errors<5>,  Next: Examples<6>,  Prev: Modes and number of proofs<5>,  Up: {}/1

2.2.4.4 Errors
..............

     ‘Term’ is a variable: 
          ‘instantiation_error’ 
     ‘Term’ is neither a variable nor a callable term: 
          ‘type_error(callable, Term)’ 
           
     ‘Goal’ is a variable: 
          ‘instantiation_error’ 
     ‘Goal’ is neither a variable nor a callable term: 
          ‘type_error(callable, Goal)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<6>,  Prev: Errors<5>,  Up: {}/1

2.2.4.5 Examples
................

     % bypass the compiler for the next term:
     {:- load_foreign_resource(file)}.

     % overload the standard </2 operator:
     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).

     % 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.50.0.info,  Node: Context switching calls,  Prev: Calling external predicates,  Up: Control constructs

2.2.5 Context switching calls
-----------------------------

* Menu:

* <</2::


File: TheLogtalkHandbook-3.50.0.info,  Node: <</2,  Up: Context switching calls

2.2.5.1 ‘<</2’
..............

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<6>,  Next: Modes and number of proofs<6>,  Up: <</2

2.2.5.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 execution context (*note
sender: 3b4, *note this: 169, and *note self: 64.) set to the object.
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: 2b4. compiler flag set to ‘allow’.  Set this
compiler flag to ‘deny’ to disable this control construct and thus
preventing using it to break encapsulation.

The ‘{Proxy}<<Goal’ syntax allows simplified access to *note parametric
object proxies: 3b6.  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: c9. 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.50.0.info,  Node: Modes and number of proofs<6>,  Next: Errors<6>,  Prev: Description<6>,  Up: <</2

2.2.5.3 Modes and number of proofs
..................................

     +object_identifier<<+callable - zero_or_more
     {+object_identifier}<<+callable - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<6>,  Next: Examples<7>,  Prev: Modes and number of proofs<6>,  Up: <</2

2.2.5.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.50.0.info,  Node: Examples<7>,  Prev: Errors<6>,  Up: <</2

2.2.5.5 Examples
................

     % call the member/2 predicate in the
     % context of the "list" object:
     test(member) :-
         list << member(1, [1]).


File: TheLogtalkHandbook-3.50.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: Entity directives<2>.
* Predicate directives: Predicate directives<3>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Source file directives<2>,  Next: Conditional compilation directives<2>,  Up: Directives<2>

2.3.1 Source file directives
----------------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: encoding/1,  Next: include/1,  Up: Source file directives<2>

2.3.1.1 ‘encoding/1’
....................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<7>,  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: 32. 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: b2. 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: 27a. 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.50.0.info,  Node: Template and modes,  Next: Examples<8>,  Prev: Description<7>,  Up: encoding/1

2.3.1.3 Template and modes
..........................

     encoding(+atom)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<8>,  Prev: Template and modes,  Up: encoding/1

2.3.1.4 Examples
................

     :- encoding('UTF-8').


File: TheLogtalkHandbook-3.50.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<8>.
* Template and modes: Template and modes<2>.
* Examples: Examples<9>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<8>,  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: 288. 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.

When using the *note reflection API: 46, 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: 279. 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: 5d. and *note create_category/4: 110.
     predicates, the objects and categories will not be recreated or
     redefined when the included file(s) are modified and the *note
     logtalk_make/0: 280. predicate or the *note logtalk_make/1: 281.
     (with target ‘all’) predicates are called.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<2>,  Next: Examples<9>,  Prev: Description<8>,  Up: include/1

2.3.1.7 Template and modes
..........................

     include(@source_file_name)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<9>,  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'))], []).


File: TheLogtalkHandbook-3.50.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<9>.
* Template and modes: Template and modes<3>.
* Examples: Examples<10>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<9>,  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.

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: 308. 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.50.0.info,  Node: Template and modes<3>,  Next: Examples<10>,  Prev: Description<9>,  Up: initialization/1

2.3.1.11 Template and modes
...........................

     initialization(@callable)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<10>,  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.


File: TheLogtalkHandbook-3.50.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<10>.
* Template and modes: Template and modes<4>.
* Examples: Examples<11>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<10>,  Next: Template and modes<4>,  Up: op/3

2.3.1.14 Description
....................

     op(Precedence, Associativity, Operator)
     op(Precedence, Associativity, [Operator, ...])

Declares operators.  Operators declared inside entities have local
scope.  Global operators can be declared inside a source file by writing
the respective directives before the entity opening directives.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<4>,  Next: Examples<11>,  Prev: Description<10>,  Up: op/3

2.3.1.15 Template and modes
...........................

     op(+integer, +associativity, +atom_or_atom_list)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<11>,  Prev: Template and modes<4>,  Up: op/3

2.3.1.16 Examples
.................

     :- op(200, fy, +).
     :- op(200, fy, ?).
     :- op(200, fy, @).
     :- op(200, fy, -).

See also
........

*note current_op/3: 14d.


File: TheLogtalkHandbook-3.50.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<11>.
* Template and modes: Template and modes<5>.
* Errors: Errors<7>.
* Examples: Examples<12>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<11>,  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: 4c. built-in predicate called from an *note
initialization/1: 40. directive.  For a description of the predefined
compiler flags, consult the *note Compiler flags: 232. section in the
User Manual.  The directive affects the compilation of all terms that
follow it within scope of the directive.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<5>,  Next: Errors<7>,  Prev: Description<11>,  Up: set_logtalk_flag/2

2.3.1.19 Template and modes
...........................

     set_logtalk_flag(+atom, +nonvar)


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<7>,  Next: Examples<12>,  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.50.0.info,  Node: Examples<12>,  Prev: Errors<7>,  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.50.0.info,  Node: Conditional compilation directives<2>,  Next: Entity directives<2>,  Prev: Source file directives<2>,  Up: Directives<2>

2.3.2 Conditional compilation directives
----------------------------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: if/1,  Next: elif/1,  Up: Conditional compilation directives<2>

2.3.2.1 ‘if/1’
..............

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<12>,  Next: Template and modes<6>,  Up: if/1

2.3.2.2 Description
...................

     if(Goal)

Starts conditional compilation.  The code following the directive is
compiled iff ‘Goal’ is true.  The goal is subjected to *note goal
expansion: c5. 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.50.0.info,  Node: Template and modes<6>,  Next: Examples<13>,  Prev: Description<12>,  Up: if/1

2.3.2.3 Template and modes
..........................

     if(@callable)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<13>,  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.

See also
........

*note elif/1: 2cd, *note else/0: 2ce, *note endif/0: 2cf.


File: TheLogtalkHandbook-3.50.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<13>.
* Template and modes: Template and modes<7>.
* Examples: Examples<14>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<13>,  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.  The
goal is subjected to *note goal expansion: c5. 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.50.0.info,  Node: Template and modes<7>,  Next: Examples<14>,  Prev: Description<13>,  Up: elif/1

2.3.2.7 Template and modes
..........................

     elif(@callable)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<14>,  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: 2ce, *note endif/0: 2cf, *note if/1: 2cc.


File: TheLogtalkHandbook-3.50.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<14>.
* Template and modes: Template and modes<8>.
* Examples: Examples<15>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<14>,  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: 2cc. or *note elif/1: 2cd. directive is false.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<8>,  Next: Examples<15>,  Prev: Description<14>,  Up: else/0

2.3.2.11 Template and modes
...........................

     else


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<15>,  Prev: Template and modes<8>,  Up: else/0

2.3.2.12 Examples
.................

An example where a hypothetic application would have some limitations
that the user should be made aware 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: 2cd, *note endif/0: 2cf, *note if/1: 2cc.


File: TheLogtalkHandbook-3.50.0.info,  Node: endif/0,  Prev: else/0,  Up: Conditional compilation directives<2>

2.3.2.13 ‘endif/0’
..................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<15>,  Next: Template and modes<9>,  Up: endif/0

2.3.2.14 Description
....................

     endif

Ends conditional compilation for the matching *note if/1: 2cc.
directive.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<9>,  Next: Examples<16>,  Prev: Description<15>,  Up: endif/0

2.3.2.15 Template and modes
...........................

     endif


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<16>,  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: 2cd, *note else/0: 2ce, *note if/1: 2cc.


File: TheLogtalkHandbook-3.50.0.info,  Node: Entity directives<2>,  Next: Predicate directives<3>,  Prev: Conditional compilation directives<2>,  Up: Directives<2>

2.3.3 Entity directives
-----------------------

* 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.50.0.info,  Node: built_in/0,  Next: category/1-4,  Up: Entity directives<2>

2.3.3.1 ‘built_in/0’
....................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<16>,  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.50.0.info,  Node: Template and modes<10>,  Next: Examples<17>,  Prev: Description<16>,  Up: built_in/0

2.3.3.3 Template and modes
..........................

     built_in


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<17>,  Prev: Template and modes<10>,  Up: built_in/0

2.3.3.4 Examples
................

     :- built_in.


File: TheLogtalkHandbook-3.50.0.info,  Node: category/1-4,  Next: dynamic/0,  Prev: built_in/0,  Up: Entity directives<2>

2.3.3.5 ‘category/1-4’
......................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<17>,  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.50.0.info,  Node: Template and modes<11>,  Next: Examples<18>,  Prev: Description<17>,  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.50.0.info,  Node: Examples<18>,  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: 107.


File: TheLogtalkHandbook-3.50.0.info,  Node: dynamic/0,  Next: end_category/0,  Prev: category/1-4,  Up: Entity directives<2>

2.3.3.9 ‘dynamic/0’
...................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<18>,  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.

     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.50.0.info,  Node: Template and modes<12>,  Next: Examples<19>,  Prev: Description<18>,  Up: dynamic/0

2.3.3.11 Template and modes
...........................

     dynamic


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<19>,  Prev: Template and modes<12>,  Up: dynamic/0

2.3.3.12 Examples
.................

     :- dynamic.

See also
........

*note dynamic/1: 149, *note object_property/2: c1, *note
protocol_property/2: ed, *note category_property/2: 122.


File: TheLogtalkHandbook-3.50.0.info,  Node: end_category/0,  Next: end_object/0,  Prev: dynamic/0,  Up: Entity directives<2>

2.3.3.13 ‘end_category/0’
.........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<19>,  Next: Template and modes<13>,  Up: end_category/0

2.3.3.14 Description
....................

     end_category

Ending category directive.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<13>,  Next: Examples<20>,  Prev: Description<19>,  Up: end_category/0

2.3.3.15 Template and modes
...........................

     end_category


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<20>,  Prev: Template and modes<13>,  Up: end_category/0

2.3.3.16 Examples
.................

     :- end_category.

See also
........

*note category/1-4: 106.


File: TheLogtalkHandbook-3.50.0.info,  Node: end_object/0,  Next: end_protocol/0,  Prev: end_category/0,  Up: Entity directives<2>

2.3.3.17 ‘end_object/0’
.......................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<20>,  Next: Template and modes<14>,  Up: end_object/0

2.3.3.18 Description
....................

     end_object

Ending object directive.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<14>,  Next: Examples<21>,  Prev: Description<20>,  Up: end_object/0

2.3.3.19 Template and modes
...........................

     end_object


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<21>,  Prev: Template and modes<14>,  Up: end_object/0

2.3.3.20 Examples
.................

     :- end_object.

See also
........

*note object/1-5: 96.


File: TheLogtalkHandbook-3.50.0.info,  Node: end_protocol/0,  Next: info/1,  Prev: end_object/0,  Up: Entity directives<2>

2.3.3.21 ‘end_protocol/0’
.........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<21>,  Next: Template and modes<15>,  Up: end_protocol/0

2.3.3.22 Description
....................

     end_protocol

Ending protocol directive.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<15>,  Next: Examples<22>,  Prev: Description<21>,  Up: end_protocol/0

2.3.3.23 Template and modes
...........................

     end_protocol


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<22>,  Prev: Template and modes<15>,  Up: end_protocol/0

2.3.3.24 Examples
.................

     :- end_protocol.

See also
........

*note protocol/1-2: d5.


File: TheLogtalkHandbook-3.50.0.info,  Node: info/1,  Next: object/1-5,  Prev: end_protocol/0,  Up: Entity directives<2>

2.3.3.25 ‘info/1’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<22>,  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 directives: 2fc. section for a description of the
default keys.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<16>,  Next: Examples<23>,  Prev: Description<22>,  Up: info/1

2.3.3.27 Template and modes
...........................

     info(+entity_info_list)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<23>,  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: 156, *note object_property/2: c1, *note
protocol_property/2: ed, *note category_property/2: 122.


File: TheLogtalkHandbook-3.50.0.info,  Node: object/1-5,  Next: protocol/1-2,  Prev: info/1,  Up: Entity directives<2>

2.3.3.29 ‘object/1-5’
.....................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<23>,  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.50.0.info,  Node: Template and modes<17>,  Next: Examples<24>,  Prev: Description<23>,  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.50.0.info,  Node: Examples<24>,  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: 97.


File: TheLogtalkHandbook-3.50.0.info,  Node: protocol/1-2,  Next: threaded/0,  Prev: object/1-5,  Up: Entity directives<2>

2.3.3.33 ‘protocol/1-2’
.......................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<24>,  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.50.0.info,  Node: Template and modes<18>,  Next: Examples<25>,  Prev: Description<24>,  Up: protocol/1-2

2.3.3.35 Template and modes
...........................

     protocol(+protocol_identifier)

     protocol(+protocol_identifier,
         extends(+extended_protocols))


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<25>,  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: d6.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded/0,  Next: uses/1,  Prev: protocol/1-2,  Up: Entity directives<2>

2.3.3.37 ‘threaded/0’
.....................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<25>,  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: c9.
pseudo-object is automatically created at Logtalk startup (provided that
multi-threading programming is supported and enabled for the chosen
*note backend Prolog compiler: 32.).

     Note: This directive requires a *note backend Prolog compiler: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 206. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<19>,  Next: Examples<26>,  Prev: Description<25>,  Up: threaded/0

2.3.3.39 Template and modes
...........................

     threaded


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<26>,  Prev: Template and modes<19>,  Up: threaded/0

2.3.3.40 Examples
.................

     :- threaded.

See also
........

*note synchronized/1: 6f, *note object_property/2: c1.


File: TheLogtalkHandbook-3.50.0.info,  Node: uses/1,  Next: use_module/1,  Prev: threaded/0,  Up: Entity directives<2>

2.3.3.41 ‘uses/1’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<26>,  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: 9d. or
parametric objects where one of 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: 33, and thus optimal message
sending performance, the objects should be loaded before compiling the
entities that call their predicates.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<20>,  Next: Examples<27>,  Prev: Description<26>,  Up: uses/1

2.3.3.43 Template and modes
...........................

     uses(+object_alias_list)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<27>,  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: 48, *note use_module/1: 49, *note use_module/2: 4a.


File: TheLogtalkHandbook-3.50.0.info,  Node: use_module/1,  Prev: uses/1,  Up: Entity directives<2>

2.3.3.45 ‘use_module/1’
.......................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<27>,  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: 9d. 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: 33, 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.50.0.info,  Node: Template and modes<21>,  Next: Examples<28>,  Prev: Description<27>,  Up: use_module/1

2.3.3.47 Template and modes
...........................

     use_module(+module_alias_list)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<28>,  Prev: Template and modes<21>,  Up: use_module/1

2.3.3.48 Examples
.................

     :- object(foo(_DataModule_)).

         :- use_module([
             _DataModule_ as data
         ]).

         bar :-
             ...,
             % the same as _DataModule_:xy(X, Y)
             data:xy(X, Y),
             ...

See also
........

*note uses/1: b5, *note uses/2: 48, *note use_module/2: 4a.


File: TheLogtalkHandbook-3.50.0.info,  Node: Predicate directives<3>,  Prev: Entity directives<2>,  Up: Directives<2>

2.3.4 Predicate directives
--------------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: alias/2,  Next: coinductive/1,  Up: Predicate directives<3>

2.3.4.1 ‘alias/2’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<28>,  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 aliases.  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 appropriated 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.50.0.info,  Node: Template and modes<22>,  Next: Examples<29>,  Prev: Description<28>,  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.50.0.info,  Node: Examples<29>,  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: 48, *note use_module/2: 4a, *note uses/1: b5.


File: TheLogtalkHandbook-3.50.0.info,  Node: coinductive/1,  Next: discontiguous/1,  Prev: alias/2,  Up: Predicate directives<3>

2.3.4.5 ‘coinductive/1’
.......................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<29>,  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 coinductive
predicates.  Requires a *note backend Prolog compiler: 32. 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: 465. 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.50.0.info,  Node: Template and modes<23>,  Next: Examples<30>,  Prev: Description<29>,  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.50.0.info,  Node: Examples<30>,  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: 465, *note predicate_property/2:
137.


File: TheLogtalkHandbook-3.50.0.info,  Node: discontiguous/1,  Next: dynamic/1,  Prev: coinductive/1,  Up: Predicate directives<3>

2.3.4.9 ‘discontiguous/1’
.........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<30>,  Next: Template and modes<24>,  Up: discontiguous/1

2.3.4.10 Description
....................

     discontiguous(Name/Arity)
     discontiguous((Name/Arity, ...))
     discontiguous([Name/Arity, ...])

     discontiguous(Name//Arity)
     discontiguous((Name//Arity, ...))
     discontiguous([Name//Arity, ...])

Declares discontiguous predicates and discontiguous grammar rule
non-terminals.  The use of this directive should be avoided as not all
*note backend Prolog compilers: 32. 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.50.0.info,  Node: Template and modes<24>,  Next: Examples<31>,  Prev: Description<30>,  Up: discontiguous/1

2.3.4.11 Template and modes
...........................

     discontiguous(+predicate_indicator_term)
     discontiguous(+non_terminal_indicator_term)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<31>,  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]).


File: TheLogtalkHandbook-3.50.0.info,  Node: dynamic/1,  Next: info/2,  Prev: discontiguous/1,  Up: Predicate directives<3>

2.3.4.13 ‘dynamic/1’
....................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<31>,  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 dynamic 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: 13a. 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: 159.

Note that dynamic predicates cannot be declared synchronized (when
necessary, declare the predicates updating the dynamic predicates as
*note synchronized: 6f.).

     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.50.0.info,  Node: Template and modes<25>,  Next: Examples<32>,  Prev: Description<31>,  Up: dynamic/1

2.3.4.15 Template and modes
...........................

     dynamic(+qualified_predicate_indicator_term)
     dynamic(+qualified_non_terminal_indicator_term)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<32>,  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: ab, *note predicate_property/2: 137.


File: TheLogtalkHandbook-3.50.0.info,  Node: info/2,  Next: meta_predicate/1,  Prev: dynamic/1,  Up: Predicate directives<3>

2.3.4.17 ‘info/2’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<32>,  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 directives: 2fe.
section for a description of the default keys.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<26>,  Next: Examples<33>,  Prev: Description<32>,  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.50.0.info,  Node: Examples<33>,  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: ae, *note mode/2: 13d, *note predicate_property/2: 137.


File: TheLogtalkHandbook-3.50.0.info,  Node: meta_predicate/1,  Next: meta_non_terminal/1,  Prev: info/2,  Up: Predicate directives<3>

2.3.4.21 ‘meta_predicate/1’
...........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<33>,  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 meta-predicates, i.e., predicates that have arguments that will
be called as goals.  An argument may also be a *note closure: 13f.
instead of a goal if the meta-predicate uses the *note call/1-N: 16d.
Logtalk built-in methods to construct and call the actual goal from the
closure and the additional arguments.

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
meta-call.  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 ‘*’.  Meta-arguments are always called in the meta-predicate *note
calling context: 140, not in the meta-predicate *note definition
context: 141.

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.

     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.50.0.info,  Node: Template and modes<27>,  Next: Examples<34>,  Prev: Description<33>,  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.50.0.info,  Node: Examples<34>,  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: 47c, *note predicate_property/2: 137.


File: TheLogtalkHandbook-3.50.0.info,  Node: meta_non_terminal/1,  Next: mode/2,  Prev: meta_predicate/1,  Up: Predicate directives<3>

2.3.4.25 ‘meta_non_terminal/1’
..............................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<34>,  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: 13f. instead of a goal if the
non-terminal uses the *note call//1-N: 1ac. Logtalk built-in methods to
construct and call the actual non-terminal from the closure and the
additional arguments.

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.50.0.info,  Node: Template and modes<28>,  Next: Examples<35>,  Prev: Description<34>,  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.50.0.info,  Node: Examples<35>,  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: 142, *note predicate_property/2: 137.


File: TheLogtalkHandbook-3.50.0.info,  Node: mode/2,  Next: multifile/1,  Prev: meta_non_terminal/1,  Up: Predicate directives<3>

2.3.4.29 ‘mode/2’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<35>,  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 instantiation mode and the
corresponding number of proofs (not necessarily distinct solutions).
You may also use this directive for documenting grammar rule
non-terminals.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<29>,  Next: Examples<36>,  Prev: Description<35>,  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.50.0.info,  Node: Examples<36>,  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 info/2: 156, *note predicate_property/2: 137.


File: TheLogtalkHandbook-3.50.0.info,  Node: multifile/1,  Next: private/1,  Prev: mode/2,  Up: Predicate directives<3>

2.3.4.33 ‘multifile/1’
......................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<36>,  Next: Template and modes<30>,  Up: multifile/1

2.3.4.34 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 multifile 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: 1c5. 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.50.0.info,  Node: Template and modes<30>,  Next: Examples<37>,  Prev: Description<36>,  Up: multifile/1

2.3.4.35 Template and modes
...........................

     multifile(+qualified_predicate_indicator_term)
     multifile(+qualified_non_terminal_indicator_term)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<37>,  Prev: Template and modes<30>,  Up: multifile/1

2.3.4.36 Examples
.................

     :- multifile(table/3).
     :- multifile(user::hook/2).

See also
........

*note public/1: 138, *note protected/1: 139, *note private/1: 13a, *note
predicate_property/2: 137.


File: TheLogtalkHandbook-3.50.0.info,  Node: private/1,  Next: protected/1,  Prev: multifile/1,  Up: Predicate directives<3>

2.3.4.37 ‘private/1’
....................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<37>,  Next: Template and modes<31>,  Up: private/1

2.3.4.38 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 private 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: 17a. and *note phrase/3:
17b. methods from the object containing the private directive.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<31>,  Next: Examples<38>,  Prev: Description<37>,  Up: private/1

2.3.4.39 Template and modes
...........................

     private(+predicate_indicator_term)
     private(+non_terminal_indicator_term)
     private(+operator_declaration)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<38>,  Prev: Template and modes<31>,  Up: private/1

2.3.4.40 Examples
.................

     :- private(counter/1).

     :- private((init/1, free/1)).

     :- private([data/3, key/1, keys/1]).

See also
........

*note protected/1: 139, *note public/1: 138, *note predicate_property/2:
137.


File: TheLogtalkHandbook-3.50.0.info,  Node: protected/1,  Next: public/1,  Prev: private/1,  Up: Predicate directives<3>

2.3.4.41 ‘protected/1’
......................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<38>,  Next: Template and modes<32>,  Up: protected/1

2.3.4.42 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 protected 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: 17a. and *note phrase/3: 17b. 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.50.0.info,  Node: Template and modes<32>,  Next: Examples<39>,  Prev: Description<38>,  Up: protected/1

2.3.4.43 Template and modes
...........................

     protected(+predicate_indicator_term)
     protected(+non_terminal_indicator_term)
     protected(+operator_declaration)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<39>,  Prev: Template and modes<32>,  Up: protected/1

2.3.4.44 Examples
.................

     :- protected(init/1).

     :- protected((print/2, convert/4)).

     :- protected([load/1, save/3]).

See also
........

*note private/1: 13a, *note public/1: 138, *note predicate_property/2:
137.


File: TheLogtalkHandbook-3.50.0.info,  Node: public/1,  Next: synchronized/1,  Prev: protected/1,  Up: Predicate directives<3>

2.3.4.45 ‘public/1’
...................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<39>,  Next: Template and modes<33>,  Up: public/1

2.3.4.46 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 public 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: 17a.
and *note phrase/3: 17b. 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.


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<33>,  Next: Examples<40>,  Prev: Description<39>,  Up: public/1

2.3.4.47 Template and modes
...........................

     public(+predicate_indicator_term)
     public(+non_terminal_indicator_term)
     public(+operator_declaration)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<40>,  Prev: Template and modes<33>,  Up: public/1

2.3.4.48 Examples
.................

     :- public(ancestor/1).

     :- public((instance/1, instances/1)).

     :- public([leaf/1, leaves/1]).

See also
........

*note private/1: 13a, *note protected/1: 139, *note
predicate_property/2: 137.


File: TheLogtalkHandbook-3.50.0.info,  Node: synchronized/1,  Next: uses/2,  Prev: public/1,  Up: Predicate directives<3>

2.3.4.49 ‘synchronized/1’
.........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<40>,  Next: Template and modes<34>,  Up: synchronized/1

2.3.4.50 Description
....................

     synchronized(Name/Arity)
     synchronized((Name/Arity, ...))
     synchronized([Name/Arity, ...])

     synchronized(Name//Arity)
     synchronized((Name//Arity, ...))
     synchronized([Name//Arity, ...])

Declares synchronized 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: 32, calls to synchronized predicates behave as wrapped by
     the standard *note once/1: 19e. meta-predicate.

Note that synchronized predicates cannot be declared *note dynamic: 149.
(when necessary, declare the predicates updating the dynamic predicates
as synchronized).


File: TheLogtalkHandbook-3.50.0.info,  Node: Template and modes<34>,  Next: Examples<41>,  Prev: Description<40>,  Up: synchronized/1

2.3.4.51 Template and modes
...........................

     synchronized(+predicate_indicator_term)
     synchronized(+non_terminal_indicator_term)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<41>,  Prev: Template and modes<34>,  Up: synchronized/1

2.3.4.52 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: 137.


File: TheLogtalkHandbook-3.50.0.info,  Node: uses/2,  Next: use_module/2,  Prev: synchronized/1,  Up: Predicate directives<3>

2.3.4.53 ‘uses/2’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<41>,  Next: Template and modes<35>,  Up: uses/2

2.3.4.54 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 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: 193. and *note reflection: 1a7. 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 ‘uses/2’
directives or for giving more meaningful names considering the calling
context of the predicates.  For predicates, 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: 33, 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:
9d. 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: 34. 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.50.0.info,  Node: Template and modes<35>,  Next: Examples<42>,  Prev: Description<41>,  Up: uses/2

2.3.4.55 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.50.0.info,  Node: Examples<42>,  Prev: Template and modes<35>,  Up: uses/2

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

An example of using a *note parameter variable: 9d. 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: b5, *note use_module/1: 49, *note use_module/2: 4a, *note
alias/2: 153.


File: TheLogtalkHandbook-3.50.0.info,  Node: use_module/2,  Prev: uses/2,  Up: Predicate directives<3>

2.3.4.57 ‘use_module/2’
.......................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<42>,  Next: Template and modes<36>,  Up: use_module/2

2.3.4.58 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 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: 193. and *note reflection: 1a7. 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: 48. directives or for giving more meaningful names considering
the calling context of the predicates.  For predicates, 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 of
the used *note backend Prolog compiler: 32. 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: 1bb. 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:
9d. 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: 34. 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.50.0.info,  Node: Template and modes<36>,  Next: Examples<43>,  Prev: Description<42>,  Up: use_module/2

2.3.4.59 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.50.0.info,  Node: Examples<43>,  Prev: Template and modes<36>,  Up: use_module/2

2.3.4.60 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: 9d. 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: 49, *note uses/2: 48, *note uses/1: b5, *note
alias/2: 153.


File: TheLogtalkHandbook-3.50.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.50.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
---------------------------------------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.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<43>.
* Modes and number of proofs: Modes and number of proofs<7>.
* Errors: Errors<8>.
* Examples: Examples<44>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<43>,  Next: Modes and number of proofs<7>,  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.50.0.info,  Node: Modes and number of proofs<7>,  Next: Errors<8>,  Prev: Description<43>,  Up: current_category/1

2.4.1.3 Modes and number of proofs
..................................

     current_category(?category_identifier) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<8>,  Next: Examples<44>,  Prev: Modes and number of proofs<7>,  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.50.0.info,  Node: Examples<44>,  Prev: Errors<8>,  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: ee, *note category_property/2: 122, *note
create_category/4: 110, *note complements_object/2: be, *note
extends_category/2-3: 11f, *note imports_category/2-3: bb.


File: TheLogtalkHandbook-3.50.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<44>.
* Modes and number of proofs: Modes and number of proofs<8>.
* Errors: Errors<9>.
* Examples: Examples<45>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<44>,  Next: Modes and number of proofs<8>,  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.50.0.info,  Node: Modes and number of proofs<8>,  Next: Errors<9>,  Prev: Description<44>,  Up: current_object/1

2.4.1.8 Modes and number of proofs
..................................

     current_object(?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<9>,  Next: Examples<45>,  Prev: Modes and number of proofs<8>,  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.50.0.info,  Node: Examples<45>,  Prev: Errors<9>,  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: 5f, *note create_object/4: 5d, *note
object_property/2: c1, *note extends_object/2-3: ba, *note
instantiates_class/2-3: b8, *note specializes_class/2-3: b9, *note
complements_object/2: be.


File: TheLogtalkHandbook-3.50.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<45>.
* Modes and number of proofs: Modes and number of proofs<9>.
* Errors: Errors<10>.
* Examples: Examples<46>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<45>,  Next: Modes and number of proofs<9>,  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.50.0.info,  Node: Modes and number of proofs<9>,  Next: Errors<10>,  Prev: Description<45>,  Up: current_protocol/1

2.4.1.13 Modes and number of proofs
...................................

     current_protocol(?protocol_identifier) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<10>,  Next: Examples<46>,  Prev: Modes and number of proofs<9>,  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.50.0.info,  Node: Examples<46>,  Prev: Errors<10>,  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: df, *note create_protocol/3: dc, *note
protocol_property/2: ed, *note conforms_to_protocol/2-3: bd, *note
extends_protocol/2-3: e9, *note implements_protocol/2-3: bc.


File: TheLogtalkHandbook-3.50.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
--------------------------------------------------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.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<46>.
* Modes and number of proofs: Modes and number of proofs<10>.
* Errors: Errors<11>.
* Examples: Examples<47>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<46>,  Next: Modes and number of proofs<10>,  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: c3. and described in the User Manual
section on *note category properties: 120.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<10>,  Next: Errors<11>,  Prev: Description<46>,  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.50.0.info,  Node: Errors<11>,  Next: Examples<47>,  Prev: Modes and number of proofs<10>,  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.50.0.info,  Node: Examples<47>,  Prev: Errors<11>,  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: ee, *note create_category/4: 110, *note
current_category/1: ea, *note complements_object/2: be, *note
extends_category/2-3: 11f, *note imports_category/2-3: bb.


File: TheLogtalkHandbook-3.50.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<47>.
* Modes and number of proofs: Modes and number of proofs<11>.
* Errors: Errors<12>.
* Examples: Examples<48>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<47>,  Next: Modes and number of proofs<11>,  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: c3. and described in the User Manual
section on *note object properties: c0.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<11>,  Next: Errors<12>,  Prev: Description<47>,  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.50.0.info,  Node: Errors<12>,  Next: Examples<48>,  Prev: Modes and number of proofs<11>,  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.50.0.info,  Node: Examples<48>,  Prev: Errors<12>,  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: 5f, *note create_object/4: 5d, *note
current_object/1: a0, *note extends_object/2-3: ba, *note
instantiates_class/2-3: b8, *note specializes_class/2-3: b9, *note
complements_object/2: be.


File: TheLogtalkHandbook-3.50.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<48>.
* Modes and number of proofs: Modes and number of proofs<12>.
* Errors: Errors<13>.
* Examples: Examples<49>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<48>,  Next: Modes and number of proofs<12>,  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: c3. and described
in the User Manual section on *note protocol properties: ec.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<12>,  Next: Errors<13>,  Prev: Description<48>,  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.50.0.info,  Node: Errors<13>,  Next: Examples<49>,  Prev: Modes and number of proofs<12>,  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.50.0.info,  Node: Examples<49>,  Prev: Errors<13>,  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: df, *note create_protocol/3: dc, *note
current_protocol/1: d9, *note conforms_to_protocol/2-3: bd, *note
extends_protocol/2-3: e9, *note implements_protocol/2-3: bc.


File: TheLogtalkHandbook-3.50.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
----------------------------------------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.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<49>.
* Modes and number of proofs: Modes and number of proofs<13>.
* Errors: Errors<14>.
* Examples: Examples<50>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<49>,  Next: Modes and number of proofs<13>,  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: 32. with bounded integer support.  The portable solution, when
creating a large number of dynamic category 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: 9c. 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.50.0.info,  Node: Modes and number of proofs<13>,  Next: Errors<14>,  Prev: Description<49>,  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.50.0.info,  Node: Errors<14>,  Next: Examples<50>,  Prev: Modes and number of proofs<13>,  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.50.0.info,  Node: Examples<50>,  Prev: Errors<14>,  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: ee, *note category_property/2: 122, *note
current_category/1: ea, *note complements_object/2: be, *note
extends_category/2-3: 11f, *note imports_category/2-3: bb.


File: TheLogtalkHandbook-3.50.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<50>.
* Modes and number of proofs: Modes and number of proofs<14>.
* Errors: Errors<15>.
* Examples: Examples<51>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<50>,  Next: Modes and number of proofs<14>,  Up: create_object/4

2.4.3.7 Description
...................

     create_object(Identifier, Relations, Directives, Clauses)

Creates a new, dynamic object.  The word *note object: 4e0. 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: 32. 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: 9c. 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.50.0.info,  Node: Modes and number of proofs<14>,  Next: Errors<15>,  Prev: Description<50>,  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.50.0.info,  Node: Errors<15>,  Next: Examples<51>,  Prev: Modes and number of proofs<14>,  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.50.0.info,  Node: Examples<51>,  Prev: Errors<15>,  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: 5f, *note current_object/1: a0, *note
object_property/2: c1, *note extends_object/2-3: ba, *note
instantiates_class/2-3: b8, *note specializes_class/2-3: b9, *note
complements_object/2: be.


File: TheLogtalkHandbook-3.50.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<51>.
* Modes and number of proofs: Modes and number of proofs<15>.
* Errors: Errors<16>.
* Examples: Examples<52>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<51>,  Next: Modes and number of proofs<15>,  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: 32. 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.50.0.info,  Node: Modes and number of proofs<15>,  Next: Errors<16>,  Prev: Description<51>,  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.50.0.info,  Node: Errors<16>,  Next: Examples<52>,  Prev: Modes and number of proofs<15>,  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.50.0.info,  Node: Examples<52>,  Prev: Errors<16>,  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: df, *note current_protocol/1: d9, *note
protocol_property/2: ed, *note conforms_to_protocol/2-3: bd, *note
extends_protocol/2-3: e9, *note implements_protocol/2-3: bc.


File: TheLogtalkHandbook-3.50.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
--------------------------------------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.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<52>.
* Modes and number of proofs: Modes and number of proofs<16>.
* Errors: Errors<17>.
* Examples: Examples<53>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<52>,  Next: Modes and number of proofs<16>,  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.50.0.info,  Node: Modes and number of proofs<16>,  Next: Errors<17>,  Prev: Description<52>,  Up: abolish_category/1

2.4.4.3 Modes and number of proofs
..................................

     abolish_category(+category_identifier) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<17>,  Next: Examples<53>,  Prev: Modes and number of proofs<16>,  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.50.0.info,  Node: Examples<53>,  Prev: Errors<17>,  Up: abolish_category/1

2.4.4.5 Examples
................

     | ?- abolish_category(monitoring).

See also
........

*note category_property/2: 122, *note create_category/4: 110, *note
current_category/1: ea. *note complements_object/2: be, *note
extends_category/2-3: 11f, *note imports_category/2-3: bb.


File: TheLogtalkHandbook-3.50.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<53>.
* Modes and number of proofs: Modes and number of proofs<17>.
* Errors: Errors<18>.
* Examples: Examples<54>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<53>,  Next: Modes and number of proofs<17>,  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.50.0.info,  Node: Modes and number of proofs<17>,  Next: Errors<18>,  Prev: Description<53>,  Up: abolish_object/1

2.4.4.8 Modes and number of proofs
..................................

     abolish_object(+object_identifier) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<18>,  Next: Examples<54>,  Prev: Modes and number of proofs<17>,  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.50.0.info,  Node: Examples<54>,  Prev: Errors<18>,  Up: abolish_object/1

2.4.4.10 Examples
.................

     | ?- abolish_object(list).

See also
........

*note create_object/4: 5d, *note current_object/1: a0, *note
object_property/2: c1, *note extends_object/2-3: ba, *note
instantiates_class/2-3: b8, *note specializes_class/2-3: b9, *note
complements_object/2: be.


File: TheLogtalkHandbook-3.50.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<54>.
* Modes and number of proofs: Modes and number of proofs<18>.
* Errors: Errors<19>.
* Examples: Examples<55>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<54>,  Next: Modes and number of proofs<18>,  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.50.0.info,  Node: Modes and number of proofs<18>,  Next: Errors<19>,  Prev: Description<54>,  Up: abolish_protocol/1

2.4.4.13 Modes and number of proofs
...................................

     abolish_protocol(@protocol_identifier) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<19>,  Next: Examples<55>,  Prev: Modes and number of proofs<18>,  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.50.0.info,  Node: Examples<55>,  Prev: Errors<19>,  Up: abolish_protocol/1

2.4.4.15 Examples
.................

     | ?- abolish_protocol(listp).

See also
........

*note create_protocol/3: dc, *note current_protocol/1: d9, *note
protocol_property/2: ed, *note conforms_to_protocol/2-3: bd, *note
extends_protocol/2-3: e9, *note implements_protocol/2-3: bc.


File: TheLogtalkHandbook-3.50.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
--------------------------------------------------

* 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.50.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<55>.
* Modes and number of proofs: Modes and number of proofs<19>.
* Errors: Errors<20>.
* Examples: Examples<56>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<55>,  Next: Modes and number of proofs<19>,  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.50.0.info,  Node: Modes and number of proofs<19>,  Next: Errors<20>,  Prev: Description<55>,  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.50.0.info,  Node: Errors<20>,  Next: Examples<56>,  Prev: Modes and number of proofs<19>,  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.50.0.info,  Node: Examples<56>,  Prev: Errors<20>,  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: a0, *note instantiates_class/2-3: b8, *note
specializes_class/2-3: b9.


File: TheLogtalkHandbook-3.50.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<56>.
* Modes and number of proofs: Modes and number of proofs<20>.
* Errors: Errors<21>.
* Examples: Examples<57>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<56>,  Next: Modes and number of proofs<20>,  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.50.0.info,  Node: Modes and number of proofs<20>,  Next: Errors<21>,  Prev: Description<56>,  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.50.0.info,  Node: Errors<21>,  Next: Examples<57>,  Prev: Modes and number of proofs<20>,  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.50.0.info,  Node: Examples<57>,  Prev: Errors<21>,  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: d9, *note implements_protocol/2-3: bc, *note
conforms_to_protocol/2-3: bd.


File: TheLogtalkHandbook-3.50.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<57>.
* Modes and number of proofs: Modes and number of proofs<21>.
* Errors: Errors<22>.
* Examples: Examples<58>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<57>,  Next: Modes and number of proofs<21>,  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.50.0.info,  Node: Modes and number of proofs<21>,  Next: Errors<22>,  Prev: Description<57>,  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.50.0.info,  Node: Errors<22>,  Next: Examples<58>,  Prev: Modes and number of proofs<21>,  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.50.0.info,  Node: Examples<58>,  Prev: Errors<22>,  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: ea, *note complements_object/2: be, *note
imports_category/2-3: bb.


File: TheLogtalkHandbook-3.50.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<58>.
* Modes and number of proofs: Modes and number of proofs<22>.
* Errors: Errors<23>.
* Examples: Examples<59>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<58>,  Next: Modes and number of proofs<22>,  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; it does not implement a
transitive closure.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<22>,  Next: Errors<23>,  Prev: Description<58>,  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.50.0.info,  Node: Errors<23>,  Next: Examples<59>,  Prev: Modes and number of proofs<22>,  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.50.0.info,  Node: Examples<59>,  Prev: Errors<23>,  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: a0, *note current_protocol/1: d9, *note
current_category/1: ea, *note conforms_to_protocol/2-3: bd.


File: TheLogtalkHandbook-3.50.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<59>.
* Modes and number of proofs: Modes and number of proofs<23>.
* Errors: Errors<24>.
* Examples: Examples<60>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<59>,  Next: Modes and number of proofs<23>,  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.50.0.info,  Node: Modes and number of proofs<23>,  Next: Errors<24>,  Prev: Description<59>,  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.50.0.info,  Node: Errors<24>,  Next: Examples<60>,  Prev: Modes and number of proofs<23>,  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.50.0.info,  Node: Examples<60>,  Prev: Errors<24>,  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: a0, *note current_protocol/1: d9, *note
current_category/1: ea, *note implements_protocol/2-3: bc.


File: TheLogtalkHandbook-3.50.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<60>.
* Modes and number of proofs: Modes and number of proofs<24>.
* Errors: Errors<25>.
* Examples: Examples<61>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<60>,  Next: Modes and number of proofs<24>,  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.50.0.info,  Node: Modes and number of proofs<24>,  Next: Errors<25>,  Prev: Description<60>,  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.50.0.info,  Node: Errors<25>,  Next: Examples<61>,  Prev: Modes and number of proofs<24>,  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.50.0.info,  Node: Examples<61>,  Prev: Errors<25>,  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: ea, *note imports_category/2-3: bb.


File: TheLogtalkHandbook-3.50.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<61>.
* Modes and number of proofs: Modes and number of proofs<25>.
* Errors: Errors<26>.
* Examples: Examples<62>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<61>,  Next: Modes and number of proofs<25>,  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.50.0.info,  Node: Modes and number of proofs<25>,  Next: Errors<26>,  Prev: Description<61>,  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.50.0.info,  Node: Errors<26>,  Next: Examples<62>,  Prev: Modes and number of proofs<25>,  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.50.0.info,  Node: Examples<62>,  Prev: Errors<26>,  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: ea, *note complements_object/2: be.


File: TheLogtalkHandbook-3.50.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<62>.
* Modes and number of proofs: Modes and number of proofs<26>.
* Errors: Errors<27>.
* Examples: Examples<63>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<62>,  Next: Modes and number of proofs<26>,  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.50.0.info,  Node: Modes and number of proofs<26>,  Next: Errors<27>,  Prev: Description<62>,  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.50.0.info,  Node: Errors<27>,  Next: Examples<63>,  Prev: Modes and number of proofs<26>,  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.50.0.info,  Node: Examples<63>,  Prev: Errors<27>,  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: a0, *note extends_object/2-3: ba, *note
specializes_class/2-3: b9.


File: TheLogtalkHandbook-3.50.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<63>.
* Modes and number of proofs: Modes and number of proofs<27>.
* Errors: Errors<28>.
* Examples: Examples<64>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<63>,  Next: Modes and number of proofs<27>,  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.50.0.info,  Node: Modes and number of proofs<27>,  Next: Errors<28>,  Prev: Description<63>,  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.50.0.info,  Node: Errors<28>,  Next: Examples<64>,  Prev: Modes and number of proofs<27>,  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.50.0.info,  Node: Examples<64>,  Prev: Errors<28>,  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: a0, *note extends_object/2-3: ba, *note
instantiates_class/2-3: b8.


File: TheLogtalkHandbook-3.50.0.info,  Node: Event handling<2>,  Next: Multi-threading,  Prev: Objects categories and protocols relations,  Up: Built-in predicates

2.4.6 Event handling
--------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: abolish_events/5,  Next: current_event/5,  Up: Event handling<2>

2.4.6.1 ‘abolish_events/5’
..........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<64>,  Next: Modes and number of proofs<28>,  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.50.0.info,  Node: Modes and number of proofs<28>,  Next: Errors<29>,  Prev: Description<64>,  Up: abolish_events/5

2.4.6.3 Modes and number of proofs
..................................

     abolish_events(@term, @term, @term, @term, @term) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<29>,  Next: Examples<65>,  Prev: Modes and number of proofs<28>,  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.50.0.info,  Node: Examples<65>,  Prev: Errors<29>,  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: 1ff, *note define_events/5: 1f9, *note before/3:
fa, *note after/3: fb.


File: TheLogtalkHandbook-3.50.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<65>.
* Modes and number of proofs: Modes and number of proofs<29>.
* Errors: Errors<30>.
* Examples: Examples<66>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<65>,  Next: Modes and number of proofs<29>,  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.50.0.info,  Node: Modes and number of proofs<29>,  Next: Errors<30>,  Prev: Description<65>,  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.50.0.info,  Node: Errors<30>,  Next: Examples<66>,  Prev: Modes and number of proofs<29>,  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.50.0.info,  Node: Examples<66>,  Prev: Errors<30>,  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: 1fc, *note define_events/5: 1f9, *note before/3:
fa, *note after/3: fb.


File: TheLogtalkHandbook-3.50.0.info,  Node: define_events/5,  Prev: current_event/5,  Up: Event handling<2>

2.4.6.11 ‘define_events/5’
..........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<66>,  Next: Modes and number of proofs<30>,  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.50.0.info,  Node: Modes and number of proofs<30>,  Next: Errors<31>,  Prev: Description<66>,  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.50.0.info,  Node: Errors<31>,  Next: Examples<67>,  Prev: Modes and number of proofs<30>,  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.50.0.info,  Node: Examples<67>,  Prev: Errors<31>,  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: 1fc, *note current_event/5: 1ff, *note before/3:
fa, *note after/3: fb.


File: TheLogtalkHandbook-3.50.0.info,  Node: Multi-threading,  Next: Multi-threading engines,  Prev: Event handling<2>,  Up: Built-in predicates

2.4.7 Multi-threading
---------------------

* 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.50.0.info,  Node: threaded/1,  Next: threaded_call/1-2,  Up: Multi-threading

2.4.7.1 ‘threaded/1’
....................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<67>,  Next: Modes and number of proofs<31>,  Up: threaded/1

2.4.7.2 Description
...................

     threaded(Goals)

     threaded(Conjunction)
     threaded(Disjunction)

Proves each goal in a conjunction (disjunction) of goals in its own
thread.  This 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.

When the argument is a disjunction of goals, a call to this predicate
blocks until either one of the goals succeeds, all the goals fail, or
one of the goals generate an exception; the success 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'
one of the goals is true.

When the predicate argument is neither a conjunction not a disjunction
of goals, no threads are used.  In this case, the predicate call is
equivalent to a ‘once/1’ predicate call.

     Note: This predicate requires a *note backend Prolog compiler: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 206. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<31>,  Next: Errors<32>,  Prev: Description<67>,  Up: threaded/1

2.4.7.3 Modes and number of proofs
..................................

     threaded(+callable) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<32>,  Next: Examples<68>,  Prev: Modes and number of proofs<31>,  Up: threaded/1

2.4.7.4 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.50.0.info,  Node: Examples<68>,  Prev: Errors<32>,  Up: threaded/1

2.4.7.5 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: 211, *note threaded_once/1-2: 213, *note
threaded_ignore/1: 218, *note synchronized/1: 6f.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_call/1-2,  Next: threaded_once/1-2,  Prev: threaded/1,  Up: Multi-threading

2.4.7.6 ‘threaded_call/1-2’
...........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<68>,  Next: Modes and number of proofs<32>,  Up: threaded_call/1-2

2.4.7.7 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 succeeds and
return immediately.  The results (success, failure, or exception) are
sent back to the message queue of the object containing the call (*note
this: 169.) and can be retrieved by calling the *note threaded_exit/1:
212. predicate.

The ‘threaded_call/2’ variant returns a threaded call identifier tag
that can be used with the *note threaded_exit/2: 212. and *note
threaded_cancel/1: 215. predicates.  Tags shall be regarded as opaque
terms; users shall not rely on its type.

     Note: This predicate requires a *note backend Prolog compiler: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 206. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<32>,  Next: Errors<33>,  Prev: Description<68>,  Up: threaded_call/1-2

2.4.7.8 Modes and number of proofs
..................................

     threaded_call(@callable) - one
     threaded_call(@callable, --nonvar) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<33>,  Next: Examples<69>,  Prev: Modes and number of proofs<32>,  Up: threaded_call/1-2

2.4.7.9 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: 
          ‘type_error(variable, Goal)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<69>,  Prev: Errors<33>,  Up: threaded_call/1-2

2.4.7.10 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: 212, *note threaded_ignore/1: 218, *note
threaded_once/1-2: 213, *note threaded_peek/1-2: 214, *note
threaded_cancel/1: 215, *note threaded/1: 20c, *note synchronized/1: 6f.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_once/1-2,  Next: threaded_ignore/1,  Prev: threaded_call/1-2,  Up: Multi-threading

2.4.7.11 ‘threaded_once/1-2’
............................

* Menu:

* Description: Description<69>.
* Modes and number of proofs: Modes and number of proofs<33>.
* Errors: Errors<34>.
* Examples: Examples<70>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<69>,  Next: Modes and number of proofs<33>,  Up: threaded_once/1-2

2.4.7.12 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: 169.).

The ‘threaded_once/2’ variant returns a threaded call identifier tag
that can be used with the *note threaded_exit/2: 212. and *note
threaded_cancel/1: 215. predicates.  Tags shall be regarded as opaque
terms; users shall not rely on its type.

     Note: This predicate requires a *note backend Prolog compiler: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 206. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<33>,  Next: Errors<34>,  Prev: Description<69>,  Up: threaded_once/1-2

2.4.7.13 Modes and number of proofs
...................................

     threaded_once(@callable) - one
     threaded_once(@callable, --nonvar) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<34>,  Next: Examples<70>,  Prev: Modes and number of proofs<33>,  Up: threaded_once/1-2

2.4.7.14 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: 
          ‘type_error(variable, Goal)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<70>,  Prev: Errors<34>,  Up: threaded_once/1-2

2.4.7.15 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: 211, *note threaded_exit/1-2: 212, *note
threaded_ignore/1: 218, *note threaded_peek/1-2: 214, *note
threaded_cancel/1: 215, *note threaded/1: 20c, *note synchronized/1: 6f.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_ignore/1,  Next: threaded_exit/1-2,  Prev: threaded_once/1-2,  Up: Multi-threading

2.4.7.16 ‘threaded_ignore/1’
............................

* Menu:

* Description: Description<70>.
* Modes and number of proofs: Modes and number of proofs<34>.
* Errors: Errors<35>.
* Examples: Examples<71>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<70>,  Next: Modes and number of proofs<34>,  Up: threaded_ignore/1

2.4.7.17 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: 169.).

     Note: This predicate requires a *note backend Prolog compiler: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 206. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<34>,  Next: Errors<35>,  Prev: Description<70>,  Up: threaded_ignore/1

2.4.7.18 Modes and number of proofs
...................................

     threaded_ignore(@callable) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<35>,  Next: Examples<71>,  Prev: Modes and number of proofs<34>,  Up: threaded_ignore/1

2.4.7.19 Errors
...............

     ‘Goal’ is a variable: 
          ‘instantiation_error’ 
     ‘Goal’ is neither a variable nor a callable term: 
          ‘type_error(callable, Goal)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<71>,  Prev: Errors<35>,  Up: threaded_ignore/1

2.4.7.20 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: 211, *note threaded_exit/1-2: 212, *note
threaded_once/1-2: 213, *note threaded_peek/1-2: 214, *note threaded/1:
20c, *note synchronized/1: 6f.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_exit/1-2,  Next: threaded_peek/1-2,  Prev: threaded_ignore/1,  Up: Multi-threading

2.4.7.21 ‘threaded_exit/1-2’
............................

* Menu:

* Description: Description<71>.
* Modes and number of proofs: Modes and number of proofs<35>.
* Errors: Errors<36>.
* Examples: Examples<72>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<71>,  Next: Modes and number of proofs<35>,  Up: threaded_exit/1-2

2.4.7.22 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: 169. 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: 211. or *note threaded_once/1:
213. 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: 211. and *note
threaded_once/2: 213. predicates.  Tags shall be regarded as an opaque
term; users shall not rely on its type.

     Note: This predicate requires a *note backend Prolog compiler: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 206. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<35>,  Next: Errors<36>,  Prev: Description<71>,  Up: threaded_exit/1-2

2.4.7.23 Modes and number of proofs
...................................

     threaded_exit(+callable) - zero_or_more
     threaded_exit(+callable, +nonvar) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<36>,  Next: Examples<72>,  Prev: Modes and number of proofs<35>,  Up: threaded_exit/1-2

2.4.7.24 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’: 
          ‘existence_error(goal_thread, Goal)’ 
     ‘Tag’ is a variable: 
          ‘instantiation_error’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<72>,  Prev: Errors<36>,  Up: threaded_exit/1-2

2.4.7.25 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: 211, *note threaded_ignore/1: 218, *note
threaded_once/1-2: 213, *note threaded_peek/1-2: 214, *note
threaded_cancel/1: 215, *note threaded/1: 20c.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_peek/1-2,  Next: threaded_cancel/1,  Prev: threaded_exit/1-2,  Up: Multi-threading

2.4.7.26 ‘threaded_peek/1-2’
............................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<72>,  Next: Modes and number of proofs<36>,  Up: threaded_peek/1-2

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

The argument of this predicate should be a `variant' of the argument of
the corresponding *note threaded_call/1: 211. or *note threaded_once/1:
213. 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: 211. and *note
threaded_once/2: 213. predicates.  Tags shall be regarded as an opaque
term; users shall not rely on its type.

     Note: This predicate requires a *note backend Prolog compiler: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 206. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<36>,  Next: Errors<37>,  Prev: Description<72>,  Up: threaded_peek/1-2

2.4.7.28 Modes and number of proofs
...................................

     threaded_peek(+callable) - zero_or_one
     threaded_peek(+callable, +nonvar) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<37>,  Next: Examples<73>,  Prev: Modes and number of proofs<36>,  Up: threaded_peek/1-2

2.4.7.29 Errors
...............

     ‘Goal’ is a variable: 
          ‘instantiation_error’ 
     ‘Goal’ is neither a variable nor a callable term: 
          ‘type_error(callable, Goal)’ 
     ‘Tag’ is a variable: 
          ‘instantiation_error’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<73>,  Prev: Errors<37>,  Up: threaded_peek/1-2

2.4.7.30 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: 211, *note threaded_exit/1-2: 212, *note
threaded_ignore/1: 218, *note threaded_once/1-2: 213, *note
threaded_cancel/1: 215, *note threaded/1: 20c.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_cancel/1,  Next: threaded_wait/1,  Prev: threaded_peek/1-2,  Up: Multi-threading

2.4.7.31 ‘threaded_cancel/1’
............................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<73>,  Next: Modes and number of proofs<37>,  Up: threaded_cancel/1

2.4.7.32 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 have already terminated or canceled.  The threaded call identifier
tag is generated by calls to the *note threaded_call/2: 211. and *note
threaded_once/2: 213. predicates.  Tags shall be regarded as an opaque
term; users shall not rely on its type.

     Note: This predicate requires a *note backend Prolog compiler: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 206. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<37>,  Next: Errors<38>,  Prev: Description<73>,  Up: threaded_cancel/1

2.4.7.33 Modes and number of proofs
...................................

     threaded_cancel(+nonvar) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<38>,  Next: Examples<74>,  Prev: Modes and number of proofs<37>,  Up: threaded_cancel/1

2.4.7.34 Errors
...............

     ‘Tag’ is a variable: 
          ‘instantiation_error’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<74>,  Prev: Errors<38>,  Up: threaded_cancel/1

2.4.7.35 Examples
.................

(none)

See also
........

*note threaded_call/1-2: 211, *note threaded_exit/1-2: 212, *note
threaded_ignore/1: 218, *note threaded_once/1-2: 213, *note threaded/1:
20c.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_wait/1,  Next: threaded_notify/1,  Prev: threaded_cancel/1,  Up: Multi-threading

2.4.7.36 ‘threaded_wait/1’
..........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<74>,  Next: Modes and number of proofs<38>,  Up: threaded_wait/1

2.4.7.37 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: 169.) containing the calls to the *note threaded_notify/1:
21d. 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: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 206. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<38>,  Next: Errors<39>,  Prev: Description<74>,  Up: threaded_wait/1

2.4.7.38 Modes and number of proofs
...................................

     threaded_wait(?term) - one
     threaded_wait(+list(term)) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<39>,  Next: Examples<75>,  Prev: Modes and number of proofs<38>,  Up: threaded_wait/1

2.4.7.39 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<75>,  Prev: Errors<39>,  Up: threaded_wait/1

2.4.7.40 Examples
.................

     % wait until the "data_available" notification is received:
     ..., threaded_wait(data_available), ...

See also
........

*note threaded_notify/1: 21d.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_notify/1,  Prev: threaded_wait/1,  Up: Multi-threading

2.4.7.41 ‘threaded_notify/1’
............................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<75>,  Next: Modes and number of proofs<39>,  Up: threaded_notify/1

2.4.7.42 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: 169.) containing the calls to the *note threaded_wait/1: 21c.
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: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 206. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<39>,  Next: Errors<40>,  Prev: Description<75>,  Up: threaded_notify/1

2.4.7.43 Modes and number of proofs
...................................

     threaded_notify(@term) - one
     threaded_notify(@list(term)) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<40>,  Next: Examples<76>,  Prev: Modes and number of proofs<39>,  Up: threaded_notify/1

2.4.7.44 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<76>,  Prev: Errors<40>,  Up: threaded_notify/1

2.4.7.45 Examples
.................

     % send a "data_available" notification:
     ..., threaded_notify(data_available), ...

See also
........

*note threaded_wait/1: 21c.


File: TheLogtalkHandbook-3.50.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
-----------------------------

* 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.50.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<76>.
* Modes and number of proofs: Modes and number of proofs<40>.
* Errors: Errors<41>.
* Examples: Examples<77>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<76>,  Next: Modes and number of proofs<40>,  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: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 299. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<40>,  Next: Errors<41>,  Prev: Description<76>,  Up: threaded_engine_create/3

2.4.8.3 Modes and number of proofs
..................................

     threaded_engine_create(@term, @callable, @nonvar) - one
     threaded_engine_create(@term, @callable, --nonvar) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<41>,  Next: Examples<77>,  Prev: Modes and number of proofs<40>,  Up: threaded_engine_create/3

2.4.8.4 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.50.0.info,  Node: Examples<77>,  Prev: Errors<41>,  Up: threaded_engine_create/3

2.4.8.5 Examples
................

     % create a new engine for finding members of a list:
     | ?- threaded_engine_create(X, member(X, [1,2,3]), worker_1).

See also
........

*note threaded_engine_destroy/1: 223, *note threaded_engine_self/1: 58d,
*note threaded_engine/1: 58e, *note threaded_engine_next/2: 221, *note
threaded_engine_next_reified/2: 222.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_engine_destroy/1,  Next: threaded_engine/1,  Prev: threaded_engine_create/3,  Up: Multi-threading engines

2.4.8.6 ‘threaded_engine_destroy/1’
...................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<77>,  Next: Modes and number of proofs<41>,  Up: threaded_engine_destroy/1

2.4.8.7 Description
...................

     threaded_engine_destroy(Engine)

Stops and destroys an engine.

     Note: This predicate requires a *note backend Prolog compiler: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 299. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<41>,  Next: Errors<42>,  Prev: Description<77>,  Up: threaded_engine_destroy/1

2.4.8.8 Modes and number of proofs
..................................

     threaded_engine_destroy(@nonvar) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<42>,  Next: Examples<78>,  Prev: Modes and number of proofs<41>,  Up: threaded_engine_destroy/1

2.4.8.9 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.50.0.info,  Node: Examples<78>,  Prev: Errors<42>,  Up: threaded_engine_destroy/1

2.4.8.10 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: 220, *note threaded_engine_self/1: 58d,
*note threaded_engine/1: 58e.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_engine/1,  Next: threaded_engine_self/1,  Prev: threaded_engine_destroy/1,  Up: Multi-threading engines

2.4.8.11 ‘threaded_engine/1’
............................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<78>,  Next: Modes and number of proofs<42>,  Up: threaded_engine/1

2.4.8.12 Description
....................

     threaded_engine(Engine)

Enumerates, by backtracking, all existing engines.  Engine names shall
be regarded as opaque terms; users shall not rely on its type.

     Note: This predicate requires a *note backend Prolog compiler: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 299. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<42>,  Next: Errors<43>,  Prev: Description<78>,  Up: threaded_engine/1

2.4.8.13 Modes and number of proofs
...................................

     threaded_engine(?nonvar) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<43>,  Next: Examples<79>,  Prev: Modes and number of proofs<42>,  Up: threaded_engine/1

2.4.8.14 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<79>,  Prev: Errors<43>,  Up: threaded_engine/1

2.4.8.15 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: 220, *note threaded_engine_self/1: 58d,
*note threaded_engine_destroy/1: 223.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_engine_self/1,  Next: threaded_engine_next/2,  Prev: threaded_engine/1,  Up: Multi-threading engines

2.4.8.16 ‘threaded_engine_self/1’
.................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<79>,  Next: Modes and number of proofs<43>,  Up: threaded_engine_self/1

2.4.8.17 Description
....................

     threaded_engine_self(Engine)

Queries the name of engine calling the predicate.

     Note: This predicate requires a *note backend Prolog compiler: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 299. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<43>,  Next: Errors<44>,  Prev: Description<79>,  Up: threaded_engine_self/1

2.4.8.18 Modes and number of proofs
...................................

     threaded_engine_self(?nonvar) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<44>,  Next: Examples<80>,  Prev: Modes and number of proofs<43>,  Up: threaded_engine_self/1

2.4.8.19 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<80>,  Prev: Errors<44>,  Up: threaded_engine_self/1

2.4.8.20 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: 220, *note threaded_engine_destroy/1:
223, *note threaded_engine/1: 58e.


File: TheLogtalkHandbook-3.50.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.21 ‘threaded_engine_next/2’
.................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<80>,  Next: Modes and number of proofs<44>,  Up: threaded_engine_next/2

2.4.8.22 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: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 299. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<44>,  Next: Errors<45>,  Prev: Description<80>,  Up: threaded_engine_next/2

2.4.8.23 Modes and number of proofs
...................................

     threaded_engine_next(@nonvar, ?term) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<45>,  Next: Examples<81>,  Prev: Modes and number of proofs<44>,  Up: threaded_engine_next/2

2.4.8.24 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.50.0.info,  Node: Examples<81>,  Prev: Errors<45>,  Up: threaded_engine_next/2

2.4.8.25 Examples
.................

     % get the next answer from the worker_1 engine:
     | ?- threaded_engine_next(worker_1, Answer).

See also
........

*note threaded_engine_create/3: 220, *note
threaded_engine_next_reified/2: 222, *note threaded_engine_yield/1: 226.


File: TheLogtalkHandbook-3.50.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.26 ‘threaded_engine_next_reified/2’
.........................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<81>,  Next: Modes and number of proofs<45>,  Up: threaded_engine_next_reified/2

2.4.8.27 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: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 299. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<45>,  Next: Errors<46>,  Prev: Description<81>,  Up: threaded_engine_next_reified/2

2.4.8.28 Modes and number of proofs
...................................

     threaded_engine_next_reified(@nonvar, ?nonvar) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<46>,  Next: Examples<82>,  Prev: Modes and number of proofs<45>,  Up: threaded_engine_next_reified/2

2.4.8.29 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.50.0.info,  Node: Examples<82>,  Prev: Errors<46>,  Up: threaded_engine_next_reified/2

2.4.8.30 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: 220, *note threaded_engine_next/2: 221,
*note threaded_engine_yield/1: 226.


File: TheLogtalkHandbook-3.50.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.31 ‘threaded_engine_yield/1’
..................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<82>,  Next: Modes and number of proofs<46>,  Up: threaded_engine_yield/1

2.4.8.32 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: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 299. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<46>,  Next: Errors<47>,  Prev: Description<82>,  Up: threaded_engine_yield/1

2.4.8.33 Modes and number of proofs
...................................

     threaded_engine_yield(@term) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<47>,  Next: Examples<83>,  Prev: Modes and number of proofs<46>,  Up: threaded_engine_yield/1

2.4.8.34 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<83>,  Prev: Errors<47>,  Up: threaded_engine_yield/1

2.4.8.35 Examples
.................

     % returns the atom "ready" as an engine answer:
     ..., threaded_engine_yield(ready), ...

See also
........

*note threaded_engine_create/3: 220, *note threaded_engine_next/2: 221,
*note threaded_engine_next_reified/2: 222.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_engine_post/2,  Next: threaded_engine_fetch/1,  Prev: threaded_engine_yield/1,  Up: Multi-threading engines

2.4.8.36 ‘threaded_engine_post/2’
.................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<83>,  Next: Modes and number of proofs<47>,  Up: threaded_engine_post/2

2.4.8.37 Description
....................

     threaded_engine_post(Engine, Term)

Posts a term to the engine term queue.

     Note: This predicate requires a *note backend Prolog compiler: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 299. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<47>,  Next: Errors<48>,  Prev: Description<83>,  Up: threaded_engine_post/2

2.4.8.38 Modes and number of proofs
...................................

     threaded_engine_post(@nonvar, @term) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<48>,  Next: Examples<84>,  Prev: Modes and number of proofs<47>,  Up: threaded_engine_post/2

2.4.8.39 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.50.0.info,  Node: Examples<84>,  Prev: Errors<48>,  Up: threaded_engine_post/2

2.4.8.40 Examples
.................

     % post the atom "ready" to the worker_1 engine queue:
     | ?- threaded_engine_post(worker_1, ready).

See also
........

*note threaded_engine_fetch/1: 224.


File: TheLogtalkHandbook-3.50.0.info,  Node: threaded_engine_fetch/1,  Prev: threaded_engine_post/2,  Up: Multi-threading engines

2.4.8.41 ‘threaded_engine_fetch/1’
..................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<84>,  Next: Modes and number of proofs<48>,  Up: threaded_engine_fetch/1

2.4.8.42 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: 32.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 299. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<48>,  Next: Errors<49>,  Prev: Description<84>,  Up: threaded_engine_fetch/1

2.4.8.43 Modes and number of proofs
...................................

     threaded_engine_fetch(?term) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<49>,  Next: Examples<85>,  Prev: Modes and number of proofs<48>,  Up: threaded_engine_fetch/1

2.4.8.44 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<85>,  Prev: Errors<49>,  Up: threaded_engine_fetch/1

2.4.8.45 Examples
.................

     % fetch a term from the engine term queue:
     ..., threaded_engine_fetch(Term), ...

See also
........

*note threaded_engine_post/2: 225.


File: TheLogtalkHandbook-3.50.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
----------------------------------------

* 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.50.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<85>.
* Modes and number of proofs: Modes and number of proofs<49>.
* Errors: Errors<50>.
* Examples: Examples<86>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<85>,  Next: Modes and number of proofs<49>,  Up: logtalk_compile/1

2.4.9.2 Description
...................

     logtalk_compile(File)
     logtalk_compile(Files)

Compiles to disk a *note source file: 5c4. 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: 288.  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: 143.

     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: 44. 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.50.0.info,  Node: Modes and number of proofs<49>,  Next: Errors<50>,  Prev: Description<85>,  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.50.0.info,  Node: Errors<50>,  Next: Examples<86>,  Prev: Modes and number of proofs<49>,  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.50.0.info,  Node: Examples<86>,  Prev: Errors<50>,  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: 292, *note logtalk_load/1: 44, *note
logtalk_load/2: 284, *note logtalk_make/0: 280, *note logtalk_make/1:
281, *note logtalk_library_path/2: 287.


File: TheLogtalkHandbook-3.50.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<86>.
* Modes and number of proofs: Modes and number of proofs<50>.
* Errors: Errors<51>.
* Examples: Examples<87>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<86>,  Next: Modes and number of proofs<50>,  Up: logtalk_compile/2

2.4.9.7 Description
...................

     logtalk_compile(File, Flags)
     logtalk_compile(Files, Flags)

Compiles to disk a *note source file: 5c4. 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: 288.
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: 232. section in the
User Manual.  The recognized Logtalk and Prolog file extensions are
defined in the *note backend adapter files: 143.

     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: 284. 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: 2be. 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: 1bb, the flags only apply to the
     loader file itself.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<50>,  Next: Errors<51>,  Prev: Description<86>,  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.50.0.info,  Node: Errors<51>,  Next: Examples<87>,  Prev: Modes and number of proofs<50>,  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.50.0.info,  Node: Examples<87>,  Prev: Errors<51>,  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: 27f, *note logtalk_load/1: 44, *note
logtalk_load/2: 284, *note logtalk_make/0: 280, *note logtalk_make/1:
281, *note logtalk_library_path/2: 287.


File: TheLogtalkHandbook-3.50.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<87>.
* Modes and number of proofs: Modes and number of proofs<51>.
* Errors: Errors<52>.
* Examples: Examples<88>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<87>,  Next: Modes and number of proofs<51>,  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: 5c4. 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: 288.  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: 143.

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 contents of the source
file are loaded.

Depending on the *note backend Prolog compiler: 32, the shortcuts
‘{File}’ or ‘{File1, File2, ...}’ may be used in 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.50.0.info,  Node: Modes and number of proofs<51>,  Next: Errors<52>,  Prev: Description<87>,  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.50.0.info,  Node: Errors<52>,  Next: Examples<88>,  Prev: Modes and number of proofs<51>,  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.50.0.info,  Node: Examples<88>,  Prev: Errors<52>,  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: 27f, *note logtalk_compile/2: 292, *note
logtalk_load/2: 284, *note logtalk_make/0: 280, *note logtalk_make/1:
281, *note logtalk_library_path/2: 287.


File: TheLogtalkHandbook-3.50.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<88>.
* Modes and number of proofs: Modes and number of proofs<52>.
* Errors: Errors<53>.
* Examples: Examples<89>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<88>,  Next: Modes and number of proofs<52>,  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: 5c4. 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: 288.  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: 232.
section in the User Manual.  The recognized Logtalk and Prolog file
extensions are defined in the *note backend adapter files: 143.  The
recognized Logtalk and Prolog file extensions are defined in the *note
backend adapter files: 143.

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: 2be. 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 contents of the source
file are 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: 1bb, the flags only apply to the
     loader file itself and not to the files loaded by it.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<52>,  Next: Errors<53>,  Prev: Description<88>,  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.50.0.info,  Node: Errors<53>,  Next: Examples<89>,  Prev: Modes and number of proofs<52>,  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.50.0.info,  Node: Examples<89>,  Prev: Errors<53>,  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: 27f, *note logtalk_compile/2: 292, *note
logtalk_load/1: 44, *note logtalk_make/0: 280, *note logtalk_make/1:
281, *note logtalk_library_path/2: 287.


File: TheLogtalkHandbook-3.50.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<89>.
* Modes and number of proofs: Modes and number of proofs<53>.
* Errors: Errors<54>.
* Examples: Examples<90>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<89>,  Next: Modes and number of proofs<53>,  Up: logtalk_make/0

2.4.9.22 Description
....................

     logtalk_make

Reloads all Logtalk source files that have been modified since the time
they are last loaded.  Only source files loaded using the *note
logtalk_load/1: 44. and *note logtalk_load/2: 284. predicates are
reloaded.  Non-modified files will also be reloaded when there is a
change to the compilation mode (i.e.  when the files were loaded without
explicit *note debug: 2bc. or *note optimize: 88. 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: b2. directive).

Depending on the *note backend Prolog compiler: 32, the shortcut ‘{*}’
may be used in alternative.  Check the *note adapter files: 143. 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: 5dd. multifile and dynamic hook
predicate using the argument ‘all’.  The additional user defined actions
are run after the default one.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<53>,  Next: Errors<54>,  Prev: Description<89>,  Up: logtalk_make/0

2.4.9.23 Modes and number of proofs
...................................

     logtalk_make - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<54>,  Next: Examples<90>,  Prev: Modes and number of proofs<53>,  Up: logtalk_make/0

2.4.9.24 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<90>,  Prev: Errors<54>,  Up: logtalk_make/0

2.4.9.25 Examples
.................

     % reload all files modified since last loaded:
     | ?- logtalk_make.

See also
........

*note logtalk_compile/1: 27f, *note logtalk_compile/2: 292, *note
logtalk_load/1: 44, *note logtalk_load/2: 284, *note logtalk_make/1:
281, *note logtalk_make_target_action/1: 5dd.


File: TheLogtalkHandbook-3.50.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<90>.
* Modes and number of proofs: Modes and number of proofs<54>.
* Errors: Errors<55>.
* Examples: Examples<91>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<90>,  Next: Modes and number of proofs<54>,  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: 34. 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: 2bc. and *note optimize: 88.
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: 44. and *note logtalk_load/2: 284. predicates are
reloaded.  Non-modified files will also be reloaded when there is a
change to the compilation mode (i.e.  when the files were loaded without
explicit *note debug: 2bc. or *note optimize: 88. 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: b2. directive).

When using the ‘check’ or ‘circular’ targets, be sure to compile your
source files with the *note source_data: c6. 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: 5e4. to be loaded.  See the ‘doclet’ tool documentation
for more details.

Depending on the *note backend Prolog compiler: 32, 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: 143. 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):
5dd. where ‘Target’ is one of the targets listed above.  The additional
user defined actions are run after the default ones.

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

   (1) ../../../docs/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<54>,  Next: Errors<55>,  Prev: Description<90>,  Up: logtalk_make/1

2.4.9.28 Modes and number of proofs
...................................

     logtalk_make(+atom) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<55>,  Next: Examples<91>,  Prev: Modes and number of proofs<54>,  Up: logtalk_make/1

2.4.9.29 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<91>,  Prev: Errors<55>,  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: 27f, *note logtalk_compile/2: 292, *note
logtalk_load/1: 44, *note logtalk_load/2: 284, *note logtalk_make/0:
280, *note logtalk_make_target_action/1: 5dd.


File: TheLogtalkHandbook-3.50.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<91>.
* Modes and number of proofs: Modes and number of proofs<55>.
* Errors: Errors<56>.
* Examples: Examples<92>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<91>,  Next: Modes and number of proofs<55>,  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: 281. 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.50.0.info,  Node: Modes and number of proofs<55>,  Next: Errors<56>,  Prev: Description<91>,  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.50.0.info,  Node: Errors<56>,  Next: Examples<92>,  Prev: Modes and number of proofs<55>,  Up: logtalk_make_target_action/1

2.4.9.34 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<92>,  Prev: Errors<56>,  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: 281, *note logtalk_make/0: 280.


File: TheLogtalkHandbook-3.50.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<92>.
* Modes and number of proofs: Modes and number of proofs<56>.
* Errors: Errors<57>.
* Examples: Examples<93>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<92>,  Next: Modes and number of proofs<56>,  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: 69. paths.  Library aliases may also be
used on 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: 281. built-in predicate can be used to detect and
     report duplicated library aliases using the ‘check’ target.

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: 2ee. predicate with the ‘directory’ key and
using the returned value to define the ‘logtalk_library_path/2’
predicate.  On a settings file or a *note loader file: 1bb. file, simply
use an *note initialization/1: 40. 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 also be used to override the default *note scratch
directory: 274. 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).

The *note logtalk: cb. 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) ../../../docs/logtalk_0.html#logtalk-0-expand-library-path-2


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<56>,  Next: Errors<57>,  Prev: Description<92>,  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.50.0.info,  Node: Errors<57>,  Next: Examples<93>,  Prev: Modes and number of proofs<56>,  Up: logtalk_library_path/2

2.4.9.39 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<93>,  Prev: Errors<57>,  Up: logtalk_library_path/2

2.4.9.40 Examples
.................

     :- initialization((
        logtalk_load_context(directory, Directory),
        assertz(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: 27f, *note logtalk_compile/2: 292, *note
logtalk_load/1: 44, *note logtalk_load/2: 284.


File: TheLogtalkHandbook-3.50.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<93>.
* Modes and number of proofs: Modes and number of proofs<57>.
* Errors: Errors<58>.
* Examples: Examples<94>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<93>,  Next: Modes and number of proofs<57>,  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

   * ‘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, ...]’)

   * ‘singletons’ - the singleton variables of the term being compiled
     (‘[Name1=Variable1, ...]’)

The ‘logtalk_load_context/2’ predicate can also be called *note
initialization/1: 40. directives in a source file.  A common scenario is
to use the ‘directory’ key to define *note library aliases: 5f7.

     Warning: The ‘term_position’ key is only supported in *note backend
     Prolog compilers: 32. 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.

     Currently, any 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 *note
     term_expansion/2: f5. and *note goal_expansion/2: f6. methods.

     Using the ‘variables’, ‘variable_names’, and ‘singletons’ keys may
     require calling the standard built-in predicate ‘term_variables/2’
     on the term read and unifying the term variables with the variables
     in the names list.  This, however, may rise portability issues with
     Prolog compilers that don’t return the variables in the same order
     for the ‘term_variables/2’ predicate and the option
     ‘variable_names/1’ of the ‘read_term/3’ built-in predicate, which
     is used by the Logtalk compiler to read source files.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<57>,  Next: Errors<58>,  Prev: Description<93>,  Up: logtalk_load_context/2

2.4.9.43 Modes and number of proofs
...................................

     logtalk_load_context(?atom, -nonvar) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<58>,  Next: Examples<94>,  Prev: Modes and number of proofs<57>,  Up: logtalk_load_context/2

2.4.9.44 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<94>,  Prev: Errors<58>,  Up: logtalk_load_context/2

2.4.9.45 Examples
.................

     term_expansion(Term, ExpandedTerms) :-
         ...
         logtalk_load_context(entity_identifier, Entity),
         ....

     :- initialization((
         logtalk_load_context(directory, Directory),
         assertz(logtalk_library_path(my_app, Directory))
     )).

See also
........

*note term_expansion/2: f5, *note goal_expansion/2: f6.


File: TheLogtalkHandbook-3.50.0.info,  Node: Flags,  Next: Linter,  Prev: Compiling and loading source files,  Up: Built-in predicates

2.4.10 Flags
------------

* Menu:

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


File: TheLogtalkHandbook-3.50.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<94>.
* Modes and number of proofs: Modes and number of proofs<58>.
* Errors: Errors<59>.
* Examples: Examples<95>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<94>,  Next: Modes and number of proofs<58>,  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: 232. section in the User Manual.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<58>,  Next: Errors<59>,  Prev: Description<94>,  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.50.0.info,  Node: Errors<59>,  Next: Examples<95>,  Prev: Modes and number of proofs<58>,  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.50.0.info,  Node: Examples<95>,  Prev: Errors<59>,  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: 2c0, *note set_logtalk_flag/2: 4c.


File: TheLogtalkHandbook-3.50.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<95>.
* Modes and number of proofs: Modes and number of proofs<59>.
* Errors: Errors<60>.
* Examples: Examples<96>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<95>,  Next: Modes and number of proofs<59>,  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: 4b. 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: 40. directive.
For a description of the predefined compiler flags, please see the *note
Compiler flags: 232. section in the User Manual.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<59>,  Next: Errors<60>,  Prev: Description<95>,  Up: set_logtalk_flag/2<2>

2.4.10.8 Modes and number of proofs
...................................

     set_logtalk_flag(+atom, +nonvar) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<60>,  Next: Examples<96>,  Prev: Modes and number of proofs<59>,  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.50.0.info,  Node: Examples<96>,  Prev: Errors<60>,  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: 2c0, *note current_logtalk_flag/2: 293.


File: TheLogtalkHandbook-3.50.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<96>.
* Modes and number of proofs: Modes and number of proofs<60>.
* Errors: Errors<61>.
* Examples: Examples<97>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<96>,  Next: Modes and number of proofs<60>,  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: 293. and *note
set_logtalk_flag/2: 4c. built-in predicates.  For a description of the
predefined compiler flags, please see the *note Compiler flags: 232.
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.50.0.info,  Node: Modes and number of proofs<60>,  Next: Errors<61>,  Prev: Description<96>,  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.50.0.info,  Node: Errors<61>,  Next: Examples<97>,  Prev: Modes and number of proofs<60>,  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.50.0.info,  Node: Examples<97>,  Prev: Errors<61>,  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: 293, *note set_logtalk_flag/2: 4c.


File: TheLogtalkHandbook-3.50.0.info,  Node: Linter,  Prev: Flags,  Up: Built-in predicates

2.4.11 Linter
-------------

* Menu:

* logtalk_linter_hook/7::


File: TheLogtalkHandbook-3.50.0.info,  Node: logtalk_linter_hook/7,  Up: Linter

2.4.11.1 ‘logtalk_linter_hook/7’
................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<97>,  Next: Modes and number of proofs<61>,  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.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<61>,  Next: Errors<62>,  Prev: Description<97>,  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_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<62>,  Next: Examples<98>,  Prev: Modes and number of proofs<61>,  Up: logtalk_linter_hook/7

2.4.11.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<98>,  Prev: Errors<62>,  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.50.0.info,  Node: Built-in methods<2>,  Prev: Built-in predicates,  Up: Reference Manual

2.5 Built-in methods
====================

* Menu:

* 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.50.0.info,  Node: Execution context,  Next: Reflection<2>,  Up: Built-in methods<2>

2.5.1 Execution context
-----------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: context/1,  Next: parameter/2,  Up: Execution context

2.5.1.1 ‘context/1’
...................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<98>,  Next: Modes and number of proofs<62>,  Up: context/1

2.5.1.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 a default 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.

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

   (1) ../../../docs/logtalk_0.html#logtalk-0-execution-context-7


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<62>,  Next: Errors<63>,  Prev: Description<98>,  Up: context/1

2.5.1.3 Modes and number of proofs
..................................

     context(--callable) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<63>,  Next: Examples<99>,  Prev: Modes and number of proofs<62>,  Up: context/1

2.5.1.4 Errors
..............

     ‘Context’ is not a variable: 
          ‘type_error(var, Context)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<99>,  Prev: Errors<63>,  Up: context/1

2.5.1.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: 9c, *note self/1: 62, *note sender/1: 181, *note
this/1: 63.


File: TheLogtalkHandbook-3.50.0.info,  Node: parameter/2,  Next: self/1,  Prev: context/1,  Up: Execution context

2.5.1.6 ‘parameter/2’
.....................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<99>,  Next: Modes and number of proofs<63>,  Up: parameter/2

2.5.1.7 Description
...................

     parameter(Number, Term)

Used in *note parametric objects: 628. (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 allows us to abstract parameter positions thus simplifying
code maintenance.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<63>,  Next: Errors<64>,  Prev: Description<99>,  Up: parameter/2

2.5.1.8 Modes and number of proofs
..................................

     parameter(+integer, ?term) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<64>,  Next: Examples<100>,  Prev: Modes and number of proofs<63>,  Up: parameter/2

2.5.1.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.50.0.info,  Node: Examples<100>,  Prev: Errors<64>,  Up: parameter/2

2.5.1.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: 182, *note self/1: 62, *note sender/1: 181, *note
this/1: 63.


File: TheLogtalkHandbook-3.50.0.info,  Node: self/1,  Next: sender/1,  Prev: parameter/2,  Up: Execution context

2.5.1.11 ‘self/1’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<100>,  Next: Modes and number of proofs<64>,  Up: self/1

2.5.1.12 Description
....................

     self(Self)

Returns the object that has received the message under processing.  This
private method is translated to 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 instantiated (the most common case).


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<64>,  Next: Errors<65>,  Prev: Description<100>,  Up: self/1

2.5.1.13 Modes and number of proofs
...................................

     self(?object_identifier) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<65>,  Next: Examples<101>,  Prev: Modes and number of proofs<64>,  Up: self/1

2.5.1.14 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<101>,  Prev: Errors<65>,  Up: self/1

2.5.1.15 Examples
.................

     % upon compilation, the write/1 call will be
     % the first goal on the clause body
     test :-
         self(Self),
         write('executing a method in behalf of '),
         writeq(Self), nl.

See also
........

*note context/1: 182, *note parameter/2: 9c, *note sender/1: 181, *note
this/1: 63.


File: TheLogtalkHandbook-3.50.0.info,  Node: sender/1,  Next: this/1,  Prev: self/1,  Up: Execution context

2.5.1.16 ‘sender/1’
...................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<101>,  Next: Modes and number of proofs<65>,  Up: sender/1

2.5.1.17 Description
....................

     sender(Sender)

Returns the object that has 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 instantiated (the most common case).


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<65>,  Next: Errors<66>,  Prev: Description<101>,  Up: sender/1

2.5.1.18 Modes and number of proofs
...................................

     sender(?object_identifier) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<66>,  Next: Examples<102>,  Prev: Modes and number of proofs<65>,  Up: sender/1

2.5.1.19 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<102>,  Prev: Errors<66>,  Up: sender/1

2.5.1.20 Examples
.................

     % after compilation, the write/1 call will
     % be the first goal on the clause body
     test :-
         sender(Sender),
         write('executing a method to answer a message sent by '),
         writeq(Sender), nl.

See also
........

*note context/1: 182, *note parameter/2: 9c, *note self/1: 62, *note
this/1: 63.


File: TheLogtalkHandbook-3.50.0.info,  Node: this/1,  Prev: sender/1,  Up: Execution context

2.5.1.21 ‘this/1’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<102>,  Next: Modes and number of proofs<66>,  Up: this/1

2.5.1.22 Description
....................

     this(This)

Unifies its argument with the identifier of the object for which the
predicate clause whose body is being executed is defined (or the object
importing the category that contains the predicate clause).  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 instantiated (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.50.0.info,  Node: Modes and number of proofs<66>,  Next: Errors<67>,  Prev: Description<102>,  Up: this/1

2.5.1.23 Modes and number of proofs
...................................

     this(?object_identifier) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<67>,  Next: Examples<103>,  Prev: Modes and number of proofs<66>,  Up: this/1

2.5.1.24 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<103>,  Prev: Errors<67>,  Up: this/1

2.5.1.25 Examples
.................

     % after compilation, the write/1 call will
     % be the first goal on the clause body
     test :-
         this(This),
         write('Using a predicate clause contained in '),
         writeq(This), nl.

See also
........

*note context/1: 182, *note parameter/2: 9c, *note self/1: 62, *note
sender/1: 181.


File: TheLogtalkHandbook-3.50.0.info,  Node: Reflection<2>,  Next: Database,  Prev: Execution context,  Up: Built-in methods<2>

2.5.2 Reflection
----------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: current_op/3,  Next: current_predicate/1,  Up: Reflection<2>

2.5.2.1 ‘current_op/3’
......................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<103>,  Next: Modes and number of proofs<67>,  Up: current_op/3

2.5.2.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.50.0.info,  Node: Modes and number of proofs<67>,  Next: Errors<68>,  Prev: Description<103>,  Up: current_op/3

2.5.2.3 Modes and number of proofs
..................................

     current_op(?operator_priority, ?operator_specifier, ?atom) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<68>,  Next: Examples<104>,  Prev: Modes and number of proofs<67>,  Up: current_op/3

2.5.2.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.50.0.info,  Node: Examples<104>,  Prev: Errors<68>,  Up: current_op/3

2.5.2.5 Examples
................

     To enumerate, by backtracking, the local operators or the operators visible in *note this: 169.: 
          ‘current_op(Priority, Specifier, Operator)’ 
     To enumerate, by backtracking, the public and protected operators visible in *note self: 64.: 
          ‘::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: 136, *note predicate_property/2: 137, *note
op/3: 14c.


File: TheLogtalkHandbook-3.50.0.info,  Node: current_predicate/1,  Next: predicate_property/2,  Prev: current_op/3,  Up: Reflection<2>

2.5.2.6 ‘current_predicate/1’
.............................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<104>,  Next: Modes and number of proofs<68>,  Up: current_predicate/1

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

When ‘Predicate’ is ground at compile time, this predicate also succeeds
for any predicates listed in *note uses/2: 48. and *note use_module/2:
4a. directives.

When ‘Predicate’ is bound at compile time to a ‘:/2’ term, this
predicate enumerates module predicates (assuming that the *note backend
Prolog compiler: 32. supports modules).


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<68>,  Next: Errors<69>,  Prev: Description<104>,  Up: current_predicate/1

2.5.2.8 Modes and number of proofs
..................................

     current_predicate(?predicate_indicator) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<69>,  Next: Examples<105>,  Prev: Modes and number of proofs<68>,  Up: current_predicate/1

2.5.2.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.50.0.info,  Node: Examples<105>,  Prev: Errors<69>,  Up: current_predicate/1

2.5.2.10 Examples
.................

     To enumerate, by backtracking, the locally visible user predicates or the user predicates visible in *note this: 169.: 
          ‘current_predicate(Predicate)’ 
     To enumerate, by backtracking, the public and protected user predicates visible in *note self: 64.: 
          ‘::current_predicate(Predicate)’ 
     To enumerate, by backtracking, the public user predicates visible for an explicit object: 
          ‘Object::current_predicate(Predicate)’ 

See also
........

*note current_op/3: 14d, *note predicate_property/2: 137, *note uses/2:
48, *note use_module/2: 4a.


File: TheLogtalkHandbook-3.50.0.info,  Node: predicate_property/2,  Prev: current_predicate/1,  Up: Reflection<2>

2.5.2.11 ‘predicate_property/2’
...............................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<105>,  Next: Modes and number of proofs<69>,  Up: predicate_property/2

2.5.2.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: 3a8. and
described in the User Manual section on *note predicate properties: 1af.

When ‘Predicate’ is ground at compile time and its predicate indicator
is listed in a *note uses/2: 48. or *note use_module/2: 4a. 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: 32. supports modules).


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<69>,  Next: Errors<70>,  Prev: Description<105>,  Up: predicate_property/2

2.5.2.13 Modes and number of proofs
...................................

     predicate_property(+callable, ?predicate_property) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<70>,  Next: Examples<106>,  Prev: Modes and number of proofs<69>,  Up: predicate_property/2

2.5.2.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.50.0.info,  Node: Examples<106>,  Prev: Errors<70>,  Up: predicate_property/2

2.5.2.15 Examples
.................

     To enumerate, by backtracking, the properties of a locally visible user predicate or a user predicate visible in *note this: 169.: 
          ‘predicate_property(Predicate, Property)’ 
     To enumerate, by backtracking, the properties of a public or protected predicate visible in *note self: 64.: 
          ‘::predicate_property(Predicate, Property)’ 
     To enumerate, by backtracking, the properties of a public predicate visible in an explicit object: 
          ‘Object::predicate_property(Predicate, Property)’ 

See also
........

*note current_op/3: 14d, *note current_predicate/1: 136, *note uses/2:
48, *note use_module/2: 4a.


File: TheLogtalkHandbook-3.50.0.info,  Node: Database,  Next: Meta-calls,  Prev: Reflection<2>,  Up: Built-in methods<2>

2.5.3 Database
--------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: abolish/1,  Next: asserta/1,  Up: Database

2.5.3.1 ‘abolish/1’
...................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<106>,  Next: Modes and number of proofs<70>,  Up: abolish/1

2.5.3.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: 196. or *note assertz/1:
197. built-in methods) can be abolished.

When the predicate indicator is declared in a *note uses/2: 48. or *note
use_module/2: 4a. 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.50.0.info,  Node: Modes and number of proofs<70>,  Next: Errors<71>,  Prev: Description<106>,  Up: abolish/1

2.5.3.3 Modes and number of proofs
..................................

     abolish(@predicate_indicator) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<71>,  Next: Examples<107>,  Prev: Modes and number of proofs<70>,  Up: abolish/1

2.5.3.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.50.0.info,  Node: Examples<107>,  Prev: Errors<71>,  Up: abolish/1

2.5.3.5 Examples
................

     To abolish a local dynamic predicate or a dynamic predicate in *note this: 169.: 
          ‘abolish(Predicate)’ 
     To abolish a public or protected dynamic predicate in *note self: 64.: 
          ‘::abolish(Predicate)’ 
     To abolish a public dynamic predicate in an explicit object: 
          ‘Object::abolish(Predicate)’ 

See also
........

*note asserta/1: 196, *note assertz/1: 197, *note clause/2: 198, *note
retract/1: 199, *note retractall/1: 19a. *note dynamic/0: ab, *note
dynamic/1: 149, *note uses/2: 48, *note use_module/2: 4a.


File: TheLogtalkHandbook-3.50.0.info,  Node: asserta/1,  Next: assertz/1,  Prev: abolish/1,  Up: Database

2.5.3.6 ‘asserta/1’
...................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<107>,  Next: Modes and number of proofs<71>,  Up: asserta/1

2.5.3.7 Description
...................

     asserta(Head)
     asserta((Head:-Body))

Asserts a clause as the first one for an object dynamic predicate.  If
the predicate is not previously declared (using a scope directive), then
a dynamic predicate declaration is added to the object (assuming that we
are asserting locally or that the *note dynamic_declarations: 2b3.
compiler flag was set to ‘allow’ when the object was created or
compiled).

When the predicate indicator for ‘Head’ is declared in a *note uses/2:
48. or *note use_module/2: 4a. 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: 169.  This allows easy initialization of
dynamically created objects when writing constructors.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<71>,  Next: Errors<72>,  Prev: Description<107>,  Up: asserta/1

2.5.3.8 Modes and number of proofs
..................................

     asserta(+clause) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<72>,  Next: Examples<108>,  Prev: Modes and number of proofs<71>,  Up: asserta/1

2.5.3.9 Errors
..............

     ‘Head’ is a variable: 
          ‘instantiation_error’ 
     ‘Head’ is a 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.50.0.info,  Node: Examples<108>,  Prev: Errors<72>,  Up: asserta/1

2.5.3.10 Examples
.................

     To assert a clause as the first one for a local dynamic predicate or a dynamic predicate in *note this: 169.: 
          ‘asserta(Clause)’ 
     To assert a clause as the first one for any public or protected dynamic predicate in *note self: 64.: 
          ‘::asserta(Clause)’ 
     To assert a clause as the first one for any public dynamic predicate in an explicit object: 
          ‘Object::asserta(Clause)’ 

See also
........

*note abolish/1: 195, *note assertz/1: 197, *note clause/2: 198, *note
retract/1: 199, *note retractall/1: 19a. *note dynamic/0: ab, *note
dynamic/1: 149, *note uses/2: 48, *note use_module/2: 4a.


File: TheLogtalkHandbook-3.50.0.info,  Node: assertz/1,  Next: clause/2,  Prev: asserta/1,  Up: Database

2.5.3.11 ‘assertz/1’
....................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<108>,  Next: Modes and number of proofs<72>,  Up: assertz/1

2.5.3.12 Description
....................

     assertz(Head)
     assertz((Head:-Body))

Asserts a clause as the last one for a dynamic predicate.  If the
predicate is not previously declared (using a scope directive), then a
dynamic predicate declaration is added to the object (assuming that we
are asserting locally or that the *note dynamic_declarations: 2b3.
compiler flag was set to ‘allow’ when the object was created or
compiled).

When the predicate indicator for ‘Head’ is declared in a *note uses/2:
48. or *note use_module/2: 4a. 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: 169.  This allows easy initialization of
dynamically created objects when writing constructors.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<72>,  Next: Errors<73>,  Prev: Description<108>,  Up: assertz/1

2.5.3.13 Modes and number of proofs
...................................

     assertz(+clause) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<73>,  Next: Examples<109>,  Prev: Modes and number of proofs<72>,  Up: assertz/1

2.5.3.14 Errors
...............

     ‘Head’ is a variable: 
          ‘instantiation_error’ 
     ‘Head’ is a 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.50.0.info,  Node: Examples<109>,  Prev: Errors<73>,  Up: assertz/1

2.5.3.15 Examples
.................

     To assert a clause as the last one for a local dynamic predicate or a dynamic predicate in *note this: 169.: 
          ‘assertz(Clause)’ 
     To assert a clause as the last one for any public or protected dynamic predicate in *note self: 64.: 
          ‘::assertz(Clause)’ 
     To assert a clause as the last one for any public dynamic predicate in an explicit object: 
          ‘Object::assertz(Clause)’ 

See also
........

*note abolish/1: 195, *note asserta/1: 196, *note clause/2: 198, *note
retract/1: 199, *note retractall/1: 19a. *note dynamic/0: ab, *note
dynamic/1: 149, *note uses/2: 48, *note use_module/2: 4a.


File: TheLogtalkHandbook-3.50.0.info,  Node: clause/2,  Next: retract/1,  Prev: assertz/1,  Up: Database

2.5.3.16 ‘clause/2’
...................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<109>,  Next: Modes and number of proofs<73>,  Up: clause/2

2.5.3.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:
48. or *note use_module/2: 4a. 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: 169.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<73>,  Next: Errors<74>,  Prev: Description<109>,  Up: clause/2

2.5.3.18 Modes and number of proofs
...................................

     clause(+callable, ?body) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<74>,  Next: Examples<110>,  Prev: Modes and number of proofs<73>,  Up: clause/2

2.5.3.19 Errors
...............

     ‘Head’ is a variable: 
          ‘instantiation_error’ 
     ‘Head’ is a neither a variable nor a callable term: 
          ‘type_error(callable, Head)’ 
     ‘Body’ is a 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.50.0.info,  Node: Examples<110>,  Prev: Errors<74>,  Up: clause/2

2.5.3.20 Examples
.................

     To retrieve a matching clause of a local dynamic predicate or a dynamic predicate in *note this: 169.: 
          ‘clause(Head, Body)’ 
     To retrieve a matching clause of a public or protected dynamic predicate in *note self: 64.: 
          ‘::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: 195, *note asserta/1: 196, *note assertz/1: 197, *note
retract/1: 199, *note retractall/1: 19a. *note dynamic/0: ab, *note
dynamic/1: 149, *note uses/2: 48, *note use_module/2: 4a.


File: TheLogtalkHandbook-3.50.0.info,  Node: retract/1,  Next: retractall/1,  Prev: clause/2,  Up: Database

2.5.3.21 ‘retract/1’
....................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<110>,  Next: Modes and number of proofs<74>,  Up: retract/1

2.5.3.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:
48. or *note use_module/2: 4a. 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: 169.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<74>,  Next: Errors<75>,  Prev: Description<110>,  Up: retract/1

2.5.3.23 Modes and number of proofs
...................................

     retract(+clause) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<75>,  Next: Examples<111>,  Prev: Modes and number of proofs<74>,  Up: retract/1

2.5.3.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.50.0.info,  Node: Examples<111>,  Prev: Errors<75>,  Up: retract/1

2.5.3.25 Examples
.................

     To retract a matching clause of a dynamic predicate in *note this: 169.: 
          ‘retract(Clause)’ 
     To retract a matching clause of a public or protected dynamic predicate in *note self: 64.: 
          ‘::retract(Clause)’ 
     To retract a matching clause of a public dynamic predicate in an explicit object: 
          ‘Object::retract(Clause)’ 

See also
........

*note abolish/1: 195, *note asserta/1: 196, *note assertz/1: 197, *note
clause/2: 198, *note retractall/1: 19a, *note dynamic/0: ab, *note
dynamic/1: 149, *note uses/2: 48, *note use_module/2: 4a.


File: TheLogtalkHandbook-3.50.0.info,  Node: retractall/1,  Prev: retract/1,  Up: Database

2.5.3.26 ‘retractall/1’
.......................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<111>,  Next: Modes and number of proofs<75>,  Up: retractall/1

2.5.3.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:
48. or *note use_module/2: 4a. 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: 169.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<75>,  Next: Errors<76>,  Prev: Description<111>,  Up: retractall/1

2.5.3.28 Modes and number of proofs
...................................

     retractall(@callable) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<76>,  Next: Examples<112>,  Prev: Modes and number of proofs<75>,  Up: retractall/1

2.5.3.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.50.0.info,  Node: Examples<112>,  Prev: Errors<76>,  Up: retractall/1

2.5.3.30 Examples
.................

     To retract all clauses with a matching head of a dynamic predicate in *note this: 169.: 
          ‘retractall(Head)’ 
     To retract all clauses with a matching head of a public or protected dynamic predicate in *note self: 64.: 
          ‘::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: 195, *note asserta/1: 196, *note assertz/1: 197, *note
clause/2: 198, *note retract/1: 199, *note dynamic/0: ab, *note
dynamic/1: 149, *note uses/2: 48, *note use_module/2: 4a.


File: TheLogtalkHandbook-3.50.0.info,  Node: Meta-calls,  Next: Error handling<2>,  Prev: Database,  Up: Built-in methods<2>

2.5.4 Meta-calls
----------------

* Menu:

* call/1-N::
* ignore/1::
* once/1::
* \\+/1::


File: TheLogtalkHandbook-3.50.0.info,  Node: call/1-N,  Next: ignore/1,  Up: Meta-calls

2.5.4.1 ‘call/1-N’
..................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<112>,  Next: Modes and number of proofs<76>,  Up: call/1-N

2.5.4.2 Description
...................

     call(Goal)
     call(Closure, Arg1, ...)

Calls a goal constructed by appending additional arguments to a *note
closure: 13f.  The upper limit for ‘N’ depends on the upper limit for
the arity of a compound term of the *note backend Prolog compiler: 32.
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.50.0.info,  Node: Modes and number of proofs<76>,  Next: Errors<77>,  Prev: Description<112>,  Up: call/1-N

2.5.4.3 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.50.0.info,  Node: Errors<77>,  Next: Examples<113>,  Prev: Modes and number of proofs<76>,  Up: call/1-N

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<113>,  Prev: Errors<77>,  Up: call/1-N

2.5.4.5 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: 64.: 
          ‘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: 16c, *note once/1: 19e, *note \\+/1: 19f.


File: TheLogtalkHandbook-3.50.0.info,  Node: ignore/1,  Next: once/1,  Prev: call/1-N,  Up: Meta-calls

2.5.4.6 ‘ignore/1’
..................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<113>,  Next: Modes and number of proofs<77>,  Up: ignore/1

2.5.4.7 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.50.0.info,  Node: Modes and number of proofs<77>,  Next: Errors<78>,  Prev: Description<113>,  Up: ignore/1

2.5.4.8 Modes and number of proofs
..................................

     ignore(+callable) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<78>,  Next: Examples<114>,  Prev: Modes and number of proofs<77>,  Up: ignore/1

2.5.4.9 Errors
..............

     ‘Goal’ is a variable: 
          ‘instantiation_error’ 
     ‘Goal’ is neither a variable nor a callable term: 
          ‘type_error(callable, Goal)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<114>,  Prev: Errors<78>,  Up: ignore/1

2.5.4.10 Examples
.................

     Call a goal and succeeding even if it fails: 
          ‘ignore(Goal)’ 
     To send a message succeeding even if it fails to *note self: 64.: 
          ‘ignore(::Goal)’ 
     To send a message succeeding even if it fails to an explicit object: 
          ‘ignore(Object::Goal)’ 

See also
........

*note call/1-N: 16d, *note once/1: 19e, *note \\+/1: 19f.


File: TheLogtalkHandbook-3.50.0.info,  Node: once/1,  Next: \\+/1,  Prev: ignore/1,  Up: Meta-calls

2.5.4.11 ‘once/1’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<114>,  Next: Modes and number of proofs<78>,  Up: once/1

2.5.4.12 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.50.0.info,  Node: Modes and number of proofs<78>,  Next: Errors<79>,  Prev: Description<114>,  Up: once/1

2.5.4.13 Modes and number of proofs
...................................

     once(+callable) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<79>,  Next: Examples<115>,  Prev: Modes and number of proofs<78>,  Up: once/1

2.5.4.14 Errors
...............

     ‘Goal’ is a variable: 
          ‘instantiation_error’ 
     ‘Goal’ is neither a variable nor a callable term: 
          ‘type_error(callable, Goal)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<115>,  Prev: Errors<79>,  Up: once/1

2.5.4.15 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: 64.: 
          ‘once(::Goal)’ 
     To send a goal as a non-backtracable message to an explicit object: 
          ‘once(Object::Goal)’ 

See also
........

*note call/1-N: 16d, *note ignore/1: 16c, *note \\+/1: 19f.


File: TheLogtalkHandbook-3.50.0.info,  Node: \\+/1,  Prev: once/1,  Up: Meta-calls

2.5.4.16 ‘\\+/1’
................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<115>,  Next: Modes and number of proofs<79>,  Up: \\+/1

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<79>,  Next: Errors<80>,  Prev: Description<115>,  Up: \\+/1

2.5.4.18 Modes and number of proofs
...................................

     \+ +callable - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<80>,  Next: Examples<116>,  Prev: Modes and number of proofs<79>,  Up: \\+/1

2.5.4.19 Errors
...............

     ‘Goal’ is a variable: 
          ‘instantiation_error’ 
     ‘Goal’ is neither a variable nor a callable term: 
          ‘type_error(callable, Goal)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<116>,  Prev: Errors<80>,  Up: \\+/1

2.5.4.20 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: 64.: 
          ‘\+ ::Goal’ 
     Not-provable goal sent as a message to an explicit object: 
          ‘\+ Object::Goal’ 

See also
........

*note call/1-N: 16d, *note ignore/1: 16c, *note once/1: 19e.


File: TheLogtalkHandbook-3.50.0.info,  Node: Error handling<2>,  Next: All solutions,  Prev: Meta-calls,  Up: Built-in methods<2>

2.5.5 Error handling
--------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: catch/3,  Next: throw/1,  Up: Error handling<2>

2.5.5.1 ‘catch/3’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<116>,  Next: Modes and number of proofs<80>,  Up: catch/3

2.5.5.2 Description
...................

     catch(Goal, Catcher, Recovery)

Catches exceptions thrown by a goal.  See 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.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<80>,  Next: Errors<81>,  Prev: Description<116>,  Up: catch/3

2.5.5.3 Modes and number of proofs
..................................

     catch(?callable, ?term, ?callable) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<81>,  Next: Examples<117>,  Prev: Modes and number of proofs<80>,  Up: catch/3

2.5.5.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<117>,  Prev: Errors<81>,  Up: catch/3

2.5.5.5 Examples
................

(none)

See also
........

*note throw/1: 186, *note context/1: 182, *note instantiation_error/0:
187, *note uninstantiation_error/1: 188, *note type_error/2: 189, *note
domain_error/2: 18a, *note existence_error/2: 18b, *note
permission_error/3: 18c, *note evaluation_error/1: 18e, *note
representation_error/1: 18d. *note resource_error/1: 18f, *note
syntax_error/1: 190, *note system_error/0: 191.


File: TheLogtalkHandbook-3.50.0.info,  Node: throw/1,  Next: instantiation_error/0,  Prev: catch/3,  Up: Error handling<2>

2.5.5.6 ‘throw/1’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<117>,  Next: Modes and number of proofs<81>,  Up: throw/1

2.5.5.7 Description
...................

     throw(Exception)

Throws an exception.  This built-in method is declared private and thus
cannot be used as a message to an object.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<81>,  Next: Errors<82>,  Prev: Description<117>,  Up: throw/1

2.5.5.8 Modes and number of proofs
..................................

     throw(+nonvar) - error


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<82>,  Next: Examples<118>,  Prev: Modes and number of proofs<81>,  Up: throw/1

2.5.5.9 Errors
..............

     ‘Exception’ is a variable: 
          ‘instantiation_error’ 
     ‘Exception’ does not unify with the second argument of any call of *note catch/3: 185.: 
          ‘system_error’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<118>,  Prev: Errors<82>,  Up: throw/1

2.5.5.10 Examples
.................

(none)

See also
........

*note catch/3: 185, *note context/1: 182, *note instantiation_error/0:
187, *note uninstantiation_error/1: 188, *note type_error/2: 189, *note
domain_error/2: 18a, *note existence_error/2: 18b, *note
permission_error/3: 18c, *note evaluation_error/1: 18e, *note
representation_error/1: 18d. *note resource_error/1: 18f, *note
syntax_error/1: 190, *note system_error/0: 191.


File: TheLogtalkHandbook-3.50.0.info,  Node: instantiation_error/0,  Next: uninstantiation_error/1,  Prev: throw/1,  Up: Error handling<2>

2.5.5.11 ‘instantiation_error/0’
................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<118>,  Next: Modes and number of proofs<82>,  Up: instantiation_error/0

2.5.5.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.50.0.info,  Node: Modes and number of proofs<82>,  Next: Errors<83>,  Prev: Description<118>,  Up: instantiation_error/0

2.5.5.13 Modes and number of proofs
...................................

     instantiation_error - error


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<83>,  Next: Examples<119>,  Prev: Modes and number of proofs<82>,  Up: instantiation_error/0

2.5.5.14 Errors
...............

     When called: 
          ‘instantiation_error’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<119>,  Prev: Errors<83>,  Up: instantiation_error/0

2.5.5.15 Examples
.................

     ...,
     var(Handler),
     instantiation_error.

See also
........

*note catch/3: 185, *note throw/1: 186, *note context/1: 182, *note
uninstantiation_error/1: 188, *note type_error/2: 189, *note
domain_error/2: 18a, *note existence_error/2: 18b, *note
permission_error/3: 18c, *note representation_error/1: 18d, *note
evaluation_error/1: 18e, *note resource_error/1: 18f, *note
syntax_error/1: 190, *note system_error/0: 191.


File: TheLogtalkHandbook-3.50.0.info,  Node: uninstantiation_error/1,  Next: type_error/2,  Prev: instantiation_error/0,  Up: Error handling<2>

2.5.5.16 ‘uninstantiation_error/1’
..................................

* Menu:

* Description: Description<119>.
* Modes and number of proofs: Modes and number of proofs<83>.
* Errors: Errors<84>.
* Examples: Examples<120>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<119>,  Next: Modes and number of proofs<83>,  Up: uninstantiation_error/1

2.5.5.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.50.0.info,  Node: Modes and number of proofs<83>,  Next: Errors<84>,  Prev: Description<119>,  Up: uninstantiation_error/1

2.5.5.18 Modes and number of proofs
...................................

     uninstantiation_error(@nonvar) - error


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<84>,  Next: Examples<120>,  Prev: Modes and number of proofs<83>,  Up: uninstantiation_error/1

2.5.5.19 Errors
...............

     When called: 
          ‘uninstantiation_error(Culprit)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<120>,  Prev: Errors<84>,  Up: uninstantiation_error/1

2.5.5.20 Examples
.................

     ...,
     var(Handler),
     uninstantiation_error(my_stream).

See also
........

*note catch/3: 185, *note throw/1: 186, *note context/1: 182, *note
instantiation_error/0: 187, *note type_error/2: 189, *note
domain_error/2: 18a, *note existence_error/2: 18b, *note
permission_error/3: 18c, *note representation_error/1: 18d, *note
evaluation_error/1: 18e, *note resource_error/1: 18f, *note
syntax_error/1: 190, *note system_error/0: 191.


File: TheLogtalkHandbook-3.50.0.info,  Node: type_error/2,  Next: domain_error/2,  Prev: uninstantiation_error/1,  Up: Error handling<2>

2.5.5.21 ‘type_error/2’
.......................

* Menu:

* Description: Description<120>.
* Modes and number of proofs: Modes and number of proofs<84>.
* Errors: Errors<85>.
* Examples: Examples<121>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<120>,  Next: Modes and number of proofs<84>,  Up: type_error/2

2.5.5.22 Description
....................

     type_error(Type, Culprit)

Throws a type error.  Used when the type of an argument is incorrect.
For example, trying ot 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.50.0.info,  Node: Modes and number of proofs<84>,  Next: Errors<85>,  Prev: Description<120>,  Up: type_error/2

2.5.5.23 Modes and number of proofs
...................................

     type_error(@nonvar, @term) - error


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<85>,  Next: Examples<121>,  Prev: Modes and number of proofs<84>,  Up: type_error/2

2.5.5.24 Errors
...............

     When called: 
          ‘type_error(Type, Culprit)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<121>,  Prev: Errors<85>,  Up: type_error/2

2.5.5.25 Examples
.................

     ...,
     \+ atom(Name),
     type_error(atom, Name).

See also
........

*note catch/3: 185, *note throw/1: 186, *note context/1: 182, *note
instantiation_error/0: 187, *note uninstantiation_error/1: 188, *note
domain_error/2: 18a, *note existence_error/2: 18b, *note
permission_error/3: 18c, *note representation_error/1: 18d. *note
evaluation_error/1: 18e, *note resource_error/1: 18f, *note
syntax_error/1: 190, *note system_error/0: 191,


File: TheLogtalkHandbook-3.50.0.info,  Node: domain_error/2,  Next: existence_error/2,  Prev: type_error/2,  Up: Error handling<2>

2.5.5.26 ‘domain_error/2’
.........................

* Menu:

* Description: Description<121>.
* Modes and number of proofs: Modes and number of proofs<85>.
* Errors: Errors<86>.
* Examples: Examples<122>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<121>,  Next: Modes and number of proofs<85>,  Up: domain_error/2

2.5.5.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.50.0.info,  Node: Modes and number of proofs<85>,  Next: Errors<86>,  Prev: Description<121>,  Up: domain_error/2

2.5.5.28 Modes and number of proofs
...................................

     domain_error(+atom, @nonvar) - error


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<86>,  Next: Examples<122>,  Prev: Modes and number of proofs<85>,  Up: domain_error/2

2.5.5.29 Errors
...............

     When called: 
          ‘domain_error(Domain, Culprit)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<122>,  Prev: Errors<86>,  Up: domain_error/2

2.5.5.30 Examples
.................

     ...,
     atom(Color),
     \+ color(Color),
     domain_error(color, Color).

See also
........

*note catch/3: 185, *note throw/1: 186, *note context/1: 182, *note
instantiation_error/0: 187, *note uninstantiation_error/1: 188, *note
type_error/2: 189, *note existence_error/2: 18b, *note
permission_error/3: 18c, *note representation_error/1: 18d, *note
evaluation_error/1: 18e, *note resource_error/1: 18f, *note
syntax_error/1: 190, *note system_error/0: 191.


File: TheLogtalkHandbook-3.50.0.info,  Node: existence_error/2,  Next: permission_error/3,  Prev: domain_error/2,  Up: Error handling<2>

2.5.5.31 ‘existence_error/2’
............................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<122>,  Next: Modes and number of proofs<86>,  Up: existence_error/2

2.5.5.32 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_declaration’

   - ‘procedure’

   - ‘source_sink’

   - ‘stream’

   - ‘object’

   - ‘protocol’

   - ‘category’

   - ‘module’

   - ‘library’

   - ‘file’

   - ‘goal_thread’

The value of ‘Culprit’ is the argument or one of its sub-terms that
caused the error.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<86>,  Next: Errors<87>,  Prev: Description<122>,  Up: existence_error/2

2.5.5.33 Modes and number of proofs
...................................

     existence_error(@nonvar, @nonvar) - error


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<87>,  Next: Examples<123>,  Prev: Modes and number of proofs<86>,  Up: existence_error/2

2.5.5.34 Errors
...............

     When called: 
          ‘existence_error(Thing, Culprit)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<123>,  Prev: Errors<87>,  Up: existence_error/2

2.5.5.35 Examples
.................

     ...,
     \+ current_object(payroll),
     existence_error(object, payroll).

See also
........

*note catch/3: 185, *note throw/1: 186, *note context/1: 182, *note
instantiation_error/0: 187, *note uninstantiation_error/1: 188, *note
type_error/2: 189, *note domain_error/2: 18a, *note evaluation_error/1:
18e, *note permission_error/3: 18c, *note representation_error/1: 18d,
*note resource_error/1: 18f, *note syntax_error/1: 190, *note
system_error/0: 191.


File: TheLogtalkHandbook-3.50.0.info,  Node: permission_error/3,  Next: representation_error/1,  Prev: existence_error/2,  Up: Error handling<2>

2.5.5.36 ‘permission_error/3’
.............................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<123>,  Next: Modes and number of proofs<87>,  Up: permission_error/3

2.5.5.37 Description
....................

     permission_error(Operation, Permission, Culprit)

Throws an 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,Permission,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Operation’ include:

   - ‘access’

   - ‘create’

   - ‘modify’

   - ‘open’

   - ‘input’

   - ‘output’

   - ‘reposition’

   - ‘repeat’

Possible values for ‘Permission’ include:

   - ‘predicate_declaration’

   - ‘protected_predicate’

   - ‘private_predicate’

   - ‘static_predicate’

   - ‘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.50.0.info,  Node: Modes and number of proofs<87>,  Next: Errors<88>,  Prev: Description<123>,  Up: permission_error/3

2.5.5.38 Modes and number of proofs
...................................

     permission_error(@nonvar, @nonvar, @nonvar) - error


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<88>,  Next: Examples<124>,  Prev: Modes and number of proofs<87>,  Up: permission_error/3

2.5.5.39 Errors
...............

     When called: 
          ‘permission_error(Operation, Permission, Culprit)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<124>,  Prev: Errors<88>,  Up: permission_error/3

2.5.5.40 Examples
.................

     ...,
     \+ writable(File),
     permission_error(modify, file, File).

See also
........

*note catch/3: 185, *note throw/1: 186, *note context/1: 182, *note
instantiation_error/0: 187, *note uninstantiation_error/1: 188, *note
type_error/2: 189, *note domain_error/2: 18a, *note existence_error/2:
18b, *note representation_error/1: 18d, *note evaluation_error/1: 18e,
*note resource_error/1: 18f, *note syntax_error/1: 190, *note
system_error/0: 191.


File: TheLogtalkHandbook-3.50.0.info,  Node: representation_error/1,  Next: evaluation_error/1,  Prev: permission_error/3,  Up: Error handling<2>

2.5.5.41 ‘representation_error/1’
.................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<124>,  Next: Modes and number of proofs<88>,  Up: representation_error/1

2.5.5.42 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’

   - ‘lambda_parameters’

   - ‘entity_prefix’


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<88>,  Next: Errors<89>,  Prev: Description<124>,  Up: representation_error/1

2.5.5.43 Modes and number of proofs
...................................

     representation_error(+atom) - error


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<89>,  Next: Examples<125>,  Prev: Modes and number of proofs<88>,  Up: representation_error/1

2.5.5.44 Errors
...............

     When called: 
          ‘representation_error(Flag)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<125>,  Prev: Errors<89>,  Up: representation_error/1

2.5.5.45 Examples
.................

     ...,
     Code > 127,
     representation_error(character_code).

See also
........

*note catch/3: 185, *note throw/1: 186, *note context/1: 182, *note
instantiation_error/0: 187, *note uninstantiation_error/1: 188, *note
type_error/2: 189, *note domain_error/2: 18a, *note existence_error/2:
18b, *note permission_error/3: 18c, *note evaluation_error/1: 18e, *note
resource_error/1: 18f, *note syntax_error/1: 190, *note system_error/0:
191.


File: TheLogtalkHandbook-3.50.0.info,  Node: evaluation_error/1,  Next: resource_error/1,  Prev: representation_error/1,  Up: Error handling<2>

2.5.5.46 ‘evaluation_error/1’
.............................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<125>,  Next: Modes and number of proofs<89>,  Up: evaluation_error/1

2.5.5.47 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.50.0.info,  Node: Modes and number of proofs<89>,  Next: Errors<90>,  Prev: Description<125>,  Up: evaluation_error/1

2.5.5.48 Modes and number of proofs
...................................

     evaluation_error(@nonvar) - error


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<90>,  Next: Examples<126>,  Prev: Modes and number of proofs<89>,  Up: evaluation_error/1

2.5.5.49 Errors
...............

     When called: 
          ‘evaluation_error(Exception)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<126>,  Prev: Errors<90>,  Up: evaluation_error/1

2.5.5.50 Examples
.................

     ...,
     Divisor =:= 0,
     evaluation_error(zero_divisor).

See also
........

*note catch/3: 185, *note throw/1: 186, *note context/1: 182, *note
instantiation_error/0: 187, *note uninstantiation_error/1: 188, *note
type_error/2: 189, *note domain_error/2: 18a, *note existence_error/2:
18b, *note permission_error/3: 18c, *note representation_error/1: 18d,
*note resource_error/1: 18f, *note syntax_error/1: 190, *note
system_error/0: 191.


File: TheLogtalkHandbook-3.50.0.info,  Node: resource_error/1,  Next: syntax_error/1,  Prev: evaluation_error/1,  Up: Error handling<2>

2.5.5.51 ‘resource_error/1’
...........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<126>,  Next: Modes and number of proofs<90>,  Up: resource_error/1

2.5.5.52 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:

Possible values for ‘Resource’ include:

   - ‘threads’

   - ‘coinduction’

   - ‘soft_cut_support’

     ...,
     context(Context),
     throw(error(resource_error(Resource), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<90>,  Next: Errors<91>,  Prev: Description<126>,  Up: resource_error/1

2.5.5.53 Modes and number of proofs
...................................

     resource_error(@nonvar) - error


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<91>,  Next: Examples<127>,  Prev: Modes and number of proofs<90>,  Up: resource_error/1

2.5.5.54 Errors
...............

     When called: 
          ‘resource_error(Resource)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<127>,  Prev: Errors<91>,  Up: resource_error/1

2.5.5.55 Examples
.................

     ...,
     empty(Tank),
     resource_error(gas).

See also
........

*note catch/3: 185, *note throw/1: 186, *note context/1: 182, *note
instantiation_error/0: 187, *note uninstantiation_error/1: 188, *note
type_error/2: 189, *note domain_error/2: 18a, *note existence_error/2:
18b, *note permission_error/3: 18c, *note representation_error/1: 18d,
*note syntax_error/1: 190, *note system_error/0: 191.


File: TheLogtalkHandbook-3.50.0.info,  Node: syntax_error/1,  Next: system_error/0,  Prev: resource_error/1,  Up: Error handling<2>

2.5.5.56 ‘syntax_error/1’
.........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<127>,  Next: Modes and number of proofs<91>,  Up: syntax_error/1

2.5.5.57 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.50.0.info,  Node: Modes and number of proofs<91>,  Next: Errors<92>,  Prev: Description<127>,  Up: syntax_error/1

2.5.5.58 Modes and number of proofs
...................................

     syntax_error(@nonvar) - error


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<92>,  Next: Examples<128>,  Prev: Modes and number of proofs<91>,  Up: syntax_error/1

2.5.5.59 Errors
...............

     When called: 
          ‘syntax_error(Description)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<128>,  Prev: Errors<92>,  Up: syntax_error/1

2.5.5.60 Examples
.................

(none)

See also
........

*note catch/3: 185, *note throw/1: 186, *note context/1: 182, *note
instantiation_error/0: 187, *note uninstantiation_error/1: 188, *note
type_error/2: 189, *note domain_error/2: 18a, *note existence_error/2:
18b, *note permission_error/3: 18c, *note representation_error/1: 18d,
*note system_error/0: 191. *note resource_error/1: 18f.


File: TheLogtalkHandbook-3.50.0.info,  Node: system_error/0,  Prev: syntax_error/1,  Up: Error handling<2>

2.5.5.61 ‘system_error/0’
.........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<128>,  Next: Modes and number of proofs<92>,  Up: system_error/0

2.5.5.62 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.50.0.info,  Node: Modes and number of proofs<92>,  Next: Errors<93>,  Prev: Description<128>,  Up: system_error/0

2.5.5.63 Modes and number of proofs
...................................

     system_error - error


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<93>,  Next: Examples<129>,  Prev: Modes and number of proofs<92>,  Up: system_error/0

2.5.5.64 Errors
...............

     When called: 
          ‘system_error’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<129>,  Prev: Errors<93>,  Up: system_error/0

2.5.5.65 Examples
.................

(none)

See also
........

*note catch/3: 185, *note throw/1: 186, *note context/1: 182, *note
instantiation_error/0: 187, *note uninstantiation_error/1: 188, *note
type_error/2: 189, *note domain_error/2: 18a, *note existence_error/2:
18b, *note permission_error/3: 18c, *note representation_error/1: 18d.
*note evaluation_error/1: 18e, *note resource_error/1: 18f, *note
syntax_error/1: 190,


File: TheLogtalkHandbook-3.50.0.info,  Node: All solutions,  Next: Event handling<3>,  Prev: Error handling<2>,  Up: Built-in methods<2>

2.5.6 All solutions
-------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: bagof/3,  Next: findall/3,  Up: All solutions

2.5.6.1 ‘bagof/3’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<129>,  Next: Modes and number of proofs<93>,  Up: bagof/3

2.5.6.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.50.0.info,  Node: Modes and number of proofs<93>,  Next: Errors<94>,  Prev: Description<129>,  Up: bagof/3

2.5.6.3 Modes and number of proofs
..................................

     bagof(@term, +callable, -list) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<94>,  Next: Examples<130>,  Prev: Modes and number of proofs<93>,  Up: bagof/3

2.5.6.4 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.50.0.info,  Node: Examples<130>,  Prev: Errors<94>,  Up: bagof/3

2.5.6.5 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: 64.: 
          ‘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: 1a3, *note findall/4: 1a4, *note forall/2: 1a6, *note
setof/3: 1a5.


File: TheLogtalkHandbook-3.50.0.info,  Node: findall/3,  Next: findall/4,  Prev: bagof/3,  Up: All solutions

2.5.6.6 ‘findall/3’
...................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<130>,  Next: Modes and number of proofs<94>,  Up: findall/3

2.5.6.7 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.50.0.info,  Node: Modes and number of proofs<94>,  Next: Errors<95>,  Prev: Description<130>,  Up: findall/3

2.5.6.8 Modes and number of proofs
..................................

     findall(?term, +callable, ?list) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<95>,  Next: Examples<131>,  Prev: Modes and number of proofs<94>,  Up: findall/3

2.5.6.9 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.50.0.info,  Node: Examples<131>,  Prev: Errors<95>,  Up: findall/3

2.5.6.10 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: 64.: 
          ‘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: 1a2, *note findall/4: 1a4, *note forall/2: 1a6, *note
setof/3: 1a5.


File: TheLogtalkHandbook-3.50.0.info,  Node: findall/4,  Next: forall/2,  Prev: findall/3,  Up: All solutions

2.5.6.11 ‘findall/4’
....................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<131>,  Next: Modes and number of proofs<95>,  Up: findall/4

2.5.6.12 Description
....................

     findall(Template, Goal, List, Tail)

Variant of the *note findall/3: 1a3. 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.50.0.info,  Node: Modes and number of proofs<95>,  Next: Errors<96>,  Prev: Description<131>,  Up: findall/4

2.5.6.13 Modes and number of proofs
...................................

     findall(?term, +callable, ?list, ?term) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<96>,  Next: Examples<132>,  Prev: Modes and number of proofs<95>,  Up: findall/4

2.5.6.14 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.50.0.info,  Node: Examples<132>,  Prev: Errors<96>,  Up: findall/4

2.5.6.15 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: 64.: 
          ‘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: 1a2, *note findall/3: 1a3, *note forall/2: 1a6, *note
setof/3: 1a5.


File: TheLogtalkHandbook-3.50.0.info,  Node: forall/2,  Next: setof/3,  Prev: findall/4,  Up: All solutions

2.5.6.16 ‘forall/2’
...................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<132>,  Next: Modes and number of proofs<96>,  Up: forall/2

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

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.50.0.info,  Node: Modes and number of proofs<96>,  Next: Errors<97>,  Prev: Description<132>,  Up: forall/2

2.5.6.18 Modes and number of proofs
...................................

     forall(@callable, @callable) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<97>,  Next: Examples<133>,  Prev: Modes and number of proofs<96>,  Up: forall/2

2.5.6.19 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.50.0.info,  Node: Examples<133>,  Prev: Errors<97>,  Up: forall/2

2.5.6.20 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: 64.: 
          ‘forall(::Generator, ::Test)’ 
     To send both goals as messages to explicit objects: 
          ‘forall(Object1::Generator, Object2::Test)’ 

See also
........

*note bagof/3: 1a2, *note findall/3: 1a3, *note findall/4: 1a4, *note
setof/3: 1a5.


File: TheLogtalkHandbook-3.50.0.info,  Node: setof/3,  Prev: forall/2,  Up: All solutions

2.5.6.21 ‘setof/3’
..................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<133>,  Next: Modes and number of proofs<97>,  Up: setof/3

2.5.6.22 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.50.0.info,  Node: Modes and number of proofs<97>,  Next: Errors<98>,  Prev: Description<133>,  Up: setof/3

2.5.6.23 Modes and number of proofs
...................................

     setof(@term, +callable, -list) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<98>,  Next: Examples<134>,  Prev: Modes and number of proofs<97>,  Up: setof/3

2.5.6.24 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.50.0.info,  Node: Examples<134>,  Prev: Errors<98>,  Up: setof/3

2.5.6.25 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: 64.: 
          ‘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: 1a2, *note findall/3: 1a3, *note findall/4: 1a4, *note
forall/2: 1a6.


File: TheLogtalkHandbook-3.50.0.info,  Node: Event handling<3>,  Next: Message forwarding,  Prev: All solutions,  Up: Built-in methods<2>

2.5.7 Event handling
--------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: before/3,  Next: after/3,  Up: Event handling<3>

2.5.7.1 ‘before/3’
..................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<134>,  Next: Modes and number of proofs<98>,  Up: before/3

2.5.7.2 Description
...................

     before(Object, Message, Sender)

User-defined method for handling `before' events.  This method is
declared in the monitoring(1) built-in protocol as a public predicate
and automatically called by the runtime for messages sent using the
*note ;;/2: 7a. control construct from within objects compiled with the
*note events: 85. flag set to ‘allow’.

Note that you can make this predicate scope protected or private by
using, respectively, *note protected or private implementation: 9a. of
the ‘monitoring’ protocol.

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

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<98>,  Next: Errors<99>,  Prev: Description<134>,  Up: before/3

2.5.7.3 Modes and number of proofs
..................................

     before(?object_identifier, ?callable, ?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<99>,  Next: Examples<135>,  Prev: Modes and number of proofs<98>,  Up: before/3

2.5.7.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<135>,  Prev: Errors<99>,  Up: before/3

2.5.7.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: fb, *note abolish_events/5: 1fc, *note current_event/5:
1ff, *note define_events/5: 1f9.


File: TheLogtalkHandbook-3.50.0.info,  Node: after/3,  Prev: before/3,  Up: Event handling<3>

2.5.7.6 ‘after/3’
.................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<135>,  Next: Modes and number of proofs<99>,  Up: after/3

2.5.7.7 Description
...................

     after(Object, Message, Sender)

User-defined method for handling `after' events.  This method is
declared in the monitoring(1) built-in protocol as a public predicate
and automatically called by the runtime for messages sent using the
*note ;;/2: 7a. control construct from within objects compiled with the
*note events: 85. flag set to ‘allow’.

Note that you can make this predicate scope protected or private by
using, respectively, *note protected or private implementation: 9a. of
the ‘monitoring’ protocol.

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

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<99>,  Next: Errors<100>,  Prev: Description<135>,  Up: after/3

2.5.7.8 Modes and number of proofs
..................................

     after(?object_identifier, ?callable, ?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<100>,  Next: Examples<136>,  Prev: Modes and number of proofs<99>,  Up: after/3

2.5.7.9 Errors
..............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<136>,  Prev: Errors<100>,  Up: after/3

2.5.7.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: fa, *note abolish_events/5: 1fc, *note current_event/5:
1ff, *note define_events/5: 1f9.


File: TheLogtalkHandbook-3.50.0.info,  Node: Message forwarding,  Next: Definite clause grammar rules<2>,  Prev: Event handling<3>,  Up: Built-in methods<2>

2.5.8 Message forwarding
------------------------

* Menu:

* forward/1::


File: TheLogtalkHandbook-3.50.0.info,  Node: forward/1,  Up: Message forwarding

2.5.8.1 ‘forward/1’
...................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<136>,  Next: Modes and number of proofs<100>,  Up: forward/1

2.5.8.2 Description
...................

     forward(Message)

User-defined method for forwarding unknown messages sent to an object
(using the *note ;;/2: 7a. control construct), automatically called by
the runtime when defined.  This method is declared in the forwarding(1)
built-in protocol as a *note public: 138. predicate.  Note that you can
make its scope protected or private by using, respectively, *note
protected or private implementation: 9a. of the ‘forwarding’ protocol.

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

   (1) ../../../docs/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<100>,  Next: Errors<101>,  Prev: Description<136>,  Up: forward/1

2.5.8.3 Modes and number of proofs
..................................

     forward(+callable) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<101>,  Next: Examples<137>,  Prev: Modes and number of proofs<100>,  Up: forward/1

2.5.8.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<137>,  Prev: Errors<101>,  Up: forward/1

2.5.8.5 Examples
................

     :- object(proxy,
         implements(forwarding),
         ...).

         forward(Message) :-
             % delegate unknown messages to the "real" object
             [real::Message].

See also
........

*note []/1: 7d.


File: TheLogtalkHandbook-3.50.0.info,  Node: Definite clause grammar rules<2>,  Next: Term and goal expansion<2>,  Prev: Message forwarding,  Up: Built-in methods<2>

2.5.9 Definite clause grammar rules
-----------------------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: call//1-N,  Next: eos//0,  Up: Definite clause grammar rules<2>

2.5.9.1 ‘call//1-N’
...................

* Menu:

* Description: Description<137>.
* Modes and number of proofs: Modes and number of proofs<101>.
* Errors: Errors<102>.
* Examples: Examples<138>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<137>,  Next: Modes and number of proofs<101>,  Up: call//1-N

2.5.9.2 Description
...................

     call(Closure)
     call(Closure, Arg1, ...)
     call(Object::Closure, Arg1, ...)
     call(::Closure, Arg1, ...)
     call(^^Closure, Arg1, ...)
     ...

This non-terminal takes a *note closure: 13f. and is processed by
appending the input list of tokens and the list of remaining tokens 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 input list of tokens and the list of
remaining tokens 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.

When using a *note backend Prolog compiler: 32. supporting a module
system, calls in the format ‘call(Module:Closure)’ may also be used.  By
using as argument a *note lambda expression: 16e, this built-in
non-terminal can provide controlled access to the input list of tokens
and to the list of the remaining tokens processed by the grammar rule
containing the call.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<101>,  Next: Errors<102>,  Prev: Description<137>,  Up: call//1-N

2.5.9.3 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.50.0.info,  Node: Errors<102>,  Next: Examples<138>,  Prev: Modes and number of proofs<101>,  Up: call//1-N

2.5.9.4 Errors
..............

     ‘Closure’ is a variable: 
          ‘instantiation_error’ 
     ‘Closure’ is neither a variable nor a callable term: 
          ‘type_error(callable, Closure)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<138>,  Prev: Errors<102>,  Up: call//1-N

2.5.9.5 Examples
................

     Calls a goal, constructed by appending the tokens difference list 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 tokens difference list to the closure: 
          ‘call(^^Closure)’ 
     To send a goal, constructed by appending the tokens difference list to the closure, as a message to *note self: 64.: 
          ‘call(::Closure)’ 
     To send a goal, constructed by appending the tokens difference list to the closure, as a message to an explicit object: 
          ‘call(Object::Closure)’ 

See also
........

*note eos//0: 1ad, *note phrase//1: 1ab, *note phrase/2: 17a, *note
phrase/3: 17b.


File: TheLogtalkHandbook-3.50.0.info,  Node: eos//0,  Next: phrase//1,  Prev: call//1-N,  Up: Definite clause grammar rules<2>

2.5.9.6 ‘eos//0’
................

* Menu:

* Description: Description<138>.
* Modes and number of proofs: Modes and number of proofs<102>.
* Errors: Errors<103>.
* Examples: Examples<139>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<138>,  Next: Modes and number of proofs<102>,  Up: eos//0

2.5.9.7 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.50.0.info,  Node: Modes and number of proofs<102>,  Next: Errors<103>,  Prev: Description<138>,  Up: eos//0

2.5.9.8 Modes and number of proofs
..................................

     eos - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<103>,  Next: Examples<139>,  Prev: Modes and number of proofs<102>,  Up: eos//0

2.5.9.9 Errors
..............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<139>,  Prev: Errors<103>,  Up: eos//0

2.5.9.10 Examples
.................

     abc --> a, b, c, eos.

See also
........

*note call//1-N: 1ac, *note phrase//1: 1ab, *note phrase/2: 17a, *note
phrase/3: 17b.


File: TheLogtalkHandbook-3.50.0.info,  Node: phrase//1,  Next: phrase/2,  Prev: eos//0,  Up: Definite clause grammar rules<2>

2.5.9.11 ‘phrase//1’
....................

* Menu:

* Description: Description<139>.
* Modes and number of proofs: Modes and number of proofs<103>.
* Errors: Errors<104>.
* Examples: Examples<140>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<139>,  Next: Modes and number of proofs<103>,  Up: phrase//1

2.5.9.12 Description
....................

     phrase(NonTerminal)

This non-terminal takes a non-terminal or a grammar rule body and parses
it using the implicit difference list of tokens.  A common use is to
wrap what otherwise would be a naked variable in a grammar rule body.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<103>,  Next: Errors<104>,  Prev: Description<139>,  Up: phrase//1

2.5.9.13 Modes and number of proofs
...................................

     phrase(+callable) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<104>,  Next: Examples<140>,  Prev: Modes and number of proofs<103>,  Up: phrase//1

2.5.9.14 Errors
...............

     ‘NonTerminal’ is a variable: 
          ‘instantiation_error’ 
     ‘NonTerminal’ is neither a variable nor a callable term: 
          ‘type_error(callable, NonTerminal)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<140>,  Prev: Errors<104>,  Up: phrase//1

2.5.9.15 Examples
.................

     (none)

See also
........

*note call//1-N: 1ac, *note phrase/2: 17a, *note phrase/3: 17b.


File: TheLogtalkHandbook-3.50.0.info,  Node: phrase/2,  Next: phrase/3,  Prev: phrase//1,  Up: Definite clause grammar rules<2>

2.5.9.16 ‘phrase/2’
...................

* Menu:

* Description: Description<140>.
* Modes and number of proofs: Modes and number of proofs<104>.
* Errors: Errors<105>.
* Examples: Examples<141>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<140>,  Next: Modes and number of proofs<104>,  Up: phrase/2

2.5.9.17 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: 32. 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.50.0.info,  Node: Modes and number of proofs<104>,  Next: Errors<105>,  Prev: Description<140>,  Up: phrase/2

2.5.9.18 Modes and number of proofs
...................................

     phrase(+callable, ?list) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<105>,  Next: Examples<141>,  Prev: Modes and number of proofs<104>,  Up: phrase/2

2.5.9.19 Errors
...............

     ‘GrammarRuleBody’ is a variable: 
          ‘instantiation_error’ 
     ‘GrammarRuleBody’ is neither a variable nor a callable term: 
          ‘type_error(callable, GrammarRuleBody)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<141>,  Prev: Errors<105>,  Up: phrase/2

2.5.9.20 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: 64.: 
          ‘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: 1ac, *note phrase//1: 1ab, *note phrase/3: 17b.


File: TheLogtalkHandbook-3.50.0.info,  Node: phrase/3,  Prev: phrase/2,  Up: Definite clause grammar rules<2>

2.5.9.21 ‘phrase/3’
...................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<141>,  Next: Modes and number of proofs<105>,  Up: phrase/3

2.5.9.22 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: 32.
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.50.0.info,  Node: Modes and number of proofs<105>,  Next: Errors<106>,  Prev: Description<141>,  Up: phrase/3

2.5.9.23 Modes and number of proofs
...................................

     phrase(+callable, ?list, ?list) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<106>,  Next: Examples<142>,  Prev: Modes and number of proofs<105>,  Up: phrase/3

2.5.9.24 Errors
...............

     ‘GrammarRuleBody’ is a variable: 
          ‘instantiation_error’ 
     ‘GrammarRuleBody’ is neither a variable nor a callable term: 
          ‘type_error(callable, GrammarRuleBody)’ 


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<142>,  Prev: Errors<106>,  Up: phrase/3

2.5.9.25 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: 64.: 
          ‘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: 1ac, *note phrase/2: 17a, *note phrase/3: 17b.


File: TheLogtalkHandbook-3.50.0.info,  Node: Term and goal expansion<2>,  Next: Coinduction hooks,  Prev: Definite clause grammar rules<2>,  Up: Built-in methods<2>

2.5.10 Term and goal expansion
------------------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: expand_term/2,  Next: term_expansion/2,  Up: Term and goal expansion<2>

2.5.10.1 ‘expand_term/2’
........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<142>,  Next: Modes and number of proofs<106>,  Up: expand_term/2

2.5.10.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: f5. 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: 35e.
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.50.0.info,  Node: Modes and number of proofs<106>,  Next: Errors<107>,  Prev: Description<142>,  Up: expand_term/2

2.5.10.3 Modes and number of proofs
...................................

     expand_term(?term, ?term) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<107>,  Next: Examples<143>,  Prev: Modes and number of proofs<106>,  Up: expand_term/2

2.5.10.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<143>,  Prev: Errors<107>,  Up: expand_term/2

2.5.10.5 Examples
.................

(none)

See also
........

*note expand_goal/2: 2e9, *note goal_expansion/2: f6, *note
term_expansion/2: f5.


File: TheLogtalkHandbook-3.50.0.info,  Node: term_expansion/2,  Next: expand_goal/2,  Prev: expand_term/2,  Up: Term and goal expansion<2>

2.5.10.6 ‘term_expansion/2’
...........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<143>,  Next: Modes and number of proofs<107>,  Up: term_expansion/2

2.5.10.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: 19b.
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 be also be applied when compiling source files by
defining the object providing access to the ‘term_expansion/2’ clauses
as a *note hook object: 35e.  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: 17c. 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: 9a. to restrict the scope of this predicate.

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

   (1) ../../../docs/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<107>,  Next: Errors<108>,  Prev: Description<143>,  Up: term_expansion/2

2.5.10.8 Modes and number of proofs
...................................

     term_expansion(+nonvar, -nonvar) - zero_or_one
     term_expansion(+nonvar, -list(nonvar)) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<108>,  Next: Examples<144>,  Prev: Modes and number of proofs<107>,  Up: term_expansion/2

2.5.10.9 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<144>,  Prev: Errors<108>,  Up: term_expansion/2

2.5.10.10 Examples
..................

     term_expansion((:- license(default)), (:- license(gplv3))).
     term_expansion(data(Millimeters), data(Meters)) :- Meters is Millimeters / 1000.

See also
........

*note expand_goal/2: 2e9, *note expand_term/2: 19b, *note
goal_expansion/2: f6, *note logtalk_load_context/2: 2ee.


File: TheLogtalkHandbook-3.50.0.info,  Node: expand_goal/2,  Next: goal_expansion/2,  Prev: term_expansion/2,  Up: Term and goal expansion<2>

2.5.10.11 ‘expand_goal/2’
.........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<144>,  Next: Modes and number of proofs<108>,  Up: expand_goal/2

2.5.10.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: 35e.  This predicate can be used by the user
to manually perform goal expansion at runtime (for example, before
asserting a clause).


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<108>,  Next: Errors<109>,  Prev: Description<144>,  Up: expand_goal/2

2.5.10.13 Modes and number of proofs
....................................

     expand_goal(?term, ?term) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<109>,  Next: Examples<145>,  Prev: Modes and number of proofs<108>,  Up: expand_goal/2

2.5.10.14 Errors
................

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<145>,  Prev: Errors<109>,  Up: expand_goal/2

2.5.10.15 Examples
..................

(none)

See also
........

*note expand_term/2: 19b, *note goal_expansion/2: f6, *note
term_expansion/2: f5.


File: TheLogtalkHandbook-3.50.0.info,  Node: goal_expansion/2,  Prev: expand_goal/2,  Up: Term and goal expansion<2>

2.5.10.16 ‘goal_expansion/2’
............................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<145>,  Next: Modes and number of proofs<109>,  Up: goal_expansion/2

2.5.10.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: 2e9. method.  Use of this predicate by the
‘expand_goal/2’ method may be restricted by changing its default public
scope.

Goal expansion may be also be applied when compiling source files by
defining the object providing access to the ‘goal_expansion/2’ clauses
as a *note hook object: 35e.  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: 17c. 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: 9a. to restrict the scope of this
predicate.

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

   (1) ../../../docs/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<109>,  Next: Errors<110>,  Prev: Description<145>,  Up: goal_expansion/2

2.5.10.18 Modes and number of proofs
....................................

     goal_expansion(+callable, -callable) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<110>,  Next: Examples<146>,  Prev: Modes and number of proofs<109>,  Up: goal_expansion/2

2.5.10.19 Errors
................

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<146>,  Prev: Errors<110>,  Up: goal_expansion/2

2.5.10.20 Examples
..................

     goal_expansion(write(Term), (write_term(Term, []), nl)).
     goal_expansion(read(Term), (write('Input: '), {read(Term)})).

See also
........

*note expand_goal/2: 2e9, *note expand_term/2: 19b, *note
term_expansion/2: f5, *note logtalk_load_context/2: 2ee.


File: TheLogtalkHandbook-3.50.0.info,  Node: Coinduction hooks,  Next: Message printing,  Prev: Term and goal expansion<2>,  Up: Built-in methods<2>

2.5.11 Coinduction hooks
------------------------

* Menu:

* coinductive_success_hook/1-2::


File: TheLogtalkHandbook-3.50.0.info,  Node: coinductive_success_hook/1-2,  Up: Coinduction hooks

2.5.11.1 ‘coinductive_success_hook/1-2’
.......................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<146>,  Next: Modes and number of proofs<110>,  Up: coinductive_success_hook/1-2

2.5.11.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
used that 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.50.0.info,  Node: Modes and number of proofs<110>,  Next: Errors<111>,  Prev: Description<146>,  Up: coinductive_success_hook/1-2

2.5.11.3 Modes and number of proofs
...................................

     coinductive_success_hook(+callable, +callable) - zero_or_one
     coinductive_success_hook(+callable) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<111>,  Next: Examples<147>,  Prev: Modes and number of proofs<110>,  Up: coinductive_success_hook/1-2

2.5.11.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<147>,  Prev: Errors<111>,  Up: coinductive_success_hook/1-2

2.5.11.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: 15d.


File: TheLogtalkHandbook-3.50.0.info,  Node: Message printing,  Next: Question asking,  Prev: Coinduction hooks,  Up: Built-in methods<2>

2.5.12 Message printing
-----------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: print_message/3,  Next: message_tokens//2,  Up: Message printing

2.5.12.1 ‘print_message/3’
..........................

* Menu:

* Description: Description<147>.
* Modes and number of proofs: Modes and number of proofs<111>.
* Errors: Errors<112>.
* Examples: Examples<148>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<147>,  Next: Modes and number of proofs<111>,  Up: print_message/3

2.5.12.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): 2db. 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): 2e0.
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): 2df. hook predicate.  If this predicate succeeds, the
‘print_message/3’ predicate assumes that the message have been
successfully printed.

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

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<111>,  Next: Errors<112>,  Prev: Description<147>,  Up: print_message/3

2.5.12.3 Modes and number of proofs
...................................

     print_message(+nonvar, +nonvar, +nonvar) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<112>,  Next: Examples<148>,  Prev: Modes and number of proofs<111>,  Up: print_message/3

2.5.12.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<148>,  Prev: Errors<112>,  Up: print_message/3

2.5.12.5 Examples
.................

     ..., logtalk::print_message(information, core, redefining_entity(object, foo)), ...

See also
........

*note message_hook/4: 2df, *note message_prefix_stream/4: 2e0, *note
message_tokens//2: 2db, *note print_message_tokens/3: 76b, *note
print_message_token/4: 76c, *note ask_question/5: 2e2, *note
question_hook/6: 2e4, *note question_prompt_stream/4: 76d.


File: TheLogtalkHandbook-3.50.0.info,  Node: message_tokens//2,  Next: message_hook/4,  Prev: print_message/3,  Up: Message printing

2.5.12.6 ‘message_tokens//2’
............................

* Menu:

* Description: Description<148>.
* Modes and number of proofs: Modes and number of proofs<112>.
* Errors: Errors<113>.
* Examples: Examples<149>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<148>,  Next: Modes and number of proofs<112>,  Up: message_tokens//2

2.5.12.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: 76b. method.  This
non-terminal hook is automatically called by the *note print_message/3:
2d8. method.

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

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<112>,  Next: Errors<113>,  Prev: Description<148>,  Up: message_tokens//2

2.5.12.8 Modes and number of proofs
...................................

     message_tokens(+nonvar, +nonvar) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<113>,  Next: Examples<149>,  Prev: Modes and number of proofs<112>,  Up: message_tokens//2

2.5.12.9 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<149>,  Prev: Errors<113>,  Up: message_tokens//2

2.5.12.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: 2df, *note message_prefix_stream/4: 2e0, *note
print_message/3: 2d8, *note print_message_tokens/3: 76b, *note
print_message_token/4: 76c, *note ask_question/5: 2e2, *note
question_hook/6: 2e4, *note question_prompt_stream/4: 76d.


File: TheLogtalkHandbook-3.50.0.info,  Node: message_hook/4,  Next: message_prefix_stream/4,  Prev: message_tokens//2,  Up: Message printing

2.5.12.11 ‘message_hook/4’
..........................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<149>,  Next: Modes and number of proofs<113>,  Up: message_hook/4

2.5.12.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: 2d8. method.  When the call succeeds, the
‘print_message/3’ method assumes that the message have been successfully
printed.

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

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<113>,  Next: Errors<114>,  Prev: Description<149>,  Up: message_hook/4

2.5.12.13 Modes and number of proofs
....................................

     message_hook(@nonvar, @nonvar, @nonvar, @list(nonvar)) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<114>,  Next: Examples<150>,  Prev: Modes and number of proofs<113>,  Up: message_hook/4

2.5.12.14 Errors
................

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<150>,  Prev: Errors<114>,  Up: message_hook/4

2.5.12.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: 2e0, *note message_tokens//2: 2db, *note
print_message/3: 2d8, *note print_message_tokens/3: 76b, *note
print_message_token/4: 76c, *note ask_question/5: 2e2, *note
question_hook/6: 2e4, *note question_prompt_stream/4: 76d.


File: TheLogtalkHandbook-3.50.0.info,  Node: message_prefix_stream/4,  Next: print_message_tokens/3,  Prev: message_hook/4,  Up: Message printing

2.5.12.16 ‘message_prefix_stream/4’
...................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<150>,  Next: Modes and number of proofs<114>,  Up: message_prefix_stream/4

2.5.12.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: 31d.  This
method is declared in the logtalk(1) built-in object as a public,
multifile, and dynamic predicate.

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

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<114>,  Next: Errors<115>,  Prev: Description<150>,  Up: message_prefix_stream/4

2.5.12.18 Modes and number of proofs
....................................

     message_prefix_stream(?nonvar, ?nonvar, ?atom, ?stream_or_alias) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<115>,  Next: Examples<151>,  Prev: Modes and number of proofs<114>,  Up: message_prefix_stream/4

2.5.12.19 Errors
................

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<151>,  Prev: Errors<115>,  Up: message_prefix_stream/4

2.5.12.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_hook/4: 2df, *note message_tokens//2: 2db, *note
print_message/3: 2d8, *note print_message_tokens/3: 76b, *note
print_message_token/4: 76c, *note ask_question/5: 2e2, *note
question_hook/6: 2e4, *note question_prompt_stream/4: 76d.


File: TheLogtalkHandbook-3.50.0.info,  Node: print_message_tokens/3,  Next: print_message_token/4,  Prev: message_prefix_stream/4,  Up: Message printing

2.5.12.21 ‘print_message_tokens/3’
..................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<151>,  Next: Modes and number of proofs<115>,  Up: print_message_tokens/3

2.5.12.22 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: 2d8. method (assuming
that the message was not intercepted by a *note message_hook/4: 2df.
definition) and calls the user-defined hook predicate *note
print_message_token/4: 76c. for each token.  When a call to this hook
predicate succeeds, the ‘print_message_tokens/3’ predicate assumes that
the token have been printed.  When the call fails, the
‘print_message_tokens/3’ predicate uses a default printing procedure for
the token.

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

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<115>,  Next: Errors<116>,  Prev: Description<151>,  Up: print_message_tokens/3

2.5.12.23 Modes and number of proofs
....................................

     print_message_tokens(@stream_or_alias, +atom, @list(nonvar)) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<116>,  Next: Examples<152>,  Prev: Modes and number of proofs<115>,  Up: print_message_tokens/3

2.5.12.24 Errors
................

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<152>,  Prev: Errors<116>,  Up: print_message_tokens/3

2.5.12.25 Examples
..................

     ...,
     logtalk::print_message_tokens(user_error, '% ', ['Redefining ~w ~q'-[object,foo], nl]),
     ...

See also
........

*note message_hook/4: 2df, *note message_prefix_stream/4: 2e0, *note
message_tokens//2: 2db, *note print_message/3: 2d8, *note
print_message_token/4: 76c, *note ask_question/5: 2e2, *note
question_hook/6: 2e4, *note question_prompt_stream/4: 76d.


File: TheLogtalkHandbook-3.50.0.info,  Node: print_message_token/4,  Prev: print_message_tokens/3,  Up: Message printing

2.5.12.26 ‘print_message_token/4’
.................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<152>,  Next: Modes and number of proofs<116>,  Up: print_message_token/4

2.5.12.27 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: 76b. built-in method for each token.

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

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<116>,  Next: Errors<117>,  Prev: Description<152>,  Up: print_message_token/4

2.5.12.28 Modes and number of proofs
....................................

     print_message_token(@stream_or_alias, @atom, @nonvar, @list(nonvar)) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<117>,  Next: Examples<153>,  Prev: Modes and number of proofs<116>,  Up: print_message_token/4

2.5.12.29 Errors
................

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<153>,  Prev: Errors<117>,  Up: print_message_token/4

2.5.12.30 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: 2df, *note message_prefix_stream/4: 2e0, *note
message_tokens//2: 2db, *note print_message/3: 2d8, *note
print_message_tokens/3: 76b, *note ask_question/5: 2e2, *note
question_hook/6: 2e4, *note question_prompt_stream/4: 76d.


File: TheLogtalkHandbook-3.50.0.info,  Node: Question asking,  Prev: Message printing,  Up: Built-in methods<2>

2.5.13 Question asking
----------------------

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: ask_question/5,  Next: question_hook/6,  Up: Question asking

2.5.13.1 ‘ask_question/5’
.........................

* Menu:

* Description: Description<153>.
* Modes and number of proofs: Modes and number of proofs<117>.
* Meta-predicate template::
* Errors: Errors<118>.
* Examples: Examples<154>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<153>,  Next: Modes and number of proofs<117>,  Up: ask_question/5

2.5.13.2 Description
....................

     ask_question(Question, Kind, Component, 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): 2db. 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): 76d.
hook predicate.  The ‘Check’ argument is a *note closure: 13f. 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
checking predicate succeeds.

This predicate starts by calling the *note
logtalk;;question_hook(Question, Kind, Component, Check, Answer): 2e4.
hook predicate.  If this predicate succeeds, the ‘ask_question/5’
predicate assumes that the question have been successfully asked and
replied.


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<117>,  Next: Meta-predicate template,  Prev: Description<153>,  Up: ask_question/5

2.5.13.3 Modes and number of proofs
...................................

     ask_question(+nonvar, +nonvar, +nonvar, +callable, -term) - one


File: TheLogtalkHandbook-3.50.0.info,  Node: Meta-predicate template,  Next: Errors<118>,  Prev: Modes and number of proofs<117>,  Up: ask_question/5

2.5.13.4 Meta-predicate template
................................

     ask_question(*, *, *, 1, *)


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<118>,  Next: Examples<154>,  Prev: Meta-predicate template,  Up: ask_question/5

2.5.13.5 Errors
...............

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<154>,  Prev: Errors<118>,  Up: ask_question/5

2.5.13.6 Examples
.................

     ...,
     logtalk::ask_question(enter_age, question, my_app, integer, Age),
     ...

See also
........

*note question_hook/6: 2e4, *note question_prompt_stream/4: 76d, *note
message_hook/4: 2df, *note message_prefix_stream/4: 2e0, *note
message_tokens//2: 2db, *note print_message/3: 2d8, *note
print_message_tokens/3: 76b, *note print_message_token/4: 76c.


File: TheLogtalkHandbook-3.50.0.info,  Node: question_hook/6,  Next: question_prompt_stream/4,  Prev: ask_question/5,  Up: Question asking

2.5.13.7 ‘question_hook/6’
..........................

* Menu:

* Description: Description<154>.
* Modes and number of proofs: Modes and number of proofs<118>.
* Meta-predicate template: Meta-predicate template<2>.
* Errors: Errors<119>.
* Examples: Examples<155>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<154>,  Next: Modes and number of proofs<118>,  Up: question_hook/6

2.5.13.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: 2e2. method.  When the call succeeds, the
‘ask_question/5’ method assumes that the question have been successfully
asked and replied.

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

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<118>,  Next: Meta-predicate template<2>,  Prev: Description<154>,  Up: question_hook/6

2.5.13.9 Modes and number of proofs
...................................

     question_hook(+nonvar, +nonvar, +nonvar, +list(nonvar), +callable, -term) - zero_or_one


File: TheLogtalkHandbook-3.50.0.info,  Node: Meta-predicate template<2>,  Next: Errors<119>,  Prev: Modes and number of proofs<118>,  Up: question_hook/6

2.5.13.10 Meta-predicate template
.................................

     question_hook(*, *, *, *, 1, *)


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<119>,  Next: Examples<155>,  Prev: Meta-predicate template<2>,  Up: question_hook/6

2.5.13.11 Errors
................

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<155>,  Prev: Errors<119>,  Up: question_hook/6

2.5.13.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: 2e2, *note question_prompt_stream/4: 76d. *note
message_hook/4: 2df, *note message_prefix_stream/4: 2e0, *note
message_tokens//2: 2db, *note print_message/3: 2d8, *note
print_message_tokens/3: 76b, *note print_message_token/4: 76c,


File: TheLogtalkHandbook-3.50.0.info,  Node: question_prompt_stream/4,  Prev: question_hook/6,  Up: Question asking

2.5.13.13 ‘question_prompt_stream/4’
....................................

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Description<155>,  Next: Modes and number of proofs<119>,  Up: question_prompt_stream/4

2.5.13.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: 31d.
This method is declared in the logtalk(1) built-in object as a public,
multifile, and dynamic predicate.

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

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Modes and number of proofs<119>,  Next: Errors<120>,  Prev: Description<155>,  Up: question_prompt_stream/4

2.5.13.15 Modes and number of proofs
....................................

     question_prompt_stream(?nonvar, ?nonvar, ?atom, ?stream_or_alias) - zero_or_more


File: TheLogtalkHandbook-3.50.0.info,  Node: Errors<120>,  Next: Examples<156>,  Prev: Modes and number of proofs<119>,  Up: question_prompt_stream/4

2.5.13.16 Errors
................

(none)


File: TheLogtalkHandbook-3.50.0.info,  Node: Examples<156>,  Prev: Errors<120>,  Up: question_prompt_stream/4

2.5.13.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: 2e2, *note question_hook/6: 2e4, *note
message_hook/4: 2df, *note message_prefix_stream/4: 2e0, *note
message_tokens//2: 2db, *note print_message/3: 2d8, *note
print_message_tokens/3: 76b, *note print_message_token/4: 76c.


File: TheLogtalkHandbook-3.50.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.50.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.50.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: 96. and *note end_object/0: 97, 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: 138. 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: 332. section on the User Manual), we can compile and load the
object using the *note logtalk_load/1: 44. 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: 7a. 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.50.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 compilations
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:
d5. and *note end_protocol/0: d6. 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: 13d. 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.50.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 put 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.50.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.50.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 attributes
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 predicates directives and/or
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, the calls to the
built-in methods that handle the private dynamic predicate (such as
*note assertz/1: 197. or *note retract/1: 199.) must be made either in
the context of `self', using the `message to self' control structure,
*note ;;/1: 57, 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 predicates definitions
are straightforward.  For example, if opting for storing 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 for storing the attributes on `this', is
similar: just delete the uses of the ‘::/1’ control structure from the
code above.

We have two new directives, *note category/1-4: 106. and *note
end_category/0: 107, that encapsulate the category code.  If needed, we
can put the predicates 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.50.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.50.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.50.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 instance
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]: 12, 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]: 98.  This extension provides, along with root objects
for the instantiation and specialization hierarchies, explicit support
for abstract classes *note [Moura94]: 99.

* Menu:

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


File: TheLogtalkHandbook-3.50.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: 35. endless loops.


File: TheLogtalkHandbook-3.50.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.50.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.50.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 have multiple solutions, then one ‘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: 7a. operator.


File: TheLogtalkHandbook-3.50.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: fa.
for ‘before’ events and *note after/3: fb. 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: 1f9.
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: 1fc. 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.50.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 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:
     fa. and *note after/3: fb, that are automatically called by the
     runtime engine when a spied event occurs.

   - Three built-in predicates, *note define_events/5: 1f9, *note
     current_event/5: 1ff, and *note abolish_events/5: 1fc, enables us
     define, query, and abolish both events and monitors.


File: TheLogtalkHandbook-3.50.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.50.0.info,  Node: General,  Next: Compatibility,  Up: FAQ

4.1 General
===========

   * *note Why are all versions of Logtalk numbered 2.x or 3.x?: 7c4.

   * *note Why do I need a Prolog compiler to use Logtalk?: 7c5.

   * *note Is the Logtalk implementation based on Prolog modules?: 7c6.

   * *note Does the Logtalk implementation use term-expansion?: 7c7.

* 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.50.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 refers to,
respectively, the second and the third generations of the Logtalk
language.  Development of Logtalk 2 started on January 1998, with the
first alpha release for registered users on July and the first public
beta on October.  The first stable version of Logtalk 2 was released on
February 9, 1999.  Development of Logtalk 3 started on April 2012, with
the first public alpha released on August 21, 2012.  The first stable
version of Logtalk 3 was released on January 7, 2015.


File: TheLogtalkHandbook-3.50.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 Prolog extension
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 Prolog extension
allows users to use Logtalk together with features only available on
specific Prolog compilers.


File: TheLogtalkHandbook-3.50.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 is 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: 34b. for details).


File: TheLogtalkHandbook-3.50.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.50.0.info,  Node: Compatibility,  Next: Installation,  Prev: General,  Up: FAQ

4.2 Compatibility
=================

   * *note What are the backend Prolog compiler requirements to run
     Logtalk?: 7cf.

   * *note Can I use constraint-based packages with Logtalk?: 7d0.

   * *note Can I use Logtalk objects and Prolog modules at the same
     time?: 7d1.

* 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.50.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.50.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: 17c. control construct (thus
bypassing the Logtalk compiler).


File: TheLogtalkHandbook-3.50.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: 4a. directive or use
explicit module qualification (possibly wrapping the call using the
Logtalk control construct *note {}/1: 17c. 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: 34b. for details).


File: TheLogtalkHandbook-3.50.0.info,  Node: Installation,  Next: Portability,  Prev: Compatibility,  Up: FAQ

4.3 Installation
================

   * *note The integration scripts/shortcuts are not working!: 7d8.

   * *note I get errors when starting up Logtalk after upgrading to the
     latest version!: 7d9.

* Menu:

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


File: TheLogtalkHandbook-3.50.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 on 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.50.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.50.0.info,  Node: Portability,  Next: Programming,  Prev: Installation,  Up: FAQ

4.4 Portability
===============

   * *note Are my Logtalk applications portable across Prolog
     compilers?: 7df.

   * *note Are my Logtalk applications portable across operating
     systems?: 7e0.

* Menu:

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


File: TheLogtalkHandbook-3.50.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: 1b4.
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.50.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 in some
operating-systems.  You may need to change the end-of-lines 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-lines
characters.


File: TheLogtalkHandbook-3.50.0.info,  Node: Programming,  Next: Troubleshooting,  Prev: Portability,  Up: FAQ

4.5 Programming
===============

   * *note Should I use prototypes or classes in my application?: 7e6.

   * *note Can I use both classes and prototypes in the same
     application?: 7e7.

   * *note Can I mix classes and prototypes in the same hierarchy?: 7e8.

   * *note Can I use a protocol or a category with both prototypes and
     classes?: 7e9.

   * *note What support is provided in Logtalk for defining and using
     components?: 7ea.

   * *note What support is provided in Logtalk for reflective
     programming?: 7eb.

* 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.50.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.50.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.50.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.50.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.50.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 on the Smalltalk-80
(documentation-only) concept of method categories and on Objective-C
categories, hence the name.  For more information, please consult the
*note Categories: 101. section and the examples provided with the
distribution.


File: TheLogtalkHandbook-3.50.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.50.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 do not work!: 7f5.

   * *note Gecko-based browsers (e.g.  Firefox) show non-rendered HTML
     entities when browsing XML documenting files!: 7f6.

   * *note Compiling a source file results in errors or warnings but the
     Logtalk compiler reports a successful compilation with zero errors
     and zero warnings!: 7f7.

* Menu:

* Using compiler options on calls to the Logtalk compiling and loading predicates do 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.50.0.info,  Node: Using compiler options on calls to the Logtalk compiling and loading predicates do 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 do not work!
--------------------------------------------------------------------------------------------------

Using compiler options on calls to the Logtalk *note logtalk_compile/2:
292. and *note logtalk_load/2: 284. built-in predicates only apply the
file being compiled.  If the first argument is a *note loader file: 1bb,
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.50.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 do 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 other 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.50.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.50.0.info,  Node: Usability,  Next: Deployment,  Prev: Troubleshooting,  Up: FAQ

4.7 Usability
=============

   * *note Is there a shortcut for compiling and loading source files?:
     7fe.

   * *note Is there an equivalent directive to the ensure_loaded/1
     Prolog directive?: 7ff.

   * *note Are there shortcuts for the make functionality?: 800.

* 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.50.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: 44. predicate for details.


File: TheLogtalkHandbook-3.50.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’ is only loaded once.  See the documentation of the *note
logtalk_load/2: 284. predicate for details.


File: TheLogtalkHandbook-3.50.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: 281. predicate for details.


File: TheLogtalkHandbook-3.50.0.info,  Node: Deployment,  Next: Performance<3>,  Prev: Usability,  Up: FAQ

4.8 Deployment
==============

   * *note Can I create standalone applications with Logtalk?: 807.

* Menu:

* Can I create standalone applications with Logtalk?::


File: TheLogtalkHandbook-3.50.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.50.0.info,  Node: Performance<3>,  Next: Licensing,  Prev: Deployment,  Up: FAQ

4.9 Performance
===============

   * *note Is Logtalk implemented as a meta-interpreter?: 80c.

   * *note What kind of code Logtalk generates when compiling objects?
     Dynamic code?  Static code?: 80d.

   * *note How about message-sending performance?  Does Logtalk use
     static binding or dynamic binding?: 80e.

   * *note How does Logtalk performance compare with plain Prolog and
     with Prolog modules?: 80f.

* 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.50.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.50.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.50.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: 36. for more
details.


File: TheLogtalkHandbook-3.50.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.50.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.50.0.info,  Node: Licensing,  Next: Support,  Prev: Performance<3>,  Up: FAQ

4.10 Licensing
==============

   * *note What’s the Logtalk distribution license?: 818.

   * *note Can Logtalk be used in commercial applications?: 819.

   * *note What’s the final license for a combination of Logtalk with a
     Prolog compiler?: 81a.

* 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.50.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.50.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) http://www.apache.org/foundation/license-faq.html


File: TheLogtalkHandbook-3.50.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.50.0.info,  Node: Support,  Prev: Licensing,  Up: FAQ

4.11 Support
============

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

* Menu:

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


File: TheLogtalkHandbook-3.50.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,
developing, training, and other supporting services.

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

   (1) https://logtalk.pt


File: TheLogtalkHandbook-3.50.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::
* lgtdoc::
* lgtunit::
* linter::
* make::
* ports_profiler::
* profiler::
* tutor::
* wrapper::


File: TheLogtalkHandbook-3.50.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) and ‘NOTES.md’ documentation files:

   - ‘asdf’

   - ‘assertions’

   - ‘code_metrics’

   - ‘dead_code_scanner’

   - ‘debug_messages’

   - ‘debugger’

   - ‘diagrams’

   - ‘doclet’

   - ‘help’

   - ‘lgtdoc’

   - ‘lgtunit’

   - ‘linter’

   - ‘make’

   - ‘ports_profiler’

   - ‘profiler’

   - ‘tutor’

   - ‘wrapper’

* Menu:

* Loading the developer tools::
* Tools documentation::


File: TheLogtalkHandbook-3.50.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 useful 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.50.0.info,  Node: Tools documentation,  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 on
the ‘docs’ directory (open the ‘../docs/index.html’ file with your web
browser).  The documentation for these tools can be regenerated using
the shell scripts ‘../scripts/update_html_docs.sh’ and
‘../scripts/update_svg_diagrams.sh’.


File: TheLogtalkHandbook-3.50.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.50.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 using 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 on 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.50.0.info,  Node: API documentation,  Next: Loading,  Up: assertions

5.3.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../docs/library_index.html#assertions’


File: TheLogtalkHandbook-3.50.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.50.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.50.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.50.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.50.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.50.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.50.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.50.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.  One 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::
* Usage::
* Defining new metrics::
* Third-party tools::
* Applying metrics to Prolog modules::
* Applying metrics to plain Prolog code::


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<2>,  Next: Loading<2>,  Up: code_metrics

5.4.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../docs/library_index.html#code-metrics’


File: TheLogtalkHandbook-3.50.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.50.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.50.0.info,  Node: Available metrics,  Next: Usage,  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.

For interpretation of the coupling metric scores, see e.g.  the original
paper by Robert Martin, “OO Design Quality Metrics”:

     @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 Halstead metric computation uses the reflection API for performance.
The main consequence of this choice is that we abstract all predicate
arguments.  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 large computation cost.

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.

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 cyclomatic complexity metric uses the same predicate abstraction as
the UPN metric and it is also described in the above paper besides 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",
     }

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.50.0.info,  Node: Usage,  Next: Defining new metrics,  Prev: Available metrics,  Up: code_metrics

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Defining new metrics,  Next: Third-party tools,  Prev: Usage,  Up: code_metrics

5.4.6 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.50.0.info,  Node: Third-party tools,  Next: Applying metrics to Prolog modules,  Prev: Defining new metrics,  Up: code_metrics

5.4.7 Third-party tools
-----------------------

‘cloc’ is an open-source command-line program that counts blank lines,
comment lines, and lines of source code in many programming languages
including Logtalk.  Available at ‘https://github.com/AlDanial/cloc’

‘ohcount’ is an open-source command-line program that counts blank
lines, comment lines, and lines of source code in many programming
languages including Logtalk.  Available at
‘https://github.com/blackducksoftware/ohcount’

‘tokei’ is an open-source command-line program that counts blank lines,
comment lines, and lines of source code in many programming languages
including Logtalk.  Available at ‘https://github.com/Aaronepower/tokei’


File: TheLogtalkHandbook-3.50.0.info,  Node: Applying metrics to Prolog modules,  Next: Applying metrics to plain Prolog code,  Prev: Third-party tools,  Up: code_metrics

5.4.8 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.50.0.info,  Node: Applying metrics to plain Prolog code,  Prev: Applying metrics to Prolog modules,  Up: code_metrics

5.4.9 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(object_wrapper_hook)).
     ...

     | ?- 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
of working when wrapped by an object.


File: TheLogtalkHandbook-3.50.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.

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 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>.
* Integration with the make tool::
* Caveats::
* Scanning Prolog modules::
* Scanning plain Prolog files::


File: TheLogtalkHandbook-3.50.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:

‘../../docs/library_index.html#dead-code-scanner’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.50.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.50.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.50.0.info,  Node: Usage<2>,  Next: Integration with the make tool,  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 in 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 is also a
‘rlibrary/1’ predicate that performs 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.50.0.info,  Node: Integration with the make tool,  Next: Caveats,  Prev: Usage<2>,  Up: dead_code_scanner

5.5.5 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.50.0.info,  Node: Caveats,  Next: Scanning Prolog modules,  Prev: Integration with the make tool,  Up: dead_code_scanner

5.5.6 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.50.0.info,  Node: Scanning Prolog modules,  Next: Scanning plain Prolog files,  Prev: Caveats,  Up: dead_code_scanner

5.5.7 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.50.0.info,  Node: Scanning plain Prolog files,  Prev: Scanning Prolog modules,  Up: dead_code_scanner

5.5.8 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(object_wrapper_hook)).
     ...

     | ?- 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.50.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.50.0.info,  Node: API documentation<4>,  Next: Loading<4>,  Up: debug_messages

5.6.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../docs/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:

‘../../manuals/userman/debugging.html’


File: TheLogtalkHandbook-3.50.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.50.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.50.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.50.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.50.0.info,  Node: API documentation<5>,  Next: Loading<5>,  Up: debugger

5.7.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../docs/library_index.html#debugger’


File: TheLogtalkHandbook-3.50.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)).

Note that this tool cannot be loaded at the same time as other tools
(e.g.  the ports profiler) that also provide a debug handler, which must
be unique in a running session.

When the code to be debugged runs computationally expensive
initializations, loading this tool after the code may have a noticeable
impact in loading times.


File: TheLogtalkHandbook-3.50.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.50.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:

‘../../manuals/userman/debugging.html’

The ‘debugger_messages.lgt’ source file defines the default debugger
message translations.

The ‘dump_trace.lgt’ contains a simple code example on how to redirect a
goal trace to a file.


File: TheLogtalkHandbook-3.50.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 ‘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:

     | ?- gtrace, foo::bar.

You can also use the ‘gspy/1’ predicate to spy 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.50.0.info,  Node: Known issues,  Prev: Alternative debugger tools,  Up: debugger

5.7.6 Known issues
------------------

Line number spy points (aka breakpoints) require a Prolog backend
compiler that supports accessing read term starting line but only some
backends (B-Prolog, GNU Prolog, JIProlog, Lean Prolog, LVM, SICStus
Prolog, SWI-Prolog, 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)).

and checking 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.

Line number spy points are currently not available when using XSB as the
Prolog backend compiler.


File: TheLogtalkHandbook-3.50.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’ script.  See the ‘doclet’ tool examples and
documentation for details.  See also the ‘diagrams’ tool ‘lgt2svg’
script.

* Menu:

* 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.50.0.info,  Node: API documentation<6>,  Next: Loading<6>,  Up: diagrams

5.8.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../docs/library_index.html#diagrams’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<6>,  Next: Testing<6>,  Prev: API documentation<6>,  Up: diagrams

5.8.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(diagrams(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<6>,  Next: Supported diagrams,  Prev: Loading<6>,  Up: diagrams

5.8.3 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(diagrams(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Supported diagrams,  Next: Graph elements,  Prev: Testing<6>,  Up: diagrams

5.8.4 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 in 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, specially 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.50.0.info,  Node: Graph elements,  Next: Supported graph languages,  Prev: Supported diagrams,  Up: diagrams

5.8.5 Graph elements
--------------------

Limitations in both the graph language and UML forces the invention of a
modeling language that can represent all kinds of Logtalk entities and
entity relations.  Currently we use the following Graphviz DOT shapes
(libraries, entities, predicates, and files) and arrows (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 
          ‘tab’ (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) 

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.50.0.info,  Node: Supported graph languages,  Next: Customization,  Prev: Graph elements,  Up: diagrams

5.8.6 Supported graph languages
-------------------------------

Currently only the DOT graph language is supported (tested with Graphviz
version 2.43 on macOS; visit the ‘http://www.graphviz.org/’ website for
more information).  Some recent versions have a nasty regression in the
SVG exporter where text overflows the boxes that should contain it.
Also, old stable versions such as 2.40.1 have a bug (fixed in the recent
versions) that can result in very long edges.

The diagrams ‘.dot’ files are created on the current directory by
default.  These files can be easily converted into a printable format
such as SVG, PDF, or Postscript.  For example, using the ‘dot’
command-line executable we can simply type:

     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 to experiment with different layouts to find the one
that produces the best results (see the ‘layout/1’ option described
below).

Some output formats such as SVG support 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”).

Sample helper scripts are provided for converting ‘.dot’ files to ‘.svg’
files:

   - ‘lgt2svg.sh’ for POSIX systems

   - ‘lgt2svg.js’ and ‘lgt2svg.bat’ for Windows systems

The scripts assume that the Graphviz command-line executables are
available from the system path (the default is the ‘dot’ executable but
the scripts accept a command-line option to select in alternative the
‘circo’, ‘fdp’, or ‘neato’ executables).

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 in 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.50.0.info,  Node: Customization,  Next: Linking diagrams,  Prev: Supported graph languages,  Up: diagrams

5.8.7 Customization
-------------------

A set of options are 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’) 

   - 
          ‘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 .dot files (an atom; default is ‘'./'’) 

   - 
          ‘exclude_directories(Directories)’ 
          list of directories to exclude (default is ‘[]’) 

   - 
          ‘exclude_files(Files)’ 
          list of source files to exclude (default is ‘[]’) 

   - 
          ‘exclude_libraries(Libraries)’ 
          list of libraries to exclude (default is ‘[startup, scratch_directory]’) 

   - 
          ‘exclude_entities(Entities)’ 
          list of entities to exclude (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 an empty list) 

   - 
          ‘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 is also the
option:

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

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

   - 
          ‘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 an empty list) 

   - 
          ‘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 .dot files (an atom; default is ‘'./'’) 

   - 
          ‘exclude_directories(Directories)’ 
          list of directories to exclude (default is ‘[]’) 

   - 
          ‘exclude_files(Files)’ 
          list of source files to exclude (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’) 

   - 
          ‘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 an empty list) 

   - 
          ‘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 .dot files (an atom; default is ‘'./'’) 

   - 
          ‘exclude_directories(Directories)’ 
          list of directories to exclude (default is ‘[]’) 

   - 
          ‘exclude_files(Files)’ 
          list of source files to exclude (default is ‘[]’) 

   - 
          ‘exclude_libraries(Libraries)’ 
          list of libraries to exclude (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'’) 

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 generated 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.50.0.info,  Node: Linking diagrams,  Next: Creating diagrams for Prolog module applications,  Prev: Customization,  Up: diagrams

5.8.8 Linking diagrams
----------------------

When using SVG output, it’s possible to generate diagrams that link to
other diagrams, to API documentation, and to source code repositories
(to both files and directories).

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.  The sub-diagrams are automatically generated.  For
example, using the predicates that generate library diagrams will
automatically also generate the entity and predicate cross-referencing
diagrams.

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 in the Logtalk
website.  The relevant URLs in this case are:

   - ‘https://github.com/LogtalkDotOrg/logtalk3/tree/’ (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/tree/...',
          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.

See the ‘SCRIPT.txt’ file in the tool directory for additional examples.


File: TheLogtalkHandbook-3.50.0.info,  Node: Creating diagrams for Prolog module applications,  Next: Creating diagrams for plain Prolog files,  Prev: Linking diagrams,  Up: diagrams

5.8.9 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.50.0.info,  Node: Creating diagrams for plain Prolog files,  Next: Other notes,  Prev: Creating diagrams for Prolog module applications,  Up: diagrams

5.8.10 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(object_wrapper_hook)).
     ...

     | ?- logtalk_load(code, [hook(object_wrapper_hook)]),
          xref_diagram::entity(code).


File: TheLogtalkHandbook-3.50.0.info,  Node: Other notes,  Prev: Creating diagrams for plain Prolog files,  Up: diagrams

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

The zoom icons, ‘zoom.png’ and ‘zoom.svg’ have been designed by Xinh
Studio:

‘https://www.iconfinder.com/xinhstudio’

Currently, only the ‘zoom.png’ file is used.  A copy of this file must
exist in any directory used for publishing diagrams using it.  The
‘lgt2svg’ scripts take care of copying this file.

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 re-doing
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.


File: TheLogtalkHandbook-3.50.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 object 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.50.0.info,  Node: API documentation<7>,  Next: Loading<7>,  Up: doclet

5.9.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../docs/library_index.html#doclet’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.50.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.50.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.50.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.50.0.info,  Node: help,  Next: lgtdoc,  Prev: doclet,  Up: Developer Tools

5.10 ‘help’
===========

This tool provides basic on-line help for Logtalk features and libraries
when running in a limited set of operating-systems.  For help on the
Logtalk compiler error and warning messages, see the ‘tutor’ tool.

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<8>,  Next: Loading<8>,  Up: help

5.10.1 API documentation
------------------------

This tool API documentation is available at:

‘../../docs/library_index.html#help’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<8>,  Next: Testing<7>,  Prev: API documentation<8>,  Up: help

5.10.2 Loading
--------------

     | ?- logtalk_load(help(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<7>,  Next: Supported operating-systems,  Prev: Loading<8>,  Up: help

5.10.3 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(help(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Supported operating-systems,  Next: Usage<5>,  Prev: Testing<7>,  Up: help

5.10.4 Supported operating-systems
----------------------------------

Currently, support is limited to Linux, macOS, and Windows.

On Windows, the ‘start’ command must be available.  On Linux, the
‘xdg-open’ command must be available.  On macOS, the command ‘open’ is
used.

This tool relies on the library portable operating-system access
abstraction.


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<5>,  Next: Known issues<2>,  Prev: Supported operating-systems,  Up: help

5.10.5 Usage
------------

After loading the tool, use the query ‘help::help’ to get started.


File: TheLogtalkHandbook-3.50.0.info,  Node: Known issues<2>,  Prev: Usage<5>,  Up: help

5.10.6 Known issues
-------------------

On macOS, the ‘open’ command used to open documentation URLs drops the
anchors, thus preventing navigating to the specified position on the
documentation page.

ECLiPSe defines a ‘help’ prefix operator that forces wrapping this atom
between parenthesis when sending messages to the tool.  E.g.  use
‘(help)::help’ instead of ‘help::help’.


File: TheLogtalkHandbook-3.50.0.info,  Node: lgtdoc,  Next: lgtunit,  Prev: help,  Up: Developer Tools

5.11 ‘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 scripts for
converting the XML documenting files into final formats including
(X)HTML, PDF, Markdown, and reStructuredText (for use with Sphinx), or
plain text files.  The scripts are described in their ‘man’ pages and
made available in the system path by default.  See also the
‘lgtdoc/xml/NOTES.md’ for details, including `required third-party
software'.

* Menu:

* API documentation: API documentation<9>.
* Loading: Loading<9>.
* Testing: Testing<8>.
* Documenting source code::
* Generating documentation::


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<9>,  Next: Loading<9>,  Up: lgtdoc

5.11.1 API documentation
------------------------

This tool API documentation is available at:

‘../../docs/library_index.html#lgtdoc’


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<9>,  Next: Testing<8>,  Prev: API documentation<9>,  Up: lgtdoc

5.11.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(lgtdoc(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<8>,  Next: Documenting source code,  Prev: Loading<9>,  Up: lgtdoc

5.11.3 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(lgtdoc(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Documenting source code,  Next: Generating documentation,  Prev: Testing<8>,  Up: lgtdoc

5.11.4 Documenting source code
------------------------------

For information on documenting your source code, notably on documenting
directives, consult the documenting section of the User Manual:

‘../../manuals/userman/documenting.html’

Extracting documenting information from your source code using with 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.50.0.info,  Node: Generating documentation,  Prev: Documenting source code,  Up: lgtdoc

5.11.5 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) https://logtalk.org/docs/library_index.html#lgtdoc


File: TheLogtalkHandbook-3.50.0.info,  Node: lgtunit,  Next: linter,  Prev: lgtdoc,  Up: Developer Tools

5.12 ‘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 facilitate 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<10>.
* Testing: Testing<9>.
* Writing and loading tests::
* Running unit tests::
* Parametric test objects::
* Test dialects::
* User-defined test dialects::
* QuickCheck::
* Skipping 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::
* Flaky tests::
* Debugging failed tests::
* Code coverage::
* Automating running tests::
* 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::
* Minimizing test results output::
* Known issues: Known issues<3>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Main files,  Next: API documentation<10>,  Up: lgtunit

5.12.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 output, e.g.
to make it less verbose, or for integration with e.g.  GUI IDEs and
continuous integration servers.

Other files part of this tool provide support for alternative output
formats of test results and are discussed below.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<10>,  Next: Loading<10>,  Prev: Main files,  Up: lgtunit

5.12.2 API documentation
------------------------

This tool API documentation is available at:

‘../../docs/library_index.html#lgtunit’


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<10>,  Next: Testing<9>,  Prev: API documentation<10>,  Up: lgtunit

5.12.3 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(lgtunit(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<9>,  Next: Writing and loading tests,  Prev: Loading<10>,  Up: lgtunit

5.12.4 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(lgtunit(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Writing and loading tests,  Next: Running unit tests,  Prev: Testing<9>,  Up: lgtunit

5.12.5 Writing and loading tests
--------------------------------

In order to write your own unit tests, define objects extending the
‘lgtunit’ object.  You may start by copying the ‘tests-sample.lgt’ file
(at the root of the Logtalk distribution) to a ‘tests.lgt’ file in your
project directory and edit it to add your tests:

     :- object(tests,
         extends(lgtunit)).

         % test definitions
         ...

     :- end_object.

The section on *note test dialects: 87a. 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(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 tests
execution.

The ‘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 for 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
         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 tests files (the
‘logtalk_tester’ testing automation script defaults to look for test
driver files named ‘tester.lgt’ or ‘tester.logtalk’).

Debugged test sets should preferably be compiled in optimal mode,
specially when containing deterministic tests and when using the utility
benchmarking predicates.


File: TheLogtalkHandbook-3.50.0.info,  Node: Running unit tests,  Next: Parametric test objects,  Prev: Writing and loading tests,  Up: lgtunit

5.12.6 Running unit tests
-------------------------

Assuming that your test object is named ‘tests’, after compiling and
loading its source file, you can run the tests by typing:

     | ?- tests::run.

Usually, this goal is called automatically from an ‘initialization/1’
directive in a ‘tester.lgt’ loader file.  You can also 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 using 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 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.50.0.info,  Node: Parametric test objects,  Next: Test dialects,  Prev: Running unit tests,  Up: lgtunit

5.12.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.50.0.info,  Node: Test dialects,  Next: User-defined test dialects,  Prev: Parametric test objects,  Up: lgtunit

5.12.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 generated
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 binding ‘Result’ to a term that is subsumed by the ‘Expected’ term 

   - 
          ‘variant(Term1, Term2)’ 
          the test is expected to succeed binding ‘Term1’ to a term that is a variant of the ‘Term2’ term 

   - 
          ‘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(Error, _)’ 

   - 
          ‘errors(Errors)’ 
          the test is expected to throw an exception term ‘error(Error, _)’ where ‘Error’ is an element of the list ‘Errors’ 

   - 
          ‘ball(Ball)’ 
          the test is expected to throw the exception term ‘Ball’ 

   - 
          ‘balls(Balls)’ 
          the test is expected to throw an exception term ‘Ball’ where ‘Ball’ is an element of the list ‘Balls’ 

In the case of the ‘true(Assertion)’ and ‘deterministic(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.

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

   - 
          ‘note(Term)’ 
          annotation to print (between parenthesis 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.50.0.info,  Node: User-defined test dialects,  Next: QuickCheck,  Prev: Test dialects,  Up: lgtunit

5.12.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 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(library(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.50.0.info,  Node: QuickCheck,  Next: Skipping tests,  Prev: User-defined test dialects,  Up: lgtunit

5.12.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 labels argument; no default).

   - ‘v/1’: boolean option for verbose reporting of generated random
     tests (default is ‘false’).

The ‘quick_check/1’ uses the default option values.  When using the
‘quick_check/2-3’ predicates, invalid options are ignored and replaced
with the default value if applicable.  The ‘quick_check/3’ predicate
returns results in reified form:

   - ‘passed(Seed, Discarded, Labels)’,

   - ‘failed(Goal, Seed)’

   - ‘error(Error, Culprit)’ or ‘error(Error, Goal, Seed)’

The ‘Goal’ argument is the random test that failed.  The ‘Seed’ argument
is the starting seed used to generate the random tests and should be
regarded as an opaque term.  See below how to use it when testing bug
fixes.  The ‘error(Error, Culprit)’ result only occurs when the template
is not callable (e.g.  a non-existing predicate) or when there’s 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).

The ‘Discarded’ argument returns the number of generated tests that were
discarded for failing to comply 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 verify that the generated tests provide
the necessary coverage.  The labelling 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('}U')
     *     Failure:   atom(-13)
     *     Shrinked:  atom(-6)
     *     Shrinked:  atom(-3)
     *     Shrinked:  atom(-1)
     *     Shrinked:  atom(0)
     *     quick check test failure (at test 2 after 4 shrinks):
     *       atom(0)
     *     starting seed: seed(1341,12174,18263)
     no

The other two predicates print the test results.  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.  A simple example by 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)
     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
succeed 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)
     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 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

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
(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 of 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 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 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 using 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 ‘arbitrary’
library category multifile predicates.


File: TheLogtalkHandbook-3.50.0.info,  Node: Skipping tests,  Next: Checking test goal results,  Prev: QuickCheck,  Up: lgtunit

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

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 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.50.0.info,  Node: Checking test goal results,  Next: Testing local predicates,  Prev: Skipping tests,  Up: lgtunit

5.12.12 Checking test goal results
----------------------------------

Checking test goal results can be performed using the ‘test/2-3’
dialects ‘true/1’ and ‘deterministic/1’ assertions.  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 check 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.


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing local predicates,  Next: Testing non-deterministic predicates,  Prev: Checking test goal results,  Up: lgtunit

5.12.13 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.50.0.info,  Node: Testing non-deterministic predicates,  Next: Testing generators,  Prev: Testing local predicates,  Up: lgtunit

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing generators,  Next: Testing input/output predicates,  Prev: Testing non-deterministic predicates,  Up: lgtunit

5.12.15 Testing generators
--------------------------

To test all solutions of a predicate that acts as a `generator', we can
use 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:

     :- uses(lgtunit, [assertion/2]).
     ...

     test(test_solution_generator) :-
         forall(
             generator(X, Y, Z),
             assertion(generator(X,Y,Z), test(X,Y,Z))
         ).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing input/output predicates,  Next: Suppressing tested predicates output,  Prev: Testing generators,  Up: lgtunit

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

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 consist 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 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(my_alias, 'qwerty'),
         get_char(my_alias, Char).

     test(get_char_2_02, true(Assertion)) :-
         ^^set_text_input(my_alias, 'qwerty'),
         get_char(my_alias, _Char),
         ^^text_input_assertion(my_alias, 'werty', Assertion).

Testing output predicates follows the same pattern by using instead the
‘set_text_output/1-2’ and ‘text_output_assertion/2-3’ predicates.  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
conformance of standard input/output predicates.


File: TheLogtalkHandbook-3.50.0.info,  Node: Suppressing tested predicates output,  Next: Tests with timeout limits,  Prev: Testing input/output predicates,  Up: lgtunit

5.12.17 Suppressing tested predicates output
--------------------------------------------

Sometimes predicates being tested output text or binary data that at
best clutters testing logs and at worse 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.

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Tests with timeout limits,  Next: Setup and cleanup goals,  Prev: Suppressing tested predicates output,  Up: lgtunit

5.12.18 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’ predicate

   - ECLiPSe: ‘timeout/3’ and ‘timeout/7’ library predicates

   - SICStus Prolog: ‘time_out/3’ library predicate

   - SWI-Prolog: ‘call_with_time_limit/2’ library 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.50.0.info,  Node: Setup and cleanup goals,  Next: Test annotations,  Prev: Tests with timeout limits,  Up: lgtunit

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Test annotations,  Next: Flaky tests,  Prev: Setup and cleanup goals,  Up: lgtunit

5.12.20 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')]) :-
         ...

Annotations are written, by default, between parenthesis after and in
the same line as the test results.


File: TheLogtalkHandbook-3.50.0.info,  Node: Flaky tests,  Next: Debugging failed tests,  Prev: Test annotations,  Up: lgtunit

5.12.21 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
‘note/1’ annotation can be used to alert that a test failure is for a
flaky test.  If the ‘note/1’ argument is an atom containing the sub-atom
‘flaky’, the testing automation support outputs the text ‘[flaky]’ when
reporting failed tests.  Moreover, the ‘logtalk_tester’ automation
script will ignore failed flaky tests when setting its exit status.


File: TheLogtalkHandbook-3.50.0.info,  Node: Debugging failed tests,  Next: Code coverage,  Prev: Flaky tests,  Up: lgtunit

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

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 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 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 to define
‘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.50.0.info,  Node: Code coverage,  Next: Automating running tests,  Prev: Debugging failed tests,  Up: lgtunit

5.12.23 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 represents 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

   - XSB: ‘set_file_write_depth/1’ predicate

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

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Automating running tests,  Next: Utility predicates,  Prev: Code coverage,  Up: lgtunit

5.12.24 Automating running tests
--------------------------------

You can use the ‘scripts/logtalk_tester.sh’ Bash shell script for
automating running unit tests.  See the ‘scripts/NOTES.md’ file for
details or type:

     $ logtalk_tester -h

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’

This 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 their 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.50.0.info,  Node: Utility predicates,  Next: Exporting test results in xUnit XML format,  Prev: Automating running tests,  Up: lgtunit

5.12.25 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, Epsilon)’ 
          for number approximate equality 

   - 
          ‘essentially_equal(Number1, Number2, Epsilon)’ 
          for number essential 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 is a call to local predicate of the tests object, you
must call ‘assertion/1-2’ using an implicit or explicit message instead
of a using `super' call.  To use an implicit message, add the following
directive to the tests object:

     :- uses(lgtunit, [assertion/1, assertion/2]).

The reason this is required is that the ‘assertion/1-2’ predicates are
declared as meta-predicates and thus assertion goals are 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.  But note that the CPU execution
time (in seconds) for each individual test is reported by default when
running the tests.

Consult the ‘lgtunit’ object documentation for more details on these
predicates.


File: TheLogtalkHandbook-3.50.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.12.26 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 in alternative 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 on the test set directories.

There are several third-party xUnit report converters that can generate
HTML files for easy browsing.  For example:

   - ‘http://allure.qatools.ru’ (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.50.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.12.27 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 on 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.50.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.12.28 Generating Allure reports
---------------------------------

A shell script is provided for generating Allure(1) reports.  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 ‘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 persistant 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.  For example:

     $ logtalk_allure_report -- Backend='GNU Prolog' Version=1.4.5

Or:

     $ logtalk_allure_report -- Project='Deep Thought' Commit=`git rev-parse --short HEAD`

When using the ‘xunit_net_v2’ output format, it’s possible to generate
reports with 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:

     $ cd $LOGTALKUSER
     $ logtalk_tester \
       -p gnu \
       -f xunit_net_v2 \
       -s "$LOGTALKUSER" \
       -u "https://github.com/LogtalkDotOrg/logtalk3/tree/3e4ea295986fb09d0d4aade1f3b4968e29ef594e/"

The use of 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 tests 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.

There are some caveats when generating Allure reports that users must be
aware.  First, Allure expects test names to be unique across different
tests sets.  If there are two test with the same name in two different
test sets, only one of them will be reported.  Second, skipped test sets
are not reported.  Finally, when using the xUnit.net v2 XML format,
tests are reported in a random order instead of their run order.

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

   (1) http://allure.qatools.ru


File: TheLogtalkHandbook-3.50.0.info,  Node: Exporting code coverage results in XML format,  Next: Minimizing test results output,  Prev: Generating Allure reports,  Up: lgtunit

5.12.29 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

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 in 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 are you running.


File: TheLogtalkHandbook-3.50.0.info,  Node: Minimizing test results output,  Next: Known issues<3>,  Prev: Exporting code coverage results in XML format,  Up: lgtunit

5.12.30 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.50.0.info,  Node: Known issues<3>,  Prev: Minimizing test results output,  Up: lgtunit

5.12.31 Known issues
--------------------

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.  Use in alternative the ‘parameter/2’
built-in execution context predicate.

Deterministic unit tests are currently not available when using Quintus
Prolog as it lacks built-in support that cannot be sensibly defined in
Prolog.


File: TheLogtalkHandbook-3.50.0.info,  Node: linter,  Next: make,  Prev: lgtunit,  Up: Developer Tools

5.13 ‘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 overriden from a
settings file or from a source file (e.g.  a loader file).  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.

By loading the ‘tutor’ tool, most lint warnings are expanded with
explanations and suggestions on how to fix the reported issues.

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 locally the flag that controls the warning.

Lint checks include:

   - Missing directives (including scope, meta-predicate, dynamic,
     discontiguous, and multifile directives)

   - Duplicated directives, clauses, and grammar rules

   - Missing predicates (calls to non-declared and non-defined
     predicates)

   - Calls to declared but not defined static predicates

   - Non-portable predicate calls, predicate options, arithmetic
     function calls, directives, flags, and flag values

   - Suspicious calls (syntactically valid calls that are likely
     semantic errors; e.g.  float comparisons using the standard
     arithmetic comparison operators)

   - Deprecated directives, predicates, 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 creating a cyclic term

   - Goals that are always true or always false

   - Trivial goal fails (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

   - 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

   - Calls to standard predicates that have more efficient alternatives

   - Entity, predicate, and variable names not following official coding
     guidelines

   - Variable names that differ only on case

   - Clauses whose body is a disjunction

Additional checks are provided by the ‘make’ and ‘dead_code_scanner’
tools.  For large projects, the data generated by the ‘code_metrics’
tool may also be relevant in accessing the quality of your code.

Experimental support for extending the linter with user-defined warnings
is available using the logtalk_linter_hook/7(4) multifile hook
predicate.

   ---------- 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) ../refman/predicates/logtalk_linter_hook_7.html


File: TheLogtalkHandbook-3.50.0.info,  Node: make,  Next: ports_profiler,  Prev: linter,  Up: Developer Tools

5.14 ‘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>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<11>,  Up: make

5.14.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.50.0.info,  Node: ports_profiler,  Next: profiler,  Prev: make,  Up: Developer Tools

5.15 ‘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
is inspired by the ECLiPSe ‘port_profiler’ tool.

The procedure box model is the same 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 distinguishes 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<12>.
* Loading: Loading<11>.
* Testing: Testing<10>.
* 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<4>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<12>,  Next: Loading<11>,  Up: ports_profiler

5.15.1 API documentation
------------------------

This tool API documentation is available at:

‘../../docs/library_index.html#ports-profiler’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<11>,  Next: Testing<10>,  Prev: API documentation<12>,  Up: ports_profiler

5.15.2 Loading
--------------

     | ?- logtalk_load(ports_profiler(loader)).

Note that this tool cannot be loaded at the same time as other tools
(e.g.  the debugger) that also provide a debug handler, which must be
unique in a running session.


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<10>,  Next: Compiling source files for port profiling,  Prev: Loading<11>,  Up: ports_profiler

5.15.3 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ports_profiler(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Compiling source files for port profiling,  Next: Generating profiling data,  Prev: Testing<10>,  Up: ports_profiler

5.15.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 default flag values and thus loaded files may not be compiled
in debug mode.  In this case, you will need to modify the loader files
themselves.


File: TheLogtalkHandbook-3.50.0.info,  Node: Generating profiling data,  Next: Printing profiling data reports,  Prev: Compiling source files for port profiling,  Up: ports_profiler

5.15.5 Generating profiling data
--------------------------------

After loading this tool and compiling the source files that you want to
profile in debug mode, simply call the goals to be profiled.


File: TheLogtalkHandbook-3.50.0.info,  Node: Printing profiling data reports,  Next: Interpreting profiling data,  Prev: Generating profiling data,  Up: ports_profiler

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

The profiling data can be reset using the query:

     | ?- ports_profiler::reset.

To reset only the data about 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

     | ?- 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
     familytree  sister/2        0     1     1     0     4     1     4     0
     -----------------------------------------------------------------------
     yes


File: TheLogtalkHandbook-3.50.0.info,  Node: Interpreting profiling data,  Next: Profiling Prolog modules,  Prev: Printing profiling data reports,  Up: ports_profiler

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

The profiling data should be analyzed taking into account the expected
behavior for the profiled predicates.


File: TheLogtalkHandbook-3.50.0.info,  Node: Profiling Prolog modules,  Next: Profiling plain Prolog code,  Prev: Interpreting profiling data,  Up: ports_profiler

5.15.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.50.0.info,  Node: Profiling plain Prolog code,  Next: Known issues<4>,  Prev: Profiling Prolog modules,  Up: ports_profiler

5.15.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(object_wrapper_hook)).
     ...

     | ?- 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
of working as-is when wrapped by an object.  Often any required changes
are straight-forward (e.g.  adding ‘use_module/2’ directives for called
module library predicates).


File: TheLogtalkHandbook-3.50.0.info,  Node: Known issues<4>,  Prev: Profiling plain Prolog code,  Up: ports_profiler

5.15.10 Known issues
--------------------

Determinism information is currently not available when using Lean
Prolog or Quintus Prolog as backend compilers.


File: TheLogtalkHandbook-3.50.0.info,  Node: profiler,  Next: tutor,  Prev: ports_profiler,  Up: Developer Tools

5.16 ‘profiler’
===============

This tool contains simple wrappers for selected Prolog profiler tools.

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<12>,  Next: Testing<11>,  Up: profiler

5.16.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.50.0.info,  Node: Testing<11>,  Next: Supported backend Prolog compilers,  Prev: Loading<12>,  Up: profiler

5.16.2 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(profiler(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Supported backend Prolog compilers,  Next: Compiling source code for profiling,  Prev: Testing<11>,  Up: profiler

5.16.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 is added to the caller
predicates.


File: TheLogtalkHandbook-3.50.0.info,  Node: Compiling source code for profiling,  Prev: Supported backend Prolog compilers,  Up: profiler

5.16.4 Compiling source code for profiling
------------------------------------------

In order to get user-level object and predicate names instead of
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 ‘settings-sample.lgt’ file for automating the necessary
setup at Logtalk startup.


File: TheLogtalkHandbook-3.50.0.info,  Node: tutor,  Next: wrapper,  Prev: profiler,  Up: Developer Tools

5.17 ‘tutor’
============

This tool adds explanations and suggestions to selected compiler warning
and error messages.  It’s most useful for new users not yet familiar
with the compiler and runtime warning and error messages.

* Menu:

* API documentation: API documentation<13>.
* Loading: Loading<13>.
* Usage: Usage<6>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<13>,  Next: Loading<13>,  Up: tutor

5.17.1 API documentation
------------------------

This tool API documentation is available at:

‘../../docs/library_index.html#tutor’


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<13>,  Next: Usage<6>,  Prev: API documentation<13>,  Up: tutor

5.17.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(tutor(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<6>,  Prev: Loading<13>,  Up: tutor

5.17.3 Usage
------------

Simply load the tool at startup (e.g.  from a settings file).


File: TheLogtalkHandbook-3.50.0.info,  Node: wrapper,  Prev: tutor,  Up: Developer Tools

5.18 ‘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<14>.
* Loading: Loading<14>.
* Workflows::
* Customization: Customization<2>.
* Current limitations::


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<14>,  Next: Loading<14>,  Up: wrapper

5.18.1 API documentation
------------------------

This tool API documentation is available at:

‘../../docs/library_index.html#wrapper’


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<14>,  Next: Workflows,  Prev: API documentation<14>,  Up: wrapper

5.18.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(wrapper(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Workflows,  Next: Customization<2>,  Prev: Loading<14>,  Up: wrapper

5.18.3 Workflows
----------------

The typical porting workflow is simply:

     | ?- 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.50.0.info,  Node: Customization<2>,  Next: Current limitations,  Prev: Workflows,  Up: wrapper

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


File: TheLogtalkHandbook-3.50.0.info,  Node: Current limitations,  Prev: Customization<2>,  Up: wrapper

5.18.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 are 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 isn’t yet any support for dealing with meta-predicates and
     advise on missing meta-predicate directives.


File: TheLogtalkHandbook-3.50.0.info,  Node: Libraries,  Next: Glossary,  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::
* coroutining::
* cbor::
* csv::
* dates::
* dependents::
* dictionaries::
* edcg::
* events::
* expand_library_alias_paths::
* expecteds::
* gensym::
* git::
* heaps::
* hierarchies::
* hook_flows::
* hook_objects::
* html::
* intervals::
* java::
* json::
* logging::
* loops::
* meta::
* meta_compiler::
* nested_dictionaries::
* optionals::
* options::
* os::
* queues::
* random::
* reader::
* redis::
* sets::
* statistics::
* term_io::
* timeout::
* types::
* unicode_data::
* uuid::
* zippers::


File: TheLogtalkHandbook-3.50.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.50.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/index.html’ file with your
web browser).  The documentation for these libraries can be regenerated
using the shell scripts ‘../scripts/update_html_docs.sh’ and
‘../scripts/update_svg_diagrams.sh’.


File: TheLogtalkHandbook-3.50.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)).

For existing applications still relying on the old library
‘*_loader.lgt’ files, these loader files are still provided but are
considered deprecated.

There is 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.50.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 libraries 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.50.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 predicate ‘reverse/2’ in object list 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 part 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.50.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.50.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.

* Menu:

* API documentation: API documentation<15>.
* Loading: Loading<15>.
* Testing: Testing<12>.
* Usage: Usage<7>.
* Examples: Examples<157>.
* Known issues: Known issues<5>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<15>,  Next: Loading<15>,  Up: arbitrary

6.2.1 API documentation
-----------------------

Open the ‘../../docs/library_index.html#arbitrary’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<15>,  Next: Testing<12>,  Prev: API documentation<15>,  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.50.0.info,  Node: Testing<12>,  Next: Usage<7>,  Prev: Loading<15>,  Up: arbitrary

6.2.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(coroutining(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<7>,  Next: Examples<157>,  Prev: Testing<12>,  Up: arbitrary

6.2.4 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

To define a generator of arbitrary values for a type, define a clause
for the ‘type::arbitrary/1’ multifile predicate specifying the type and
a clause for the ‘type::arbitrary/2’ multifile predicate generating an
arbitrary term of the specified type.  For example:

     :- multifile(type::arbitrary/1).
     type::arbitrary(foo).

     :- multifile(type::arbitrary/2).
     type::arbitrary(foo, Arbitrary) :-
         ...

Optionally, define a clause for the ‘type::shrink/3’ multifile predicate
for shrinking arbitrary values for QuickCheck usage.  For example:

     :- multifile(type::shrink/3).
     type::shrink(foo, Large, Small) :-
         ...

It is also possible to define edge cases for a given type for use with
QuickCheck implementations.  For example:

     :- multifile(edge_case/2).
     type::edge_case(cost, 0).

Edge cases are usually tried before resorting to generating arbitrary
values for a type.

The ‘arbitrary’ category also 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.50.0.info,  Node: Examples<157>,  Next: Known issues<5>,  Prev: Usage<7>,  Up: arbitrary

6.2.5 Examples
--------------

See the implementation of the ‘optionals’ and ‘expecteds’ libraries.


File: TheLogtalkHandbook-3.50.0.info,  Node: Known issues<5>,  Prev: Examples<157>,  Up: arbitrary

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


File: TheLogtalkHandbook-3.50.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, Qu-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<16>.
* Loading: Loading<16>.
* Testing: Testing<13>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<16>,  Next: Loading<16>,  Up: assignvars

6.3.1 API documentation
-----------------------

Open the ‘../../docs/library_index.html#assignvars’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<16>,  Next: Testing<13>,  Prev: API documentation<16>,  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.50.0.info,  Node: Testing<13>,  Prev: Loading<16>,  Up: assignvars

6.3.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(coroutining(tester)).


File: TheLogtalkHandbook-3.50.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://tools.ietf.org/html/rfc4648’

* Menu:

* API documentation: API documentation<17>.
* Loading: Loading<17>.
* Testing: Testing<14>.
* Encoding::
* Decoding::


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<17>,  Next: Loading<17>,  Up: base64

6.4.1 API documentation
-----------------------

Open the ‘../../docs/library_index.html#base64’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<17>,  Next: Testing<14>,  Prev: API documentation<17>,  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.50.0.info,  Node: Testing<14>,  Next: Encoding,  Prev: Loading<17>,  Up: base64

6.4.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(base64(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Encoding,  Next: Decoding,  Prev: Testing<14>,  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.50.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.50.0.info,  Node: basic_types,  Next: coroutining,  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:

   - ‘termp’, ‘term’

   - ‘atomic’, ‘atom’, ‘number’, ‘float’, ‘integer’

   - ‘compound’, ‘listp’, ‘list’

   - ‘type’

* Menu:

* API documentation: API documentation<18>.
* Loading: Loading<18>.
* Testing: Testing<15>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<18>,  Next: Loading<18>,  Up: basic_types

6.5.1 API documentation
-----------------------

Open the ‘../../docs/library_index.html#types’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<18>,  Next: Testing<15>,  Prev: API documentation<18>,  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.50.0.info,  Node: Testing<15>,  Prev: Loading<18>,  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.50.0.info,  Node: coroutining,  Next: cbor,  Prev: basic_types,  Up: Libraries

6.6 ‘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, 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 predicates directly.

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<19>,  Next: Loading<19>,  Up: coroutining

6.6.1 API documentation
-----------------------

Open the ‘../../docs/library_index.html#coroutining’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<19>,  Next: Testing<16>,  Prev: API documentation<19>,  Up: coroutining

6.6.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(coroutining(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<16>,  Prev: Loading<19>,  Up: coroutining

6.6.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(coroutining(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: cbor,  Next: csv,  Prev: coroutining,  Up: Libraries

6.7 ‘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<20>.
* Testing: Testing<17>.


File: TheLogtalkHandbook-3.50.0.info,  Node: Representation,  Next: Encoding<2>,  Up: cbor

6.7.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.50.0.info,  Node: Encoding<2>,  Next: Decoding<2>,  Prev: Representation,  Up: cbor

6.7.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.50.0.info,  Node: Decoding<2>,  Next: API documentation<20>,  Prev: Encoding<2>,  Up: cbor

6.7.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.50.0.info,  Node: API documentation<20>,  Next: Loading<20>,  Prev: Decoding<2>,  Up: cbor

6.7.4 API documentation
-----------------------

Open the ‘../../docs/library_index.html#cbor’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<20>,  Next: Testing<17>,  Prev: API documentation<20>,  Up: cbor

6.7.5 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(cbor(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<17>,  Prev: Loading<20>,  Up: cbor

6.7.6 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(cbor(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: csv,  Next: dates,  Prev: cbor,  Up: Libraries

6.8 ‘csv’
=========

The ‘csv’ library provides predicates for reading and writing CSV files:

‘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 include predicates to guess the separator and guess the
number of columns in a given CSV file.

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

Data can be saved to a CSV file by providing the object and predicate
for accessing the data plus the name of the destination file.

* Menu:

* API documentation: API documentation<21>.
* Loading: Loading<21>.
* Testing: Testing<18>.
* Usage: Usage<8>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<21>,  Next: Loading<21>,  Up: csv

6.8.1 API documentation
-----------------------

Open the ‘../../docs/library_index.html#csv’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<21>,  Next: Testing<18>,  Prev: API documentation<21>,  Up: csv

6.8.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(csv(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<18>,  Next: Usage<8>,  Prev: Loading<21>,  Up: csv

6.8.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(csv(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<8>,  Prev: Testing<18>,  Up: csv

6.8.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, 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.  For example:

     | ?- 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:

     | ?- 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.50.0.info,  Node: dates,  Next: dependents,  Prev: csv,  Up: Libraries

6.9 ‘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<22>.
* Loading: Loading<22>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<22>,  Next: Loading<22>,  Up: dates

6.9.1 API documentation
-----------------------

Open the ‘../../docs/library_index.html#dates’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<22>,  Prev: API documentation<22>,  Up: dates

6.9.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(dates(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: dependents,  Next: dictionaries,  Prev: dates,  Up: Libraries

6.10 ‘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<23>.
* Loading: Loading<23>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<23>,  Next: Loading<23>,  Up: dependents

6.10.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#dependents’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<23>,  Prev: API documentation<23>,  Up: dependents

6.10.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(dependents(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: dictionaries,  Next: edcg,  Prev: dependents,  Up: Libraries

6.11 ‘dictionaries’
===================

This library provides a dictionary (also know 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<24>.
* Loading: Loading<24>.
* Testing: Testing<19>.
* Usage: Usage<9>.
* Credits: Credits<2>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<24>,  Next: Loading<24>,  Up: dictionaries

6.11.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#dictionaries’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<24>,  Next: Testing<19>,  Prev: API documentation<24>,  Up: dictionaries

6.11.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(dictionaries(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<19>,  Next: Usage<9>,  Prev: Loading<24>,  Up: dictionaries

6.11.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(dictionaries(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<9>,  Next: Credits<2>,  Prev: Testing<19>,  Up: dictionaries

6.11.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 an ‘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 an ‘uses/2’ directive.

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.50.0.info,  Node: Credits<2>,  Prev: Usage<9>,  Up: dictionaries

6.11.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.50.0.info,  Node: edcg,  Next: events,  Prev: dictionaries,  Up: Libraries

6.12 ‘edcg’
===========

This library provides a Logtalk port of the Peter Van Roy’s extended DCG
implementation.  For full documentation on EDCGs, see:

‘https://www.info.ucl.ac.be/%7Epvr/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<25>.
* Loading: Loading<25>.
* Testing: Testing<20>.
* Usage: Usage<10>.
* Introduction::
* Syntax::
* Declaration of Predicates::
* Declaration of Accumulators::
* Declaration of Passed Arguments::
* Additional documentation::


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<25>,  Next: Loading<25>,  Up: edcg

6.12.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#edcg’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<25>,  Next: Testing<20>,  Prev: API documentation<25>,  Up: edcg

6.12.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(edcg(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<20>,  Next: Usage<10>,  Prev: Loading<25>,  Up: edcg

6.12.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file of the
‘edcgs’ example:

     | ?- logtalk_load(edcgs(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<10>,  Next: Introduction,  Prev: Testing<20>,  Up: edcg

6.12.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.50.0.info,  Node: Introduction,  Next: Syntax,  Prev: Usage<10>,  Up: edcg

6.12.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 accumulator implementation with a single declaration (ex,
     switching from ordsets to rbtrees)


File: TheLogtalkHandbook-3.50.0.info,  Node: Syntax,  Next: Declaration of Predicates,  Prev: Introduction,  Up: edcg

6.12.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.50.0.info,  Node: Declaration of Predicates,  Next: Declaration of Accumulators,  Prev: Syntax,  Up: edcg

6.12.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.50.0.info,  Node: Declaration of Accumulators,  Next: Declaration of Passed Arguments,  Prev: Declaration of Predicates,  Up: edcg

6.12.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.50.0.info,  Node: Declaration of Passed Arguments,  Next: Additional documentation,  Prev: Declaration of Accumulators,  Up: edcg

6.12.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.50.0.info,  Node: Additional documentation,  Prev: Declaration of Passed Arguments,  Up: edcg

6.12.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://www.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.50.0.info,  Node: events,  Next: expand_library_alias_paths,  Prev: edcg,  Up: Libraries

6.13 ‘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<26>.
* Loading: Loading<26>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<26>,  Next: Loading<26>,  Up: events

6.13.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#events’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<26>,  Prev: API documentation<26>,  Up: events

6.13.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ loader file:

     | ?- logtalk_load(events(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: expand_library_alias_paths,  Next: expecteds,  Prev: events,  Up: Libraries

6.14 ‘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<27>.
* Loading: Loading<27>.
* Usage: Usage<11>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<27>,  Next: Loading<27>,  Up: expand_library_alias_paths

6.14.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#expand_library_alias_paths’ link
in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<27>,  Next: Usage<11>,  Prev: API documentation<27>,  Up: expand_library_alias_paths

6.14.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.50.0.info,  Node: Usage<11>,  Prev: Loading<27>,  Up: expand_library_alias_paths

6.14.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.50.0.info,  Node: expecteds,  Next: gensym,  Prev: expand_library_alias_paths,  Up: Libraries

6.15 ‘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<28>.
* Loading: Loading<28>.
* Testing: Testing<21>.
* Usage: Usage<12>.
* See also::


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<28>,  Next: Loading<28>,  Up: expecteds

6.15.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#expecteds’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<28>,  Next: Testing<21>,  Prev: API documentation<28>,  Up: expecteds

6.15.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(expecteds(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<21>,  Next: Usage<12>,  Prev: Loading<28>,  Up: expecteds

6.15.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(expecteds(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<12>,  Next: See also,  Prev: Testing<21>,  Up: expecteds

6.15.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.50.0.info,  Node: See also,  Prev: Usage<12>,  Up: expecteds

6.15.5 See also
---------------

The ‘optionals’ library.


File: TheLogtalkHandbook-3.50.0.info,  Node: gensym,  Next: git,  Prev: expecteds,  Up: Libraries

6.16 ‘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<29>.
* Loading: Loading<29>.
* Testing: Testing<22>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<29>,  Next: Loading<29>,  Up: gensym

6.16.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#gensym’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<29>,  Next: Testing<22>,  Prev: API documentation<29>,  Up: gensym

6.16.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(gensym(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<22>,  Prev: Loading<29>,  Up: gensym

6.16.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(gensym(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: git,  Next: heaps,  Prev: gensym,  Up: Libraries

6.17 ‘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<30>.
* Loading: Loading<30>.
* Testing: Testing<23>.
* Usage: Usage<13>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<30>,  Next: Loading<30>,  Up: git

6.17.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#git’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<30>,  Next: Testing<23>,  Prev: API documentation<30>,  Up: git

6.17.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(git(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<23>,  Next: Usage<13>,  Prev: Loading<30>,  Up: git

6.17.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(git(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<13>,  Prev: Testing<23>,  Up: git

6.17.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 common 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.50.0.info,  Node: heaps,  Next: hierarchies,  Prev: git,  Up: Libraries

6.18 ‘heaps’
============

This library implements minimum and maximum heaps.

* Menu:

* API documentation: API documentation<31>.
* Loading: Loading<31>.
* Testing: Testing<24>.
* Credits: Credits<3>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<31>,  Next: Loading<31>,  Up: heaps

6.18.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#heaps’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<31>,  Next: Testing<24>,  Prev: API documentation<31>,  Up: heaps

6.18.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(heaps(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<24>,  Next: Credits<3>,  Prev: Loading<31>,  Up: heaps

6.18.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(heaps(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Credits<3>,  Prev: Testing<24>,  Up: heaps

6.18.4 Credits
--------------

Original code by Richard O’’Keefe.  Adapted to Logtalk by Paulo Moura
and Victor Lagerkvist.


File: TheLogtalkHandbook-3.50.0.info,  Node: hierarchies,  Next: hook_flows,  Prev: heaps,  Up: Libraries

6.19 ‘hierarchies’
==================

This library provides objects implementing reflection predicates over
class and prototype hierarchies.

* Menu:

* API documentation: API documentation<32>.
* Loading: Loading<32>.
* Testing: Testing<25>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<32>,  Next: Loading<32>,  Up: hierarchies

6.19.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#hierarchies’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<32>,  Next: Testing<25>,  Prev: API documentation<32>,  Up: hierarchies

6.19.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hierarchies(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<25>,  Prev: Loading<32>,  Up: hierarchies

6.19.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hierarchies(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: hook_flows,  Next: hook_objects,  Prev: hierarchies,  Up: Libraries

6.20 ‘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 used as examples of how to construct your own custom expansion
workflows.

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<33>,  Next: Loading<33>,  Up: hook_flows

6.20.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#hook_flows’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<33>,  Next: Testing<26>,  Prev: API documentation<33>,  Up: hook_flows

6.20.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hook_flows(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<26>,  Next: Usage<14>,  Prev: Loading<33>,  Up: hook_flows

6.20.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hook_flows(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<14>,  Prev: Testing<26>,  Up: hook_flows

6.20.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 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.  This
parametric object is used when the 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.  For
term-expansion, hooks in the set are tried until one of them succeeds.
For goal-expansion, as the compiler expands a goal until a fixed-point
is reached, all the hooks objects in the set that are applicable at any
point will be used.  This parametric object is used when applying
multiple independent expansions.

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.50.0.info,  Node: hook_objects,  Next: html,  Prev: hook_flows,  Up: Libraries

6.21 ‘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<34>.
* Loading: Loading<34>.
* Testing: Testing<27>.
* Usage: Usage<15>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<34>,  Next: Loading<34>,  Up: hook_objects

6.21.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#hook_objects’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<34>,  Next: Testing<27>,  Prev: API documentation<34>,  Up: hook_objects

6.21.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.50.0.info,  Node: Testing<27>,  Next: Usage<15>,  Prev: Loading<34>,  Up: hook_objects

6.21.3 Testing
--------------

To test this library hook objects, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hook_objects(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<15>,  Prev: Testing<27>,  Up: hook_objects

6.21.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::
* Printing entity predicate goals before or after calling them::
* Suppressing goals::


File: TheLogtalkHandbook-3.50.0.info,  Node: Using the Prolog backend adapter file expansion rules,  Next: Restoring the default compiler expansion workflow,  Up: Usage<15>

6.21.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.50.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<15>

6.21.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.50.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<15>

6.21.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
to preserve the grammar rules, use the hook objects described below to
write them to a stream.


File: TheLogtalkHandbook-3.50.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<15>

6.21.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.50.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<15>

6.21.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.50.0.info,  Node: Wrap the contents of a plain Prolog file as an object,  Next: Outputting term-expansion results to a stream,  Prev: Using the expansion rules defined in a Prolog module,  Up: Usage<15>

6.21.4.6 Wrap the contents of a plain Prolog file as an object
..............................................................

Load the ‘object_wrapper_hook.lgt’, which defines the parametric hook
object ‘object_wrapper_hook’.  Use it to wrap the contents of a plain
Prolog file as an object named after the file.  Can be used to apply
Logtalk developer tools to plain Prolog code or when porting Prolog
application to Logtalk.  For example:

     | ?- logtalk_load('plain.pl', [hook(object_wrapper_hook)]).
     ...

     | ?- current_object(plain).
     yes

The ‘object_wrapper_hook’ sets the ‘context_switching_calls’ flag to
‘allow’ for the generated object.  This enables calling the predicates
using the ‘<</2’ context-switching control construct.


File: TheLogtalkHandbook-3.50.0.info,  Node: Outputting term-expansion results to a stream,  Next: Printing entity predicate goals before or after calling them,  Prev: Wrap the contents of a plain Prolog file as an object,  Up: Usage<15>

6.21.4.7 Outputting term-expansion results to a stream
......................................................

Load the ‘write_to_stream_hook.lgt’ file and using the
‘write_to_stream_hook(Stream)’ or ‘write_to_stream_hook(Stream,
Options)’ hook object.  The terms are not modified and thus these hook
objects may be used at any point in an expansion workflow.


File: TheLogtalkHandbook-3.50.0.info,  Node: Printing entity predicate goals before or after calling them,  Next: Suppressing goals,  Prev: Outputting term-expansion results to a stream,  Up: Usage<15>

6.21.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.50.0.info,  Node: Suppressing goals,  Prev: Printing entity predicate goals before or after calling them,  Up: Usage<15>

6.21.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.50.0.info,  Node: html,  Next: intervals,  Prev: hook_objects,  Up: Libraries

6.22 ‘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<35>.
* Loading: Loading<35>.
* Testing: Testing<28>.
* Generating a HTML document::
* Generating a HTML fragment::
* Working with callbacks to generate content::
* Working with custom elements::


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<35>,  Next: Loading<35>,  Up: html

6.22.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#html’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<35>,  Next: Testing<28>,  Prev: API documentation<35>,  Up: html

6.22.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(html(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<28>,  Next: Generating a HTML document,  Prev: Loading<35>,  Up: html

6.22.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(html(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Generating a HTML document,  Next: Generating a HTML fragment,  Prev: Testing<28>,  Up: html

6.22.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.50.0.info,  Node: Generating a HTML fragment,  Next: Working with callbacks to generate content,  Prev: Generating a HTML document,  Up: html

6.22.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
then ‘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.50.0.info,  Node: Working with callbacks to generate content,  Next: Working with custom elements,  Prev: Generating a HTML fragment,  Up: html

6.22.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.50.0.info,  Node: Working with custom elements,  Prev: Working with callbacks to generate content,  Up: html

6.22.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.50.0.info,  Node: intervals,  Next: java,  Prev: html,  Up: Libraries

6.23 ‘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<36>.
* Loading: Loading<36>.
* Testing: Testing<29>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<36>,  Next: Loading<36>,  Up: intervals

6.23.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#intervals’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<36>,  Next: Testing<29>,  Prev: API documentation<36>,  Up: intervals

6.23.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(intervals(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<29>,  Prev: Loading<36>,  Up: intervals

6.23.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(intervals(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: java,  Next: json,  Prev: intervals,  Up: Libraries

6.24 ‘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 object, 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 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<37>.
* Loading: Loading<37>.
* Testing: Testing<30>.
* Usage: Usage<16>.
* Known issues: Known issues<6>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<37>,  Next: Loading<37>,  Up: java

6.24.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#java’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<37>,  Next: Testing<30>,  Prev: API documentation<37>,  Up: java

6.24.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(java(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<30>,  Next: Usage<16>,  Prev: Loading<37>,  Up: java

6.24.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(java(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<16>,  Next: Known issues<6>,  Prev: Testing<30>,  Up: java

6.24.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 and YAP) there is also a
‘java_hook’ hook object for removing any overhead when using this
library abstraction.

For usage examples and unit tests, see the ‘jpl’ example.


File: TheLogtalkHandbook-3.50.0.info,  Node: Known issues<6>,  Prev: Usage<16>,  Up: java

6.24.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 SWI-Prolog/YAP
and Logtalk.


File: TheLogtalkHandbook-3.50.0.info,  Node: json,  Next: logging,  Prev: java,  Up: Libraries

6.25 ‘json’
===========

The ‘json’ library provides predicates for parsing and generating data
in the JSON format based on the specification and standard found at:

   - ‘https://tools.ietf.org/html/rfc8259’

   - 
     ‘https://www.ecma-international.org/publications-and-standards/standards/ecma-404/’

It includes a parametric object whose parameter indicates the preferred
representation for decoded JSON text strings (‘atom’, ‘chars’, or
‘codes’).

* Menu:

* API documentation: API documentation<38>.
* Loading: Loading<38>.
* Testing: Testing<31>.
* Representation: Representation<2>.
* Encoding: Encoding<3>.
* Decoding: Decoding<3>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<38>,  Next: Loading<38>,  Up: json

6.25.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#json’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<38>,  Next: Testing<31>,  Prev: API documentation<38>,  Up: json

6.25.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(json(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<31>,  Next: Representation<2>,  Prev: Loading<38>,  Up: json

6.25.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.50.0.info,  Node: Representation<2>,  Next: Encoding<3>,  Prev: Testing<31>,  Up: json

6.25.4 Representation
---------------------

The following choices of syntax has been made to represent JSON elements
as terms:

   - JSON objects are represented using curly-bracketed terms,
     ‘{Pairs}’, where each pair uses the representation ‘Key-Value’.

   - 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
(with) JSON strings being represented as atoms:

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]
                              
                              
{“foo”:”bar”}                 {foo-bar}
                              
                              
{}                            {}
                              


File: TheLogtalkHandbook-3.50.0.info,  Node: Encoding<3>,  Next: Decoding<3>,  Prev: Representation<2>,  Up: json

6.25.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.50.0.info,  Node: Decoding<3>,  Prev: Encoding<3>,  Up: json

6.25.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(Source)’, ‘stream(Source)’, ‘file(Source)’, ‘chars(Source)’ or
‘atom(Source)’) containing a JSON payload to be decoded into the Prolog
term in the second argument.


File: TheLogtalkHandbook-3.50.0.info,  Node: logging,  Next: loops,  Prev: json,  Up: Libraries

6.26 ‘logging’
==============

This library provides support for logging events to files.

* Menu:

* API documentation: API documentation<39>.
* Loading: Loading<39>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<39>,  Next: Loading<39>,  Up: logging

6.26.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#logging’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<39>,  Prev: API documentation<39>,  Up: logging

6.26.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(logging(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: loops,  Next: meta,  Prev: logging,  Up: Libraries

6.27 ‘loops’
============

This library provides implementations of several kinds of loops typical
of imperative languages.

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<40>,  Next: Loading<40>,  Up: loops

6.27.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#loops’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<40>,  Next: Testing<32>,  Prev: API documentation<40>,  Up: loops

6.27.2 Loading
--------------

To load the main entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(loops(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<32>,  Next: Usage<17>,  Prev: Loading<40>,  Up: loops

6.27.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(loops(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<17>,  Prev: Testing<32>,  Up: loops

6.27.4 Usage
------------

See e.g.  the ‘searching’ example.


File: TheLogtalkHandbook-3.50.0.info,  Node: meta,  Next: meta_compiler,  Prev: loops,  Up: Libraries

6.28 ‘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<41>.
* Loading: Loading<41>.
* Testing: Testing<33>.
* Usage: Usage<18>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<41>,  Next: Loading<41>,  Up: meta

6.28.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#meta’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<41>,  Next: Testing<33>,  Prev: API documentation<41>,  Up: meta

6.28.2 Loading
--------------

To load the main entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(meta(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<33>,  Next: Usage<18>,  Prev: Loading<41>,  Up: meta

6.28.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(meta(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<18>,  Prev: Testing<33>,  Up: meta

6.28.4 Usage
------------

See e.g.  the ‘metapredicates’ example and unit tests.


File: TheLogtalkHandbook-3.50.0.info,  Node: meta_compiler,  Next: nested_dictionaries,  Prev: meta,  Up: Libraries

6.29 ‘meta_compiler’
====================

This library supports implementations optimized compilation of
meta-calls for the predicates defined in the ‘meta’ library.

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<42>,  Next: Loading<42>,  Up: meta_compiler

6.29.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#meta_compiler’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<42>,  Next: Testing<34>,  Prev: API documentation<42>,  Up: meta_compiler

6.29.2 Loading
--------------

To load the main entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(meta_compiler(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<34>,  Next: Usage<19>,  Prev: Loading<42>,  Up: meta_compiler

6.29.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(meta_compiler(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<19>,  Prev: Testing<34>,  Up: meta_compiler

6.29.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)’ complier
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.50.0.info,  Node: nested_dictionaries,  Next: optionals,  Prev: meta_compiler,  Up: Libraries

6.30 ‘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<43>.
* Loading: Loading<43>.
* Testing: Testing<35>.
* Usage: Usage<20>.
* Curly term representation::


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<43>,  Next: Loading<43>,  Up: nested_dictionaries

6.30.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#nested_dictionaries’ link in a
web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<43>,  Next: Testing<35>,  Prev: API documentation<43>,  Up: nested_dictionaries

6.30.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(nested_dictionaries(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<35>,  Next: Usage<20>,  Prev: Loading<43>,  Up: nested_dictionaries

6.30.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(nested_dictionaries(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<20>,  Next: Curly term representation,  Prev: Testing<35>,  Up: nested_dictionaries

6.30.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 an ‘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 an ‘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.50.0.info,  Node: Curly term representation,  Prev: Usage<20>,  Up: nested_dictionaries

6.30.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.50.0.info,  Node: optionals,  Next: options,  Prev: nested_dictionaries,  Up: Libraries

6.31 ‘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 hold by optional terms are not present.

* Menu:

* API documentation: API documentation<44>.
* Loading: Loading<44>.
* Testing: Testing<36>.
* Usage: Usage<21>.
* See also: See also<2>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<44>,  Next: Loading<44>,  Up: optionals

6.31.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#optionals’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<44>,  Next: Testing<36>,  Prev: API documentation<44>,  Up: optionals

6.31.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(optionals(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<36>,  Next: Usage<21>,  Prev: Loading<44>,  Up: optionals

6.31.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(optionals(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<21>,  Next: See also<2>,  Prev: Testing<36>,  Up: optionals

6.31.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 hold by optional terms.  It also provides some predicates for
handling lists of optional terms.


File: TheLogtalkHandbook-3.50.0.info,  Node: See also<2>,  Prev: Usage<21>,  Up: optionals

6.31.5 See also
---------------

The ‘expecteds’ library.


File: TheLogtalkHandbook-3.50.0.info,  Node: options,  Next: os,  Prev: optionals,  Up: Libraries

6.32 ‘options’
==============

This library provides useful predicates for managing developer tool and
application options.

* Menu:

* API documentation: API documentation<45>.
* Loading: Loading<45>.
* Testing: Testing<37>.
* Usage: Usage<22>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<45>,  Next: Loading<45>,  Up: options

6.32.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#options’ file in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<45>,  Next: Testing<37>,  Prev: API documentation<45>,  Up: options

6.32.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(options(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<37>,  Next: Usage<22>,  Prev: Loading<45>,  Up: options

6.32.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(options(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<22>,  Prev: Testing<37>,  Up: options

6.32.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.  This library requires options to be
represented by compound terms but leaves otherwise to the clients the
actual representation.

The library also supports a user-defined ‘fix_option/2’ predicate.  An
usage example is when an option value can be a relative file path that
should be expanded before used.  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.


File: TheLogtalkHandbook-3.50.0.info,  Node: os,  Next: queues,  Prev: options,  Up: Libraries

6.33 ‘os’
=========

This library entities define 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<46>.
* Loading: Loading<46>.
* Testing: Testing<38>.
* Known issues: Known issues<7>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<46>,  Next: Loading<46>,  Up: os

6.33.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#os’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<46>,  Next: Testing<38>,  Prev: API documentation<46>,  Up: os

6.33.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(os(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<38>,  Next: Known issues<7>,  Prev: Loading<46>,  Up: os

6.33.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(os(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Known issues<7>,  Prev: Testing<38>,  Up: os

6.33.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, specially across
operating-systems.  See the remarks section in the ‘os’ object
documentation for details.


File: TheLogtalkHandbook-3.50.0.info,  Node: queues,  Next: random,  Prev: os,  Up: Libraries

6.34 ‘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<47>.
* Loading: Loading<47>.
* Testing: Testing<39>.
* Usage: Usage<23>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<47>,  Next: Loading<47>,  Up: queues

6.34.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#queues’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<47>,  Next: Testing<39>,  Prev: API documentation<47>,  Up: queues

6.34.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(queues(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<39>,  Next: Usage<23>,  Prev: Loading<47>,  Up: queues

6.34.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(queues(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<23>,  Prev: Testing<39>,  Up: queues

6.34.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.50.0.info,  Node: random,  Next: reader,  Prev: queues,  Up: Libraries

6.35 ‘random’
=============

This library provides portable random number generators and an
abstraction over native backend Prolog compiler random number generator
if available.

* Menu:

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


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<48>,  Next: Loading<48>,  Up: random

6.35.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#random’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<48>,  Next: Testing<40>,  Prev: API documentation<48>,  Up: random

6.35.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(random(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<40>,  Next: Usage<24>,  Prev: Loading<48>,  Up: random

6.35.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(random(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<24>,  Prev: Testing<40>,  Up: random

6.35.4 Usage
------------

The ‘random’ object implements 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 not portable
solution to protect seed updates from signals and prevent inconsistent
state when threads are canceled.

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 can allow
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, Lean Prolog, Qu-Prolog, 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.


File: TheLogtalkHandbook-3.50.0.info,  Node: reader,  Next: redis,  Prev: random,  Up: Libraries

6.36 ‘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<49>.
* Loading: Loading<49>.
* Testing: Testing<41>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<49>,  Next: Loading<49>,  Up: reader

6.36.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#reader’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<49>,  Next: Testing<41>,  Prev: API documentation<49>,  Up: reader

6.36.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(reader(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<41>,  Prev: Loading<49>,  Up: reader

6.36.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(reader(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: redis,  Next: sets,  Prev: reader,  Up: Libraries

6.37 ‘redis’
============

Redis client library.  Supports GNU Prolog, LVM, Qu-Prolog, SICStus
Prolog, SWI-Prolog, and XSB. 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<50>.
* Loading: Loading<50>.
* Testing: Testing<42>.
* Credits: Credits<4>.
* Known issues: Known issues<8>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<50>,  Next: Loading<50>,  Up: redis

6.37.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#redis’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<50>,  Next: Testing<42>,  Prev: API documentation<50>,  Up: redis

6.37.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(redis(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<42>,  Next: Credits<4>,  Prev: Loading<50>,  Up: redis

6.37.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.50.0.info,  Node: Credits<4>,  Next: Known issues<8>,  Prev: Testing<42>,  Up: redis

6.37.4 Credits
--------------

This library is inspired by the Sean Charles GNU Prolog Redis client
library.


File: TheLogtalkHandbook-3.50.0.info,  Node: Known issues<8>,  Prev: Credits<4>,  Up: redis

6.37.5 Known issues
-------------------

Recent version 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’ 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 first argument.


File: TheLogtalkHandbook-3.50.0.info,  Node: sets,  Next: statistics,  Prev: redis,  Up: Libraries

6.38 ‘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 representation, is best practice to regard
sets as opaque terms and only access them using the library predicates.

* Menu:

* API documentation: API documentation<51>.
* Loading: Loading<51>.
* Testing: Testing<43>.
* Usage: Usage<25>.
* Credits: Credits<5>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<51>,  Next: Loading<51>,  Up: sets

6.38.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#sets’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<51>,  Next: Testing<43>,  Prev: API documentation<51>,  Up: sets

6.38.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(sets(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<43>,  Next: Usage<25>,  Prev: Loading<51>,  Up: sets

6.38.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(sets(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Usage<25>,  Next: Credits<5>,  Prev: Testing<43>,  Up: sets

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

For details on these and other provided predicates, consult the library
API documentation.


File: TheLogtalkHandbook-3.50.0.info,  Node: Credits<5>,  Prev: Usage<25>,  Up: sets

6.38.5 Credits
--------------

Some predicates adapted from code authored by Richard O’Keefe.


File: TheLogtalkHandbook-3.50.0.info,  Node: statistics,  Next: term_io,  Prev: sets,  Up: Libraries

6.39 ‘statistics’
=================

The entities in this group 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<52>.
* Loading: Loading<52>.
* Testing: Testing<44>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<52>,  Next: Loading<52>,  Up: statistics

6.39.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#statistics’ link in a web
browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<52>,  Next: Testing<44>,  Prev: API documentation<52>,  Up: statistics

6.39.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(statistics(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<44>,  Prev: Loading<52>,  Up: statistics

6.39.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(statistics(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: term_io,  Next: timeout,  Prev: statistics,  Up: Libraries

6.40 ‘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<53>.
* Loading: Loading<53>.
* Testing: Testing<45>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<53>,  Next: Loading<53>,  Up: term_io

6.40.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#term_io’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<53>,  Next: Testing<45>,  Prev: API documentation<53>,  Up: term_io

6.40.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(term_io(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<45>,  Prev: Loading<53>,  Up: term_io

6.40.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(term_io(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: timeout,  Next: types,  Prev: term_io,  Up: Libraries

6.41 ‘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, XSB, 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<54>.
* Loading: Loading<54>.
* Testing: Testing<46>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<54>,  Next: Loading<54>,  Up: timeout

6.41.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#timeout’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<54>,  Next: Testing<46>,  Prev: API documentation<54>,  Up: timeout

6.41.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(timeout(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<46>,  Prev: Loading<54>,  Up: timeout

6.41.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(timeout(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: types,  Next: unicode_data,  Prev: timeout,  Up: Libraries

6.42 ‘types’
============

This library implements predicates over standard Prolog term types and
also term 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.

* Menu:

* API documentation: API documentation<55>.
* Loading: Loading<55>.
* Testing: Testing<47>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<55>,  Next: Loading<55>,  Up: types

6.42.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#types’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<55>,  Next: Testing<47>,  Prev: API documentation<55>,  Up: types

6.42.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(types(loader)).

In case 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.50.0.info,  Node: Testing<47>,  Prev: Loading<55>,  Up: types

6.42.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(types(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_data,  Next: uuid,  Prev: types,  Up: Libraries

6.43 ‘unicode_data’
===================

VivoMind Prolog Unicode Resources

* Menu:

* Authors::
* License::
* Website::
* Description: Description<156>.
* Requirements::
* Usage: Usage<26>.
* Known issues: Known issues<9>.
* Acknowledgements::
* Files and API Summary::


File: TheLogtalkHandbook-3.50.0.info,  Node: Authors,  Next: License,  Up: unicode_data

6.43.1 Authors
--------------

     Arun Majumdar @ VivoMind LLC 
     Paulo Moura @ VivoMind LLC 


File: TheLogtalkHandbook-3.50.0.info,  Node: License,  Next: Website,  Prev: Authors,  Up: unicode_data

6.43.2 License
--------------

Creative Commons CC0 1.0 Universal (CC0 1.0) - Public Domain Dedication:

‘http://creativecommons.org/publicdomain/zero/1.0/’

We do appreciate acknowledgement if you use these resources, however,
and we also welcome contributions to improve them.


File: TheLogtalkHandbook-3.50.0.info,  Node: Website,  Next: Description<156>,  Prev: License,  Up: unicode_data

6.43.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.50.0.info,  Node: Description<156>,  Next: Requirements,  Prev: Website,  Up: unicode_data

6.43.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.50.0.info,  Node: Requirements,  Next: Usage<26>,  Prev: Description<156>,  Up: unicode_data

6.43.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.50.0.info,  Node: Usage<26>,  Next: Known issues<9>,  Prev: Requirements,  Up: unicode_data

6.43.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 generated derived tables more fit for your
specific application.


File: TheLogtalkHandbook-3.50.0.info,  Node: Known issues<9>,  Next: Acknowledgements,  Prev: Usage<26>,  Up: unicode_data

6.43.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 rise portability issues on
their own.


File: TheLogtalkHandbook-3.50.0.info,  Node: Acknowledgements,  Next: Files and API Summary,  Prev: Known issues<9>,  Up: unicode_data

6.43.8 Acknowledgements
-----------------------

We thank Richard O’Keefe for helpful suggestions to improve the
usability of these resources.


File: TheLogtalkHandbook-3.50.0.info,  Node: Files and API Summary,  Prev: Acknowledgements,  Up: unicode_data

6.43.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 an utility file, ‘unicode_data.pl’, that can be used to
load all the files in these resources.  Is mostly used to test
portability of the code across Prolog compilers.  Also included is a
Logtalk version of this file, ‘unicode_data.lgt’, that 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.50.0.info,  Node: unicode_arabic_shaping pl,  Next: unicode_bidi_mirroring pl,  Up: Files and API Summary

6.43.9.1 ‘unicode_arabic_shaping.pl’
....................................

   - Provides: ‘unicode_arabic_shaping/4’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_bidi_mirroring pl,  Next: unicode_blocks pl,  Prev: unicode_arabic_shaping pl,  Up: Files and API Summary

6.43.9.2 ‘unicode_bidi_mirroring.pl’
....................................

   - Provides: ‘unicode_bidi_mirroring/2’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_blocks pl,  Next: unicode_case_folding pl,  Prev: unicode_bidi_mirroring pl,  Up: Files and API Summary

6.43.9.3 ‘unicode_blocks.pl’
............................

   - Provides: ‘unicode_block/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_case_folding pl,  Next: unicode_categories pl,  Prev: unicode_blocks pl,  Up: Files and API Summary

6.43.9.4 ‘unicode_case_folding.pl’
..................................

   - Provides: ‘unicode_case_folding/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_categories pl,  Next: unicode_cjk_radicals pl,  Prev: unicode_case_folding pl,  Up: Files and API Summary

6.43.9.5 ‘unicode_categories.pl’
................................

   - Provides: ‘unicode_category/2’

   - Dependencies: files in the ‘unicode_categories’ directory


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_cjk_radicals pl,  Next: unicode_composition_exclusions pl,  Prev: unicode_categories pl,  Up: Files and API Summary

6.43.9.6 ‘unicode_cjk_radicals.pl’
..................................

   - Provides: ‘unicode_cjk_radical/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_composition_exclusions pl,  Next: unicode_core_properties pl,  Prev: unicode_cjk_radicals pl,  Up: Files and API Summary

6.43.9.7 ‘unicode_composition_exclusions.pl’
............................................

   - Provides: ‘unicode_composition_exclusion/1’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_core_properties pl,  Next: unicode_decomposition_type pl,  Prev: unicode_composition_exclusions pl,  Up: Files and API Summary

6.43.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.50.0.info,  Node: unicode_decomposition_type pl,  Next: unicode_derived_age pl,  Prev: unicode_core_properties pl,  Up: Files and API Summary

6.43.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.50.0.info,  Node: unicode_derived_age pl,  Next: unicode_derived_bidi_class pl,  Prev: unicode_decomposition_type pl,  Up: Files and API Summary

6.43.9.10 ‘unicode_derived_age.pl’
..................................

   - Provides: ‘unicode_age/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.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.43.9.11 ‘unicode_derived_bidi_class.pl’
.........................................

   - Provides: ‘unicode_bidi_class/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.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.43.9.12 ‘unicode_derived_combining_class.pl’
..............................................

   - Provides: ‘unicode_combining_class/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.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.43.9.13 ‘unicode_derived_core_properties.pl’
..............................................

   - Provides: ‘unicode_core_property/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.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.43.9.14 ‘unicode_derived_decomposition_type.pl’
.................................................

   - Provides: ‘unicode_decomposition_type/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.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.43.9.15 ‘unicode_derived_east_asian_width.pl’
...............................................

   - Provides: ‘unicode_east_asian_width/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.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.43.9.16 ‘unicode_derived_joining_group.pl’
............................................

   - Provides: ‘unicode_joining_group/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.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.43.9.17 ‘unicode_derived_joining_type.pl’
...........................................

   - Provides: ‘unicode_joining_type/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.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.43.9.18 ‘unicode_derived_line_break.pl’
.........................................

   - Provides: ‘unicode_line_break/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.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.43.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.50.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.43.9.20 ‘unicode_derived_numeric_type.pl’
...........................................

   - Provides: ‘unicode_numeric_type/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.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.43.9.21 ‘unicode_derived_numeric_values.pl’
.............................................

   - Provides: ‘unicode_numerical_value/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.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.43.9.22 ‘unicode_hangul_syllable_type.pl’
...........................................

   - Provides: ‘unicode_hangul_syllable_type/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.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.43.9.23 ‘unicode_indic_matra_category.pl’
...........................................

   - Provides: ‘unicode_indic_matra_category/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_indic_syllabic_category pl,  Next: unicode_jamo pl,  Prev: unicode_indic_matra_category pl,  Up: Files and API Summary

6.43.9.24 ‘unicode_indic_syllabic_category.pl’
..............................................

   - Provides: ‘unicode_indic_syllabic_category/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_jamo pl,  Next: unicode_name_aliases pl,  Prev: unicode_indic_syllabic_category pl,  Up: Files and API Summary

6.43.9.25 ‘unicode_jamo.pl’
...........................

   - Provides: ‘unicode_jamo/2’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_name_aliases pl,  Next: unicode_names pl,  Prev: unicode_jamo pl,  Up: Files and API Summary

6.43.9.26 ‘unicode_name_aliases.pl’
...................................

   - Provides: ‘unicode_name_alias/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_names pl,  Next: unicode_prop_list pl,  Prev: unicode_name_aliases pl,  Up: Files and API Summary

6.43.9.27 ‘unicode_names.pl’
............................

   - Provides: ‘unicode_name/2’

   - Dependencies: files in the ‘unicode_names’ directory


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_prop_list pl,  Next: unicode_range_scripts pl,  Prev: unicode_names pl,  Up: Files and API Summary

6.43.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.50.0.info,  Node: unicode_range_scripts pl,  Next: unicode_script_extensions pl,  Prev: unicode_prop_list pl,  Up: Files and API Summary

6.43.9.29 ‘unicode_range_scripts.pl’
....................................

   - Provides: ‘unicode_range_script/3’ ‘unicode_script/2’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_script_extensions pl,  Next: unicode_scripts pl,  Prev: unicode_range_scripts pl,  Up: Files and API Summary

6.43.9.30 ‘unicode_script_extensions.pl’
........................................

   - Provides: ‘unicode_script_extension/2-3’

   - Dependencies: ‘unicode_scripts.pl’


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_scripts pl,  Next: unicode_special_casing pl,  Prev: unicode_script_extensions pl,  Up: Files and API Summary

6.43.9.31 ‘unicode_scripts.pl’
..............................

   - Provides: ‘unicode_script/6’ ‘unicode_script_category/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_special_casing pl,  Next: unicode_unihan_variants pl,  Prev: unicode_scripts pl,  Up: Files and API Summary

6.43.9.32 ‘unicode_special_casing.pl’
.....................................

   - Provides: ‘unicode_special_casing/5’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_unihan_variants pl,  Next: unicode_version pl,  Prev: unicode_special_casing pl,  Up: Files and API Summary

6.43.9.33 ‘unicode_unihan_variants.pl’
......................................

   - Provides: ‘unicode_unihan_variant/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: unicode_version pl,  Prev: unicode_unihan_variants pl,  Up: Files and API Summary

6.43.9.34 ‘unicode_version.pl’
..............................

   - Provides: ‘unicode_version/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.50.0.info,  Node: uuid,  Next: zippers,  Prev: unicode_data,  Up: Libraries

6.44 ‘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.

* Menu:

* API documentation: API documentation<56>.
* Loading: Loading<56>.
* Testing: Testing<48>.
* Generating version 1 UUIDs::
* Generating version 4 UUIDs::
* Generating the null UUID::


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<56>,  Next: Loading<56>,  Up: uuid

6.44.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#uuid’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<56>,  Next: Testing<48>,  Prev: API documentation<56>,  Up: uuid

6.44.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(uuid(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<48>,  Next: Generating version 1 UUIDs,  Prev: Loading<56>,  Up: uuid

6.44.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(uuid(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Generating version 1 UUIDs,  Next: Generating version 4 UUIDs,  Prev: Testing<48>,  Up: uuid

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

Similar 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.50.0.info,  Node: Generating version 4 UUIDs,  Next: Generating the null UUID,  Prev: Generating version 1 UUIDs,  Up: uuid

6.44.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.50.0.info,  Node: Generating the null UUID,  Prev: Generating version 4 UUIDs,  Up: uuid

6.44.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.50.0.info,  Node: zippers,  Prev: uuid,  Up: Libraries

6.45 ‘zippers’
==============

This library implements zippers over lists.

* Menu:

* API documentation: API documentation<57>.
* Loading: Loading<57>.
* Testing: Testing<49>.


File: TheLogtalkHandbook-3.50.0.info,  Node: API documentation<57>,  Next: Loading<57>,  Up: zippers

6.45.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#zippers’ link in a web browser.


File: TheLogtalkHandbook-3.50.0.info,  Node: Loading<57>,  Next: Testing<49>,  Prev: API documentation<57>,  Up: zippers

6.45.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(zippers(loader)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Testing<49>,  Prev: Loading<57>,  Up: zippers

6.45.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(zippers(tester)).


File: TheLogtalkHandbook-3.50.0.info,  Node: Glossary,  Next: Index<2>,  Prev: Libraries,  Up: Top

7 Glossary
**********

abstract class

     A *note class: a1a. 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: a1c. implementing an algorithm whose step
     corresponds to calls to methods defined in the descendants of the
     object (or *note category: a1d.) 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: 32.

ancestor

     A *note class: a1a. or a parent *note prototype: a1f. 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).

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.

built-in method

     A predefined *note method: a1c. that can be called from within any
     object or *note category: a1d.  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: 4e0. and *note
     categories: a1d.

category

     A set of *note predicates directives: a22. 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: 103. of existing objects.  A category should be
     functionally-cohesive, defining a single functionality.

class

     An *note object: 4e0. that specializes another object, interpreted
     as its superclass.  A class define the common predicates of a set
     of objects that instantiates it.  An object can also be interpreted
     as a class when it instantiates itself.

closed-world assumption

     The assumption that what cannot be proved true is false.
     Therefore, sending a *note message: 41. 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: 4d. 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: 103. 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.

directive

     A source file term that affects the interpretation of source code.
     Directives use the ‘(:-)/1’ prefix operator as functor.

doclet file

     A *note source file: 5c4. whose main purpose is to generate
     documentation for e.g.  a *note library: 69. or an application.

doclet object

     An object specifying the steps necessary to (re)generate the API
     documentation for a project.  See the doclet(1) and lgtdoc(2) tools
     for details.

dynamic binding

     Runtime lookup of a *note predicate declaration: 52. and *note
     predicate definition: 53. to verify the validity of a *note
     message: 41. (or a *note super call: 10b.) 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: 33.

dynamic entity

     See *note entity: a27.

early binding

     See *note static binding: 33.

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: 1c5.

entity

     Generic name for Logtalk compilation units: *note objects: 4e0,
     *note categories: a1d, and *note protocols: 54.  Entities share a
     single namespace (i.e.  entity *note identifiers: a2a. 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 directive

     A directive that affects how Logtalk *note entities: a27. are used
     or compiled.

event

     The sending of a *note message: 41. to an object.  An event can be
     expressed as an ordered tuple: ‘(Event, Object, Message, Sender)’.
     Logtalk distinguish between the sending of a message — ‘before’
     event — and the return of control to the sender — ‘after’ event.

expansion workflow

     A sequence of term-expansion or goal-expansion steps where each
     step is usually defined using a *note hook object: 35e. or a
     combination of hook objects.

grammar rule

     An alternative notation for predicates used to parse or generate
     sentences on 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.

hook object

     An object, implementing the expanding(3) built-in protocol,
     defining term- and goal-expansion predicates, used in the
     compilation of Logtalk or Prolog source files.  A hook object can
     be specified using the *note hook: f7. flag.  It can also be
     specified using a *note set_logtalk_flag/2: 4b. directive in the
     source files to be expanded.

hook predicate

     A predicate, usually declared *note multifile: 2e8, 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: a2b. and predicates or
     adding new entity directives and predicates to loaded *note
     entities: a27. in a running application without requiring access to
     the entities source code or restarting the application.  Achieved
     using *note complementing categories: a23.

identity

     Property of an *note entity: a27. 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: a1d. 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: a27. inherits *note predicates directives: a22.
     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: a31, *note protected inheritance:
     a32, and *note private inheritance: a33.

instance

     An *note object: 4e0. that instantiates one another object,
     interpreted as its *note class: a1a.  An object may instantiate
     multiple objects (also known as multiple instantiation).

instantiation

     The process of creating a new *note class: a1a. *note instance:
     a34.  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: 54.

lambda expression

     A compound term that can be used in place of a goal or *note
     closure: 13f. meta-argument and that abstracts a *note predicate
     definition: 53. by listing its variables and a callable term that
     implements the definition.  Lambda expressions help avoiding the
     need of naming and defining auxiliary predicates.

lambda free variable

     A variable that is global to a *note lambda expression: 16e.  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: 16e.  All lambda parameters
     must be explicitly enumerated in a lambda expression for
     well-defined semantics.

late binding

     See *note dynamic binding: 34.

library

     A directory containing source files.  See also *note library alias:
     5f7. and *note library notation: 288.

library alias

     An atom that can be used as an alias for a *note library: 69. full
     path.  Library aliases and their corresponding paths can be defined
     using the *note logtalk_library_path/2: 287. predicate.  See also
     *note library notation: 288.

library notation

     A compound term where the name is a *note library alias: 5f7. and
     the single argument is a *note source file: 5c4. 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: 5c4. 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:
     a1d.) but that is not listed in a *note scope directive: 1c5.
     These predicates behave like private predicates but are invisible
     to the reflection *note built-in methods: a20.  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 seen
     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: 52, to check if the message is within the
     scope of the sender, and a lookup for the *note predicate
     definition: 53. that is going to be called to answer the message.
     Message lookup can occur at *note compile: 33. time or at *note
     runtime: 34.

message to self

     A message sent to the object that received the original message
     under processing.  Messages to self require *note dynamic binding:
     34. 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: 13f. 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: a38.  For
     example, *note call/1-N: 16d. and *note findall/3: 1a3. are
     built-in meta-predicates.

metaclass

     The *note class: a1a. of a class, when interpreted as an instance.
     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: 53. used to answer a *note message:
     41. sent to an object.  Logtalk supports both *note static binding:
     33. and *note dynamic binding: 34. to find which method to run to
     answer a message.

module

     A Prolog entity characterized by an identity and a set of *note
     predicates directives: a22. and clauses.  Prolog modules are
     usually static although some Prolog systems allow the creation of
     dynamic modules at runtime.  Prolog modules can be seen as
     prototypes.

monitor

     Any object, implementing the monitoring(4) built-in protocol, that
     is notified by the runtime when a spied event occurs.  The spied
     *note events: a2c. 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: a27. and *note source files: 5c4.  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: 1c5. and a *note
     multifile/1: 159. directive for the predicate.

object

     An entity characterized by an *note identity: a2a. and a set of
     *note predicates directives: a22. 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 predicate clauses.

parameter variable

     A variable used as parameter in a parametric object or a parametric
     category using the syntax ‘_ParameterName_’.  Parameter variables
     are `logical variables' shared by all entity terms.  Occurrences of
     parameter variables in *note entity directives: a2b. and clauses
     are implicitly unified with the corresponding entity parameters.

parametric category

     See *note parametric entity: 628.

parametric entity

     An *note object: 4e0. or *note category: a1d. whose *note
     identifier: a2a. 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: 628.

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 prototype 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: 35. 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: 628.
     enable implementation of `parametric polymorphism' by using one of
     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’.  When
     predicates defined in *note objects: 4e0. or *note categories: a1d.
     they are also referred to as *note methods: a1c.

predicate alias

     An alternative functor (‘Name/Arity’) for a predicate.  Predicate
     aliases can be defined for any inherited predicate using the *note
     alias/2: 153. directive and for predicates listed in *note uses/2:
     48. and *note use_module/2: 4a. directives.  Predicate aliases can
     be used to solve inheritance conflicts and to improve code clarity
     by using alternative names that are more meaningful in the calling
     context.

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: a22, which must include ar least a *note scope
     directive: 1c5.

predicate definition

     The set of clauses for a predicate, contained in an object or
     category.  Predicate definitions can be overriden 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: 3b4, *note self:
     64, and *note this: 169.) required for the correct execution of a
     predicate call.

predicate scope container

     The object that inherits a *note predicate declaration: 52. from an
     imported *note category: a1d. or an implemented *note protocol: 54.

predicate scope directive

     A directive that declares a predicate by specifying its visibility
     as `public', `protected', or `private'.

predicate shorthand

     A *note predicate alias: c4. 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:
     48. and *note use_module/2: 4a. 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: 2e8.

private inheritance

     All public and protected predicates are inherited as private
     predicates.  See also *note public inheritance: a31. and *note
     protected inheritance: a32.

private predicate

     A predicate that can only be called from the object that contains
     its *note scope directive: 1c5.

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: a31. and *note private inheritance: a33.

protected predicate

     A predicate that can only be called from the object containing its
     *note scope directive: 1c5. or from an object that inherits the
     predicate.

protocol

     An entity that contains *note predicate declarations: 52.  A
     predicate is declared using a *note scope directive: 1c5.  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 object that may extend or be extended by other
     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: a32. and *note private inheritance:
     a33.

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: 5c4.

self

     The object that received the *note message: 41. under processing.

sender

     An object that sends a *note message: 41. to other object.  When a
     message is sent from within a *note category: a1d, the `sender' is
     the object importing the category.

settings file

     A *note source file: 5c4, 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: 143.

singleton method

     A *note method: a1c. defined in an *note instance: a34. 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: 32, the text encoding may
     be specified using an *note encoding/1: 279. directive as the first
     term in the first line in the file.

source file directive

     A *note directive: a24. that affects how a *note source file: 5c4.
     is compiled.

specialization

     A *note class: a1a. is specialized by defining a new class that
     inherit its predicates and possibly add new ones.

static binding

     Compile time lookup of a *note predicate declaration: 52. and *note
     predicate definition: 53. when compiling a *note message: 41.
     sending call (or a *note super call: 10b.).  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: 34.

static entity

     See *note entity: a27.

steadfastness

     A predicate definition is `steadfast' when it still generates only
     correct answers when called with unexpected 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: a1a. 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: 53.
     Mainly used when redefining an inherited (or imported) predicate to
     call the overridden definition while making additional calls.
     Super calls preserve *note self: 64. and may require *note dynamic
     binding: 34. if the predicate is dynamic.

superclass

     A *note class: a1a. 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: a1b.

tester file

     A *note source file: 5c4. 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: a1d,
     `this' is a reference to the object importing the category for
     which the predicate clause is being executed.

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: 44. and *note logtalk_make/1: 281.  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: a20, 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: ‘http://www.cs.mu.oz.au/~lee/papers/oolp/’

(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:
‘http://www.cs.mu.oz.au/tr_db/mu_92_03.ps.gz’

(Davison93) The deductive and object oriented features of BeBOP Davison,
A. Tech Report 93/6, Dept.  of Computer Science, University of
Melbourne, Australia URL:‘http://www.cs.mu.oz.au/tr_db/mu_93_06.ps.gz’

(Delzanno97) Logic and Object-Oriented Programming in Linear Logic
Delzanno, G. Ph.D. Thesis, University of Pisa, Italy
URL:‘http://www.mpi-sb.mpg.de/~delzanno/’

(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. Comunications 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:
‘http://www.sics.se/ps/sicstus.html’

(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) 
https://github.com/LogtalkDotOrg/logtalk3/tree/master/tools/doclet/NOTES.md

   (2) 
https://github.com/LogtalkDotOrg/logtalk3/tree/master/tools/lgtdoc/NOTES.md

   (3) ../docs/expanding_0.html#expanding-0

   (4) ../docs/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.50.0.info,  Node: Index<2>,  Next: Index,  Prev: Glossary,  Up: Top

8 Index
*******


File: TheLogtalkHandbook-3.50.0.info,  Node: Index,  Prev: Index<2>,  Up: Top

Index
*****

[index]
* Menu:

* ;;/1; Control construct:               Examples<2>.         (line  17)
* ;;/2; Control construct:               Message sending<2>.  (line   6)
* <</2; Control construct:               Context switching calls.
                                                              (line   6)
* []/1; Control construct:               Message delegation.  (line   6)
* \+/1; Built-in method:                 Examples<115>.       (line  17)
* ^^/1; Control construct:               Calling imported and inherited predicates<2>.
                                                              (line   6)
* {}/1; Control construct:               Calling external predicates.
                                                              (line   6)
* abolish/1; Built-in method:            Database.            (line   6)
* abolish_category/1; Built-in predicate: Abolishing objects categories and protocols.
                                                              (line   6)
* abolish_events/5; Built-in predicate:  Event handling<2>.   (line   6)
* abolish_object/1; Built-in predicate:  Examples<53>.        (line  14)
* abolish_protocol/1; Built-in predicate: Examples<54>.       (line  15)
* abstract class:                        Glossary.            (line   6)
* abstract method:                       Glossary.            (line  10)
* adapter file:                          Glossary.            (line  16)
* after/3; Built-in method:              Examples<135>.       (line  20)
* alias/2; Directive:                    Predicate directives<3>.
                                                              (line   6)
* always_true_or_false_goals; Flag:      Lint flags.          (line  70)
* ancestor:                              Glossary.            (line  22)
* ask_question/5; Built-in method:       Question asking.     (line   6)
* asserta/1; Built-in method:            Examples<107>.       (line  19)
* assertz/1; Built-in method:            Examples<108>.       (line  19)
* backend Prolog compiler:               Glossary.            (line  31)
* bagof/3; Built-in method:              All solutions.       (line   6)
* before/3; Built-in method:             Event handling<3>.   (line   6)
* begin_of_file:                         Hook objects.        (line  42)
* behavioral reflection:                 Black-box view.      (line  18)
* black-box view:                        Transparent-box view.
                                                              (line  28)
* built-in method:                       Glossary.            (line  37)
* built-in predicate:                    Glossary.            (line  44)
* built_in/0; Directive:                 Entity directives<2>.
                                                              (line   6)
* call//1-N; Built-in method:            Definite clause grammar rules<2>.
                                                              (line   6)
* call/1-N; Built-in method:             Meta-calls.          (line   6)
* catch/3; Built-in method:              Error handling<2>.   (line   6)
* category:                              Glossary.            (line  50)
* category/1-4; Directive:               Examples<17>.        (line   7)
* category_property/2; Built-in predicate: Enumerating objects categories and protocols properties.
                                                              (line   6)
* class:                                 Glossary.            (line  58)
* clause/2; Built-in method:             Examples<109>.       (line  19)
* clean; Flag:                           Other flags.         (line 107)
* closed-world assumption:               Glossary.            (line  65)
* closure:                               Glossary.            (line  73)
* code_prefix; Flag:                     Other flags.         (line  28)
* coinduction; Flag:                     Read-only flags.     (line  87)
* coinductive predicate:                 Glossary.            (line  79)
* coinductive/1; Directive:              Examples<29>.        (line  17)
* coinductive_success_hook/1-2; Built-in method: Coinduction hooks.
                                                              (line   6)
* complementing category:                Glossary.            (line  85)
* complements; Flag:                     Optional features compilation flags.
                                                              (line   6)
* complements_object/2; Built-in predicate: Examples<60>.     (line  23)
* component:                             Glossary.            (line  90)
* conforms_to_protocol/2-3; Built-in predicate: Examples<59>. (line  23)
* context/1; Built-in method:            Execution context.   (line   6)
* context_switching_calls; Flag:         Optional features compilation flags.
                                                              (line  40)
* create_category/4; Built-in predicate: Creating new objects categories and protocols.
                                                              (line   6)
* create_logtalk_flag/3; Built-in predicate: Examples<96>.    (line  14)
* create_object/4; Built-in predicate:   Examples<50>.        (line  19)
* create_protocol/3; Built-in predicate: Examples<51>.        (line  61)
* current_category/1; Built-in predicate: Enumerating objects categories and protocols.
                                                              (line   6)
* current_event/5; Built-in predicate:   Examples<65>.        (line  15)
* current_logtalk_flag/2; Built-in predicate: Flags.          (line   6)
* current_object/1; Built-in predicate:  Examples<44>.        (line  18)
* current_op/3; Built-in method:         Reflection<2>.       (line   6)
* current_predicate/1; Built-in method:  Examples<104>.       (line  18)
* current_protocol/1; Built-in predicate: Examples<45>.       (line  20)
* debug; Flag:                           Other flags.         (line  72)
* define_events/5; Built-in predicate:   Examples<66>.        (line  14)
* deprecated; Flag:                      Lint flags.          (line  45)
* directive:                             Glossary.            (line  98)
* discontiguous/1; Directive:            Examples<30>.        (line  15)
* disjunctions; Flag:                    Lint flags.          (line 140)
* doclet file:                           Glossary.            (line 103)
* doclet object:                         Glossary.            (line 108)
* domain_error/2; Built-in method:       Examples<121>.       (line  19)
* duplicated_clauses; Flag:              Lint flags.          (line 131)
* duplicated_directives; Flag:           Lint flags.          (line  56)
* dynamic binding:                       Glossary.            (line 114)
* dynamic entity:                        Glossary.            (line 123)
* dynamic/0; Directive:                  Examples<18>.        (line  25)
* dynamic/1; Directive:                  Examples<31>.        (line  11)
* dynamic_declarations; Flag:            Optional features compilation flags.
                                                              (line  18)
* early binding:                         Glossary.            (line 127)
* elif/1; Directive:                     Examples<13>.        (line  30)
* else/0; Directive:                     Examples<14>.        (line  24)
* encapsulation:                         Glossary.            (line 131)
* encoding/1; Directive:                 Source file directives<2>.
                                                              (line   6)
* encoding_directive; Flag:              Read-only flags.     (line  51)
* endif/0; Directive:                    Examples<15>.        (line  28)
* end_category/0; Directive:             Examples<19>.        (line  13)
* end_object/0; Directive:               Examples<20>.        (line  12)
* end_of_file:                           Hook objects.        (line  41)
* end_protocol/0; Directive:             Examples<21>.        (line  12)
* engines; Flag:                         Read-only flags.     (line  66)
* entity:                                Glossary.            (line 138)
* entity directive:                      Glossary.            (line 148)
* eos//0; Built-in method:               Examples<138>.       (line  20)
* evaluation_error/1; Built-in method:   Examples<125>.       (line  19)
* event:                                 Glossary.            (line 153)
* events; Flag:                          Optional features compilation flags.
                                                              (line  29)
* existence_error/2; Built-in method:    Examples<122>.       (line  20)
* expand_goal/2; Built-in method:        Examples<144>.       (line  14)
* expand_term/2; Built-in method:        Term and goal expansion<2>.
                                                              (line   6)
* expansion workflow:                    Glossary.            (line 160)
* extends_category/2-3; Built-in predicate: Examples<57>.     (line  17)
* extends_object/2-3; Built-in predicate: Objects categories and protocols relations.
                                                              (line   6)
* extends_protocol/2-3; Built-in predicate: Examples<56>.     (line  17)
* findall/3; Built-in method:            Examples<130>.       (line  18)
* findall/4; Built-in method:            Examples<131>.       (line  18)
* forall/2; Built-in method:             Examples<132>.       (line  18)
* forward/1; Built-in method:            Message forwarding.  (line   6)
* goal_expansion/2; Built-in method:     Examples<145>.       (line  13)
* grammar rule:                          Glossary.            (line 166)
* grammar rule non-terminal:             Glossary.            (line 175)
* grammar rule terminal:                 Glossary.            (line 181)
* hook object:                           Glossary.            (line 185)
* hook predicate:                        Glossary.            (line 194)
* hook; Flag:                            Other flags.         (line  98)
* hot patching:                          Glossary.            (line 200)
* identity:                              Glossary.            (line 208)
* if/1; Directive:                       Conditional compilation directives<2>.
                                                              (line   6)
* ignore/1; Built-in method:             Examples<113>.       (line  17)
* implements_protocol/2-3; Built-in predicate: Examples<58>.  (line  17)
* imports_category/2-3; Built-in predicate: Examples<61>.     (line  13)
* include/1; Directive:                  Examples<8>.         (line   7)
* info/1; Directive:                     Examples<22>.        (line  12)
* info/2; Directive:                     Examples<32>.        (line  16)
* inheritance:                           Glossary.            (line 217)
* initialization/1; Directive:           Examples<9>.         (line  20)
* instance:                              Glossary.            (line 227)
* instantiates_class/2-3; Built-in predicate: Examples<62>.   (line  16)
* instantiation:                         Glossary.            (line 233)
* instantiation_error/0; Built-in method: Examples<118>.      (line  17)
* interface:                             Glossary.            (line 240)
* lambda expression:                     Glossary.            (line 244)
* lambda free variable:                  Glossary.            (line 252)
* lambda parameter:                      Glossary.            (line 258)
* lambda_variables; Flag:                Lint flags.          (line  76)
* late binding:                          Glossary.            (line 265)
* library:                               Glossary.            (line 269)
* library alias:                         Glossary.            (line 274)
* library notation:                      Glossary.            (line 281)
* loader file:                           Glossary.            (line 289)
* local predicate:                       Glossary.            (line 295)
* logtalk_compile/1; Built-in predicate: Compiling and loading source files.
                                                              (line   6)
* logtalk_compile/2; Built-in predicate: Examples<86>.        (line  24)
* logtalk_library_path/2; Built-in predicate: Examples<92>.   (line  18)
* logtalk_linter_hook/7; Built-in predicate: Linter.          (line   6)
* logtalk_load/1; Built-in predicate:    Examples<87>.        (line  24)
* logtalk_load/2; Built-in predicate:    Examples<88>.        (line  24)
* logtalk_load_context/2; Built-in predicate: Examples<93>.   (line  52)
* logtalk_make/0; Built-in predicate:    Examples<89>.        (line  24)
* logtalk_make/1; Built-in predicate:    Examples<90>.        (line  15)
* logtalk_make_target_action/1; Built-in predicate: Examples<91>.
                                                              (line  22)
* message:                               Glossary.            (line 304)
* message lookup:                        Glossary.            (line 310)
* message to self:                       Glossary.            (line 319)
* message_hook/4; Built-in method:       Examples<149>.       (line  19)
* message_prefix_stream/4; Built-in method: Examples<150>.    (line  21)
* message_tokens//2; Built-in method:    Examples<148>.       (line  15)
* meta-argument:                         Glossary.            (line 325)
* meta-interpreter:                      Glossary.            (line 332)
* meta-predicate:                        Glossary.            (line 337)
* metaclass:                             Glossary.            (line 343)
* meta_non_terminal/1; Directive:        Examples<34>.        (line  21)
* meta_predicate/1; Directive:           Examples<33>.        (line  19)
* method:                                Glossary.            (line 350)
* missing_directives; Flag:              Lint flags.          (line  50)
* mode/2; Directive:                     Examples<35>.        (line  13)
* module:                                Glossary.            (line 357)
* modules; Flag:                         Read-only flags.     (line  80)
* monitor:                               Glossary.            (line 365)
* multifile predicate:                   Glossary.            (line 372)
* multifile/1; Directive:                Examples<36>.        (line  17)
* naming; Flag:                          Lint flags.          (line 121)
* object:                                Glossary.            (line 381)
* object database:                       Glossary.            (line 389)
* object/1-5; Directive:                 Examples<23>.        (line  18)
* object_property/2; Built-in predicate: Examples<47>.        (line  20)
* once/1; Built-in method:               Examples<114>.       (line  17)
* op/3; Directive:                       Examples<10>.        (line  23)
* optimize; Flag:                        Other flags.         (line  43)
* parameter:                             Glossary.            (line 393)
* parameter variable:                    Glossary.            (line 399)
* parameter/2; Built-in method:          Examples<99>.        (line  19)
* parametric category:                   Glossary.            (line 407)
* parametric entity:                     Glossary.            (line 411)
* parametric object:                     Glossary.            (line 422)
* parametric object proxy:               Glossary.            (line 426)
* parent:                                Glossary.            (line 432)
* permission_error/3; Built-in method:   Examples<123>.       (line  19)
* phrase//1; Built-in method:            Examples<139>.       (line  13)
* phrase/2; Built-in method:             Examples<140>.       (line  12)
* phrase/3; Built-in method:             Examples<141>.       (line  17)
* polymorphism:                          Glossary.            (line 436)
* portability; Flag:                     Lint flags.          (line  37)
* predicate:                             Glossary.            (line 451)
* predicate alias:                       Glossary.            (line 459)
* predicate calling context:             Glossary.            (line 469)
* predicate declaration:                 Glossary.            (line 475)
* predicate definition:                  Glossary.            (line 481)
* predicate definition context:          Glossary.            (line 487)
* predicate directive:                   Glossary.            (line 492)
* predicate execution context:           Glossary.            (line 497)
* predicate scope container:             Glossary.            (line 503)
* predicate scope directive:             Glossary.            (line 509)
* predicate shorthand:                   Glossary.            (line 513)
* predicate_property/2; Built-in method: Examples<105>.       (line  18)
* primary predicate declaration:         Glossary.            (line 524)
* print_message/3; Built-in method:      Message printing.    (line   6)
* print_message_token/4; Built-in method: Examples<152>.      (line  17)
* print_message_tokens/3; Built-in method: Examples<151>.     (line  18)
* private inheritance:                   Glossary.            (line 528)
* private predicate:                     Glossary.            (line 534)
* private/1; Directive:                  Examples<37>.        (line  14)
* profiler:                              Glossary.            (line 539)
* prolog_compatible_version; Flag:       Read-only flags.     (line  35)
* prolog_compiler; Flag:                 Backend Prolog compiler and loader flags.
                                                              (line   6)
* prolog_dialect; Flag:                  Read-only flags.     (line  21)
* prolog_loader; Flag:                   Backend Prolog compiler and loader flags.
                                                              (line  15)
* prolog_version; Flag:                  Read-only flags.     (line  27)
* protected inheritance:                 Glossary.            (line 543)
* protected predicate:                   Glossary.            (line 549)
* protected/1; Directive:                Examples<38>.        (line  17)
* protocol:                              Glossary.            (line 555)
* protocol/1-2; Directive:               Examples<24>.        (line  33)
* protocol_property/2; Built-in predicate: Examples<48>.      (line  23)
* prototype:                             Glossary.            (line 565)
* public inheritance:                    Glossary.            (line 572)
* public predicate:                      Glossary.            (line 577)
* public/1; Directive:                   Examples<39>.        (line  17)
* question_hook/6; Built-in method:      Examples<154>.       (line  17)
* question_prompt_stream/4; Built-in method: Examples<155>.   (line  19)
* redefined_built_ins; Flag:             Lint flags.          (line  88)
* redefined_operators; Flag:             Lint flags.          (line  97)
* reflection:                            Message sending.     (line  26)
* relative_to; Flag:                     Other flags.         (line  92)
* reload; Flag:                          Other flags.         (line  81)
* report; Flag:                          Other flags.         (line  20)
* representation_error/1; Built-in method: Examples<124>.     (line  19)
* resource_error/1; Built-in method:     Examples<126>.       (line  19)
* retract/1; Built-in method:            Examples<110>.       (line  19)
* retractall/1; Built-in method:         Examples<111>.       (line  19)
* scratch directory:                     Glossary.            (line 581)
* scratch_directory; Flag:               Other flags.         (line   6)
* self:                                  Glossary.            (line 586)
* self/1; Built-in method:               Examples<100>.       (line  40)
* sender:                                Glossary.            (line 590)
* sender/1; Built-in method:             Examples<101>.       (line  18)
* setof/3; Built-in method:              Examples<133>.       (line  18)
* settings file:                         Glossary.            (line 596)
* settings_file; Flag:                   Read-only flags.     (line   8)
* set_logtalk_flag/2; Built-in predicate: Examples<95>.       (line  13)
* set_logtalk_flag/2; Directive:         Examples<11>.        (line  15)
* singleton method:                      Glossary.            (line 603)
* singleton_variables; Flag:             Lint flags.          (line 105)
* source file:                           Glossary.            (line 609)
* source file directive:                 Glossary.            (line 618)
* source_data; Flag:                     Other flags.         (line  60)
* specialization:                        Glossary.            (line 623)
* specializes_class/2-3; Built-in predicate: Examples<63>.    (line  18)
* static binding:                        Glossary.            (line 628)
* static entity:                         Glossary.            (line 638)
* steadfastness:                         Glossary.            (line 642)
* steadfastness; Flag:                   Lint flags.          (line  29)
* structural reflection:                 Reflection.          (line  13)
* subclass:                              Glossary.            (line 650)
* super call:                            Glossary.            (line 655)
* superclass:                            Glossary.            (line 663)
* suspicious_calls; Flag:                Lint flags.          (line  82)
* synchronized predicate:                Glossary.            (line 669)
* synchronized/1; Directive:             Examples<40>.        (line  17)
* syntax_error/1; Built-in method:       Examples<127>.       (line  18)
* system_error/0; Built-in method:       Examples<128>.       (line  16)
* tabling; Flag:                         Read-only flags.     (line  60)
* tail_recursive; Flag:                  Lint flags.          (line 146)
* template method:                       Glossary.            (line 675)
* term_expansion/2; Built-in method:     Examples<143>.       (line  13)
* tester file:                           Glossary.            (line 679)
* this:                                  Glossary.            (line 684)
* this/1; Built-in method:               Examples<102>.       (line  18)
* threaded engine:                       Glossary.            (line 691)
* threaded/0; Directive:                 Examples<25>.        (line  18)
* threaded/1; Built-in predicate:        Multi-threading.     (line   6)
* threaded_call/1-2; Built-in predicate: Examples<68>.        (line  16)
* threaded_cancel/1; Built-in predicate: Examples<73>.        (line  19)
* threaded_engine/1; Built-in predicate: Examples<78>.        (line  20)
* threaded_engine_create/3; Built-in predicate: Multi-threading engines.
                                                              (line   6)
* threaded_engine_destroy/1; Built-in predicate: Examples<77>.
                                                              (line  15)
* threaded_engine_fetch/1; Built-in predicate: Examples<84>.  (line  13)
* threaded_engine_next/2; Built-in predicate: Examples<80>.   (line  17)
* threaded_engine_next_reified/2; Built-in predicate: Examples<81>.
                                                              (line  14)
* threaded_engine_post/2; Built-in predicate: Examples<83>.   (line  14)
* threaded_engine_self/1; Built-in predicate: Examples<79>.   (line  20)
* threaded_engine_yield/1; Built-in predicate: Examples<82>.  (line  14)
* threaded_exit/1-2; Built-in predicate: Examples<71>.        (line  19)
* threaded_ignore/1; Built-in predicate: Examples<70>.        (line  19)
* threaded_notify/1; Built-in predicate: Examples<75>.        (line  13)
* threaded_once/1-2; Built-in predicate: Examples<69>.        (line  19)
* threaded_peek/1-2; Built-in predicate: Examples<72>.        (line  19)
* threaded_wait/1; Built-in predicate:   Examples<74>.        (line  14)
* threads; Flag:                         Read-only flags.     (line  73)
* throw/1; Built-in method:              Examples<117>.       (line  17)
* top-level interpreter shorthand:       Glossary.            (line 699)
* transparent-box view:                  Structural reflection.
                                                              (line  11)
* trivial_goal_fails; Flag:              Lint flags.          (line  64)
* type_error/2; Built-in method:         Examples<120>.       (line  19)
* undefined_predicates; Flag:            Lint flags.          (line  21)
* underscore_variables; Flag:            Lint flags.          (line 110)
* unicode; Flag:                         Read-only flags.     (line  44)
* unknown_entities; Flag:                Lint flags.          (line   6)
* unknown_predicates; Flag:              Lint flags.          (line  13)
* ununinstantiation_error/1; Built-in method: Examples<119>.  (line  19)
* uses/1; Directive:                     Examples<26>.        (line  12)
* uses/2; Directive:                     Examples<41>.        (line  16)
* use_module/1; Directive:               Examples<27>.        (line  31)
* use_module/2; Directive:               Examples<42>.        (line  60)
* version_data; Flag:                    Version flags.       (line   6)
* visible predicate:                     Glossary.            (line 706)



Tag Table:
Node: Top462
Ref: index doc698
Ref: 0698
Node: User Manual57761
Ref: userman/index doc57868
Ref: 157868
Ref: userman/index the-logtalk-handbook57868
Ref: 257868
Ref: userman/index user-manual57868
Ref: 357868
Node: Declarative object-oriented programming58395
Ref: userman/declarative doc58523
Ref: 458523
Ref: userman/declarative declarative-declarative58523
Ref: 558523
Ref: userman/declarative declarative-object-oriented-programming58523
Ref: 658523
Node: Main features62090
Ref: userman/features doc62239
Ref: 762239
Ref: userman/features features-features62239
Ref: 862239
Ref: userman/features main-features62239
Ref: 962239
Node: Integration of logic and object-oriented programming64181
Ref: userman/features features-logic64370
Ref: a64370
Ref: userman/features integration-of-logic-and-object-oriented-programming64370
Ref: b64370
Node: Integration of event-driven and object-oriented programming65422
Ref: userman/features features-events65659
Ref: c65659
Ref: userman/features integration-of-event-driven-and-object-oriented-programming65659
Ref: d65659
Node: Support for component-based programming66928
Ref: userman/features features-categories67163
Ref: 1367163
Ref: userman/features support-for-component-based-programming67163
Ref: 1467163
Node: Support for both prototype and class-based systems67999
Ref: userman/features features-both68214
Ref: 1568214
Ref: userman/features support-for-both-prototype-and-class-based-systems68214
Ref: 1668214
Node: Support for multiple object hierarchies69224
Ref: userman/features features-multiple69447
Ref: 1869447
Ref: userman/features support-for-multiple-object-hierarchies69447
Ref: 1969447
Node: Separation between interface and implementation70268
Ref: userman/features features-interface70481
Ref: 1d70481
Ref: userman/features separation-between-interface-and-implementation70481
Ref: 1e70481
Node: Private protected and public inheritance70981
Ref: userman/features features-inheritance71201
Ref: 1f71201
Ref: userman/features private-protected-and-public-inheritance71201
Ref: 2071201
Node: Private protected and public object predicates71547
Ref: userman/features features-predicates71738
Ref: 2271738
Ref: userman/features private-protected-and-public-object-predicates71738
Ref: 2371738
Node: Parametric objects72230
Ref: userman/features features-parametric72427
Ref: 2472427
Ref: userman/features parametric-objects72427
Ref: 2572427
Node: High level multi-threading programming support73171
Ref: userman/features features-threading73343
Ref: 2973343
Ref: userman/features high-level-multi-threading-programming-support73343
Ref: 2a73343
Node: Smooth learning curve73899
Ref: userman/features features-learning74112
Ref: 2b74112
Ref: userman/features smooth-learning-curve74112
Ref: 2c74112
Node: Compatibility with most Prolog systems and the ISO standard74332
Ref: userman/features compatibility-with-most-prolog-systems-and-the-iso-standard74510
Ref: 2d74510
Ref: userman/features features-compatibility74510
Ref: 2e74510
Node: Performance74885
Ref: userman/features features-performance75055
Ref: 3075055
Ref: userman/features performance75055
Ref: 3175055
Node: Logtalk scope76373
Ref: userman/features features-scope76475
Ref: 3776475
Ref: userman/features logtalk-scope76475
Ref: 3876475
Node: Nomenclature79148
Ref: userman/nomenclature doc79266
Ref: 3979266
Ref: userman/nomenclature nomenclature79266
Ref: 3a79266
Ref: userman/nomenclature nomenclature-nomenclature79266
Ref: 3b79266
Node: Prolog nomenclature80952
Ref: userman/nomenclature nomenclature-prolog81070
Ref: 3e81070
Ref: userman/nomenclature prolog-nomenclature81070
Ref: 3f81070
Node: Smalltalk nomenclature87795
Ref: userman/nomenclature nomenclature-smalltalk87938
Ref: 5587938
Ref: userman/nomenclature smalltalk-nomenclature87938
Ref: 5687938
Node: C++ nomenclature93197
Ref: userman/nomenclature c-nomenclature93338
Ref: 5993338
Ref: userman/nomenclature nomenclature-cpp93338
Ref: 5a93338
Node: Java nomenclature96586
Ref: userman/nomenclature java-nomenclature96724
Ref: 6696724
Ref: userman/nomenclature nomenclature-java96724
Ref: 6796724
Node: Python nomenclature101689
Ref: userman/nomenclature nomenclature-python101802
Ref: 70101802
Ref: userman/nomenclature python-nomenclature101802
Ref: 71101802
Node: Messages105882
Ref: userman/messages doc105994
Ref: 72105994
Ref: userman/messages messages105994
Ref: 73105994
Ref: userman/messages messages-messages105994
Ref: 74105994
Node: Operators used in message sending107706
Ref: userman/messages messages-operators107842
Ref: 76107842
Ref: userman/messages operators-used-in-message-sending107842
Ref: 77107842
Node: Sending a message to an object108397
Ref: userman/messages messages-sending108575
Ref: 78108575
Ref: userman/messages sending-a-message-to-an-object108575
Ref: 79108575
Node: Delegating a message to an object109101
Ref: userman/messages delegating-a-message-to-an-object109271
Ref: 7b109271
Ref: userman/messages messages-delegating109271
Ref: 7c109271
Node: Sending a message to self109801
Ref: userman/messages sending-a-message-to-self109953
Ref: 7e109953
Node: Broadcasting110717
Ref: userman/messages broadcasting110877
Ref: 7f110877
Ref: userman/messages messages-broadcasting110877
Ref: 80110877
Node: Calling imported and inherited predicates111646
Ref: userman/messages calling-imported-and-inherited-predicates111817
Ref: 81111817
Ref: userman/messages messages-super111817
Ref: 82111817
Node: Message sending and event generation112985
Ref: userman/messages message-sending-and-event-generation113175
Ref: 83113175
Ref: userman/messages messages-events113175
Ref: 84113175
Node: Sending a message from a module114864
Ref: userman/messages messages-from-module115040
Ref: 86115040
Ref: userman/messages sending-a-message-from-a-module115040
Ref: 87115040
Node: Message sending performance115851
Ref: userman/messages message-sending-performance115982
Ref: 89115982
Ref: userman/messages messages-performance115982
Ref: 8a115982
Node: Objects116150
Ref: userman/objects doc116259
Ref: 8b116259
Ref: userman/objects objects116259
Ref: 8c116259
Ref: userman/objects objects-objects116259
Ref: 8d116259
Ref: Objects-Footnote-1117198
Ref: Objects-Footnote-2117236
Node: Objects prototypes classes and instances117280
Ref: userman/objects objects-kind117413
Ref: 8e117413
Ref: userman/objects objects-prototypes-classes-and-instances117413
Ref: 8f117413
Node: Prototypes119041
Ref: userman/objects objects-prototypes119163
Ref: 90119163
Ref: userman/objects prototypes119163
Ref: 91119163
Node: Classes119782
Ref: userman/objects classes119904
Ref: 92119904
Ref: userman/objects objects-classes119904
Ref: 93119904
Node: Defining a new object120369
Ref: userman/objects defining-a-new-object120532
Ref: 94120532
Ref: userman/objects objects-defining120532
Ref: 95120532
Node: Parametric objects<2>126363
Ref: userman/objects objects-parametric126509
Ref: 61126509
Ref: userman/objects parametric-objects126509
Ref: 9b126509
Node: Finding defined objects130124
Ref: userman/objects finding-defined-objects130281
Ref: 9e130281
Ref: userman/objects objects-finding130281
Ref: 9f130281
Node: Creating a new object in runtime130709
Ref: userman/objects creating-a-new-object-in-runtime130874
Ref: a1130874
Ref: userman/objects objects-creating130874
Ref: a2130874
Node: Abolishing an existing object132129
Ref: userman/objects abolishing-an-existing-object132288
Ref: a3132288
Ref: userman/objects objects-abolishing132288
Ref: a4132288
Node: Object directives132588
Ref: userman/objects object-directives132735
Ref: a5132735
Ref: userman/objects objects-directives132735
Ref: a6132735
Node: Object initialization133122
Ref: userman/objects object-initialization133240
Ref: a7133240
Ref: userman/objects objects-initialization133240
Ref: a8133240
Node: Dynamic objects134462
Ref: userman/objects dynamic-objects134609
Ref: a9134609
Ref: userman/objects objects-dynamic134609
Ref: aa134609
Node: Object documentation135335
Ref: userman/objects object-documentation135489
Ref: ac135489
Ref: userman/objects objects-documentation135489
Ref: ad135489
Node: Loading files into an object135719
Ref: userman/objects loading-files-into-an-object135882
Ref: b0135882
Ref: userman/objects objects-include135882
Ref: b1135882
Node: Declaring object aliases136628
Ref: userman/objects declaring-object-aliases136762
Ref: b3136762
Ref: userman/objects objects-object-aliases136762
Ref: b4136762
Node: Object relationships137176
Ref: userman/objects object-relationships137311
Ref: b6137311
Ref: userman/objects objects-relationships137311
Ref: b7137311
Node: Object properties139425
Ref: userman/objects object-properties139559
Ref: bf139559
Ref: userman/objects objects-properties139559
Ref: c0139559
Node: Built-in objects146525
Ref: userman/objects built-in-objects146630
Ref: c7146630
Ref: userman/objects objects-built-in146630
Ref: c8146630
Node: The built-in pseudo-object user146843
Ref: userman/objects objects-user146982
Ref: c9146982
Ref: userman/objects the-built-in-pseudo-object-user146982
Ref: ca146982
Ref: The built-in pseudo-object user-Footnote-1147972
Node: The built-in object logtalk148010
Ref: userman/objects objects-logtalk148149
Ref: cb148149
Ref: userman/objects the-built-in-object-logtalk148149
Ref: cc148149
Ref: The built-in object logtalk-Footnote-1148651
Node: Protocols148695
Ref: userman/protocols doc148806
Ref: d0148806
Ref: userman/protocols protocols148806
Ref: d1148806
Ref: userman/protocols protocols-protocols148806
Ref: d2148806
Ref: Protocols-Footnote-1149700
Ref: Protocols-Footnote-2149750
Ref: Protocols-Footnote-3149798
Node: Defining a new protocol149848
Ref: userman/protocols defining-a-new-protocol149970
Ref: d3149970
Ref: userman/protocols protocols-defining149970
Ref: d4149970
Node: Finding defined protocols152058
Ref: userman/protocols finding-defined-protocols152223
Ref: d7152223
Ref: userman/protocols protocols-finding152223
Ref: d8152223
Node: Creating a new protocol in runtime152591
Ref: userman/protocols creating-a-new-protocol-in-runtime152764
Ref: da152764
Ref: userman/protocols protocols-creating152764
Ref: db152764
Node: Abolishing an existing protocol153807
Ref: userman/protocols abolishing-an-existing-protocol153974
Ref: dd153974
Ref: userman/protocols protocols-abolishing153974
Ref: de153974
Node: Protocol directives154288
Ref: userman/protocols protocol-directives154443
Ref: e0154443
Node: Dynamic protocols154668
Ref: userman/protocols dynamic-protocols154791
Ref: e1154791
Ref: userman/protocols protocols-dynamic154791
Ref: e2154791
Node: Protocol documentation155434
Ref: userman/protocols protocol-documentation155595
Ref: e3155595
Ref: userman/protocols protocols-documentation155595
Ref: e4155595
Node: Loading files into a protocol155830
Ref: userman/protocols loading-files-into-a-protocol155965
Ref: e5155965
Ref: userman/protocols protocols-include155965
Ref: e6155965
Node: Protocol relationships156214
Ref: userman/protocols protocol-relationships156357
Ref: e7156357
Ref: userman/protocols protocols-relationships156357
Ref: e8156357
Node: Protocol properties157401
Ref: userman/protocols protocol-properties157547
Ref: eb157547
Ref: userman/protocols protocols-properties157547
Ref: ec157547
Node: Implementing protocols159799
Ref: userman/protocols implementing-protocols159941
Ref: ef159941
Ref: userman/protocols protocols-implementing159941
Ref: f0159941
Node: Built-in protocols160935
Ref: userman/protocols built-in-protocols161049
Ref: f1161049
Ref: userman/protocols protocols-built-in161049
Ref: f2161049
Node: The built-in protocol expanding161312
Ref: userman/protocols protocols-expanding161458
Ref: f3161458
Ref: userman/protocols the-built-in-protocol-expanding161458
Ref: f4161458
Ref: The built-in protocol expanding-Footnote-1161780
Node: The built-in protocol monitoring161828
Ref: userman/protocols protocols-monitoring162015
Ref: f8162015
Ref: userman/protocols the-built-in-protocol-monitoring162015
Ref: f9162015
Ref: The built-in protocol monitoring-Footnote-1162339
Node: The built-in protocol forwarding162389
Ref: userman/protocols protocols-forwarding162536
Ref: fc162536
Ref: userman/protocols the-built-in-protocol-forwarding162536
Ref: fd162536
Ref: The built-in protocol forwarding-Footnote-1162945
Node: Categories162995
Ref: userman/categories doc163109
Ref: ff163109
Ref: userman/categories categories163109
Ref: 100163109
Ref: userman/categories categories-categories163109
Ref: 101163109
Ref: Categories-Footnote-1164548
Node: Defining a new category164604
Ref: userman/categories categories-defining164714
Ref: 104164714
Ref: userman/categories defining-a-new-category164714
Ref: 105164714
Node: Hot patching169988
Ref: userman/categories categories-patching170133
Ref: 108170133
Ref: userman/categories hot-patching170133
Ref: 109170133
Node: Finding defined categories173573
Ref: userman/categories categories-finding173729
Ref: 10c173729
Ref: userman/categories finding-defined-categories173729
Ref: 10d173729
Node: Creating a new category in runtime174119
Ref: userman/categories categories-creating174294
Ref: 10e174294
Ref: userman/categories creating-a-new-category-in-runtime174294
Ref: 10f174294
Node: Abolishing an existing category175542
Ref: userman/categories abolishing-an-existing-category175710
Ref: 111175710
Ref: userman/categories categories-abolishing175710
Ref: 112175710
Node: Category directives176025
Ref: userman/categories categories-directives176181
Ref: 113176181
Ref: userman/categories category-directives176181
Ref: 114176181
Node: Dynamic categories176560
Ref: userman/categories categories-dynamic176684
Ref: 115176684
Ref: userman/categories dynamic-categories176684
Ref: 116176684
Node: Category documentation177342
Ref: userman/categories categories-documentation177504
Ref: 117177504
Ref: userman/categories category-documentation177504
Ref: 118177504
Node: Loading files into a category177739
Ref: userman/categories categories-include177910
Ref: 119177910
Ref: userman/categories loading-files-into-a-category177910
Ref: 11a177910
Node: Declaring object aliases<2>178159
Ref: userman/categories categories-object-aliases178299
Ref: 11b178299
Ref: userman/categories declaring-object-aliases178299
Ref: 11c178299
Node: Category relationships178631
Ref: userman/categories categories-relationships178775
Ref: 11d178775
Ref: userman/categories category-relationships178775
Ref: 11e178775
Node: Category properties180434
Ref: userman/categories categories-properties180579
Ref: 120180579
Ref: userman/categories category-properties180579
Ref: 121180579
Node: Importing categories186734
Ref: userman/categories categories-importing186884
Ref: 123186884
Ref: userman/categories importing-categories186884
Ref: 124186884
Node: Calling category predicates187708
Ref: userman/categories calling-category-predicates187860
Ref: 125187860
Ref: userman/categories categories-predicates187860
Ref: 126187860
Node: Parametric categories189650
Ref: userman/categories categories-parametric189801
Ref: 127189801
Ref: userman/categories parametric-categories189801
Ref: 128189801
Node: Built-in categories190755
Ref: userman/categories built-in-categories190870
Ref: 129190870
Ref: userman/categories categories-built-in190870
Ref: 12a190870
Node: The built-in category core_messages191058
Ref: userman/categories categories-core-messages191168
Ref: 12b191168
Ref: userman/categories the-built-in-category-core-messages191168
Ref: 12c191168
Ref: The built-in category core_messages-Footnote-1191490
Node: Predicates191546
Ref: userman/predicates doc191662
Ref: 12d191662
Ref: userman/predicates predicates191662
Ref: 12e191662
Ref: userman/predicates predicates-predicates191662
Ref: 12f191662
Node: Reserved predicate names192456
Ref: userman/predicates predicates-reserved192575
Ref: 130192575
Ref: userman/predicates reserved-predicate-names192575
Ref: 131192575
Ref: Reserved predicate names-Footnote-1193243
Ref: Reserved predicate names-Footnote-2193291
Ref: Reserved predicate names-Footnote-3193341
Node: Declaring predicates193391
Ref: userman/predicates declaring-predicates193538
Ref: 132193538
Ref: userman/predicates predicates-declaring193538
Ref: 133193538
Node: Scope directives194649
Ref: userman/predicates predicates-scope194764
Ref: 134194764
Ref: userman/predicates scope-directives194764
Ref: 135194764
Node: Mode directive197835
Ref: userman/predicates mode-directive197983
Ref: 13b197983
Ref: userman/predicates predicates-mode197983
Ref: 13c197983
Node: Meta-predicate directive201494
Ref: userman/predicates meta-predicate-directive201649
Ref: 13e201649
Ref: userman/predicates predicates-meta201649
Ref: 60201649
Node: Discontiguous directive203892
Ref: userman/predicates discontiguous-directive204050
Ref: 144204050
Ref: userman/predicates predicates-discontiguous204050
Ref: 145204050
Node: Dynamic directive204713
Ref: userman/predicates dynamic-directive204865
Ref: 147204865
Ref: userman/predicates predicates-dynamic204865
Ref: 148204865
Node: Operator directive205860
Ref: userman/predicates operator-directive206003
Ref: 14a206003
Ref: userman/predicates predicates-op206003
Ref: 14b206003
Node: Uses directive207555
Ref: userman/predicates predicates-uses207696
Ref: 14e207696
Ref: userman/predicates uses-directive207696
Ref: 14f207696
Node: Alias directive210478
Ref: userman/predicates alias-directive210622
Ref: 151210622
Ref: userman/predicates predicates-alias210622
Ref: 152210622
Node: Documenting directive214783
Ref: userman/predicates documenting-directive214932
Ref: 154214932
Ref: userman/predicates predicates-info214932
Ref: 155214932
Node: Multifile directive215253
Ref: userman/predicates multifile-directive215408
Ref: 157215408
Ref: userman/predicates predicates-multifile215408
Ref: 158215408
Node: Coinductive directive219381
Ref: userman/predicates coinductive-directive219537
Ref: 15b219537
Ref: userman/predicates predicates-coinductive219537
Ref: 15c219537
Node: Synchronized directive220030
Ref: userman/predicates predicates-synchronized220158
Ref: 15f220158
Ref: userman/predicates synchronized-directive220158
Ref: 160220158
Node: Defining predicates220488
Ref: userman/predicates defining-predicates220640
Ref: 162220640
Ref: userman/predicates predicates-defining220640
Ref: 163220640
Node: Object predicates220827
Ref: userman/predicates object-predicates220947
Ref: 164220947
Ref: userman/predicates predicates-objects220947
Ref: 165220947
Node: Category predicates222112
Ref: userman/predicates category-predicates222256
Ref: 166222256
Ref: userman/predicates predicates-categories222256
Ref: 167222256
Node: Meta-predicates223749
Ref: userman/predicates meta-predicates223894
Ref: 16a223894
Ref: userman/predicates predicates-metadef223894
Ref: 16b223894
Node: Lambda expressions226280
Ref: userman/predicates lambda-expressions226436
Ref: 16f226436
Ref: userman/predicates predicates-lambdas226436
Ref: 170226436
Ref: Lambda expressions-Footnote-1230982
Node: Redefining built-in predicates231036
Ref: userman/predicates predicates-redefining231168
Ref: 173231168
Ref: userman/predicates redefining-built-in-predicates231168
Ref: 174231168
Node: Definite clause grammar rules233465
Ref: userman/predicates definite-clause-grammar-rules233613
Ref: 178233613
Ref: userman/predicates predicates-dcgs233613
Ref: 179233613
Node: Built-in methods239619
Ref: userman/predicates built-in-methods239768
Ref: 17d239768
Ref: userman/predicates predicates-methods239768
Ref: 17e239768
Node: Execution context methods240492
Ref: userman/predicates execution-context-methods240633
Ref: 17f240633
Ref: userman/predicates predicates-context240633
Ref: 180240633
Node: Error handling and throwing methods245079
Ref: userman/predicates error-handling-and-throwing-methods245245
Ref: 183245245
Ref: userman/predicates predicates-errors245245
Ref: 184245245
Node: Database methods245858
Ref: userman/predicates database-methods246016
Ref: 192246016
Ref: userman/predicates predicates-database246016
Ref: 193246016
Node: Meta-call methods247183
Ref: userman/predicates meta-call-methods247327
Ref: 19c247327
Ref: userman/predicates predicates-metacalls247327
Ref: 19d247327
Node: All solutions methods247781
Ref: userman/predicates all-solutions-methods247927
Ref: 1a0247927
Ref: userman/predicates predicates-solutions247927
Ref: 1a1247927
Node: Reflection methods248298
Ref: userman/predicates predicates-reflection248484
Ref: 1a7248484
Ref: userman/predicates reflection-methods248484
Ref: 1a8248484
Node: Definite clause grammar parsing methods and non-terminals249715
Ref: userman/predicates definite-clause-grammar-parsing-methods-and-non-terminals249871
Ref: 1a9249871
Ref: userman/predicates predicates-parsing249871
Ref: 1aa249871
Node: Predicate properties250674
Ref: userman/predicates predicate-properties250821
Ref: 1ae250821
Ref: userman/predicates predicates-properties250821
Ref: 1af250821
Node: Finding declared predicates256240
Ref: userman/predicates finding-declared-predicates256396
Ref: 1b0256396
Ref: userman/predicates predicates-finding256396
Ref: 1b1256396
Node: Calling Prolog predicates257287
Ref: userman/predicates calling-prolog-predicates257459
Ref: 1b2257459
Ref: userman/predicates predicates-prolog257459
Ref: 3c257459
Node: Calling Prolog built-in predicates258500
Ref: userman/predicates calling-prolog-built-in-predicates258676
Ref: 1b3258676
Node: Calling Prolog non-standard built-in meta-predicates260636
Ref: userman/predicates calling-prolog-non-standard-built-in-meta-predicates260865
Ref: 1b5260865
Ref: userman/predicates predicates-prolog-meta260865
Ref: 1b6260865
Node: Calling Prolog user-defined plain predicates262105
Ref: userman/predicates calling-prolog-user-defined-plain-predicates262332
Ref: 1b7262332
Ref: userman/predicates predicates-prolog-user262332
Ref: 1b8262332
Node: Calling Prolog module predicates263423
Ref: userman/predicates calling-prolog-module-predicates263635
Ref: 1b9263635
Ref: userman/predicates predicates-prolog-module263635
Ref: 1ba263635
Node: Calling Prolog module meta-predicates266602
Ref: userman/predicates calling-prolog-module-meta-predicates266761
Ref: 1bc266761
Node: Defining Prolog multifile predicates269418
Ref: userman/predicates defining-prolog-multifile-predicates269605
Ref: 1bd269605
Ref: userman/predicates predicates-prolog-multifile269605
Ref: 1be269605
Node: Asserting and retracting Prolog predicates270786
Ref: userman/predicates asserting-and-retracting-prolog-predicates270939
Ref: 1bf270939
Ref: userman/predicates predicates-prolog-dynamic270939
Ref: 1c0270939
Node: Inheritance272783
Ref: userman/inheritance doc272913
Ref: 1c1272913
Ref: userman/inheritance inheritance272913
Ref: 1c2272913
Ref: userman/inheritance inheritance-inheritance272913
Ref: 75272913
Node: Protocol inheritance274701
Ref: userman/inheritance inheritance-protocol274823
Ref: 1c3274823
Ref: userman/inheritance protocol-inheritance274823
Ref: 1c4274823
Node: Search order for prototype hierarchies275300
Ref: userman/inheritance inheritance-protocol-prototype275457
Ref: 1c6275457
Ref: userman/inheritance search-order-for-prototype-hierarchies275457
Ref: 1c7275457
Node: Search order for class hierarchies275990
Ref: userman/inheritance inheritance-protocol-class276147
Ref: 1c8276147
Ref: userman/inheritance search-order-for-class-hierarchies276147
Ref: 1c9276147
Node: Implementation inheritance276754
Ref: userman/inheritance implementation-inheritance276925
Ref: 1ca276925
Ref: userman/inheritance inheritance-implementation276925
Ref: 1cb276925
Node: Search order for prototype hierarchies<2>277648
Ref: userman/inheritance id1277817
Ref: 1cc277817
Ref: userman/inheritance inheritance-implementation-prototype277817
Ref: 1cd277817
Node: Search order for class hierarchies<2>278103
Ref: userman/inheritance id2278323
Ref: 1ce278323
Ref: userman/inheritance inheritance-implementation-class278323
Ref: 1cf278323
Node: Redefining inherited predicate definitions278800
Ref: userman/inheritance inheritance-implementation-redefinition279023
Ref: 1d0279023
Ref: userman/inheritance redefining-inherited-predicate-definitions279023
Ref: 1d1279023
Node: Specializing inherited predicate definitions280048
Ref: userman/inheritance inheritance-specialization280284
Ref: 1d2280284
Ref: userman/inheritance specializing-inherited-predicate-definitions280284
Ref: 1d3280284
Node: Union of inherited and local predicate definitions281098
Ref: userman/inheritance inheritance-union281338
Ref: 1d4281338
Ref: userman/inheritance union-of-inherited-and-local-predicate-definitions281338
Ref: 1d5281338
Node: Selective inheritance of predicate definitions282237
Ref: userman/inheritance inheritance-selective282424
Ref: 1d6282424
Ref: userman/inheritance selective-inheritance-of-predicate-definitions282424
Ref: 1d7282424
Node: Public protected and private inheritance283257
Ref: userman/inheritance inheritance-scope283428
Ref: 9a283428
Ref: userman/inheritance public-protected-and-private-inheritance283428
Ref: 1d8283428
Node: Multiple inheritance284726
Ref: userman/inheritance inheritance-multiple284910
Ref: 1d9284910
Ref: userman/inheritance multiple-inheritance284910
Ref: 1da284910
Node: Composition versus multiple inheritance285783
Ref: userman/inheritance composition-versus-multiple-inheritance285918
Ref: 1db285918
Ref: userman/inheritance inheritance-composition285918
Ref: 1dc285918
Node: Event-driven programming287634
Ref: userman/events doc287781
Ref: 1e1287781
Ref: userman/events event-driven-programming287781
Ref: 1e2287781
Ref: userman/events events-events287781
Ref: 68287781
Node: Definitions289591
Ref: userman/events definitions289707
Ref: 1e5289707
Ref: userman/events events-definitions289707
Ref: 1e6289707
Node: Event289934
Ref: userman/events event290022
Ref: 1e7290022
Ref: userman/events events-event290022
Ref: 1e8290022
Node: Monitor291884
Ref: userman/events events-monitor291972
Ref: 1e9291972
Ref: userman/events monitor291972
Ref: 1ea291972
Ref: Monitor-Footnote-1293479
Node: Event generation293529
Ref: userman/events event-generation293686
Ref: 1eb293686
Ref: userman/events events-generation293686
Ref: 1ec293686
Node: Communicating events to monitors294330
Ref: userman/events communicating-events-to-monitors294496
Ref: 1ed294496
Ref: userman/events events-communicating294496
Ref: 1ee294496
Ref: Communicating events to monitors-Footnote-1295020
Node: Performance concerns295070
Ref: userman/events events-performance295237
Ref: 1ef295237
Ref: userman/events performance-concerns295237
Ref: 1f0295237
Node: Monitor semantics296141
Ref: userman/events events-semantics296304
Ref: 1f1296304
Ref: userman/events monitor-semantics296304
Ref: 1f2296304
Node: Activation order of monitors297191
Ref: userman/events activation-order-of-monitors297348
Ref: 1f3297348
Ref: userman/events events-order297348
Ref: 1f4297348
Node: Event handling298516
Ref: userman/events event-handling298647
Ref: 1f5298647
Ref: userman/events events-handling298647
Ref: 1f6298647
Node: Defining new events299114
Ref: userman/events defining-new-events299237
Ref: 1f7299237
Ref: userman/events events-defining299237
Ref: 1f8299237
Node: Abolishing defined events299639
Ref: userman/events abolishing-defined-events299793
Ref: 1fa299793
Ref: userman/events events-abolishing299793
Ref: 1fb299793
Node: Finding defined events300117
Ref: userman/events events-finding300275
Ref: 1fd300275
Ref: userman/events finding-defined-events300275
Ref: 1fe300275
Node: Defining event handlers300665
Ref: userman/events defining-event-handlers300789
Ref: 200300789
Ref: userman/events events-handlers300789
Ref: 201300789
Ref: Defining event handlers-Footnote-1303466
Ref: Defining event handlers-Footnote-2303516
Node: Multi-threading programming303566
Ref: userman/threads doc303716
Ref: 202303716
Ref: userman/threads multi-threading-programming303716
Ref: 203303716
Ref: userman/threads threads-threads303716
Ref: 6e303716
Node: Enabling multi-threading support304896
Ref: userman/threads enabling-multi-threading-support305066
Ref: 204305066
Ref: userman/threads threads-enabling305066
Ref: 205305066
Node: Enabling objects to make multi-threading calls305349
Ref: userman/threads enabling-objects-to-make-multi-threading-calls305563
Ref: 207305563
Ref: userman/threads threads-directive305563
Ref: 208305563
Node: Multi-threading built-in predicates305795
Ref: userman/threads multi-threading-built-in-predicates306003
Ref: 20a306003
Ref: userman/threads threads-predicates306003
Ref: 20b306003
Node: Proving goals concurrently using threads306767
Ref: userman/threads proving-goals-concurrently-using-threads306949
Ref: 20d306949
Ref: userman/threads threads-threaded306949
Ref: 20e306949
Node: Proving goals asynchronously using threads309306
Ref: userman/threads proving-goals-asynchronously-using-threads309488
Ref: 20f309488
Ref: userman/threads threads-call309488
Ref: 210309488
Node: One-way asynchronous calls313971
Ref: userman/threads one-way-asynchronous-calls314179
Ref: 216314179
Ref: userman/threads threads-ignore314179
Ref: 217314179
Node: Asynchronous calls and synchronized predicates314854
Ref: userman/threads asynchronous-calls-and-synchronized-predicates315070
Ref: 219315070
Ref: userman/threads threads-synchronized-predicates315070
Ref: 161315070
Node: Synchronizing threads through notifications318468
Ref: userman/threads synchronizing-threads-through-notifications318674
Ref: 21a318674
Ref: userman/threads threads-notifications318674
Ref: 21b318674
Node: Threaded engines320091
Ref: userman/threads threaded-engines320278
Ref: 21e320278
Ref: userman/threads threads-engines320278
Ref: 21f320278
Node: Multi-threading performance324155
Ref: userman/threads multi-threading-performance324290
Ref: 227324290
Ref: userman/threads threads-performance324290
Ref: 228324290
Node: Error handling325354
Ref: userman/errors doc325490
Ref: 229325490
Ref: userman/errors error-handling325490
Ref: 22a325490
Ref: userman/errors errors-errors325490
Ref: 22b325490
Ref: Error handling-Footnote-1326711
Node: Raising Exceptions326775
Ref: userman/errors raising-exceptions326885
Ref: 22c326885
Node: Type-checking327443
Ref: userman/errors type-checking327576
Ref: 22e327576
Ref: Type-checking-Footnote-1330216
Ref: Type-checking-Footnote-2330254
Ref: Type-checking-Footnote-3330300
Ref: Type-checking-Footnote-4330346
Node: Expected terms330392
Ref: userman/errors expected-terms330535
Ref: 22f330535
Node: Compiler warnings and errors330831
Ref: userman/errors compiler-warnings-and-errors330975
Ref: 231330975
Node: Unknown entities332414
Ref: userman/errors errors-unknown332542
Ref: 233332542
Ref: userman/errors unknown-entities332542
Ref: 234332542
Node: Singleton variables332926
Ref: userman/errors errors-singletons333105
Ref: 235333105
Ref: userman/errors singleton-variables333105
Ref: 236333105
Node: Redefinition of Prolog built-in predicates333535
Ref: userman/errors errors-prolog333741
Ref: 237333741
Ref: userman/errors redefinition-of-prolog-built-in-predicates333741
Ref: 238333741
Node: Redefinition of Logtalk built-in predicates334271
Ref: userman/errors errors-redefinition-predicates334498
Ref: 239334498
Ref: userman/errors redefinition-of-logtalk-built-in-predicates334498
Ref: 23a334498
Node: Redefinition of Logtalk built-in methods334817
Ref: userman/errors errors-redefinition-methods335036
Ref: 23b335036
Ref: userman/errors redefinition-of-logtalk-built-in-methods335036
Ref: 23c335036
Node: Misspell calls of local predicates335328
Ref: userman/errors errors-misspell335524
Ref: 23d335524
Ref: userman/errors misspell-calls-of-local-predicates335524
Ref: 23e335524
Node: Portability warnings335865
Ref: userman/errors errors-portability336040
Ref: 23f336040
Ref: userman/errors portability-warnings336040
Ref: 240336040
Node: Deprecated elements336399
Ref: userman/errors deprecated-elements336558
Ref: 241336558
Ref: userman/errors errors-deprecated336558
Ref: 242336558
Node: Missing directives336852
Ref: userman/errors errors-missing-directives337012
Ref: 243337012
Ref: userman/errors missing-directives337012
Ref: 244337012
Node: Duplicated directives337185
Ref: userman/errors duplicated-directives337344
Ref: 245337344
Ref: userman/errors errors-duplicated-directives337344
Ref: 246337344
Node: Duplicated clauses337666
Ref: userman/errors duplicated-clauses337842
Ref: 247337842
Ref: userman/errors errors-duplicated-clauses337842
Ref: 248337842
Node: Goals that are always true or false338046
Ref: userman/errors errors-always-true-or-false-goals338214
Ref: 249338214
Ref: userman/errors goals-that-are-always-true-or-false338214
Ref: 24a338214
Node: Trivial fails338483
Ref: userman/errors errors-trivial-fails338649
Ref: 24b338649
Ref: userman/errors trivial-fails338649
Ref: 24c338649
Node: Suspicious calls338792
Ref: userman/errors errors-suspicious-calls338939
Ref: 24d338939
Ref: userman/errors suspicious-calls338939
Ref: 24e338939
Node: Lambda variables339284
Ref: userman/errors errors-lambda-variables339490
Ref: 24f339490
Ref: userman/errors lambda-variables339490
Ref: 250339490
Node: Redefinition of predicates declared in uses/2 or use_module/2 directives339868
Ref: userman/errors errors-predicate-redefinition340083
Ref: 253340083
Ref: userman/errors redefinition-of-predicates-declared-in-uses-2-or-use-module-2-directives340083
Ref: 254340083
Node: Other warnings and errors340425
Ref: userman/errors errors-others340615
Ref: 255340615
Ref: userman/errors other-warnings-and-errors340615
Ref: 256340615
Node: Runtime errors340871
Ref: userman/errors errors-runtime340992
Ref: 257340992
Ref: userman/errors runtime-errors340992
Ref: 258340992
Node: Logtalk built-in predicates341368
Ref: userman/errors errors-predicates341498
Ref: 259341498
Ref: userman/errors logtalk-built-in-predicates341498
Ref: 25a341498
Node: Logtalk built-in methods341699
Ref: userman/errors errors-methods341853
Ref: 25b341853
Ref: userman/errors logtalk-built-in-methods341853
Ref: 25c341853
Node: Message sending342044
Ref: userman/errors errors-sending342162
Ref: 25d342162
Ref: userman/errors message-sending342162
Ref: 25e342162
Ref: Message sending-Footnote-1343078
Node: Reflection343128
Ref: userman/reflection doc343269
Ref: 25f343269
Ref: userman/reflection reflection343269
Ref: 260343269
Ref: userman/reflection reflection-reflection343269
Ref: 46343269
Node: Structural reflection343729
Ref: userman/reflection reflection-structural343846
Ref: 262343846
Ref: userman/reflection structural-reflection343846
Ref: 263343846
Node: Transparent-box view344194
Ref: userman/reflection transparent-box-view344314
Ref: 264344314
Ref: Transparent-box view-Footnote-1345543
Node: Black-box view345587
Ref: userman/reflection black-box-view345707
Ref: 267345707
Node: Behavioral reflection346427
Ref: userman/reflection behavioral-reflection346544
Ref: 268346544
Ref: userman/reflection reflection-behavioral346544
Ref: 269346544
Ref: Behavioral reflection-Footnote-1347157
Node: Writing and running applications347201
Ref: userman/programming doc347366
Ref: 26b347366
Ref: userman/programming programming-programming347366
Ref: 26c347366
Ref: userman/programming writing-and-running-applications347366
Ref: 26d347366
Node: Starting Logtalk349003
Ref: userman/programming programming-starting349150
Ref: 26f349150
Ref: userman/programming starting-logtalk349150
Ref: 270349150
Node: Running parallel Logtalk processes350015
Ref: userman/programming programming-parallel-processes350183
Ref: 271350183
Ref: userman/programming running-parallel-logtalk-processes350183
Ref: 272350183
Node: Source files352241
Ref: userman/programming programming-source-files352412
Ref: 275352412
Ref: userman/programming source-files352412
Ref: 276352412
Node: Naming conventions354313
Ref: userman/programming naming-conventions354433
Ref: 277354433
Node: Source file text encoding355025
Ref: userman/programming source-file-text-encoding355145
Ref: 278355145
Node: Multi-pass compiler355492
Ref: userman/programming multi-pass-compiler355668
Ref: 27b355668
Ref: userman/programming programming-multi-pass-compiler355668
Ref: 27c355668
Node: Compiling and loading your applications357950
Ref: userman/programming compiling-and-loading-your-applications358126
Ref: 27d358126
Ref: userman/programming programming-compiling358126
Ref: 27e358126
Node: Loader files361125
Ref: userman/programming loader-files361307
Ref: 282361307
Ref: userman/programming programming-loaders361307
Ref: 283361307
Node: Libraries of source files364938
Ref: userman/programming libraries-of-source-files365095
Ref: 285365095
Ref: userman/programming programming-libraries365095
Ref: 286365095
Node: Settings files367966
Ref: userman/programming programming-settings368126
Ref: 289368126
Ref: userman/programming settings-files368126
Ref: 28a368126
Node: Compiler linter370741
Ref: userman/programming compiler-linter370890
Ref: 28d370890
Ref: userman/programming programming-linter370890
Ref: 28e370890
Node: Compiler flags371662
Ref: userman/programming compiler-flags371819
Ref: 291371819
Ref: userman/programming programming-flags371819
Ref: 232371819
Node: Read-only flags374418
Ref: userman/programming read-only-flags374525
Ref: 294374525
Ref: userman/programming flag-settings-file374733
Ref: 28b374733
Ref: userman/programming flag-prolog-dialect375405
Ref: 28c375405
Ref: userman/programming flag-prolog-version375603
Ref: 295375603
Ref: userman/programming flag-prolog-compatible-version375945
Ref: 296375945
Ref: userman/programming flag-unicode376343
Ref: 297376343
Ref: userman/programming flag-encoding-directive376616
Ref: 27a376616
Ref: userman/programming flag-tabling377048
Ref: 298377048
Ref: userman/programming flag-engines377240
Ref: 299377240
Ref: userman/programming flag-threads377500
Ref: 206377500
Ref: userman/programming flag-modules377782
Ref: 29b377782
Ref: userman/programming flag-coinduction378078
Ref: 15e378078
Node: Version flags378359
Ref: userman/programming version-flags378485
Ref: 29d378485
Ref: userman/programming flag-version-data378534
Ref: 29e378534
Node: Lint flags379051
Ref: userman/programming lint-flags379197
Ref: 29f379197
Ref: userman/programming programming-flags-lint379197
Ref: 290379197
Ref: userman/programming flag-unknown-entities379240
Ref: 2a0379240
Ref: userman/programming flag-unknown-predicates379632
Ref: 2a1379632
Ref: userman/programming flag-undefined-predicates379986
Ref: 2a2379986
Ref: userman/programming flag-steadfastness380344
Ref: 2a3380344
Ref: userman/programming flag-portability380676
Ref: 1b4380676
Ref: userman/programming flag-deprecated380996
Ref: 2a5380996
Ref: userman/programming flag-missing-directives381157
Ref: 2a6381157
Ref: userman/programming flag-duplicated-directives381356
Ref: 2a7381356
Ref: userman/programming flag-trivial-goal-fails381689
Ref: 2a8381689
Ref: userman/programming flag-always-true-or-false-goals381943
Ref: 2a9381943
Ref: userman/programming flag-lambda-variables382174
Ref: 172382174
Ref: userman/programming flag-suspicious-calls382378
Ref: 2aa382378
Ref: userman/programming flag-redefined-built-ins382575
Ref: 175382575
Ref: userman/programming flag-redefined-operators382994
Ref: 2ab382994
Ref: userman/programming flag-singleton-variables383361
Ref: 2ac383361
Ref: userman/programming flag-underscore-variables383547
Ref: 2ad383547
Ref: userman/programming flag-naming384112
Ref: 2ae384112
Ref: userman/programming flag-duplicated-clauses384588
Ref: 2af384588
Ref: userman/programming flag-disjunctions385020
Ref: 2b0385020
Ref: userman/programming flag-tail-recursive385205
Ref: 2b1385205
Node: Optional features compilation flags385655
Ref: userman/programming optional-features-compilation-flags385828
Ref: 2b2385828
Ref: userman/programming flag-complements385921
Ref: 10a385921
Ref: userman/programming flag-dynamic-declarations386608
Ref: 2b3386608
Ref: userman/programming flag-events387213
Ref: 85387213
Ref: userman/programming flag-context-switching-calls387771
Ref: 2b4387771
Node: Backend Prolog compiler and loader flags388097
Ref: userman/programming backend-prolog-compiler-and-loader-flags388271
Ref: 2b5388271
Ref: userman/programming flag-prolog-compiler388374
Ref: 2b6388374
Ref: userman/programming flag-prolog-loader388875
Ref: 2b7388875
Node: Other flags389220
Ref: userman/programming other-flags389377
Ref: 2b8389377
Ref: userman/programming flag-scratch-directory389422
Ref: 2b9389422
Ref: userman/programming flag-report390306
Ref: 2ba390306
Ref: userman/programming flag-code-prefix390684
Ref: 2bb390684
Ref: userman/programming flag-optimize391549
Ref: 88391549
Ref: userman/programming flag-source-data392498
Ref: c6392498
Ref: userman/programming flag-debug393146
Ref: 2bc393146
Ref: userman/programming flag-reload393569
Ref: 2bd393569
Ref: userman/programming flag-relative-to394125
Ref: 2be394125
Ref: userman/programming flag-hook394308
Ref: f7394308
Ref: userman/programming flag-clean394731
Ref: 273394731
Ref: Other flags-Footnote-1395762
Ref: Other flags-Footnote-2395800
Node: User-defined flags395848
Ref: userman/programming user-defined-flags395956
Ref: 2bf395956
Node: Reloading source files396120
Ref: userman/programming programming-reloading396278
Ref: 2c1396278
Ref: userman/programming reloading-source-files396278
Ref: 2c2396278
Node: Batch processing398762
Ref: userman/programming batch-processing398928
Ref: 2c3398928
Ref: userman/programming programming-batch398928
Ref: 2c4398928
Node: Optimizing performance399315
Ref: userman/programming optimizing-performance399480
Ref: 2c5399480
Ref: userman/programming programming-performance399480
Ref: 2c6399480
Node: Portable applications401525
Ref: userman/programming portable-applications401697
Ref: 2c8401697
Ref: userman/programming programming-portability401697
Ref: 2c9401697
Node: Conditional compilation402637
Ref: userman/programming conditional-compilation402809
Ref: 2ca402809
Ref: userman/programming programming-cc402809
Ref: 2cb402809
Node: Avoiding common errors403180
Ref: userman/programming avoiding-common-errors403354
Ref: 2d0403354
Ref: userman/programming programming-errors403354
Ref: 2d1403354
Node: Coding style guidelines405068
Ref: userman/programming coding-style-guidelines405210
Ref: 2d2405210
Ref: userman/programming programming-style405210
Ref: 2d3405210
Node: Printing messages and asking questions406004
Ref: userman/printing doc406182
Ref: 2d4406182
Ref: userman/printing printing-messages-and-asking-questions406182
Ref: 2d5406182
Ref: userman/printing printing-printing406182
Ref: 177406182
Ref: Printing messages and asking questions-Footnote-1409327
Node: Printing messages409371
Ref: userman/printing id1409511
Ref: 2d7409511
Ref: userman/printing printing-messages409511
Ref: cd409511
Node: Message tokenization413168
Ref: userman/printing message-tokenization413330
Ref: 2da413330
Node: Meta-messages415455
Ref: userman/printing meta-messages415621
Ref: 2dc415621
Ref: Meta-messages-Footnote-1416047
Node: Intercepting messages416091
Ref: userman/printing intercepting-messages416253
Ref: 2de416253
Node: Asking questions418105
Ref: userman/printing asking-questions418276
Ref: 2e1418276
Ref: userman/printing printing-questions418276
Ref: ce418276
Node: Intercepting questions421137
Ref: userman/printing intercepting-questions421278
Ref: 2e3421278
Node: Term and goal expansion422803
Ref: userman/expansion doc422960
Ref: 2e5422960
Ref: userman/expansion expansion-expansion422960
Ref: c5422960
Ref: userman/expansion term-and-goal-expansion422960
Ref: 2e6422960
Node: Defining expansions424353
Ref: userman/expansion defining-expansions424483
Ref: 2e7424483
Ref: Defining expansions-Footnote-1427399
Node: Expanding grammar rules427447
Ref: userman/expansion expanding-grammar-rules427606
Ref: 2ea427606
Node: Bypassing expansions428207
Ref: userman/expansion bypassing-expansions428359
Ref: 2eb428359
Node: Hook objects428769
Ref: userman/expansion hook-objects428943
Ref: 2ec428943
Ref: Hook objects-Footnote-1430564
Node: Virtual source file terms and loading context430612
Ref: userman/expansion virtual-source-file-terms-and-loading-context430801
Ref: 2ed430801
Node: Default compiler expansion workflow432738
Ref: userman/expansion default-compiler-expansion-workflow432947
Ref: 2ef432947
Node: User defined expansion workflows433693
Ref: userman/expansion user-defined-expansion-workflows433888
Ref: 2f0433888
Ref: User defined expansion workflows-Footnote-1435608
Ref: User defined expansion workflows-Footnote-2435664
Ref: User defined expansion workflows-Footnote-3435710
Ref: User defined expansion workflows-Footnote-4435780
Node: Using Prolog defined expansions435836
Ref: userman/expansion using-prolog-defined-expansions436016
Ref: 2f3436016
Ref: Using Prolog defined expansions-Footnote-1437764
Node: Debugging expansions437830
Ref: userman/expansion debugging-expansions437969
Ref: 2f4437969
Node: Documenting440228
Ref: userman/documenting doc440356
Ref: 2f7440356
Ref: userman/documenting documenting440356
Ref: 2f8440356
Ref: userman/documenting documenting-documenting440356
Ref: af440356
Node: Documenting directives441464
Ref: userman/documenting documenting-directives441602
Ref: 2fa441602
Ref: userman/documenting id1441602
Ref: 2fb441602
Node: Entity directives442028
Ref: userman/documenting documenting-entity442152
Ref: 2fc442152
Ref: userman/documenting entity-directives442152
Ref: 2fd442152
Ref: Entity directives-Footnote-1444907
Node: Predicate directives444934
Ref: userman/documenting documenting-predicate445058
Ref: 2fe445058
Ref: userman/documenting predicate-directives445058
Ref: 2ff445058
Node: Processing and viewing documenting files448075
Ref: userman/documenting documenting-processing448256
Ref: 300448256
Ref: userman/documenting processing-and-viewing-documenting-files448256
Ref: 301448256
Node: Inline formatting in comments text452133
Ref: userman/documenting documenting-formatting452300
Ref: 303452300
Ref: userman/documenting inline-formatting-in-comments-text452300
Ref: 304452300
Node: Diagrams453040
Ref: userman/documenting diagrams453158
Ref: 305453158
Node: Debugging453791
Ref: userman/debugging doc453910
Ref: 306453910
Ref: userman/debugging debugging453910
Ref: 307453910
Ref: userman/debugging debugging-debugging453910
Ref: 45453910
Node: Compiling source files in debug mode455532
Ref: userman/debugging compiling-source-files-in-debug-mode455661
Ref: 309455661
Ref: userman/debugging debugging-debug-mode455661
Ref: 30a455661
Node: Procedure box model457325
Ref: userman/debugging debugging-box-model457482
Ref: 30b457482
Ref: userman/debugging procedure-box-model457482
Ref: 30c457482
Node: Defining spy points459352
Ref: userman/debugging defining-spy-points459498
Ref: 30d459498
Node: Defining line number and predicate spy points460285
Ref: userman/debugging defining-line-number-and-predicate-spy-points460441
Ref: 30e460441
Node: Defining context spy points461344
Ref: userman/debugging defining-context-spy-points461532
Ref: 30f461532
Node: Removing all spy points462690
Ref: userman/debugging removing-all-spy-points462824
Ref: 310462824
Node: Tracing program execution463165
Ref: userman/debugging programming-trace463318
Ref: 311463318
Ref: userman/debugging tracing-program-execution463318
Ref: 312463318
Node: Debugging using spy points465336
Ref: userman/debugging debugging-debug465488
Ref: 313465488
Ref: userman/debugging debugging-using-spy-points465488
Ref: 314465488
Node: Debugging commands466140
Ref: userman/debugging debugging-commands466290
Ref: 315466290
Ref: userman/debugging id1466290
Ref: 316466290
Node: Context-switching calls469200
Ref: userman/debugging context-switching-calls469342
Ref: 317469342
Ref: userman/debugging debugging-context469342
Ref: 318469342
Node: Debugging messages471281
Ref: userman/debugging debugging-messages471453
Ref: 2dd471453
Ref: userman/debugging id2471453
Ref: 319471453
Node: Meta-messages<2>472032
Ref: userman/debugging meta-messages472167
Ref: 31a472167
Node: Selective printing of debug messages474532
Ref: userman/debugging selective-printing-of-debug-messages474667
Ref: 31b474667
Node: Using the term-expansion mechanism for debugging475744
Ref: userman/debugging debugging-hooks475908
Ref: 31e475908
Ref: userman/debugging using-the-term-expansion-mechanism-for-debugging475908
Ref: 31f475908
Ref: Using the term-expansion mechanism for debugging-Footnote-1476647
Node: Ports profiling476707
Ref: userman/debugging debugging-ports-profiling476875
Ref: 320476875
Ref: userman/debugging ports-profiling476875
Ref: 321476875
Node: Debug and trace events477216
Ref: userman/debugging debug-and-trace-events477327
Ref: 323477327
Ref: userman/debugging debugging-events477327
Ref: cf477327
Ref: Debug and trace events-Footnote-1478069
Ref: Debug and trace events-Footnote-2478127
Ref: Debug and trace events-Footnote-3478187
Node: Performance<2>478256
Ref: userman/performance doc478382
Ref: 324478382
Ref: userman/performance performance478382
Ref: 325478382
Ref: userman/performance performance-performance478382
Ref: 36478382
Node: Source code compilation modes479837
Ref: userman/performance source-code-compilation-modes479966
Ref: 326479966
Node: Local predicate calls480694
Ref: userman/performance local-predicate-calls480873
Ref: 327480873
Node: Calls to imported or inherited predicates481080
Ref: userman/performance calls-to-imported-or-inherited-predicates481256
Ref: 328481256
Node: Calls to module predicates481506
Ref: userman/performance calls-to-module-predicates481672
Ref: 329481672
Node: Messages<2>481896
Ref: userman/performance messages482068
Ref: 32a482068
Node: Automatic expansion of built-in meta-predicates483849
Ref: userman/performance automatic-expansion-of-built-in-meta-predicates484003
Ref: 32b484003
Node: Inlining484467
Ref: userman/performance inlining484657
Ref: 32c484657
Node: Generated code simplification and optimizations485190
Ref: userman/performance generated-code-simplification-and-optimizations485359
Ref: 32d485359
Node: Size of the generated code485821
Ref: userman/performance size-of-the-generated-code486001
Ref: 32e486001
Node: Debug mode overhead487168
Ref: userman/performance debug-mode-overhead487321
Ref: 32f487321
Ref: Debug mode overhead-Footnote-1488685
Ref: Debug mode overhead-Footnote-2488743
Node: Other considerations488803
Ref: userman/performance other-considerations488921
Ref: 330488921
Ref: Other considerations-Footnote-1489539
Ref: Other considerations-Footnote-2489617
Ref: Other considerations-Footnote-3489700
Node: Installing Logtalk489745
Ref: userman/installing doc489894
Ref: 331489894
Ref: userman/installing installing-installing489894
Ref: 332489894
Ref: userman/installing installing-logtalk489894
Ref: 333489894
Node: Hardware and software requirements491866
Ref: userman/installing hardware-and-software-requirements492001
Ref: 334492001
Ref: userman/installing installing-requirements492001
Ref: 335492001
Node: Computer and operating system492150
Ref: userman/installing computer-and-operating-system492293
Ref: 336492293
Ref: userman/installing installing-computer492293
Ref: 337492293
Node: Prolog compiler492500
Ref: userman/installing installing-compiler492643
Ref: 338492643
Ref: userman/installing prolog-compiler492643
Ref: 339492643
Node: Logtalk installers493926
Ref: userman/installing installing-installers494089
Ref: 33a494089
Ref: userman/installing logtalk-installers494089
Ref: 33b494089
Node: Source distribution494387
Ref: userman/installing installing-sources494537
Ref: 33c494537
Ref: userman/installing source-distribution494537
Ref: 33d494537
Node: Distribution overview495185
Ref: userman/installing distribution-overview495308
Ref: 33e495308
Ref: userman/installing installing-organization495308
Ref: 33f495308
Node: Adapter files499250
Ref: userman/installing adapter-files499369
Ref: 340499369
Ref: userman/installing installing-adapters499369
Ref: 341499369
Node: Compiler and runtime500861
Ref: userman/installing compiler-and-runtime500996
Ref: 342500996
Ref: userman/installing installing-runtime500996
Ref: 343500996
Node: Library501356
Ref: userman/installing installing-library501486
Ref: 344501486
Ref: userman/installing library501486
Ref: 345501486
Node: Examples501705
Ref: userman/installing examples501835
Ref: 346501835
Ref: userman/installing installing-examples501835
Ref: 347501835
Node: Logtalk source files502343
Ref: userman/installing installing-entities502457
Ref: 348502457
Ref: userman/installing logtalk-source-files502457
Ref: 349502457
Node: Prolog integration and migration503109
Ref: userman/migration doc503235
Ref: 34a503235
Ref: userman/migration migration-migration503235
Ref: 34b503235
Ref: userman/migration prolog-integration-and-migration503235
Ref: 34c503235
Node: Source files with both Prolog code and Logtalk code504623
Ref: userman/migration migration-hybrid504813
Ref: 34d504813
Ref: userman/migration source-files-with-both-prolog-code-and-logtalk-code504813
Ref: 34e504813
Node: Encapsulating plain Prolog code in objects505680
Ref: userman/migration encapsulating-plain-prolog-code-in-objects505917
Ref: 34f505917
Ref: userman/migration migration-encapsulating505917
Ref: 350505917
Node: Prolog multifile predicates507873
Ref: userman/migration migration-multifile507998
Ref: 351507998
Ref: userman/migration prolog-multifile-predicates507998
Ref: 352507998
Node: Converting Prolog modules into objects509686
Ref: userman/migration converting-prolog-modules-into-objects509907
Ref: 354509907
Ref: userman/migration migration-converting509907
Ref: 355509907
Node: Compiling Prolog modules as objects514487
Ref: userman/migration compiling-prolog-modules-as-objects514723
Ref: 356514723
Ref: userman/migration migration-compiling514723
Ref: 357514723
Node: Supported module directives516053
Ref: userman/migration migration-compatibility516209
Ref: 358516209
Ref: userman/migration supported-module-directives516209
Ref: 359516209
Node: Unsupported module directives520127
Ref: userman/migration migration-unsupported-module-directives520332
Ref: 35a520332
Ref: userman/migration unsupported-module-directives520332
Ref: 35b520332
Node: Modules using a term-expansion mechanism521488
Ref: userman/migration migration-module-expansions521657
Ref: 35c521657
Ref: userman/migration modules-using-a-term-expansion-mechanism521657
Ref: 35d521657
Node: Dealing with proprietary Prolog directives and predicates523491
Ref: userman/migration dealing-with-proprietary-prolog-directives-and-predicates523724
Ref: 35f523724
Ref: userman/migration migration-proprietary523724
Ref: 360523724
Node: Calling Prolog module predicates<2>526060
Ref: userman/migration calling-prolog-module-predicates526249
Ref: 361526249
Ref: userman/migration migration-calling526249
Ref: 362526249
Node: Reference Manual529282
Ref: refman/index doc529394
Ref: 363529394
Ref: refman/index reference-manual529394
Ref: 364529394
Node: Grammar529572
Ref: refman/grammar doc529678
Ref: 365529678
Ref: refman/grammar grammar529678
Ref: 366529678
Ref: refman/grammar grammar-grammar529678
Ref: 367529678
Node: Entities530314
Ref: refman/grammar entities530411
Ref: 368530411
Ref: refman/grammar grammar-entities530411
Ref: 369530411
Node: Object definition530522
Ref: refman/grammar grammar-object-definition530647
Ref: 36a530647
Ref: refman/grammar object-definition530647
Ref: 36b530647
Node: Category definition531647
Ref: refman/grammar category-definition531783
Ref: 36c531783
Ref: refman/grammar grammar-category-definition531783
Ref: 36d531783
Node: Protocol definition532402
Ref: refman/grammar grammar-protocol-definition532537
Ref: 36e532537
Ref: refman/grammar protocol-definition532537
Ref: 36f532537
Node: Entity relations532911
Ref: refman/grammar entity-relations533045
Ref: 370533045
Ref: refman/grammar grammar-entity-relations533045
Ref: 371533045
Node: Implemented protocols534111
Ref: refman/grammar grammar-implemented-protocols534231
Ref: 372534231
Ref: refman/grammar implemented-protocols534231
Ref: 373534231
Node: Extended protocols534813
Ref: refman/grammar extended-protocols534961
Ref: 374534961
Ref: refman/grammar grammar-extended-protocols534961
Ref: 375534961
Node: Imported categories535504
Ref: refman/grammar grammar-imported-categories535647
Ref: 376535647
Ref: refman/grammar imported-categories535647
Ref: 377535647
Node: Extended objects536193
Ref: refman/grammar extended-objects536337
Ref: 378536337
Ref: refman/grammar grammar-extended-objects536337
Ref: 379536337
Node: Extended categories536850
Ref: refman/grammar extended-categories536995
Ref: 37a536995
Ref: refman/grammar grammar-extended-categories536995
Ref: 37b536995
Node: Instantiated objects537541
Ref: refman/grammar grammar-instantiated-objects537689
Ref: 37c537689
Ref: refman/grammar instantiated-objects537689
Ref: 37d537689
Node: Specialized objects538254
Ref: refman/grammar grammar-specialized-objects538403
Ref: 37e538403
Ref: refman/grammar specialized-objects538403
Ref: 37f538403
Node: Complemented objects538955
Ref: refman/grammar complemented-objects539110
Ref: 380539110
Ref: refman/grammar grammar-complemented-objects539110
Ref: 381539110
Node: Entity and predicate scope539557
Ref: refman/grammar entity-and-predicate-scope539684
Ref: 382539684
Ref: refman/grammar grammar-scope539684
Ref: 383539684
Node: Entity identifiers539870
Ref: refman/grammar entity-identifiers540002
Ref: 384540002
Ref: refman/grammar grammar-entity-identifiers540002
Ref: 385540002
Node: Object identifiers540657
Ref: refman/grammar grammar-object-identifiers540778
Ref: 386540778
Ref: refman/grammar object-identifiers540778
Ref: 387540778
Node: Category identifiers541278
Ref: refman/grammar category-identifiers541428
Ref: 388541428
Ref: refman/grammar grammar-category-identifiers541428
Ref: 389541428
Node: Protocol identifiers541954
Ref: refman/grammar grammar-protocol-identifiers542104
Ref: 38a542104
Ref: refman/grammar protocol-identifiers542104
Ref: 38b542104
Node: Module identifiers542617
Ref: refman/grammar grammar-module-identifiers542738
Ref: 38c542738
Ref: refman/grammar module-identifiers542738
Ref: 38d542738
Node: Source file names542840
Ref: refman/grammar grammar-source-file-names542961
Ref: 38e542961
Ref: refman/grammar source-file-names542961
Ref: 38f542961
Node: Terms543556
Ref: refman/grammar grammar-terms543669
Ref: 390543669
Ref: refman/grammar terms543669
Ref: 391543669
Node: Object terms543740
Ref: refman/grammar grammar-object-terms543836
Ref: 392543836
Ref: refman/grammar object-terms543836
Ref: 393543836
Node: Category terms544061
Ref: refman/grammar category-terms544157
Ref: 394544157
Ref: refman/grammar grammar-category-terms544157
Ref: 395544157
Node: Directives544398
Ref: refman/grammar directives544511
Ref: 396544511
Ref: refman/grammar grammar-directives544511
Ref: 397544511
Node: Source file directives544808
Ref: refman/grammar grammar-source-file-directives544939
Ref: 398544939
Ref: refman/grammar source-file-directives544939
Ref: 399544939
Node: Conditional compilation directives545409
Ref: refman/grammar conditional-compilation-directives545569
Ref: 39a545569
Ref: refman/grammar grammar-conditional-compilation-directives545569
Ref: 39b545569
Node: Object directives<2>546059
Ref: refman/grammar grammar-object-directives546219
Ref: 39c546219
Ref: refman/grammar object-directives546219
Ref: 39d546219
Node: Category directives<2>546913
Ref: refman/grammar category-directives547061
Ref: 39e547061
Ref: refman/grammar grammar-category-directives547061
Ref: 39f547061
Node: Protocol directives<2>547661
Ref: refman/grammar grammar-protocol-directives547812
Ref: 3a0547812
Ref: refman/grammar protocol-directives547812
Ref: 3a1547812
Node: Predicate directives<2>548345
Ref: refman/grammar grammar-predicate-directives548465
Ref: 3a2548465
Ref: refman/grammar predicate-directives548465
Ref: 3a3548465
Node: Clauses and goals561636
Ref: refman/grammar clauses-and-goals561765
Ref: 3a4561765
Ref: refman/grammar grammar-clauses561765
Ref: 3a5561765
Node: Lambda expressions<2>563186
Ref: refman/grammar grammar-lambdas563322
Ref: 171563322
Ref: refman/grammar lambda-expressions563322
Ref: 3a6563322
Node: Entity properties563875
Ref: refman/grammar entity-properties564017
Ref: 3a7564017
Ref: refman/grammar grammar-entity-properties564017
Ref: c3564017
Node: Predicate properties<2>572428
Ref: refman/grammar grammar-predicate-properties572566
Ref: 3a8572566
Ref: refman/grammar predicate-properties572566
Ref: 3a9572566
Node: Compiler flags<2>574463
Ref: refman/grammar compiler-flags574575
Ref: 3aa574575
Ref: refman/grammar grammar-compiler-flags574575
Ref: 3ab574575
Node: Control constructs574675
Ref: refman/control/index doc574803
Ref: 3ac574803
Ref: refman/control/index control-constructs574803
Ref: 3ad574803
Node: Message sending<2>575073
Ref: refman/control/message_sending doc575192
Ref: 3ae575192
Ref: refman/control/message_sending id1575192
Ref: 3af575192
Ref: refman/control/message_sending message-sending575192
Ref: 3b0575192
Node: /2575271
Ref: refman/control/send_to_object_2 doc575358
Ref: 3b1575358
Ref: refman/control/send_to_object_2 control-send-to-object-2575358
Ref: 7a575358
Ref: refman/control/send_to_object_2 id1575358
Ref: 3b2575358
Node: Description575486
Ref: refman/control/send_to_object_2 description575590
Ref: 3b3575590
Node: Modes and number of proofs577081
Ref: refman/control/send_to_object_2 modes-and-number-of-proofs577200
Ref: 3b7577200
Node: Errors577374
Ref: refman/control/send_to_object_2 errors577493
Ref: 3b8577493
Node: Examples<2>578764
Ref: refman/control/send_to_object_2 examples578848
Ref: 3b9578848
Node: /1579037
Ref: refman/control/send_to_self_1 doc579124
Ref: 3ba579124
Ref: refman/control/send_to_self_1 control-send-to-self-1579124
Ref: 57579124
Ref: refman/control/send_to_self_1 id1579124
Ref: 3bb579124
Node: Description<2>579307
Ref: refman/control/send_to_self_1 description579417
Ref: 3bc579417
Node: Modes and number of proofs<2>580364
Ref: refman/control/send_to_self_1 modes-and-number-of-proofs580492
Ref: 3bd580492
Node: Errors<2>580596
Ref: refman/control/send_to_self_1 errors580721
Ref: 3be580721
Node: Examples<3>581242
Ref: refman/control/send_to_self_1 examples581329
Ref: 3bf581329
Node: Message delegation581539
Ref: refman/control/message_delegation doc581711
Ref: 3c0581711
Ref: refman/control/message_delegation id1581711
Ref: 3c1581711
Ref: refman/control/message_delegation message-delegation581711
Ref: 3c2581711
Node: []/1581781
Ref: refman/control/delegate_message_1 doc581859
Ref: 3c3581859
Ref: refman/control/delegate_message_1 control-delegate-message-1581859
Ref: 7d581859
Ref: refman/control/delegate_message_1 id1581859
Ref: 3c4581859
Node: Description<3>582042
Ref: refman/control/delegate_message_1 description582154
Ref: 3c5582154
Node: Modes and number of proofs<3>583056
Ref: refman/control/delegate_message_1 modes-and-number-of-proofs583186
Ref: 3c6583186
Node: Errors<3>583364
Ref: refman/control/delegate_message_1 errors583491
Ref: 3c7583491
Node: Examples<4>584949
Ref: refman/control/delegate_message_1 examples585038
Ref: 3c8585038
Node: Calling imported and inherited predicates<2>585273
Ref: refman/control/super_calls doc585454
Ref: 3c9585454
Ref: refman/control/super_calls calling-imported-and-inherited-predicates585454
Ref: 3ca585454
Ref: refman/control/super_calls super-calls585454
Ref: 3cb585454
Node: ^^/1585570
Ref: refman/control/call_super_1 doc585674
Ref: 3cc585674
Ref: refman/control/call_super_1 control-call-super-1585674
Ref: 58585674
Ref: refman/control/call_super_1 id1585674
Ref: 3cd585674
Node: Description<4>585857
Ref: refman/control/call_super_1 description585969
Ref: 3ce585969
Node: Modes and number of proofs<4>587939
Ref: refman/control/call_super_1 modes-and-number-of-proofs588069
Ref: 3cf588069
Node: Errors<4>588173
Ref: refman/control/call_super_1 errors588300
Ref: 3d0588300
Node: Examples<5>588831
Ref: refman/control/call_super_1 examples588920
Ref: 3d1588920
Node: Calling external predicates589159
Ref: refman/control/external_calls doc589345
Ref: 3d2589345
Ref: refman/control/external_calls calling-external-predicates589345
Ref: 3d3589345
Ref: refman/control/external_calls external-calls589345
Ref: 3d4589345
Node: {}/1589433
Ref: refman/control/external_call_1 doc589520
Ref: 3d5589520
Ref: refman/control/external_call_1 control-external-call-1589520
Ref: 17c589520
Ref: refman/control/external_call_1 id1589520
Ref: 3d6589520
Node: Description<5>589703
Ref: refman/control/external_call_1 description589815
Ref: 3d7589815
Node: Modes and number of proofs<5>591172
Ref: refman/control/external_call_1 modes-and-number-of-proofs591302
Ref: 3d9591302
Node: Errors<5>591406
Ref: refman/control/external_call_1 errors591533
Ref: 3da591533
Node: Examples<6>591923
Ref: refman/control/external_call_1 examples592012
Ref: 3db592012
Node: Context switching calls592562
Ref: refman/control/context_switching_calls doc592695
Ref: 3dc592695
Ref: refman/control/context_switching_calls context-switching-calls592695
Ref: 3dd592695
Ref: refman/control/context_switching_calls id1592695
Ref: 3de592695
Node: <</2592775
Ref: refman/control/context_switch_2 doc592858
Ref: 3df592858
Ref: refman/control/context_switch_2 control-context-switch-2592858
Ref: c2592858
Ref: refman/control/context_switch_2 id1592858
Ref: 3e0592858
Node: Description<6>593041
Ref: refman/control/context_switch_2 description593153
Ref: 3e1593153
Node: Modes and number of proofs<6>594582
Ref: refman/control/context_switch_2 modes-and-number-of-proofs594712
Ref: 3e2594712
Node: Errors<6>594886
Ref: refman/control/context_switch_2 errors595013
Ref: 3e3595013
Node: Examples<7>596143
Ref: refman/control/context_switch_2 examples596232
Ref: 3e4596232
Node: Directives<2>596401
Ref: refman/directives/index doc596541
Ref: 3e5596541
Ref: refman/directives/index directives596541
Ref: 3e6596541
Node: Source file directives<2>596804
Ref: refman/directives/source_file_directives doc596944
Ref: 3e7596944
Ref: refman/directives/source_file_directives id1596944
Ref: 3e8596944
Ref: refman/directives/source_file_directives source-file-directives596944
Ref: 3e9596944
Node: encoding/1597095
Ref: refman/directives/encoding_1 doc597204
Ref: 3ea597204
Ref: refman/directives/encoding_1 directives-encoding-1597204
Ref: 279597204
Ref: refman/directives/encoding_1 encoding-1597204
Ref: 3eb597204
Node: Description<7>597340
Ref: refman/directives/encoding_1 description597447
Ref: 3ec597447
Ref: Description<7>-Footnote-1598920
Node: Template and modes598997
Ref: refman/directives/encoding_1 template-and-modes599124
Ref: 3ed599124
Node: Examples<8>599201
Ref: refman/directives/encoding_1 examples599305
Ref: 3ee599305
Node: include/1599368
Ref: refman/directives/include_1 doc599502
Ref: 3ef599502
Ref: refman/directives/include_1 directives-include-1599502
Ref: b2599502
Ref: refman/directives/include_1 include-1599502
Ref: 3f0599502
Node: Description<8>599658
Ref: refman/directives/include_1 description599767
Ref: 3f1599767
Node: Template and modes<2>601510
Ref: refman/directives/include_1 template-and-modes601639
Ref: 3f2601639
Node: Examples<9>601727
Ref: refman/directives/include_1 examples601833
Ref: 3f3601833
Node: initialization/1602426
Ref: refman/directives/initialization_1 doc602554
Ref: 3f4602554
Ref: refman/directives/initialization_1 directives-initialization-1602554
Ref: 40602554
Ref: refman/directives/initialization_1 initialization-1602554
Ref: 3f5602554
Node: Description<9>602725
Ref: refman/directives/initialization_1 description602841
Ref: 3f6602841
Node: Template and modes<3>604256
Ref: refman/directives/initialization_1 template-and-modes604393
Ref: 3f7604393
Node: Examples<10>604482
Ref: refman/directives/initialization_1 examples604596
Ref: 3f8604596
Node: op/3605108
Ref: refman/directives/op_3 doc605245
Ref: 3f9605245
Ref: refman/directives/op_3 directives-op-3605245
Ref: 14c605245
Ref: refman/directives/op_3 op-3605245
Ref: 3fa605245
Node: Description<10>605395
Ref: refman/directives/op_3 description605500
Ref: 3fb605500
Node: Template and modes<4>605846
Ref: refman/directives/op_3 template-and-modes605972
Ref: 3fc605972
Node: Examples<11>606084
Ref: refman/directives/op_3 examples606186
Ref: 3fd606186
Node: set_logtalk_flag/2606365
Ref: refman/directives/set_logtalk_flag_2 doc606477
Ref: 3fe606477
Ref: refman/directives/set_logtalk_flag_2 directives-set-logtalk-flag-2606477
Ref: 4b606477
Ref: refman/directives/set_logtalk_flag_2 set-logtalk-flag-2606477
Ref: 3ff606477
Node: Description<11>606676
Ref: refman/directives/set_logtalk_flag_2 description606795
Ref: 400606795
Node: Template and modes<5>607338
Ref: refman/directives/set_logtalk_flag_2 template-and-modes607475
Ref: 401607475
Node: Errors<7>607571
Ref: refman/directives/set_logtalk_flag_2 errors607705
Ref: 402607705
Node: Examples<12>608216
Ref: refman/directives/set_logtalk_flag_2 examples608320
Ref: 403608320
Node: Conditional compilation directives<2>608891
Ref: refman/directives/conditional_compilation_directives doc609060
Ref: 404609060
Ref: refman/directives/conditional_compilation_directives conditional-compilation-directives609060
Ref: 176609060
Ref: refman/directives/conditional_compilation_directives id1609060
Ref: 405609060
Node: if/1609196
Ref: refman/directives/if_1 doc609308
Ref: 406609308
Ref: refman/directives/if_1 directives-if-1609308
Ref: 2cc609308
Ref: refman/directives/if_1 if-1609308
Ref: 407609308
Node: Description<12>609456
Ref: refman/directives/if_1 description609561
Ref: 408609561
Node: Template and modes<6>610151
Ref: refman/directives/if_1 template-and-modes610277
Ref: 409610277
Node: Examples<13>610352
Ref: refman/directives/if_1 examples610454
Ref: 40a610454
Node: elif/1611067
Ref: refman/directives/elif_1 doc611194
Ref: 40b611194
Ref: refman/directives/elif_1 directives-elif-1611194
Ref: 2cd611194
Ref: refman/directives/elif_1 elif-1611194
Ref: 40c611194
Node: Description<13>611346
Ref: refman/directives/elif_1 description611453
Ref: 40d611453
Node: Template and modes<7>612033
Ref: refman/directives/elif_1 template-and-modes612161
Ref: 40e612161
Node: Examples<14>612238
Ref: refman/directives/elif_1 examples612342
Ref: 40f612342
Node: else/0612682
Ref: refman/directives/else_0 doc612812
Ref: 410612812
Ref: refman/directives/else_0 directives-else-0612812
Ref: 2ce612812
Ref: refman/directives/else_0 else-0612812
Ref: 411612812
Node: Description<14>612964
Ref: refman/directives/else_0 description613071
Ref: 412613071
Node: Template and modes<8>613326
Ref: refman/directives/else_0 template-and-modes613454
Ref: 413613454
Node: Examples<15>613522
Ref: refman/directives/else_0 examples613626
Ref: 414613626
Node: endif/0614212
Ref: refman/directives/endif_0 doc614327
Ref: 415614327
Ref: refman/directives/endif_0 directives-endif-0614327
Ref: 2cf614327
Ref: refman/directives/endif_0 endif-0614327
Ref: 416614327
Node: Description<15>614483
Ref: refman/directives/endif_0 description614591
Ref: 417614591
Node: Template and modes<9>614721
Ref: refman/directives/endif_0 template-and-modes614850
Ref: 418614850
Node: Examples<16>614919
Ref: refman/directives/endif_0 examples615024
Ref: 419615024
Node: Entity directives<2>615244
Ref: refman/directives/entity_directives doc615411
Ref: 41a615411
Ref: refman/directives/entity_directives entity-directives615411
Ref: 41b615411
Ref: refman/directives/entity_directives id1615411
Ref: 41c615411
Node: built_in/0615657
Ref: refman/directives/built_in_0 doc615764
Ref: 41d615764
Ref: refman/directives/built_in_0 built-in-0615764
Ref: 41e615764
Ref: refman/directives/built_in_0 directives-built-in-0615764
Ref: 41f615764
Node: Description<16>615925
Ref: refman/directives/built_in_0 description616037
Ref: 420616037
Node: Template and modes<10>616317
Ref: refman/directives/built_in_0 template-and-modes616450
Ref: 421616450
Node: Examples<17>616520
Ref: refman/directives/built_in_0 examples616629
Ref: 422616629
Node: category/1-4616683
Ref: refman/directives/category_1_4 doc616808
Ref: 423616808
Ref: refman/directives/category_1_4 category-1-4616808
Ref: 424616808
Ref: refman/directives/category_1_4 directives-category-1-4616808
Ref: 106616808
Node: Description<17>616973
Ref: refman/directives/category_1_4 description617087
Ref: 425617087
Node: Template and modes<11>617730
Ref: refman/directives/category_1_4 template-and-modes617865
Ref: 426617865
Node: Examples<18>618736
Ref: refman/directives/category_1_4 examples618847
Ref: 427618847
Node: dynamic/0619248
Ref: refman/directives/dynamic_0 doc619377
Ref: 428619377
Ref: refman/directives/dynamic_0 directives-dynamic-0619377
Ref: ab619377
Ref: refman/directives/dynamic_0 dynamic-0619377
Ref: 429619377
Node: Description<18>619536
Ref: refman/directives/dynamic_0 description619647
Ref: 42a619647
Node: Template and modes<12>619996
Ref: refman/directives/dynamic_0 template-and-modes620128
Ref: 42b620128
Node: Examples<19>620199
Ref: refman/directives/dynamic_0 examples620307
Ref: 42c620307
Node: end_category/0620496
Ref: refman/directives/end_category_0 doc620625
Ref: 42d620625
Ref: refman/directives/end_category_0 directives-end-category-0620625
Ref: 107620625
Ref: refman/directives/end_category_0 end-category-0620625
Ref: 42e620625
Node: Description<19>620796
Ref: refman/directives/end_category_0 description620912
Ref: 42f620912
Node: Template and modes<13>621002
Ref: refman/directives/end_category_0 template-and-modes621139
Ref: 430621139
Node: Examples<20>621215
Ref: refman/directives/end_category_0 examples621328
Ref: 431621328
Node: end_object/0621433
Ref: refman/directives/end_object_0 doc621567
Ref: 432621567
Ref: refman/directives/end_object_0 directives-end-object-0621567
Ref: 97621567
Ref: refman/directives/end_object_0 end-object-0621567
Ref: 433621567
Node: Description<20>621734
Ref: refman/directives/end_object_0 description621848
Ref: 434621848
Node: Template and modes<14>621934
Ref: refman/directives/end_object_0 template-and-modes622069
Ref: 435622069
Node: Examples<21>622143
Ref: refman/directives/end_object_0 examples622254
Ref: 436622254
Node: end_protocol/0622354
Ref: refman/directives/end_protocol_0 doc622480
Ref: 437622480
Ref: refman/directives/end_protocol_0 directives-end-protocol-0622480
Ref: d6622480
Ref: refman/directives/end_protocol_0 end-protocol-0622480
Ref: 438622480
Node: Description<21>622651
Ref: refman/directives/end_protocol_0 description622767
Ref: 439622767
Node: Template and modes<15>622857
Ref: refman/directives/end_protocol_0 template-and-modes622994
Ref: 43a622994
Node: Examples<22>623070
Ref: refman/directives/end_protocol_0 examples623183
Ref: 43b623183
Node: info/1623287
Ref: refman/directives/info_1 doc623411
Ref: 43c623411
Ref: refman/directives/info_1 directives-info-1623411
Ref: ae623411
Ref: refman/directives/info_1 info-1623411
Ref: 43d623411
Node: Description<22>623566
Ref: refman/directives/info_1 description623674
Ref: 43e623674
Node: Template and modes<16>623975
Ref: refman/directives/info_1 template-and-modes624104
Ref: 43f624104
Node: Examples<23>624191
Ref: refman/directives/info_1 examples624296
Ref: 440624296
Node: object/1-5624616
Ref: refman/directives/object_1_5 doc624738
Ref: 441624738
Ref: refman/directives/object_1_5 directives-object-1-5624738
Ref: 96624738
Ref: refman/directives/object_1_5 object-1-5624738
Ref: 442624738
Node: Description<23>624901
Ref: refman/directives/object_1_5 description625013
Ref: 443625013
Node: Template and modes<17>626854
Ref: refman/directives/object_1_5 template-and-modes626987
Ref: 444626987
Node: Examples<24>629538
Ref: refman/directives/object_1_5 examples629647
Ref: 445629647
Node: protocol/1-2630177
Ref: refman/directives/protocol_1_2 doc630303
Ref: 446630303
Ref: refman/directives/protocol_1_2 directives-protocol-1-2630303
Ref: d5630303
Ref: refman/directives/protocol_1_2 protocol-1-2630303
Ref: 447630303
Node: Description<24>630470
Ref: refman/directives/protocol_1_2 description630584
Ref: 448630584
Node: Template and modes<18>630736
Ref: refman/directives/protocol_1_2 template-and-modes630871
Ref: 449630871
Node: Examples<25>631041
Ref: refman/directives/protocol_1_2 examples631152
Ref: 44a631152
Node: threaded/0631379
Ref: refman/directives/threaded_0 doc631501
Ref: 44b631501
Ref: refman/directives/threaded_0 directives-threaded-0631501
Ref: 209631501
Ref: refman/directives/threaded_0 threaded-0631501
Ref: 44c631501
Node: Description<25>631664
Ref: refman/directives/threaded_0 description631776
Ref: 44d631776
Node: Template and modes<19>632855
Ref: refman/directives/threaded_0 template-and-modes632988
Ref: 44e632988
Node: Examples<26>633060
Ref: refman/directives/threaded_0 examples633169
Ref: 44f633169
Node: uses/1633300
Ref: refman/directives/uses_1 doc633422
Ref: 450633422
Ref: refman/directives/uses_1 directives-uses-1633422
Ref: b5633422
Ref: refman/directives/uses_1 uses-1633422
Ref: 451633422
Node: Description<26>633577
Ref: refman/directives/uses_1 description633685
Ref: 452633685
Node: Template and modes<20>634793
Ref: refman/directives/uses_1 template-and-modes634922
Ref: 453634922
Node: Examples<27>635010
Ref: refman/directives/uses_1 examples635115
Ref: 454635115
Node: use_module/1635869
Ref: refman/directives/use_module_1 doc635972
Ref: 455635972
Ref: refman/directives/use_module_1 directives-use-module-1635972
Ref: 49635972
Ref: refman/directives/use_module_1 use-module-1635972
Ref: 456635972
Node: Description<27>636139
Ref: refman/directives/use_module_1 description636253
Ref: 457636253
Node: Template and modes<21>637417
Ref: refman/directives/use_module_1 template-and-modes637552
Ref: 458637552
Node: Examples<28>637646
Ref: refman/directives/use_module_1 examples637757
Ref: 459637757
Node: Predicate directives<3>638112
Ref: refman/directives/predicate_directives doc638233
Ref: 45a638233
Ref: refman/directives/predicate_directives id1638233
Ref: 45b638233
Ref: refman/directives/predicate_directives predicate-directives638233
Ref: 45c638233
Node: alias/2638535
Ref: refman/directives/alias_2 doc638643
Ref: 45d638643
Ref: refman/directives/alias_2 alias-2638643
Ref: 45e638643
Ref: refman/directives/alias_2 directives-alias-2638643
Ref: 153638643
Node: Description<28>638798
Ref: refman/directives/alias_2 description638907
Ref: 45f638907
Node: Template and modes<22>640009
Ref: refman/directives/alias_2 template-and-modes640139
Ref: 460640139
Node: Examples<29>640328
Ref: refman/directives/alias_2 examples640434
Ref: 461640434
Node: coinductive/1640798
Ref: refman/directives/coinductive_1 doc640930
Ref: 462640930
Ref: refman/directives/coinductive_1 coinductive-1640930
Ref: 463640930
Ref: refman/directives/coinductive_1 directives-coinductive-1640930
Ref: 15d640930
Node: Description<29>641097
Ref: refman/directives/coinductive_1 description641212
Ref: 464641212
Node: Template and modes<23>642830
Ref: refman/directives/coinductive_1 template-and-modes642966
Ref: 466642966
Node: Examples<30>643168
Ref: refman/directives/coinductive_1 examples643280
Ref: 467643280
Node: discontiguous/1643527
Ref: refman/directives/discontiguous_1 doc643661
Ref: 468643661
Ref: refman/directives/discontiguous_1 directives-discontiguous-1643661
Ref: 146643661
Ref: refman/directives/discontiguous_1 discontiguous-1643661
Ref: 469643661
Node: Description<30>643832
Ref: refman/directives/discontiguous_1 description643949
Ref: 46a643949
Node: Template and modes<24>644632
Ref: refman/directives/discontiguous_1 template-and-modes644770
Ref: 46b644770
Node: Examples<31>644923
Ref: refman/directives/discontiguous_1 examples645037
Ref: 46c645037
Node: dynamic/1645200
Ref: refman/directives/dynamic_1 doc645327
Ref: 46d645327
Ref: refman/directives/dynamic_1 directives-dynamic-1645327
Ref: 149645327
Ref: refman/directives/dynamic_1 dynamic-1645327
Ref: 46e645327
Node: Description<31>645488
Ref: refman/directives/dynamic_1 description645599
Ref: 46f645599
Node: Template and modes<25>647337
Ref: refman/directives/dynamic_1 template-and-modes647469
Ref: 470647469
Node: Examples<32>647630
Ref: refman/directives/dynamic_1 examples647738
Ref: 471647738
Node: info/2647957
Ref: refman/directives/info_2 doc648085
Ref: 472648085
Ref: refman/directives/info_2 directives-info-2648085
Ref: 156648085
Ref: refman/directives/info_2 info-2648085
Ref: 473648085
Node: Description<32>648240
Ref: refman/directives/info_2 description648348
Ref: 474648348
Node: Template and modes<26>648806
Ref: refman/directives/info_2 template-and-modes648935
Ref: 475648935
Node: Examples<33>649104
Ref: refman/directives/info_2 examples649209
Ref: 476649209
Node: meta_predicate/1649580
Ref: refman/directives/meta_predicate_1 doc649718
Ref: 477649718
Ref: refman/directives/meta_predicate_1 directives-meta-predicate-1649718
Ref: 142649718
Ref: refman/directives/meta_predicate_1 meta-predicate-1649718
Ref: 478649718
Node: Description<33>649893
Ref: refman/directives/meta_predicate_1 description650011
Ref: 479650011
Node: Template and modes<27>651888
Ref: refman/directives/meta_predicate_1 template-and-modes652027
Ref: 47a652027
Node: Examples<34>652352
Ref: refman/directives/meta_predicate_1 examples652467
Ref: 47b652467
Node: meta_non_terminal/1652964
Ref: refman/directives/meta_non_terminal_1 doc653102
Ref: 47d653102
Ref: refman/directives/meta_non_terminal_1 directives-meta-non-terminal-1653102
Ref: 47c653102
Ref: refman/directives/meta_non_terminal_1 meta-non-terminal-1653102
Ref: 47e653102
Node: Description<34>653283
Ref: refman/directives/meta_non_terminal_1 description653404
Ref: 47f653404
Node: Template and modes<28>654679
Ref: refman/directives/meta_non_terminal_1 template-and-modes654821
Ref: 480654821
Node: Examples<35>655170
Ref: refman/directives/meta_non_terminal_1 examples655288
Ref: 481655288
Node: mode/2655483
Ref: refman/directives/mode_2 doc655616
Ref: 482655616
Ref: refman/directives/mode_2 directives-mode-2655616
Ref: 13d655616
Ref: refman/directives/mode_2 mode-2655616
Ref: 483655616
Node: Description<35>655771
Ref: refman/directives/mode_2 description655879
Ref: 484655879
Node: Template and modes<29>656241
Ref: refman/directives/mode_2 template-and-modes656370
Ref: 485656370
Node: Examples<36>656533
Ref: refman/directives/mode_2 examples656638
Ref: 486656638
Node: multifile/1656961
Ref: refman/directives/multifile_1 doc657084
Ref: 487657084
Ref: refman/directives/multifile_1 directives-multifile-1657084
Ref: 159657084
Ref: refman/directives/multifile_1 multifile-1657084
Ref: 488657084
Node: Description<36>657249
Ref: refman/directives/multifile_1 description657362
Ref: 489657362
Node: Template and modes<30>658953
Ref: refman/directives/multifile_1 template-and-modes659087
Ref: 48a659087
Node: Examples<37>659252
Ref: refman/directives/multifile_1 examples659362
Ref: 48b659362
Node: private/1659581
Ref: refman/directives/private_1 doc659709
Ref: 48c659709
Ref: refman/directives/private_1 directives-private-1659709
Ref: 13a659709
Ref: refman/directives/private_1 private-1659709
Ref: 48d659709
Node: Description<37>659870
Ref: refman/directives/private_1 description659981
Ref: 48e659981
Node: Template and modes<31>660720
Ref: refman/directives/private_1 template-and-modes660852
Ref: 48f660852
Node: Examples<38>661029
Ref: refman/directives/private_1 examples661137
Ref: 490661137
Node: protected/1661380
Ref: refman/directives/protected_1 doc661505
Ref: 491661505
Ref: refman/directives/protected_1 directives-protected-1661505
Ref: 139661505
Ref: refman/directives/protected_1 protected-1661505
Ref: 492661505
Node: Description<38>661670
Ref: refman/directives/protected_1 description661783
Ref: 493661783
Node: Template and modes<32>662793
Ref: refman/directives/protected_1 template-and-modes662927
Ref: 494662927
Node: Examples<39>663110
Ref: refman/directives/protected_1 examples663220
Ref: 495663220
Node: public/1663461
Ref: refman/directives/public_1 doc663591
Ref: 496663591
Ref: refman/directives/public_1 directives-public-1663591
Ref: 138663591
Ref: refman/directives/public_1 public-1663591
Ref: 497663591
Node: Description<39>663750
Ref: refman/directives/public_1 description663860
Ref: 498663860
Node: Template and modes<33>664758
Ref: refman/directives/public_1 template-and-modes664889
Ref: 499664889
Node: Examples<40>665063
Ref: refman/directives/public_1 examples665170
Ref: 49a665170
Node: synchronized/1665416
Ref: refman/directives/synchronized_1 doc665541
Ref: 49b665541
Ref: refman/directives/synchronized_1 directives-synchronized-1665541
Ref: 6f665541
Ref: refman/directives/synchronized_1 synchronized-1665541
Ref: 49c665541
Node: Description<40>665712
Ref: refman/directives/synchronized_1 description665828
Ref: 49d665828
Node: Template and modes<34>667204
Ref: refman/directives/synchronized_1 template-and-modes667341
Ref: 49e667341
Node: Examples<41>667492
Ref: refman/directives/synchronized_1 examples667605
Ref: 49f667605
Node: uses/2667849
Ref: refman/directives/uses_2 doc667978
Ref: 4a0667978
Ref: refman/directives/uses_2 directives-uses-2667978
Ref: 48667978
Ref: refman/directives/uses_2 uses-2667978
Ref: 4a1667978
Node: Description<41>668133
Ref: refman/directives/uses_2 description668241
Ref: 4a2668241
Node: Template and modes<35>670619
Ref: refman/directives/uses_2 template-and-modes670748
Ref: 4a3670748
Node: Examples<42>671163
Ref: refman/directives/uses_2 examples671268
Ref: 4a4671268
Node: use_module/2672861
Ref: refman/directives/use_module_2 doc672967
Ref: 4a5672967
Ref: refman/directives/use_module_2 directives-use-module-2672967
Ref: 4a672967
Ref: refman/directives/use_module_2 use-module-2672967
Ref: 4a6672967
Node: Description<42>673134
Ref: refman/directives/use_module_2 description673248
Ref: 4a7673248
Node: Template and modes<36>676598
Ref: refman/directives/use_module_2 template-and-modes676733
Ref: 4a8676733
Node: Examples<43>677198
Ref: refman/directives/use_module_2 examples677309
Ref: 4a9677309
Node: Built-in predicates678675
Ref: refman/predicates/index doc678816
Ref: 4aa678816
Ref: refman/predicates/index built-in-predicates678816
Ref: 4ab678816
Node: Enumerating objects categories and protocols679514
Ref: refman/predicates/enumerating_entity_predicates doc679697
Ref: 4ac679697
Ref: refman/predicates/enumerating_entity_predicates enumerating-entity-predicates679697
Ref: 265679697
Ref: refman/predicates/enumerating_entity_predicates enumerating-objects-categories-and-protocols679697
Ref: 4ad679697
Node: current_category/1679879
Ref: refman/predicates/current_category_1 doc680022
Ref: 4ae680022
Ref: refman/predicates/current_category_1 current-category-1680022
Ref: 4af680022
Ref: refman/predicates/current_category_1 predicates-current-category-1680022
Ref: ea680022
Node: Description<43>680235
Ref: refman/predicates/current_category_1 description680362
Ref: 4b0680362
Node: Modes and number of proofs<7>680564
Ref: refman/predicates/current_category_1 modes-and-number-of-proofs680709
Ref: 4b1680709
Node: Errors<8>680840
Ref: refman/predicates/current_category_1 errors680982
Ref: 4b2680982
Node: Examples<44>681149
Ref: refman/predicates/current_category_1 examples681253
Ref: 4b3681253
Node: current_object/1681619
Ref: refman/predicates/current_object_1 doc681789
Ref: 4b4681789
Ref: refman/predicates/current_object_1 current-object-1681789
Ref: 4b5681789
Ref: refman/predicates/current_object_1 predicates-current-object-1681789
Ref: a0681789
Node: Description<44>681998
Ref: refman/predicates/current_object_1 description682123
Ref: 4b6682123
Node: Modes and number of proofs<8>682314
Ref: refman/predicates/current_object_1 modes-and-number-of-proofs682457
Ref: 4b7682457
Node: Errors<9>682584
Ref: refman/predicates/current_object_1 errors682724
Ref: 4b8682724
Node: Examples<45>682883
Ref: refman/predicates/current_object_1 examples682985
Ref: 4b9682985
Node: current_protocol/1683383
Ref: refman/predicates/current_protocol_1 doc683526
Ref: 4ba683526
Ref: refman/predicates/current_protocol_1 current-protocol-1683526
Ref: 4bb683526
Ref: refman/predicates/current_protocol_1 predicates-current-protocol-1683526
Ref: d9683526
Node: Description<45>683742
Ref: refman/predicates/current_protocol_1 description683869
Ref: 4bc683869
Node: Modes and number of proofs<9>684071
Ref: refman/predicates/current_protocol_1 modes-and-number-of-proofs684217
Ref: 4bd684217
Node: Errors<10>684350
Ref: refman/predicates/current_protocol_1 errors684493
Ref: 4be684493
Node: Examples<46>684662
Ref: refman/predicates/current_protocol_1 examples684767
Ref: 4bf684767
Node: Enumerating objects categories and protocols properties685192
Ref: refman/predicates/enumerating_entity_property_predicates doc685429
Ref: 4c0685429
Ref: refman/predicates/enumerating_entity_property_predicates enumerating-entity-property-predicates685429
Ref: 6a685429
Ref: refman/predicates/enumerating_entity_property_predicates enumerating-objects-categories-and-protocols-properties685429
Ref: 4c1685429
Node: category_property/2685636
Ref: refman/predicates/category_property_2 doc685792
Ref: 4c2685792
Ref: refman/predicates/category_property_2 category-property-2685792
Ref: 4c3685792
Ref: refman/predicates/category_property_2 predicates-category-property-2685792
Ref: 122685792
Node: Description<46>686009
Ref: refman/predicates/category_property_2 description686138
Ref: 4c4686138
Node: Modes and number of proofs<10>686481
Ref: refman/predicates/category_property_2 modes-and-number-of-proofs686629
Ref: 4c5686629
Node: Errors<11>686781
Ref: refman/predicates/category_property_2 errors686926
Ref: 4c6686926
Node: Examples<47>687351
Ref: refman/predicates/category_property_2 examples687457
Ref: 4c7687457
Node: object_property/2687918
Ref: refman/predicates/object_property_2 doc688102
Ref: 4c8688102
Ref: refman/predicates/object_property_2 object-property-2688102
Ref: 4c9688102
Ref: refman/predicates/object_property_2 predicates-object-property-2688102
Ref: c1688102
Node: Description<47>688315
Ref: refman/predicates/object_property_2 description688442
Ref: 4ca688442
Node: Modes and number of proofs<11>688775
Ref: refman/predicates/object_property_2 modes-and-number-of-proofs688921
Ref: 4cb688921
Node: Errors<12>689067
Ref: refman/predicates/object_property_2 errors689210
Ref: 4cc689210
Node: Examples<48>689611
Ref: refman/predicates/object_property_2 examples689715
Ref: 4cd689715
Node: protocol_property/2690256
Ref: refman/predicates/protocol_property_2 doc690412
Ref: 4ce690412
Ref: refman/predicates/protocol_property_2 predicates-protocol-property-2690412
Ref: ed690412
Ref: refman/predicates/protocol_property_2 protocol-property-2690412
Ref: 4cf690412
Node: Description<48>690631
Ref: refman/predicates/protocol_property_2 description690760
Ref: 4d0690760
Node: Modes and number of proofs<12>691113
Ref: refman/predicates/protocol_property_2 modes-and-number-of-proofs691261
Ref: 4d1691261
Node: Errors<13>691415
Ref: refman/predicates/protocol_property_2 errors691560
Ref: 4d2691560
Node: Examples<49>691975
Ref: refman/predicates/protocol_property_2 examples692081
Ref: 4d3692081
Node: Creating new objects categories and protocols692543
Ref: refman/predicates/creating_entity_predicates doc692779
Ref: 4d4692779
Ref: refman/predicates/creating_entity_predicates creating-entity-predicates692779
Ref: 4d5692779
Ref: refman/predicates/creating_entity_predicates creating-new-objects-categories-and-protocols692779
Ref: 4d6692779
Node: create_category/4692960
Ref: refman/predicates/create_category_4 doc693102
Ref: 4d7693102
Ref: refman/predicates/create_category_4 create-category-4693102
Ref: 4d8693102
Ref: refman/predicates/create_category_4 predicates-create-category-4693102
Ref: 110693102
Node: Description<49>693315
Ref: refman/predicates/create_category_4 description693442
Ref: 4d9693442
Node: Modes and number of proofs<13>694335
Ref: refman/predicates/create_category_4 modes-and-number-of-proofs694481
Ref: 4da694481
Node: Errors<14>694670
Ref: refman/predicates/create_category_4 errors694813
Ref: 4db694813
Node: Examples<50>695904
Ref: refman/predicates/create_category_4 examples696008
Ref: 4dc696008
Node: create_object/4696447
Ref: refman/predicates/create_object_4 doc696615
Ref: 4dd696615
Ref: refman/predicates/create_object_4 create-object-4696615
Ref: 4de696615
Ref: refman/predicates/create_object_4 predicates-create-object-4696615
Ref: 5d696615
Node: Description<50>696824
Ref: refman/predicates/create_object_4 description696949
Ref: 4df696949
Node: Modes and number of proofs<14>697970
Ref: refman/predicates/create_object_4 modes-and-number-of-proofs698114
Ref: 4e1698114
Node: Errors<15>698295
Ref: refman/predicates/create_object_4 errors698436
Ref: 4e2698436
Node: Examples<51>699668
Ref: refman/predicates/create_object_4 examples699770
Ref: 4e3699770
Node: create_protocol/3701292
Ref: refman/predicates/create_protocol_3 doc701434
Ref: 4e4701434
Ref: refman/predicates/create_protocol_3 create-protocol-3701434
Ref: 4e5701434
Ref: refman/predicates/create_protocol_3 predicates-create-protocol-3701434
Ref: dc701434
Node: Description<51>701649
Ref: refman/predicates/create_protocol_3 description701776
Ref: 4e6701776
Node: Modes and number of proofs<15>702511
Ref: refman/predicates/create_protocol_3 modes-and-number-of-proofs702657
Ref: 4e7702657
Node: Errors<16>702833
Ref: refman/predicates/create_protocol_3 errors702976
Ref: 4e8702976
Node: Examples<52>703809
Ref: refman/predicates/create_protocol_3 examples703913
Ref: 4e9703913
Node: Abolishing objects categories and protocols704320
Ref: refman/predicates/abolishing_entity_predicates doc704543
Ref: 4ea704543
Ref: refman/predicates/abolishing_entity_predicates abolishing-entity-predicates704543
Ref: 4eb704543
Ref: refman/predicates/abolishing_entity_predicates abolishing-objects-categories-and-protocols704543
Ref: 4ec704543
Node: abolish_category/1704723
Ref: refman/predicates/abolish_category_1 doc704865
Ref: 4ed704865
Ref: refman/predicates/abolish_category_1 abolish-category-1704865
Ref: 4ee704865
Ref: refman/predicates/abolish_category_1 predicates-abolish-category-1704865
Ref: ee704865
Node: Description<52>705080
Ref: refman/predicates/abolish_category_1 description705208
Ref: 4ef705208
Node: Modes and number of proofs<16>705387
Ref: refman/predicates/abolish_category_1 modes-and-number-of-proofs705534
Ref: 4f0705534
Node: Errors<17>705656
Ref: refman/predicates/abolish_category_1 errors705800
Ref: 4f1705800
Node: Examples<53>706259
Ref: refman/predicates/abolish_category_1 examples706364
Ref: 4f2706364
Node: abolish_object/1706649
Ref: refman/predicates/abolish_object_1 doc706818
Ref: 4f3706818
Ref: refman/predicates/abolish_object_1 abolish-object-1706818
Ref: 4f4706818
Ref: refman/predicates/abolish_object_1 predicates-abolish-object-1706818
Ref: 5f706818
Node: Description<53>707029
Ref: refman/predicates/abolish_object_1 description707155
Ref: 4f5707155
Node: Modes and number of proofs<17>707324
Ref: refman/predicates/abolish_object_1 modes-and-number-of-proofs707469
Ref: 4f6707469
Node: Errors<18>707587
Ref: refman/predicates/abolish_object_1 errors707729
Ref: 4f7707729
Node: Examples<54>708164
Ref: refman/predicates/abolish_object_1 examples708267
Ref: 4f8708267
Node: abolish_protocol/1708570
Ref: refman/predicates/abolish_protocol_1 doc708712
Ref: 4f9708712
Ref: refman/predicates/abolish_protocol_1 abolish-protocol-1708712
Ref: 4fa708712
Ref: refman/predicates/abolish_protocol_1 predicates-abolish-protocol-1708712
Ref: df708712
Node: Description<54>708929
Ref: refman/predicates/abolish_protocol_1 description709057
Ref: 4fb709057
Node: Modes and number of proofs<18>709238
Ref: refman/predicates/abolish_protocol_1 modes-and-number-of-proofs709385
Ref: 4fc709385
Node: Errors<19>709509
Ref: refman/predicates/abolish_protocol_1 errors709653
Ref: 4fd709653
Node: Examples<55>710114
Ref: refman/predicates/abolish_protocol_1 examples710219
Ref: 4fe710219
Node: Objects categories and protocols relations710505
Ref: refman/predicates/entity_relation_predicates doc710700
Ref: 4ff710700
Ref: refman/predicates/entity_relation_predicates entity-relation-predicates710700
Ref: 266710700
Ref: refman/predicates/entity_relation_predicates objects-categories-and-protocols-relations710700
Ref: 500710700
Node: extends_object/2-3711046
Ref: refman/predicates/extends_object_2_3 doc711191
Ref: 501711191
Ref: refman/predicates/extends_object_2_3 extends-object-2-3711191
Ref: 502711191
Ref: refman/predicates/extends_object_2_3 predicates-extends-object-2-3711191
Ref: ba711191
Node: Description<55>711406
Ref: refman/predicates/extends_object_2_3 description711534
Ref: 503711534
Node: Modes and number of proofs<19>711854
Ref: refman/predicates/extends_object_2_3 modes-and-number-of-proofs712001
Ref: 504712001
Node: Errors<20>712231
Ref: refman/predicates/extends_object_2_3 errors712375
Ref: 505712375
Node: Examples<56>712863
Ref: refman/predicates/extends_object_2_3 examples712968
Ref: 506712968
Node: extends_protocol/2-3713347
Ref: refman/predicates/extends_protocol_2_3 doc713521
Ref: 507713521
Ref: refman/predicates/extends_protocol_2_3 extends-protocol-2-3713521
Ref: 508713521
Ref: refman/predicates/extends_protocol_2_3 predicates-extends-protocol-2-3713521
Ref: e9713521
Node: Description<56>713740
Ref: refman/predicates/extends_protocol_2_3 description713870
Ref: 509713870
Node: Modes and number of proofs<20>714210
Ref: refman/predicates/extends_protocol_2_3 modes-and-number-of-proofs714359
Ref: 50a714359
Node: Errors<21>714601
Ref: refman/predicates/extends_protocol_2_3 errors714747
Ref: 50b714747
Node: Examples<57>715257
Ref: refman/predicates/extends_protocol_2_3 examples715364
Ref: 50c715364
Node: extends_category/2-3715755
Ref: refman/predicates/extends_category_2_3 doc715934
Ref: 50d715934
Ref: refman/predicates/extends_category_2_3 extends-category-2-3715934
Ref: 50e715934
Ref: refman/predicates/extends_category_2_3 predicates-extends-category-2-3715934
Ref: 11f715934
Node: Description<57>716155
Ref: refman/predicates/extends_category_2_3 description716285
Ref: 50f716285
Node: Modes and number of proofs<21>716628
Ref: refman/predicates/extends_category_2_3 modes-and-number-of-proofs716777
Ref: 510716777
Node: Errors<22>717021
Ref: refman/predicates/extends_category_2_3 errors717167
Ref: 511717167
Node: Examples<58>717679
Ref: refman/predicates/extends_category_2_3 examples717786
Ref: 512717786
Node: implements_protocol/2-3718184
Ref: refman/predicates/implements_protocol_2_3 doc718367
Ref: 513718367
Ref: refman/predicates/implements_protocol_2_3 implements-protocol-2-3718367
Ref: 514718367
Ref: refman/predicates/implements_protocol_2_3 predicates-implements-protocol-2-3718367
Ref: bc718367
Node: Description<58>718594
Ref: refman/predicates/implements_protocol_2_3 description718727
Ref: 515718727
Node: Modes and number of proofs<22>719275
Ref: refman/predicates/implements_protocol_2_3 modes-and-number-of-proofs719427
Ref: 516719427
Node: Errors<23>719850
Ref: refman/predicates/implements_protocol_2_3 errors719999
Ref: 517719999
Node: Examples<59>720626
Ref: refman/predicates/implements_protocol_2_3 examples720736
Ref: 518720736
Node: conforms_to_protocol/2-3721451
Ref: refman/predicates/conforms_to_protocol_2_3 doc721634
Ref: 519721634
Ref: refman/predicates/conforms_to_protocol_2_3 conforms-to-protocol-2-3721634
Ref: 51a721634
Ref: refman/predicates/conforms_to_protocol_2_3 predicates-conforms-to-protocol-2-3721634
Ref: bd721634
Node: Description<59>721863
Ref: refman/predicates/conforms_to_protocol_2_3 description721997
Ref: 51b721997
Node: Modes and number of proofs<23>722534
Ref: refman/predicates/conforms_to_protocol_2_3 modes-and-number-of-proofs722687
Ref: 51c722687
Node: Errors<24>723114
Ref: refman/predicates/conforms_to_protocol_2_3 errors723264
Ref: 51d723264
Node: Examples<60>723891
Ref: refman/predicates/conforms_to_protocol_2_3 examples724002
Ref: 51e724002
Node: complements_object/2724750
Ref: refman/predicates/complements_object_2 doc724930
Ref: 51f724930
Ref: refman/predicates/complements_object_2 complements-object-2724930
Ref: 520724930
Ref: refman/predicates/complements_object_2 predicates-complements-object-2724930
Ref: be724930
Node: Description<60>725151
Ref: refman/predicates/complements_object_2 description725281
Ref: 521725281
Node: Modes and number of proofs<24>725483
Ref: refman/predicates/complements_object_2 modes-and-number-of-proofs725632
Ref: 522725632
Node: Errors<25>725787
Ref: refman/predicates/complements_object_2 errors725933
Ref: 523725933
Node: Examples<61>726230
Ref: refman/predicates/complements_object_2 examples726337
Ref: 524726337
Node: imports_category/2-3726578
Ref: refman/predicates/imports_category_2_3 doc726756
Ref: 525726756
Ref: refman/predicates/imports_category_2_3 imports-category-2-3726756
Ref: 526726756
Ref: refman/predicates/imports_category_2_3 predicates-imports-category-2-3726756
Ref: bb726756
Node: Description<61>726977
Ref: refman/predicates/imports_category_2_3 description727107
Ref: 527727107
Node: Modes and number of proofs<25>727421
Ref: refman/predicates/imports_category_2_3 modes-and-number-of-proofs727570
Ref: 528727570
Node: Errors<26>727810
Ref: refman/predicates/imports_category_2_3 errors727956
Ref: 529727956
Node: Examples<62>728448
Ref: refman/predicates/imports_category_2_3 examples728555
Ref: 52a728555
Node: instantiates_class/2-3728926
Ref: refman/predicates/instantiates_class_2_3 doc729105
Ref: 52b729105
Ref: refman/predicates/instantiates_class_2_3 instantiates-class-2-3729105
Ref: 52c729105
Ref: refman/predicates/instantiates_class_2_3 predicates-instantiates-class-2-3729105
Ref: b8729105
Node: Description<62>729330
Ref: refman/predicates/instantiates_class_2_3 description729462
Ref: 52d729462
Node: Modes and number of proofs<26>729793
Ref: refman/predicates/instantiates_class_2_3 modes-and-number-of-proofs729944
Ref: 52e729944
Node: Errors<27>730184
Ref: refman/predicates/instantiates_class_2_3 errors730332
Ref: 52f730332
Node: Examples<63>730818
Ref: refman/predicates/instantiates_class_2_3 examples730927
Ref: 530730927
Node: specializes_class/2-3731346
Ref: refman/predicates/specializes_class_2_3 doc731496
Ref: 531731496
Ref: refman/predicates/specializes_class_2_3 predicates-specializes-class-2-3731496
Ref: b9731496
Ref: refman/predicates/specializes_class_2_3 specializes-class-2-3731496
Ref: 532731496
Node: Description<63>731719
Ref: refman/predicates/specializes_class_2_3 description731850
Ref: 533731850
Node: Modes and number of proofs<27>732182
Ref: refman/predicates/specializes_class_2_3 modes-and-number-of-proofs732332
Ref: 534732332
Node: Errors<28>732570
Ref: refman/predicates/specializes_class_2_3 errors732717
Ref: 535732717
Node: Examples<64>733207
Ref: refman/predicates/specializes_class_2_3 examples733315
Ref: 536733315
Node: Event handling<2>733719
Ref: refman/predicates/event_handling_predicates doc733886
Ref: 537733886
Ref: refman/predicates/event_handling_predicates event-handling733886
Ref: 538733886
Ref: refman/predicates/event_handling_predicates event-handling-predicates733886
Ref: 6c733886
Node: abolish_events/5734000
Ref: refman/predicates/abolish_events_5 doc734113
Ref: 539734113
Ref: refman/predicates/abolish_events_5 abolish-events-5734113
Ref: 53a734113
Ref: refman/predicates/abolish_events_5 predicates-abolish-events-5734113
Ref: 1fc734113
Node: Description<64>734324
Ref: refman/predicates/abolish_events_5 description734450
Ref: 53b734450
Node: Modes and number of proofs<28>734768
Ref: refman/predicates/abolish_events_5 modes-and-number-of-proofs734913
Ref: 53c734913
Node: Errors<29>735046
Ref: refman/predicates/abolish_events_5 errors735188
Ref: 53d735188
Node: Examples<65>735825
Ref: refman/predicates/abolish_events_5 examples735928
Ref: 53e735928
Node: current_event/5736244
Ref: refman/predicates/current_event_5 doc736381
Ref: 53f736381
Ref: refman/predicates/current_event_5 current-event-5736381
Ref: 540736381
Ref: refman/predicates/current_event_5 predicates-current-event-5736381
Ref: 1ff736381
Node: Description<65>736590
Ref: refman/predicates/current_event_5 description736715
Ref: 541736715
Node: Modes and number of proofs<29>736951
Ref: refman/predicates/current_event_5 modes-and-number-of-proofs737095
Ref: 542737095
Node: Errors<30>737250
Ref: refman/predicates/current_event_5 errors737391
Ref: 543737391
Node: Examples<66>738028
Ref: refman/predicates/current_event_5 examples738130
Ref: 544738130
Node: define_events/5738415
Ref: refman/predicates/define_events_5 doc738527
Ref: 545738527
Ref: refman/predicates/define_events_5 define-events-5738527
Ref: 546738527
Ref: refman/predicates/define_events_5 predicates-define-events-5738527
Ref: 1f9738527
Node: Description<66>738738
Ref: refman/predicates/define_events_5 description738863
Ref: 547738863
Node: Modes and number of proofs<30>739280
Ref: refman/predicates/define_events_5 modes-and-number-of-proofs739424
Ref: 548739424
Node: Errors<31>739571
Ref: refman/predicates/define_events_5 errors739712
Ref: 549739712
Node: Examples<67>740673
Ref: refman/predicates/define_events_5 examples740775
Ref: 54a740775
Node: Multi-threading741085
Ref: refman/predicates/multi_threading_predicates doc741233
Ref: 54b741233
Ref: refman/predicates/multi_threading_predicates multi-threading741233
Ref: 54c741233
Ref: refman/predicates/multi_threading_predicates multi-threading-predicates741233
Ref: 54d741233
Node: threaded/1741477
Ref: refman/predicates/threaded_1 doc741584
Ref: 54e741584
Ref: refman/predicates/threaded_1 predicates-threaded-1741584
Ref: 20c741584
Ref: refman/predicates/threaded_1 threaded-1741584
Ref: 54f741584
Node: Description<67>741783
Ref: refman/predicates/threaded_1 description741903
Ref: 550741903
Node: Modes and number of proofs<31>743366
Ref: refman/predicates/threaded_1 modes-and-number-of-proofs743505
Ref: 551743505
Node: Errors<32>743616
Ref: refman/predicates/threaded_1 errors743752
Ref: 552743752
Node: Examples<68>744166
Ref: refman/predicates/threaded_1 examples744263
Ref: 553744263
Node: threaded_call/1-2744645
Ref: refman/predicates/threaded_call_1_2 doc744778
Ref: 554744778
Ref: refman/predicates/threaded_call_1_2 predicates-threaded-call-1-2744778
Ref: 211744778
Ref: refman/predicates/threaded_call_1_2 threaded-call-1-2744778
Ref: 555744778
Node: Description<68>744991
Ref: refman/predicates/threaded_call_1_2 description745118
Ref: 556745118
Node: Modes and number of proofs<32>746076
Ref: refman/predicates/threaded_call_1_2 modes-and-number-of-proofs746222
Ref: 557746222
Node: Errors<33>746376
Ref: refman/predicates/threaded_call_1_2 errors746519
Ref: 558746519
Node: Examples<69>746803
Ref: refman/predicates/threaded_call_1_2 examples746907
Ref: 559746907
Node: threaded_once/1-2747472
Ref: refman/predicates/threaded_once_1_2 doc747612
Ref: 55a747612
Ref: refman/predicates/threaded_once_1_2 predicates-threaded-once-1-2747612
Ref: 213747612
Ref: refman/predicates/threaded_once_1_2 threaded-once-1-2747612
Ref: 55b747612
Node: Description<69>747827
Ref: refman/predicates/threaded_once_1_2 description747954
Ref: 55c747954
Node: Modes and number of proofs<33>748841
Ref: refman/predicates/threaded_once_1_2 modes-and-number-of-proofs748987
Ref: 55d748987
Node: Errors<34>749143
Ref: refman/predicates/threaded_once_1_2 errors749286
Ref: 55e749286
Node: Examples<70>749554
Ref: refman/predicates/threaded_once_1_2 examples749658
Ref: 55f749658
Node: threaded_ignore/1750223
Ref: refman/predicates/threaded_ignore_1 doc750363
Ref: 560750363
Ref: refman/predicates/threaded_ignore_1 predicates-threaded-ignore-1750363
Ref: 218750363
Ref: refman/predicates/threaded_ignore_1 threaded-ignore-1750363
Ref: 561750363
Node: Description<70>750578
Ref: refman/predicates/threaded_ignore_1 description750705
Ref: 562750705
Node: Modes and number of proofs<34>751372
Ref: refman/predicates/threaded_ignore_1 modes-and-number-of-proofs751518
Ref: 563751518
Node: Errors<35>751630
Ref: refman/predicates/threaded_ignore_1 errors751773
Ref: 564751773
Node: Examples<71>751980
Ref: refman/predicates/threaded_ignore_1 examples752084
Ref: 565752084
Node: threaded_exit/1-2752625
Ref: refman/predicates/threaded_exit_1_2 doc752765
Ref: 566752765
Ref: refman/predicates/threaded_exit_1_2 predicates-threaded-exit-1-2752765
Ref: 212752765
Ref: refman/predicates/threaded_exit_1_2 threaded-exit-1-2752765
Ref: 567752765
Node: Description<71>752980
Ref: refman/predicates/threaded_exit_1_2 description753107
Ref: 568753107
Node: Modes and number of proofs<35>754439
Ref: refman/predicates/threaded_exit_1_2 modes-and-number-of-proofs754585
Ref: 569754585
Node: Errors<36>754758
Ref: refman/predicates/threaded_exit_1_2 errors754901
Ref: 56a754901
Node: Examples<72>755279
Ref: refman/predicates/threaded_exit_1_2 examples755383
Ref: 56b755383
Node: threaded_peek/1-2755898
Ref: refman/predicates/threaded_peek_1_2 doc756038
Ref: 56c756038
Ref: refman/predicates/threaded_peek_1_2 predicates-threaded-peek-1-2756038
Ref: 214756038
Ref: refman/predicates/threaded_peek_1_2 threaded-peek-1-2756038
Ref: 56d756038
Node: Description<72>756253
Ref: refman/predicates/threaded_peek_1_2 description756380
Ref: 56e756380
Node: Modes and number of proofs<36>757544
Ref: refman/predicates/threaded_peek_1_2 modes-and-number-of-proofs757690
Ref: 56f757690
Node: Errors<37>757861
Ref: refman/predicates/threaded_peek_1_2 errors758004
Ref: 570758004
Node: Examples<73>758279
Ref: refman/predicates/threaded_peek_1_2 examples758383
Ref: 571758383
Node: threaded_cancel/1758901
Ref: refman/predicates/threaded_cancel_1 doc759039
Ref: 572759039
Ref: refman/predicates/threaded_cancel_1 predicates-threaded-cancel-1759039
Ref: 215759039
Ref: refman/predicates/threaded_cancel_1 threaded-cancel-1759039
Ref: 573759039
Node: Description<73>759254
Ref: refman/predicates/threaded_cancel_1 description759381
Ref: 574759381
Node: Modes and number of proofs<37>760091
Ref: refman/predicates/threaded_cancel_1 modes-and-number-of-proofs760237
Ref: 575760237
Node: Errors<38>760347
Ref: refman/predicates/threaded_cancel_1 errors760490
Ref: 576760490
Node: Examples<74>760592
Ref: refman/predicates/threaded_cancel_1 examples760696
Ref: 577760696
Node: threaded_wait/1760904
Ref: refman/predicates/threaded_wait_1 doc761042
Ref: 578761042
Ref: refman/predicates/threaded_wait_1 predicates-threaded-wait-1761042
Ref: 21c761042
Ref: refman/predicates/threaded_wait_1 threaded-wait-1761042
Ref: 579761042
Node: Description<74>761253
Ref: refman/predicates/threaded_wait_1 description761378
Ref: 57a761378
Node: Modes and number of proofs<38>762174
Ref: refman/predicates/threaded_wait_1 modes-and-number-of-proofs762318
Ref: 57b762318
Node: Errors<39>762462
Ref: refman/predicates/threaded_wait_1 errors762603
Ref: 57c762603
Node: Examples<75>762644
Ref: refman/predicates/threaded_wait_1 examples762746
Ref: 57d762746
Node: threaded_notify/1762944
Ref: refman/predicates/threaded_notify_1 doc763056
Ref: 57e763056
Ref: refman/predicates/threaded_notify_1 predicates-threaded-notify-1763056
Ref: 21d763056
Ref: refman/predicates/threaded_notify_1 threaded-notify-1763056
Ref: 57f763056
Node: Description<75>763271
Ref: refman/predicates/threaded_notify_1 description763398
Ref: 580763398
Node: Modes and number of proofs<39>764194
Ref: refman/predicates/threaded_notify_1 modes-and-number-of-proofs764340
Ref: 581764340
Node: Errors<40>764488
Ref: refman/predicates/threaded_notify_1 errors764631
Ref: 582764631
Node: Examples<76>764672
Ref: refman/predicates/threaded_notify_1 examples764776
Ref: 583764776
Node: Multi-threading engines764954
Ref: refman/predicates/engine_predicates doc765119
Ref: 584765119
Ref: refman/predicates/engine_predicates engine-predicates765119
Ref: 585765119
Ref: refman/predicates/engine_predicates multi-threading-engines765119
Ref: 586765119
Node: threaded_engine_create/3765443
Ref: refman/predicates/threaded_engine_create_3 doc765580
Ref: 587765580
Ref: refman/predicates/threaded_engine_create_3 predicates-threaded-engine-create-3765580
Ref: 220765580
Ref: refman/predicates/threaded_engine_create_3 threaded-engine-create-3765580
Ref: 588765580
Node: Description<76>765807
Ref: refman/predicates/threaded_engine_create_3 description765941
Ref: 589765941
Node: Modes and number of proofs<40>766644
Ref: refman/predicates/threaded_engine_create_3 modes-and-number-of-proofs766797
Ref: 58a766797
Node: Errors<41>766992
Ref: refman/predicates/threaded_engine_create_3 errors767142
Ref: 58b767142
Node: Examples<77>767459
Ref: refman/predicates/threaded_engine_create_3 examples767570
Ref: 58c767570
Node: threaded_engine_destroy/1767932
Ref: refman/predicates/threaded_engine_destroy_1 doc768095
Ref: 58f768095
Ref: refman/predicates/threaded_engine_destroy_1 predicates-threaded-engine-destroy-1768095
Ref: 223768095
Ref: refman/predicates/threaded_engine_destroy_1 threaded-engine-destroy-1768095
Ref: 590768095
Node: Description<77>768324
Ref: refman/predicates/threaded_engine_destroy_1 description768459
Ref: 591768459
Node: Modes and number of proofs<41>768808
Ref: refman/predicates/threaded_engine_destroy_1 modes-and-number-of-proofs768962
Ref: 592768962
Node: Errors<42>769078
Ref: refman/predicates/threaded_engine_destroy_1 errors769229
Ref: 593769229
Node: Examples<78>769458
Ref: refman/predicates/threaded_engine_destroy_1 examples769570
Ref: 594769570
Node: threaded_engine/1769950
Ref: refman/predicates/threaded_engine_1 doc770111
Ref: 595770111
Ref: refman/predicates/threaded_engine_1 predicates-threaded-engine-1770111
Ref: 58e770111
Ref: refman/predicates/threaded_engine_1 threaded-engine-1770111
Ref: 596770111
Node: Description<78>770326
Ref: refman/predicates/threaded_engine_1 description770453
Ref: 597770453
Node: Modes and number of proofs<42>770900
Ref: refman/predicates/threaded_engine_1 modes-and-number-of-proofs771046
Ref: 598771046
Node: Errors<43>771165
Ref: refman/predicates/threaded_engine_1 errors771308
Ref: 599771308
Node: Examples<79>771349
Ref: refman/predicates/threaded_engine_1 examples771453
Ref: 59a771453
Node: threaded_engine_self/1771858
Ref: refman/predicates/threaded_engine_self_1 doc772016
Ref: 59b772016
Ref: refman/predicates/threaded_engine_self_1 predicates-threaded-engine-self-1772016
Ref: 58d772016
Ref: refman/predicates/threaded_engine_self_1 threaded-engine-self-1772016
Ref: 59c772016
Node: Description<79>772241
Ref: refman/predicates/threaded_engine_self_1 description772373
Ref: 59d772373
Node: Modes and number of proofs<43>772741
Ref: refman/predicates/threaded_engine_self_1 modes-and-number-of-proofs772892
Ref: 59e772892
Node: Errors<44>773015
Ref: refman/predicates/threaded_engine_self_1 errors773163
Ref: 59f773163
Node: Examples<80>773204
Ref: refman/predicates/threaded_engine_self_1 examples773313
Ref: 5a0773313
Node: threaded_engine_next/2773681
Ref: refman/predicates/threaded_engine_next_2 doc773852
Ref: 5a1773852
Ref: refman/predicates/threaded_engine_next_2 predicates-threaded-engine-next-2773852
Ref: 221773852
Ref: refman/predicates/threaded_engine_next_2 threaded-engine-next-2773852
Ref: 5a2773852
Node: Description<80>774077
Ref: refman/predicates/threaded_engine_next_2 description774209
Ref: 5a3774209
Node: Modes and number of proofs<44>774875
Ref: refman/predicates/threaded_engine_next_2 modes-and-number-of-proofs775026
Ref: 5a4775026
Node: Errors<45>775156
Ref: refman/predicates/threaded_engine_next_2 errors775304
Ref: 5a5775304
Node: Examples<81>775535
Ref: refman/predicates/threaded_engine_next_2 examples775644
Ref: 5a6775644
Node: threaded_engine_next_reified/2775921
Ref: refman/predicates/threaded_engine_next_reified_2 doc776093
Ref: 5a7776093
Ref: refman/predicates/threaded_engine_next_reified_2 predicates-threaded-engine-next-reified-2776093
Ref: 222776093
Ref: refman/predicates/threaded_engine_next_reified_2 threaded-engine-next-reified-2776093
Ref: 5a8776093
Node: Description<81>776334
Ref: refman/predicates/threaded_engine_next_reified_2 description776474
Ref: 5a9776474
Node: Modes and number of proofs<45>777067
Ref: refman/predicates/threaded_engine_next_reified_2 modes-and-number-of-proofs777226
Ref: 5aa777226
Node: Errors<46>777358
Ref: refman/predicates/threaded_engine_next_reified_2 errors777514
Ref: 5ab777514
Node: Examples<82>777745
Ref: refman/predicates/threaded_engine_next_reified_2 examples777862
Ref: 5ac777862
Node: threaded_engine_yield/1778147
Ref: refman/predicates/threaded_engine_yield_1 doc778319
Ref: 5ad778319
Ref: refman/predicates/threaded_engine_yield_1 predicates-threaded-engine-yield-1778319
Ref: 226778319
Ref: refman/predicates/threaded_engine_yield_1 threaded-engine-yield-1778319
Ref: 5ae778319
Node: Description<82>778546
Ref: refman/predicates/threaded_engine_yield_1 description778679
Ref: 5af778679
Node: Modes and number of proofs<46>779598
Ref: refman/predicates/threaded_engine_yield_1 modes-and-number-of-proofs779750
Ref: 5b0779750
Node: Errors<47>779872
Ref: refman/predicates/threaded_engine_yield_1 errors780021
Ref: 5b1780021
Node: Examples<83>780062
Ref: refman/predicates/threaded_engine_yield_1 examples780172
Ref: 5b2780172
Node: threaded_engine_post/2780442
Ref: refman/predicates/threaded_engine_post_2 doc780607
Ref: 5b3780607
Ref: refman/predicates/threaded_engine_post_2 predicates-threaded-engine-post-2780607
Ref: 225780607
Ref: refman/predicates/threaded_engine_post_2 threaded-engine-post-2780607
Ref: 5b4780607
Node: Description<83>780832
Ref: refman/predicates/threaded_engine_post_2 description780964
Ref: 5b5780964
Node: Modes and number of proofs<47>781327
Ref: refman/predicates/threaded_engine_post_2 modes-and-number-of-proofs781478
Ref: 5b6781478
Node: Errors<48>781600
Ref: refman/predicates/threaded_engine_post_2 errors781748
Ref: 5b7781748
Node: Examples<84>781979
Ref: refman/predicates/threaded_engine_post_2 examples782088
Ref: 5b8782088
Node: threaded_engine_fetch/1782290
Ref: refman/predicates/threaded_engine_fetch_1 doc782423
Ref: 5b9782423
Ref: refman/predicates/threaded_engine_fetch_1 predicates-threaded-engine-fetch-1782423
Ref: 224782423
Ref: refman/predicates/threaded_engine_fetch_1 threaded-engine-fetch-1782423
Ref: 5ba782423
Node: Description<84>782650
Ref: refman/predicates/threaded_engine_fetch_1 description782783
Ref: 5bb782783
Node: Modes and number of proofs<48>783222
Ref: refman/predicates/threaded_engine_fetch_1 modes-and-number-of-proofs783374
Ref: 5bc783374
Node: Errors<49>783496
Ref: refman/predicates/threaded_engine_fetch_1 errors783645
Ref: 5bd783645
Node: Examples<85>783686
Ref: refman/predicates/threaded_engine_fetch_1 examples783796
Ref: 5be783796
Node: Compiling and loading source files783980
Ref: refman/predicates/compiling_predicates doc784135
Ref: 5bf784135
Ref: refman/predicates/compiling_predicates compiling-and-loading-source-files784135
Ref: 5c0784135
Ref: refman/predicates/compiling_predicates compiling-predicates784135
Ref: 43784135
Node: logtalk_compile/1784435
Ref: refman/predicates/logtalk_compile_1 doc784568
Ref: 5c1784568
Ref: refman/predicates/logtalk_compile_1 logtalk-compile-1784568
Ref: 5c2784568
Ref: refman/predicates/logtalk_compile_1 predicates-logtalk-compile-1784568
Ref: 27f784568
Node: Description<85>784781
Ref: refman/predicates/logtalk_compile_1 description784908
Ref: 5c3784908
Node: Modes and number of proofs<49>786430
Ref: refman/predicates/logtalk_compile_1 modes-and-number-of-proofs786576
Ref: 5c5786576
Node: Errors<50>786762
Ref: refman/predicates/logtalk_compile_1 errors786905
Ref: 5c6786905
Node: Examples<86>787588
Ref: refman/predicates/logtalk_compile_1 examples787692
Ref: 5c7787692
Node: logtalk_compile/2788290
Ref: refman/predicates/logtalk_compile_2 doc788446
Ref: 5c8788446
Ref: refman/predicates/logtalk_compile_2 logtalk-compile-2788446
Ref: 5c9788446
Ref: refman/predicates/logtalk_compile_2 predicates-logtalk-compile-2788446
Ref: 292788446
Node: Description<86>788659
Ref: refman/predicates/logtalk_compile_2 description788786
Ref: 5ca788786
Node: Modes and number of proofs<50>790788
Ref: refman/predicates/logtalk_compile_2 modes-and-number-of-proofs790934
Ref: 5cb790934
Node: Errors<51>791164
Ref: refman/predicates/logtalk_compile_2 errors791307
Ref: 5cc791307
Node: Examples<87>792646
Ref: refman/predicates/logtalk_compile_2 examples792750
Ref: 5cd792750
Node: logtalk_load/1793495
Ref: refman/predicates/logtalk_load_1 doc793648
Ref: 5ce793648
Ref: refman/predicates/logtalk_load_1 logtalk-load-1793648
Ref: 5cf793648
Ref: refman/predicates/logtalk_load_1 predicates-logtalk-load-1793648
Ref: 44793648
Node: Description<87>793857
Ref: refman/predicates/logtalk_load_1 description793981
Ref: 5d0793981
Node: Modes and number of proofs<51>795611
Ref: refman/predicates/logtalk_load_1 modes-and-number-of-proofs795754
Ref: 5d1795754
Node: Errors<52>795936
Ref: refman/predicates/logtalk_load_1 errors796076
Ref: 5d2796076
Node: Examples<88>796762
Ref: refman/predicates/logtalk_load_1 examples796863
Ref: 5d3796863
Node: logtalk_load/2797464
Ref: refman/predicates/logtalk_load_2 doc797614
Ref: 5d4797614
Ref: refman/predicates/logtalk_load_2 logtalk-load-2797614
Ref: 5d5797614
Ref: refman/predicates/logtalk_load_2 predicates-logtalk-load-2797614
Ref: 284797614
Node: Description<88>797823
Ref: refman/predicates/logtalk_load_2 description797947
Ref: 5d6797947
Node: Modes and number of proofs<52>799956
Ref: refman/predicates/logtalk_load_2 modes-and-number-of-proofs800099
Ref: 5d7800099
Node: Errors<53>800325
Ref: refman/predicates/logtalk_load_2 errors800465
Ref: 5d8800465
Node: Examples<89>801794
Ref: refman/predicates/logtalk_load_2 examples801895
Ref: 5d9801895
Node: logtalk_make/0802618
Ref: refman/predicates/logtalk_make_0 doc802768
Ref: 5da802768
Ref: refman/predicates/logtalk_make_0 logtalk-make-0802768
Ref: 5db802768
Ref: refman/predicates/logtalk_make_0 predicates-logtalk-make-0802768
Ref: 280802768
Node: Description<89>802977
Ref: refman/predicates/logtalk_make_0 description803101
Ref: 5dc803101
Node: Modes and number of proofs<53>804431
Ref: refman/predicates/logtalk_make_0 modes-and-number-of-proofs804574
Ref: 5de804574
Node: Errors<54>804672
Ref: refman/predicates/logtalk_make_0 errors804812
Ref: 5df804812
Node: Examples<90>804853
Ref: refman/predicates/logtalk_make_0 examples804954
Ref: 5e0804954
Node: logtalk_make/1805269
Ref: refman/predicates/logtalk_make_1 doc805433
Ref: 5e1805433
Ref: refman/predicates/logtalk_make_1 logtalk-make-1805433
Ref: 5e2805433
Ref: refman/predicates/logtalk_make_1 predicates-logtalk-make-1805433
Ref: 281805433
Node: Description<90>805642
Ref: refman/predicates/logtalk_make_1 description805766
Ref: 5e3805766
Ref: Description<90>-Footnote-1809900
Node: Modes and number of proofs<54>809953
Ref: refman/predicates/logtalk_make_1 modes-and-number-of-proofs810096
Ref: 5e5810096
Node: Errors<55>810209
Ref: refman/predicates/logtalk_make_1 errors810349
Ref: 5e6810349
Node: Examples<91>810390
Ref: refman/predicates/logtalk_make_1 examples810491
Ref: 5e7810491
Node: logtalk_make_target_action/1811029
Ref: refman/predicates/logtalk_make_target_action_1 doc811201
Ref: 5e8811201
Ref: refman/predicates/logtalk_make_target_action_1 logtalk-make-target-action-1811201
Ref: 5e9811201
Ref: refman/predicates/logtalk_make_target_action_1 predicates-logtalk-make-target-action-1811201
Ref: 5dd811201
Node: Description<91>811438
Ref: refman/predicates/logtalk_make_target_action_1 description811576
Ref: 5ea811576
Node: Modes and number of proofs<55>811949
Ref: refman/predicates/logtalk_make_target_action_1 modes-and-number-of-proofs812106
Ref: 5eb812106
Node: Errors<56>812234
Ref: refman/predicates/logtalk_make_target_action_1 errors812388
Ref: 5ec812388
Node: Examples<92>812429
Ref: refman/predicates/logtalk_make_target_action_1 examples812544
Ref: 5ed812544
Node: logtalk_library_path/2812893
Ref: refman/predicates/logtalk_library_path_2 doc813073
Ref: 5ee813073
Ref: refman/predicates/logtalk_library_path_2 logtalk-library-path-2813073
Ref: 5ef813073
Ref: refman/predicates/logtalk_library_path_2 predicates-logtalk-library-path-2813073
Ref: 287813073
Node: Description<92>813298
Ref: refman/predicates/logtalk_library_path_2 description813430
Ref: 5f0813430
Ref: Description<92>-Footnote-1815566
Node: Modes and number of proofs<56>815635
Ref: refman/predicates/logtalk_library_path_2 modes-and-number-of-proofs815786
Ref: 5f1815786
Node: Errors<57>815974
Ref: refman/predicates/logtalk_library_path_2 errors816122
Ref: 5f2816122
Node: Examples<93>816163
Ref: refman/predicates/logtalk_library_path_2 examples816272
Ref: 5f3816272
Node: logtalk_load_context/2817386
Ref: refman/predicates/logtalk_load_context_2 doc817529
Ref: 5f4817529
Ref: refman/predicates/logtalk_load_context_2 logtalk-load-context-2817529
Ref: 5f5817529
Ref: refman/predicates/logtalk_load_context_2 predicates-logtalk-load-context-2817529
Ref: 2ee817529
Node: Description<93>817754
Ref: refman/predicates/logtalk_load_context_2 description817886
Ref: 5f6817886
Node: Modes and number of proofs<57>820687
Ref: refman/predicates/logtalk_load_context_2 modes-and-number-of-proofs820838
Ref: 5f8820838
Node: Errors<58>820969
Ref: refman/predicates/logtalk_load_context_2 errors821117
Ref: 5f9821117
Node: Examples<94>821158
Ref: refman/predicates/logtalk_load_context_2 examples821267
Ref: 5fa821267
Node: Flags821656
Ref: refman/predicates/flag_predicates doc821794
Ref: 5fb821794
Ref: refman/predicates/flag_predicates flag-predicates821794
Ref: 5fc821794
Ref: refman/predicates/flag_predicates flags821794
Ref: 5fd821794
Node: current_logtalk_flag/2821929
Ref: refman/predicates/current_logtalk_flag_2 doc822042
Ref: 5fe822042
Ref: refman/predicates/current_logtalk_flag_2 current-logtalk-flag-2822042
Ref: 5ff822042
Ref: refman/predicates/current_logtalk_flag_2 predicates-current-logtalk-flag-2822042
Ref: 293822042
Node: Description<94>822267
Ref: refman/predicates/current_logtalk_flag_2 description822399
Ref: 600822399
Node: Modes and number of proofs<58>822668
Ref: refman/predicates/current_logtalk_flag_2 modes-and-number-of-proofs822819
Ref: 601822819
Node: Errors<59>822948
Ref: refman/predicates/current_logtalk_flag_2 errors823096
Ref: 602823096
Node: Examples<95>823314
Ref: refman/predicates/current_logtalk_flag_2 examples823423
Ref: 603823423
Node: set_logtalk_flag/2<2>823651
Ref: refman/predicates/set_logtalk_flag_2 doc823794
Ref: 604823794
Ref: refman/predicates/set_logtalk_flag_2 predicates-set-logtalk-flag-2823794
Ref: 4c823794
Ref: refman/predicates/set_logtalk_flag_2 set-logtalk-flag-2823794
Ref: 605823794
Node: Description<95>824011
Ref: refman/predicates/set_logtalk_flag_2 description824142
Ref: 606824142
Node: Modes and number of proofs<59>824624
Ref: refman/predicates/set_logtalk_flag_2 modes-and-number-of-proofs824774
Ref: 607824774
Node: Errors<60>824892
Ref: refman/predicates/set_logtalk_flag_2 errors825039
Ref: 608825039
Node: Examples<96>825603
Ref: refman/predicates/set_logtalk_flag_2 examples825711
Ref: 609825711
Node: create_logtalk_flag/3825981
Ref: refman/predicates/create_logtalk_flag_3 doc826093
Ref: 60a826093
Ref: refman/predicates/create_logtalk_flag_3 create-logtalk-flag-3826093
Ref: 60b826093
Ref: refman/predicates/create_logtalk_flag_3 predicates-create-logtalk-flag-3826093
Ref: 2c0826093
Node: Description<96>826318
Ref: refman/predicates/create_logtalk_flag_3 description826449
Ref: 60c826449
Node: Modes and number of proofs<60>827649
Ref: refman/predicates/create_logtalk_flag_3 modes-and-number-of-proofs827799
Ref: 60d827799
Node: Errors<61>827937
Ref: refman/predicates/create_logtalk_flag_3 errors828084
Ref: 60e828084
Node: Examples<97>829001
Ref: refman/predicates/create_logtalk_flag_3 examples829109
Ref: 60f829109
Node: Linter829362
Ref: refman/predicates/linter_predicates doc829457
Ref: 610829457
Ref: refman/predicates/linter_predicates linter829457
Ref: 611829457
Ref: refman/predicates/linter_predicates linter-predicates829457
Ref: 612829457
Node: logtalk_linter_hook/7829522
Ref: refman/predicates/logtalk_linter_hook_7 doc829605
Ref: 613829605
Ref: refman/predicates/logtalk_linter_hook_7 logtalk-linter-hook-7829605
Ref: 614829605
Ref: refman/predicates/logtalk_linter_hook_7 predicates-logtalk-linter-hook-7829605
Ref: 615829605
Node: Description<97>829828
Ref: refman/predicates/logtalk_linter_hook_7 description829959
Ref: 616829959
Node: Modes and number of proofs<61>830481
Ref: refman/predicates/logtalk_linter_hook_7 modes-and-number-of-proofs830631
Ref: 617830631
Node: Errors<62>830825
Ref: refman/predicates/logtalk_linter_hook_7 errors830972
Ref: 618830972
Node: Examples<98>831013
Ref: refman/predicates/logtalk_linter_hook_7 examples831121
Ref: 619831121
Node: Built-in methods<2>831551
Ref: refman/methods/index doc831670
Ref: 61a831670
Ref: refman/methods/index built-in-methods831670
Ref: 61b831670
Node: Execution context832102
Ref: refman/methods/context_methods doc832216
Ref: 61c832216
Ref: refman/methods/context_methods context-methods832216
Ref: 61d832216
Ref: refman/methods/context_methods execution-context832216
Ref: 61e832216
Node: context/1832340
Ref: refman/methods/context_1 doc832442
Ref: 61f832442
Ref: refman/methods/context_1 context-1832442
Ref: 620832442
Ref: refman/methods/context_1 methods-context-1832442
Ref: 182832442
Node: Description<98>832639
Ref: refman/methods/context_1 description832758
Ref: 621832758
Ref: Description<98>-Footnote-1833348
Node: Modes and number of proofs<62>833415
Ref: refman/methods/context_1 modes-and-number-of-proofs833553
Ref: 622833553
Node: Errors<63>833656
Ref: refman/methods/context_1 errors833791
Ref: 623833791
Node: Examples<99>833904
Ref: refman/methods/context_1 examples834000
Ref: 624834000
Node: parameter/2834351
Ref: refman/methods/parameter_2 doc834468
Ref: 625834468
Ref: refman/methods/parameter_2 methods-parameter-2834468
Ref: 9c834468
Ref: refman/methods/parameter_2 parameter-2834468
Ref: 626834468
Node: Description<99>834670
Ref: refman/methods/parameter_2 description834791
Ref: 627834791
Node: Modes and number of proofs<63>835835
Ref: refman/methods/parameter_2 modes-and-number-of-proofs835975
Ref: 629835975
Node: Errors<64>836093
Ref: refman/methods/parameter_2 errors836231
Ref: 62a836231
Node: Examples<100>836689
Ref: refman/methods/parameter_2 examples836788
Ref: 62b836788
Node: self/1837492
Ref: refman/methods/self_1 doc837608
Ref: 62c837608
Ref: refman/methods/self_1 methods-self-1837608
Ref: 62837608
Ref: refman/methods/self_1 self-1837608
Ref: 62d837608
Node: Description<100>837803
Ref: refman/methods/self_1 description837920
Ref: 62e837920
Node: Modes and number of proofs<64>838316
Ref: refman/methods/self_1 modes-and-number-of-proofs838452
Ref: 62f838452
Node: Errors<65>838570
Ref: refman/methods/self_1 errors838703
Ref: 630838703
Node: Examples<101>838744
Ref: refman/methods/self_1 examples838838
Ref: 631838838
Node: sender/1839184
Ref: refman/methods/sender_1 doc839295
Ref: 632839295
Ref: refman/methods/sender_1 methods-sender-1839295
Ref: 181839295
Ref: refman/methods/sender_1 sender-1839295
Ref: 633839295
Node: Description<101>839494
Ref: refman/methods/sender_1 description839613
Ref: 634839613
Node: Modes and number of proofs<65>840011
Ref: refman/methods/sender_1 modes-and-number-of-proofs840149
Ref: 635840149
Node: Errors<66>840269
Ref: refman/methods/sender_1 errors840404
Ref: 636840404
Node: Examples<102>840445
Ref: refman/methods/sender_1 examples840541
Ref: 637840541
Node: this/1840906
Ref: refman/methods/this_1 doc841002
Ref: 638841002
Ref: refman/methods/this_1 methods-this-1841002
Ref: 63841002
Ref: refman/methods/this_1 this-1841002
Ref: 639841002
Node: Description<102>841197
Ref: refman/methods/this_1 description841314
Ref: 63a841314
Node: Modes and number of proofs<66>842028
Ref: refman/methods/this_1 modes-and-number-of-proofs842164
Ref: 63b842164
Node: Errors<67>842282
Ref: refman/methods/this_1 errors842415
Ref: 63c842415
Node: Examples<103>842456
Ref: refman/methods/this_1 examples842550
Ref: 63d842550
Node: Reflection<2>842903
Ref: refman/methods/reflection_methods doc843034
Ref: 63e843034
Ref: refman/methods/reflection_methods reflection843034
Ref: 63f843034
Ref: refman/methods/reflection_methods reflection-methods843034
Ref: 6b843034
Node: current_op/3843145
Ref: refman/methods/current_op_3 doc843254
Ref: 640843254
Ref: refman/methods/current_op_3 current-op-3843254
Ref: 641843254
Ref: refman/methods/current_op_3 methods-current-op-3843254
Ref: 14d843254
Node: Description<103>843459
Ref: refman/methods/current_op_3 description843582
Ref: 642843582
Node: Modes and number of proofs<67>843815
Ref: refman/methods/current_op_3 modes-and-number-of-proofs843957
Ref: 643843957
Node: Errors<68>844108
Ref: refman/methods/current_op_3 errors844247
Ref: 644844247
Node: Examples<104>844846
Ref: refman/methods/current_op_3 examples844946
Ref: 645844946
Node: current_predicate/1845564
Ref: refman/methods/current_predicate_1 doc845702
Ref: 646845702
Ref: refman/methods/current_predicate_1 current-predicate-1845702
Ref: 647845702
Ref: refman/methods/current_predicate_1 methods-current-predicate-1845702
Ref: 136845702
Node: Description<104>845921
Ref: refman/methods/current_predicate_1 description846051
Ref: 648846051
Node: Modes and number of proofs<68>846641
Ref: refman/methods/current_predicate_1 modes-and-number-of-proofs846790
Ref: 649846790
Node: Errors<69>846922
Ref: refman/methods/current_predicate_1 errors847068
Ref: 64a847068
Node: Examples<105>847671
Ref: refman/methods/current_predicate_1 examples847778
Ref: 64b847778
Node: predicate_property/2848411
Ref: refman/methods/predicate_property_2 doc848528
Ref: 64c848528
Ref: refman/methods/predicate_property_2 methods-predicate-property-2848528
Ref: 137848528
Ref: refman/methods/predicate_property_2 predicate-property-2848528
Ref: 64d848528
Node: Description<105>848751
Ref: refman/methods/predicate_property_2 description848882
Ref: 64e848882
Node: Modes and number of proofs<69>849739
Ref: refman/methods/predicate_property_2 modes-and-number-of-proofs849889
Ref: 64f849889
Node: Errors<70>850034
Ref: refman/methods/predicate_property_2 errors850181
Ref: 650850181
Node: Examples<106>850538
Ref: refman/methods/predicate_property_2 examples850646
Ref: 651850646
Node: Database851341
Ref: refman/methods/database_methods doc851465
Ref: 652851465
Ref: refman/methods/database_methods database851465
Ref: 653851465
Ref: refman/methods/database_methods database-methods851465
Ref: 654851465
Node: abolish/1851592
Ref: refman/methods/abolish_1 doc851683
Ref: 655851683
Ref: refman/methods/abolish_1 abolish-1851683
Ref: 656851683
Ref: refman/methods/abolish_1 methods-abolish-1851683
Ref: 195851683
Node: Description<106>851882
Ref: refman/methods/abolish_1 description852002
Ref: 657852002
Node: Modes and number of proofs<70>852602
Ref: refman/methods/abolish_1 modes-and-number-of-proofs852741
Ref: 658852741
Node: Errors<71>852854
Ref: refman/methods/abolish_1 errors852990
Ref: 659852990
Node: Examples<107>854199
Ref: refman/methods/abolish_1 examples854296
Ref: 65a854296
Node: asserta/1854898
Ref: refman/methods/asserta_1 doc855007
Ref: 65b855007
Ref: refman/methods/asserta_1 asserta-1855007
Ref: 65c855007
Ref: refman/methods/asserta_1 methods-asserta-1855007
Ref: 196855007
Node: Description<107>855206
Ref: refman/methods/asserta_1 description855326
Ref: 65d855326
Node: Modes and number of proofs<71>856329
Ref: refman/methods/asserta_1 modes-and-number-of-proofs856468
Ref: 65e856468
Node: Errors<72>856568
Ref: refman/methods/asserta_1 errors856704
Ref: 65f856704
Node: Examples<108>857794
Ref: refman/methods/asserta_1 examples857891
Ref: 660857891
Node: assertz/1858577
Ref: refman/methods/assertz_1 doc858685
Ref: 661858685
Ref: refman/methods/assertz_1 assertz-1858685
Ref: 662858685
Ref: refman/methods/assertz_1 methods-assertz-1858685
Ref: 197858685
Node: Description<108>858886
Ref: refman/methods/assertz_1 description859006
Ref: 663859006
Node: Modes and number of proofs<72>860002
Ref: refman/methods/assertz_1 modes-and-number-of-proofs860141
Ref: 664860141
Node: Errors<73>860243
Ref: refman/methods/assertz_1 errors860379
Ref: 665860379
Node: Examples<109>861468
Ref: refman/methods/assertz_1 examples861565
Ref: 666861565
Node: clause/2862248
Ref: refman/methods/clause_2 doc862356
Ref: 667862356
Ref: refman/methods/clause_2 clause-2862356
Ref: 668862356
Ref: refman/methods/clause_2 methods-clause-2862356
Ref: 198862356
Node: Description<109>862555
Ref: refman/methods/clause_2 description862674
Ref: 669862674
Node: Modes and number of proofs<73>863280
Ref: refman/methods/clause_2 modes-and-number-of-proofs863418
Ref: 66a863418
Node: Errors<74>863537
Ref: refman/methods/clause_2 errors863672
Ref: 66b863672
Node: Examples<110>864607
Ref: refman/methods/clause_2 examples864703
Ref: 66c864703
Node: retract/1865374
Ref: refman/methods/retract_1 doc865485
Ref: 66d865485
Ref: refman/methods/retract_1 methods-retract-1865485
Ref: 199865485
Ref: refman/methods/retract_1 retract-1865485
Ref: 66e865485
Node: Description<110>865686
Ref: refman/methods/retract_1 description865806
Ref: 66f865806
Node: Modes and number of proofs<74>866477
Ref: refman/methods/retract_1 modes-and-number-of-proofs866616
Ref: 670866616
Node: Errors<75>866727
Ref: refman/methods/retract_1 errors866863
Ref: 671866863
Node: Examples<111>867724
Ref: refman/methods/retract_1 examples867821
Ref: 672867821
Node: retractall/1868450
Ref: refman/methods/retractall_1 doc868544
Ref: 673868544
Ref: refman/methods/retractall_1 methods-retractall-1868544
Ref: 19a868544
Ref: refman/methods/retractall_1 retractall-1868544
Ref: 674868544
Node: Description<111>868751
Ref: refman/methods/retractall_1 description868874
Ref: 675868874
Node: Modes and number of proofs<75>869480
Ref: refman/methods/retractall_1 modes-and-number-of-proofs869622
Ref: 676869622
Node: Errors<76>869729
Ref: refman/methods/retractall_1 errors869868
Ref: 677869868
Node: Examples<112>870729
Ref: refman/methods/retractall_1 examples870829
Ref: 678870829
Node: Meta-calls871503
Ref: refman/methods/meta_call_methods doc871631
Ref: 679871631
Ref: refman/methods/meta_call_methods meta-call-methods871631
Ref: 67a871631
Ref: refman/methods/meta_call_methods meta-calls871631
Ref: 67b871631
Node: call/1-N871723
Ref: refman/methods/call_N doc871814
Ref: 67c871814
Ref: refman/methods/call_N call-1-n871814
Ref: 67d871814
Ref: refman/methods/call_N methods-call-n871814
Ref: 16d871814
Node: Description<112>872011
Ref: refman/methods/call_N description872130
Ref: 67e872130
Node: Modes and number of proofs<76>872837
Ref: refman/methods/call_N modes-and-number-of-proofs872975
Ref: 67f872975
Node: Errors<77>873185
Ref: refman/methods/call_N errors873320
Ref: 680873320
Node: Examples<113>873707
Ref: refman/methods/call_N examples873803
Ref: 681873803
Node: ignore/1874445
Ref: refman/methods/ignore_1 doc874551
Ref: 682874551
Ref: refman/methods/ignore_1 ignore-1874551
Ref: 683874551
Ref: refman/methods/ignore_1 methods-ignore-1874551
Ref: 16c874551
Node: Description<113>874748
Ref: refman/methods/ignore_1 description874867
Ref: 684874867
Node: Modes and number of proofs<77>875189
Ref: refman/methods/ignore_1 modes-and-number-of-proofs875327
Ref: 685875327
Node: Errors<78>875428
Ref: refman/methods/ignore_1 errors875563
Ref: 686875563
Node: Examples<114>875768
Ref: refman/methods/ignore_1 examples875864
Ref: 687875864
Node: once/1876278
Ref: refman/methods/once_1 doc876381
Ref: 688876381
Ref: refman/methods/once_1 methods-once-1876381
Ref: 19e876381
Ref: refman/methods/once_1 once-1876381
Ref: 689876381
Node: Description<114>876576
Ref: refman/methods/once_1 description876693
Ref: 68a876693
Node: Modes and number of proofs<78>876994
Ref: refman/methods/once_1 modes-and-number-of-proofs877130
Ref: 68b877130
Node: Errors<79>877239
Ref: refman/methods/once_1 errors877372
Ref: 68c877372
Node: Examples<115>877579
Ref: refman/methods/once_1 examples877673
Ref: 68d877673
Node: \\+/1878128
Ref: refman/methods/not_1 doc878214
Ref: 68e878214
Ref: refman/methods/not_1 id1878214
Ref: 68f878214
Ref: refman/methods/not_1 methods-not-1878214
Ref: 19f878214
Node: Description<115>878407
Ref: refman/methods/not_1 description878523
Ref: 690878523
Node: Modes and number of proofs<79>878760
Ref: refman/methods/not_1 modes-and-number-of-proofs878895
Ref: 691878895
Node: Errors<80>879001
Ref: refman/methods/not_1 errors879133
Ref: 692879133
Node: Examples<116>879340
Ref: refman/methods/not_1 examples879433
Ref: 693879433
Node: Error handling<2>879850
Ref: refman/methods/error_handling_methods doc879983
Ref: 694879983
Ref: refman/methods/error_handling_methods error-handling879983
Ref: 695879983
Ref: refman/methods/error_handling_methods error-handling-methods879983
Ref: 22d879983
Node: catch/3880304
Ref: refman/methods/catch_3 doc880400
Ref: 696880400
Ref: refman/methods/catch_3 catch-3880400
Ref: 697880400
Ref: refman/methods/catch_3 methods-catch-3880400
Ref: 185880400
Node: Description<116>880595
Ref: refman/methods/catch_3 description880713
Ref: 698880713
Node: Modes and number of proofs<80>880983
Ref: refman/methods/catch_3 modes-and-number-of-proofs881120
Ref: 699881120
Node: Errors<81>881247
Ref: refman/methods/catch_3 errors881381
Ref: 69a881381
Node: Examples<117>881420
Ref: refman/methods/catch_3 examples881515
Ref: 69b881515
Node: throw/1881952
Ref: refman/methods/throw_1 doc882078
Ref: 69c882078
Ref: refman/methods/throw_1 methods-throw-1882078
Ref: 186882078
Ref: refman/methods/throw_1 throw-1882078
Ref: 69d882078
Node: Description<117>882273
Ref: refman/methods/throw_1 description882391
Ref: 69e882391
Node: Modes and number of proofs<81>882570
Ref: refman/methods/throw_1 modes-and-number-of-proofs882707
Ref: 69f882707
Node: Errors<82>882807
Ref: refman/methods/throw_1 errors882941
Ref: 6a0882941
Node: Examples<118>883175
Ref: refman/methods/throw_1 examples883270
Ref: 6a1883270
Node: instantiation_error/0883709
Ref: refman/methods/instantiation_error_0 doc883851
Ref: 6a2883851
Ref: refman/methods/instantiation_error_0 instantiation-error-0883851
Ref: 6a3883851
Ref: refman/methods/instantiation_error_0 methods-instantiation-error-0883851
Ref: 187883851
Node: Description<118>884076
Ref: refman/methods/instantiation_error_0 description884208
Ref: 6a4884208
Node: Modes and number of proofs<82>884821
Ref: refman/methods/instantiation_error_0 modes-and-number-of-proofs884972
Ref: 6a5884972
Node: Errors<83>885079
Ref: refman/methods/instantiation_error_0 errors885227
Ref: 6a6885227
Node: Examples<119>885317
Ref: refman/methods/instantiation_error_0 examples885426
Ref: 6a7885426
Node: uninstantiation_error/1885899
Ref: refman/methods/uninstantiation_error_1 doc886046
Ref: 6a8886046
Ref: refman/methods/uninstantiation_error_1 methods-uninstantiation-error-1886046
Ref: 188886046
Ref: refman/methods/uninstantiation_error_1 uninstantiation-error-1886046
Ref: 6a9886046
Node: Description<119>886275
Ref: refman/methods/uninstantiation_error_1 description886409
Ref: 6aa886409
Node: Modes and number of proofs<83>887019
Ref: refman/methods/uninstantiation_error_1 modes-and-number-of-proofs887172
Ref: 6ab887172
Node: Errors<84>887290
Ref: refman/methods/uninstantiation_error_1 errors887440
Ref: 6ac887440
Node: Examples<120>887541
Ref: refman/methods/uninstantiation_error_1 examples887652
Ref: 6ad887652
Node: type_error/2888136
Ref: refman/methods/type_error_2 doc888276
Ref: 6ae888276
Ref: refman/methods/type_error_2 methods-type-error-2888276
Ref: 189888276
Ref: refman/methods/type_error_2 type-error-2888276
Ref: 6af888276
Node: Description<120>888483
Ref: refman/methods/type_error_2 description888606
Ref: 6b0888606
Node: Modes and number of proofs<84>889414
Ref: refman/methods/type_error_2 modes-and-number-of-proofs889556
Ref: 6b1889556
Node: Errors<85>889670
Ref: refman/methods/type_error_2 errors889809
Ref: 6b2889809
Node: Examples<121>889905
Ref: refman/methods/type_error_2 examples890005
Ref: 6b3890005
Node: domain_error/2890491
Ref: refman/methods/domain_error_2 doc890625
Ref: 6b4890625
Ref: refman/methods/domain_error_2 domain-error-2890625
Ref: 6b5890625
Ref: refman/methods/domain_error_2 methods-domain-error-2890625
Ref: 18a890625
Node: Description<121>890836
Ref: refman/methods/domain_error_2 description890961
Ref: 6b6890961
Node: Modes and number of proofs<85>892846
Ref: refman/methods/domain_error_2 modes-and-number-of-proofs892990
Ref: 6b7892990
Node: Errors<86>893106
Ref: refman/methods/domain_error_2 errors893247
Ref: 6b8893247
Node: Examples<122>893347
Ref: refman/methods/domain_error_2 examples893449
Ref: 6b9893449
Node: existence_error/2893957
Ref: refman/methods/existence_error_2 doc894097
Ref: 6ba894097
Ref: refman/methods/existence_error_2 existence-error-2894097
Ref: 6bb894097
Ref: refman/methods/existence_error_2 methods-existence-error-2894097
Ref: 18b894097
Node: Description<122>894314
Ref: refman/methods/existence_error_2 description894442
Ref: 6bc894442
Node: Modes and number of proofs<86>895321
Ref: refman/methods/existence_error_2 modes-and-number-of-proofs895468
Ref: 6bd895468
Node: Errors<87>895589
Ref: refman/methods/existence_error_2 errors895733
Ref: 6be895733
Node: Examples<123>895835
Ref: refman/methods/existence_error_2 examples895940
Ref: 6bf895940
Node: permission_error/3896444
Ref: refman/methods/permission_error_3 doc896592
Ref: 6c0896592
Ref: refman/methods/permission_error_3 methods-permission-error-3896592
Ref: 18c896592
Ref: refman/methods/permission_error_3 permission-error-3896592
Ref: 6c1896592
Node: Description<123>896811
Ref: refman/methods/permission_error_3 description896940
Ref: 6c2896940
Node: Modes and number of proofs<87>898350
Ref: refman/methods/permission_error_3 modes-and-number-of-proofs898498
Ref: 6c3898498
Node: Errors<88>898629
Ref: refman/methods/permission_error_3 errors898774
Ref: 6c4898774
Node: Examples<124>898893
Ref: refman/methods/permission_error_3 examples898999
Ref: 6c5898999
Node: representation_error/1899497
Ref: refman/methods/representation_error_1 doc899646
Ref: 6c6899646
Ref: refman/methods/representation_error_1 methods-representation-error-1899646
Ref: 18d899646
Ref: refman/methods/representation_error_1 representation-error-1899646
Ref: 6c7899646
Node: Description<124>899873
Ref: refman/methods/representation_error_1 description900006
Ref: 6c8900006
Node: Modes and number of proofs<88>900869
Ref: refman/methods/representation_error_1 modes-and-number-of-proofs901021
Ref: 6c9901021
Node: Errors<89>901136
Ref: refman/methods/representation_error_1 errors901285
Ref: 6ca901285
Node: Examples<125>901382
Ref: refman/methods/representation_error_1 examples901492
Ref: 6cb901492
Node: evaluation_error/1901979
Ref: refman/methods/evaluation_error_1 doc902126
Ref: 6cc902126
Ref: refman/methods/evaluation_error_1 evaluation-error-1902126
Ref: 6cd902126
Ref: refman/methods/evaluation_error_1 methods-evaluation-error-1902126
Ref: 18e902126
Node: Description<125>902345
Ref: refman/methods/evaluation_error_1 description902474
Ref: 6ce902474
Node: Modes and number of proofs<89>903145
Ref: refman/methods/evaluation_error_1 modes-and-number-of-proofs903293
Ref: 6cf903293
Node: Errors<90>903406
Ref: refman/methods/evaluation_error_1 errors903551
Ref: 6d0903551
Node: Examples<126>903649
Ref: refman/methods/evaluation_error_1 examples903755
Ref: 6d1903755
Node: resource_error/1904243
Ref: refman/methods/resource_error_1 doc904382
Ref: 6d2904382
Ref: refman/methods/resource_error_1 methods-resource-error-1904382
Ref: 18f904382
Ref: refman/methods/resource_error_1 resource-error-1904382
Ref: 6d3904382
Node: Description<126>904597
Ref: refman/methods/resource_error_1 description904724
Ref: 6d4904724
Node: Modes and number of proofs<90>905378
Ref: refman/methods/resource_error_1 modes-and-number-of-proofs905524
Ref: 6d5905524
Node: Errors<91>905635
Ref: refman/methods/resource_error_1 errors905778
Ref: 6d6905778
Node: Examples<127>905873
Ref: refman/methods/resource_error_1 examples905977
Ref: 6d7905977
Node: syntax_error/1906423
Ref: refman/methods/syntax_error_1 doc906558
Ref: 6d8906558
Ref: refman/methods/syntax_error_1 methods-syntax-error-1906558
Ref: 190906558
Ref: refman/methods/syntax_error_1 syntax-error-1906558
Ref: 6d9906558
Node: Description<127>906769
Ref: refman/methods/syntax_error_1 description906894
Ref: 6da906894
Node: Modes and number of proofs<91>907408
Ref: refman/methods/syntax_error_1 modes-and-number-of-proofs907552
Ref: 6db907552
Node: Errors<92>907661
Ref: refman/methods/syntax_error_1 errors907802
Ref: 6dc907802
Node: Examples<128>907898
Ref: refman/methods/syntax_error_1 examples908000
Ref: 6dd908000
Node: system_error/0908401
Ref: refman/methods/system_error_0 doc908511
Ref: 6de908511
Ref: refman/methods/system_error_0 methods-system-error-0908511
Ref: 191908511
Ref: refman/methods/system_error_0 system-error-0908511
Ref: 6df908511
Node: Description<128>908722
Ref: refman/methods/system_error_0 description908847
Ref: 6e0908847
Node: Modes and number of proofs<92>909372
Ref: refman/methods/system_error_0 modes-and-number-of-proofs909516
Ref: 6e1909516
Node: Errors<93>909616
Ref: refman/methods/system_error_0 errors909757
Ref: 6e2909757
Node: Examples<129>909840
Ref: refman/methods/system_error_0 examples909942
Ref: 6e3909942
Node: All solutions910374
Ref: refman/methods/solution_methods doc910514
Ref: 6e4910514
Ref: refman/methods/solution_methods all-solutions910514
Ref: 6e5910514
Ref: refman/methods/solution_methods solutions-methods910514
Ref: 6e6910514
Node: bagof/3910630
Ref: refman/methods/bagof_3 doc910724
Ref: 6e7910724
Ref: refman/methods/bagof_3 bagof-3910724
Ref: 6e8910724
Ref: refman/methods/bagof_3 methods-bagof-3910724
Ref: 1a2910724
Node: Description<129>910919
Ref: refman/methods/bagof_3 description911037
Ref: 6e9911037
Node: Modes and number of proofs<93>911935
Ref: refman/methods/bagof_3 modes-and-number-of-proofs912072
Ref: 6ea912072
Node: Errors<94>912195
Ref: refman/methods/bagof_3 errors912329
Ref: 6eb912329
Node: Examples<130>912645
Ref: refman/methods/bagof_3 examples912740
Ref: 6ec912740
Node: findall/3913278
Ref: refman/methods/findall_3 doc913390
Ref: 6ed913390
Ref: refman/methods/findall_3 findall-3913390
Ref: 6ee913390
Ref: refman/methods/findall_3 methods-findall-3913390
Ref: 1a3913390
Node: Description<130>913589
Ref: refman/methods/findall_3 description913709
Ref: 6ef913709
Node: Modes and number of proofs<94>914092
Ref: refman/methods/findall_3 modes-and-number-of-proofs914231
Ref: 6f0914231
Node: Errors<95>914355
Ref: refman/methods/findall_3 errors914491
Ref: 6f1914491
Node: Examples<131>914807
Ref: refman/methods/findall_3 examples914904
Ref: 6f2914904
Node: findall/4915433
Ref: refman/methods/findall_4 doc915546
Ref: 6f3915546
Ref: refman/methods/findall_4 findall-4915546
Ref: 6f4915546
Ref: refman/methods/findall_4 methods-findall-4915546
Ref: 1a4915546
Node: Description<131>915747
Ref: refman/methods/findall_4 description915867
Ref: 6f5915867
Node: Modes and number of proofs<95>916233
Ref: refman/methods/findall_4 modes-and-number-of-proofs916372
Ref: 6f6916372
Node: Errors<96>916505
Ref: refman/methods/findall_4 errors916641
Ref: 6f7916641
Node: Examples<132>916959
Ref: refman/methods/findall_4 examples917056
Ref: 6f8917056
Node: forall/2917603
Ref: refman/methods/forall_2 doc917714
Ref: 6f9917714
Ref: refman/methods/forall_2 forall-2917714
Ref: 6fa917714
Ref: refman/methods/forall_2 methods-forall-2917714
Ref: 1a6917714
Node: Description<132>917913
Ref: refman/methods/forall_2 description918032
Ref: 6fb918032
Node: Modes and number of proofs<96>918400
Ref: refman/methods/forall_2 modes-and-number-of-proofs918538
Ref: 6fc918538
Node: Errors<97>918660
Ref: refman/methods/forall_2 errors918795
Ref: 6fd918795
Node: Examples<133>919142
Ref: refman/methods/forall_2 examples919238
Ref: 6fe919238
Node: setof/3919727
Ref: refman/methods/setof_3 doc919820
Ref: 6ff919820
Ref: refman/methods/setof_3 methods-setof-3919820
Ref: 1a5919820
Ref: refman/methods/setof_3 setof-3919820
Ref: 700919820
Node: Description<133>920017
Ref: refman/methods/setof_3 description920135
Ref: 701920135
Node: Modes and number of proofs<97>921009
Ref: refman/methods/setof_3 modes-and-number-of-proofs921146
Ref: 702921146
Node: Errors<98>921271
Ref: refman/methods/setof_3 errors921405
Ref: 703921405
Node: Examples<134>921723
Ref: refman/methods/setof_3 examples921818
Ref: 704921818
Node: Event handling<3>922358
Ref: refman/methods/event_methods doc922499
Ref: 705922499
Ref: refman/methods/event_methods event-handling922499
Ref: 706922499
Ref: refman/methods/event_methods event-methods922499
Ref: 707922499
Node: before/3922577
Ref: refman/methods/before_3 doc922674
Ref: 708922674
Ref: refman/methods/before_3 before-3922674
Ref: 709922674
Ref: refman/methods/before_3 methods-before-3922674
Ref: fa922674
Node: Description<134>922871
Ref: refman/methods/before_3 description922990
Ref: 70a922990
Ref: Description<134>-Footnote-1923596
Node: Modes and number of proofs<98>923649
Ref: refman/methods/before_3 modes-and-number-of-proofs923787
Ref: 70b923787
Node: Errors<99>923937
Ref: refman/methods/before_3 errors924072
Ref: 70c924072
Node: Examples<135>924111
Ref: refman/methods/before_3 examples924207
Ref: 70d924207
Node: after/3924644
Ref: refman/methods/after_3 doc924741
Ref: 70e924741
Ref: refman/methods/after_3 after-3924741
Ref: 70f924741
Ref: refman/methods/after_3 methods-after-3924741
Ref: fb924741
Node: Description<135>924937
Ref: refman/methods/after_3 description925055
Ref: 710925055
Ref: Description<135>-Footnote-1925659
Node: Modes and number of proofs<99>925712
Ref: refman/methods/after_3 modes-and-number-of-proofs925850
Ref: 711925850
Node: Errors<100>925999
Ref: refman/methods/after_3 errors926134
Ref: 712926134
Node: Examples<136>926173
Ref: refman/methods/after_3 examples926269
Ref: 713926269
Node: Message forwarding926714
Ref: refman/methods/forwarding_methods doc926874
Ref: 714926874
Ref: refman/methods/forwarding_methods forwarding-methods926874
Ref: 715926874
Ref: refman/methods/forwarding_methods message-forwarding926874
Ref: 716926874
Node: forward/1926949
Ref: refman/methods/forward_1 doc927032
Ref: 717927032
Ref: refman/methods/forward_1 forward-1927032
Ref: 718927032
Ref: refman/methods/forward_1 methods-forward-1927032
Ref: fe927032
Node: Description<136>927233
Ref: refman/methods/forward_1 description927354
Ref: 719927354
Ref: Description<136>-Footnote-1927881
Node: Modes and number of proofs<100>927934
Ref: refman/methods/forward_1 modes-and-number-of-proofs928075
Ref: 71a928075
Node: Errors<101>928186
Ref: refman/methods/forward_1 errors928324
Ref: 71b928324
Node: Examples<137>928363
Ref: refman/methods/forward_1 examples928461
Ref: 71c928461
Node: Definite clause grammar rules<2>928725
Ref: refman/methods/dcg_methods doc928894
Ref: 71d928894
Ref: refman/methods/dcg_methods dcg-methods928894
Ref: 71e928894
Ref: refman/methods/dcg_methods definite-clause-grammar-rules928894
Ref: 71f928894
Node: call//1-N929042
Ref: refman/methods/call_1 doc929154
Ref: 720929154
Ref: refman/methods/call_1 call-1-n929154
Ref: 721929154
Ref: refman/methods/call_1 methods-call-1929154
Ref: 1ac929154
Node: Description<137>929355
Ref: refman/methods/call_1 description929476
Ref: 722929476
Node: Modes and number of proofs<101>930688
Ref: refman/methods/call_1 modes-and-number-of-proofs930829
Ref: 723930829
Node: Errors<102>931039
Ref: refman/methods/call_1 errors931177
Ref: 724931177
Node: Examples<138>931391
Ref: refman/methods/call_1 examples931489
Ref: 725931489
Node: eos//0932264
Ref: refman/methods/eos_0 doc932394
Ref: 726932394
Ref: refman/methods/eos_0 eos-0932394
Ref: 727932394
Ref: refman/methods/eos_0 methods-eos-0932394
Ref: 1ad932394
Node: Description<138>932589
Ref: refman/methods/eos_0 description932707
Ref: 728932707
Node: Modes and number of proofs<102>932894
Ref: refman/methods/eos_0 modes-and-number-of-proofs933032
Ref: 729933032
Node: Errors<103>933127
Ref: refman/methods/eos_0 errors933262
Ref: 72a933262
Node: Examples<139>933301
Ref: refman/methods/eos_0 examples933396
Ref: 72b933396
Node: phrase//1933567
Ref: refman/methods/phrase_1 doc933696
Ref: 72c933696
Ref: refman/methods/phrase_1 methods-phrase-1933696
Ref: 1ab933696
Ref: refman/methods/phrase_1 phrase-1933696
Ref: 72d933696
Node: Description<139>933899
Ref: refman/methods/phrase_1 description934020
Ref: 72e934020
Node: Modes and number of proofs<103>934302
Ref: refman/methods/phrase_1 modes-and-number-of-proofs934443
Ref: 72f934443
Node: Errors<104>934555
Ref: refman/methods/phrase_1 errors934693
Ref: 730934693
Node: Examples<140>934921
Ref: refman/methods/phrase_1 examples935019
Ref: 731935019
Node: phrase/2935153
Ref: refman/methods/phrase_2 doc935284
Ref: 732935284
Ref: refman/methods/phrase_2 methods-phrase-2935284
Ref: 17a935284
Ref: refman/methods/phrase_2 phrase-2935284
Ref: 733935284
Node: Description<140>935485
Ref: refman/methods/phrase_2 description935605
Ref: 734935605
Node: Modes and number of proofs<104>936567
Ref: refman/methods/phrase_2 modes-and-number-of-proofs936707
Ref: 735936707
Node: Errors<105>936826
Ref: refman/methods/phrase_2 errors936963
Ref: 736936963
Node: Examples<141>937203
Ref: refman/methods/phrase_2 examples937300
Ref: 737937300
Node: phrase/3937798
Ref: refman/methods/phrase_3 doc937911
Ref: 738937911
Ref: refman/methods/phrase_3 methods-phrase-3937911
Ref: 17b937911
Ref: refman/methods/phrase_3 phrase-3937911
Ref: 739937911
Node: Description<141>938112
Ref: refman/methods/phrase_3 description938232
Ref: 73a938232
Node: Modes and number of proofs<105>939247
Ref: refman/methods/phrase_3 modes-and-number-of-proofs939387
Ref: 73b939387
Node: Errors<106>939513
Ref: refman/methods/phrase_3 errors939650
Ref: 73c939650
Node: Examples<142>939890
Ref: refman/methods/phrase_3 examples939987
Ref: 73d939987
Node: Term and goal expansion<2>940502
Ref: refman/methods/expansion_methods doc940670
Ref: 73e940670
Ref: refman/methods/expansion_methods expansion-methods940670
Ref: 73f940670
Ref: refman/methods/expansion_methods term-and-goal-expansion940670
Ref: 740940670
Node: expand_term/2940821
Ref: refman/methods/expand_term_2 doc940941
Ref: 741940941
Ref: refman/methods/expand_term_2 expand-term-2940941
Ref: 742940941
Ref: refman/methods/expand_term_2 methods-expand-term-2940941
Ref: 19b940941
Node: Description<142>941152
Ref: refman/methods/expand_term_2 description941277
Ref: 743941277
Node: Modes and number of proofs<106>942713
Ref: refman/methods/expand_term_2 modes-and-number-of-proofs942858
Ref: 744942858
Node: Errors<107>942969
Ref: refman/methods/expand_term_2 errors943111
Ref: 745943111
Node: Examples<143>943152
Ref: refman/methods/expand_term_2 examples943254
Ref: 746943254
Node: term_expansion/2943401
Ref: refman/methods/term_expansion_2 doc943543
Ref: 747943543
Ref: refman/methods/term_expansion_2 methods-term-expansion-2943543
Ref: f5943543
Ref: refman/methods/term_expansion_2 term-expansion-2943543
Ref: 748943543
Node: Description<143>943760
Ref: refman/methods/term_expansion_2 description943888
Ref: 749943888
Ref: Description<143>-Footnote-1945312
Node: Modes and number of proofs<107>945363
Ref: refman/methods/term_expansion_2 modes-and-number-of-proofs945511
Ref: 74a945511
Node: Errors<108>945695
Ref: refman/methods/term_expansion_2 errors945840
Ref: 74b945840
Node: Examples<144>945881
Ref: refman/methods/term_expansion_2 examples945986
Ref: 74c945986
Node: expand_goal/2946312
Ref: refman/methods/expand_goal_2 doc946457
Ref: 74d946457
Ref: refman/methods/expand_goal_2 expand-goal-2946457
Ref: 74e946457
Ref: refman/methods/expand_goal_2 methods-expand-goal-2946457
Ref: 2e9946457
Node: Description<144>946670
Ref: refman/methods/expand_goal_2 description946795
Ref: 74f946795
Node: Modes and number of proofs<108>947687
Ref: refman/methods/expand_goal_2 modes-and-number-of-proofs947832
Ref: 750947832
Node: Errors<109>947945
Ref: refman/methods/expand_goal_2 errors948087
Ref: 751948087
Node: Examples<145>948130
Ref: refman/methods/expand_goal_2 examples948232
Ref: 752948232
Node: goal_expansion/2948381
Ref: refman/methods/goal_expansion_2 doc948501
Ref: 753948501
Ref: refman/methods/goal_expansion_2 goal-expansion-2948501
Ref: 754948501
Ref: refman/methods/goal_expansion_2 methods-goal-expansion-2948501
Ref: f6948501
Node: Description<145>948720
Ref: refman/methods/goal_expansion_2 description948848
Ref: 755948848
Ref: Description<145>-Footnote-1950317
Node: Modes and number of proofs<109>950368
Ref: refman/methods/goal_expansion_2 modes-and-number-of-proofs950516
Ref: 756950516
Node: Errors<110>950648
Ref: refman/methods/goal_expansion_2 errors950793
Ref: 757950793
Node: Examples<146>950836
Ref: refman/methods/goal_expansion_2 examples950941
Ref: 758950941
Node: Coinduction hooks951245
Ref: refman/methods/coinduction_methods doc951397
Ref: 759951397
Ref: refman/methods/coinduction_methods coinduction-hooks951397
Ref: 75a951397
Ref: refman/methods/coinduction_methods coinduction-methods951397
Ref: 75b951397
Node: coinductive_success_hook/1-2951491
Ref: refman/methods/coinductive_success_hook_1_2 doc951592
Ref: 75c951592
Ref: refman/methods/coinductive_success_hook_1_2 coinductive-success-hook-1-2951592
Ref: 75d951592
Ref: refman/methods/coinductive_success_hook_1_2 methods-coinductive-success-hook-1-2951592
Ref: 465951592
Node: Description<146>951833
Ref: refman/methods/coinductive_success_hook_1_2 description951973
Ref: 75e951973
Node: Modes and number of proofs<110>952850
Ref: refman/methods/coinductive_success_hook_1_2 modes-and-number-of-proofs953010
Ref: 75f953010
Node: Errors<111>953205
Ref: refman/methods/coinductive_success_hook_1_2 errors953362
Ref: 760953362
Node: Examples<147>953403
Ref: refman/methods/coinductive_success_hook_1_2 examples953520
Ref: 761953520
Node: Message printing954097
Ref: refman/methods/printing_methods doc954238
Ref: 762954238
Ref: refman/methods/printing_methods message-printing954238
Ref: 763954238
Ref: refman/methods/printing_methods printing-methods954238
Ref: 764954238
Node: print_message/3954439
Ref: refman/methods/print_message_3 doc954552
Ref: 765954552
Ref: refman/methods/print_message_3 methods-print-message-3954552
Ref: 2d8954552
Ref: refman/methods/print_message_3 print-message-3954552
Ref: 766954552
Node: Description<147>954767
Ref: refman/methods/print_message_3 description954894
Ref: 767954894
Ref: Description<147>-Footnote-1955775
Node: Modes and number of proofs<111>955822
Ref: refman/methods/print_message_3 modes-and-number-of-proofs955969
Ref: 768955969
Node: Errors<112>956095
Ref: refman/methods/print_message_3 errors956239
Ref: 769956239
Node: Examples<148>956280
Ref: refman/methods/print_message_3 examples956384
Ref: 76a956384
Node: message_tokens//2956785
Ref: refman/methods/message_tokens_2 doc956921
Ref: 76e956921
Ref: refman/methods/message_tokens_2 message-tokens-2956921
Ref: 76f956921
Ref: refman/methods/message_tokens_2 methods-message-tokens-2956921
Ref: 2db956921
Node: Description<148>957140
Ref: refman/methods/message_tokens_2 description957269
Ref: 770957269
Ref: Description<148>-Footnote-1957755
Node: Modes and number of proofs<112>957802
Ref: refman/methods/message_tokens_2 modes-and-number-of-proofs957951
Ref: 771957951
Node: Errors<113>958078
Ref: refman/methods/message_tokens_2 errors958224
Ref: 772958224
Node: Examples<149>958265
Ref: refman/methods/message_tokens_2 examples958371
Ref: 773958371
Node: message_hook/4958898
Ref: refman/methods/message_hook_4 doc959042
Ref: 774959042
Ref: refman/methods/message_hook_4 message-hook-4959042
Ref: 775959042
Ref: refman/methods/message_hook_4 methods-message-hook-4959042
Ref: 2df959042
Node: Description<149>959257
Ref: refman/methods/message_hook_4 description959383
Ref: 776959383
Ref: Description<149>-Footnote-1959873
Node: Modes and number of proofs<113>959920
Ref: refman/methods/message_hook_4 modes-and-number-of-proofs960066
Ref: 777960066
Node: Errors<114>960216
Ref: refman/methods/message_hook_4 errors960359
Ref: 778960359
Node: Examples<150>960402
Ref: refman/methods/message_hook_4 examples960505
Ref: 779960505
Node: message_prefix_stream/4961164
Ref: refman/methods/message_prefix_stream_4 doc961313
Ref: 77a961313
Ref: refman/methods/message_prefix_stream_4 message-prefix-stream-4961313
Ref: 77b961313
Ref: refman/methods/message_prefix_stream_4 methods-message-prefix-stream-4961313
Ref: 2e0961313
Node: Description<150>961546
Ref: refman/methods/message_prefix_stream_4 description961681
Ref: 77c961681
Ref: Description<150>-Footnote-1962066
Node: Modes and number of proofs<114>962113
Ref: refman/methods/message_prefix_stream_4 modes-and-number-of-proofs962268
Ref: 77d962268
Node: Errors<115>962429
Ref: refman/methods/message_prefix_stream_4 errors962581
Ref: 77e962581
Node: Examples<151>962624
Ref: refman/methods/message_prefix_stream_4 examples962736
Ref: 77f962736
Node: print_message_tokens/3963222
Ref: refman/methods/print_message_tokens_3 doc963378
Ref: 780963378
Ref: refman/methods/print_message_tokens_3 methods-print-message-tokens-3963378
Ref: 76b963378
Ref: refman/methods/print_message_tokens_3 print-message-tokens-3963378
Ref: 781963378
Node: Description<151>963609
Ref: refman/methods/print_message_tokens_3 description963743
Ref: 782963743
Ref: Description<151>-Footnote-1964504
Node: Modes and number of proofs<115>964551
Ref: refman/methods/print_message_tokens_3 modes-and-number-of-proofs964705
Ref: 783964705
Node: Errors<116>964861
Ref: refman/methods/print_message_tokens_3 errors965012
Ref: 784965012
Node: Examples<152>965055
Ref: refman/methods/print_message_tokens_3 examples965166
Ref: 785965166
Node: print_message_token/4965585
Ref: refman/methods/print_message_token_4 doc965709
Ref: 786965709
Ref: refman/methods/print_message_token_4 methods-print-message-token-4965709
Ref: 76c965709
Ref: refman/methods/print_message_token_4 print-message-token-4965709
Ref: 787965709
Node: Description<152>965938
Ref: refman/methods/print_message_token_4 description966071
Ref: 788966071
Ref: Description<152>-Footnote-1966537
Node: Modes and number of proofs<116>966584
Ref: refman/methods/print_message_token_4 modes-and-number-of-proofs966737
Ref: 789966737
Node: Errors<117>966901
Ref: refman/methods/print_message_token_4 errors967051
Ref: 78a967051
Node: Examples<153>967094
Ref: refman/methods/print_message_token_4 examples967204
Ref: 78b967204
Node: Question asking967713
Ref: refman/methods/asking_methods doc967828
Ref: 78c967828
Ref: refman/methods/asking_methods asking-methods967828
Ref: 78d967828
Ref: refman/methods/asking_methods question-asking967828
Ref: 78e967828
Node: ask_question/5967953
Ref: refman/methods/ask_question_5 doc968062
Ref: 78f968062
Ref: refman/methods/ask_question_5 ask-question-5968062
Ref: 790968062
Ref: refman/methods/ask_question_5 methods-ask-question-5968062
Ref: 2e2968062
Node: Description<153>968303
Ref: refman/methods/ask_question_5 description968429
Ref: 791968429
Node: Modes and number of proofs<117>969518
Ref: refman/methods/ask_question_5 modes-and-number-of-proofs969676
Ref: 792969676
Node: Meta-predicate template969819
Ref: refman/methods/ask_question_5 meta-predicate-template969972
Ref: 793969972
Node: Errors<118>970073
Ref: refman/methods/ask_question_5 errors970208
Ref: 794970208
Node: Examples<154>970249
Ref: refman/methods/ask_question_5 examples970352
Ref: 795970352
Node: question_hook/6970755
Ref: refman/methods/question_hook_6 doc970897
Ref: 796970897
Ref: refman/methods/question_hook_6 methods-question-hook-6970897
Ref: 2e4970897
Ref: refman/methods/question_hook_6 question-hook-6970897
Ref: 797970897
Node: Description<154>971167
Ref: refman/methods/question_hook_6 description971294
Ref: 798971294
Ref: Description<154>-Footnote-1971804
Node: Modes and number of proofs<118>971851
Ref: refman/methods/question_hook_6 modes-and-number-of-proofs972013
Ref: 799972013
Node: Meta-predicate template<2>972180
Ref: refman/methods/question_hook_6 meta-predicate-template972337
Ref: 79a972337
Node: Errors<119>972444
Ref: refman/methods/question_hook_6 errors972583
Ref: 79b972583
Node: Examples<155>972626
Ref: refman/methods/question_hook_6 examples972730
Ref: 79c972730
Node: question_prompt_stream/4973263
Ref: refman/methods/question_prompt_stream_4 doc973382
Ref: 79d973382
Ref: refman/methods/question_prompt_stream_4 methods-question-prompt-stream-4973382
Ref: 76d973382
Ref: refman/methods/question_prompt_stream_4 question-prompt-stream-4973382
Ref: 79e973382
Node: Description<155>973617
Ref: refman/methods/question_prompt_stream_4 description973753
Ref: 79f973753
Ref: Description<155>-Footnote-1974143
Node: Modes and number of proofs<119>974190
Ref: refman/methods/question_prompt_stream_4 modes-and-number-of-proofs974346
Ref: 7a0974346
Node: Errors<120>974508
Ref: refman/methods/question_prompt_stream_4 errors974661
Ref: 7a1974661
Node: Examples<156>974704
Ref: refman/methods/question_prompt_stream_4 examples974817
Ref: 7a2974817
Node: Tutorial975309
Ref: tutorial/index doc975413
Ref: 7a3975413
Ref: tutorial/index tutorial975413
Ref: 7a4975413
Node: List predicates975555
Ref: tutorial/lists doc975668
Ref: 7a5975668
Ref: tutorial/lists list-predicates975668
Ref: 7a6975668
Node: Defining a list object975908
Ref: tutorial/lists defining-a-list-object976034
Ref: 7a7976034
Ref: tutorial/lists object976034
Ref: 7a8976034
Node: Defining a list protocol978576
Ref: tutorial/lists defining-a-list-protocol978718
Ref: 7a9978718
Ref: tutorial/lists protocol978718
Ref: 7aa978718
Node: Summary980917
Ref: tutorial/lists summary981028
Ref: 7ab981028
Node: Dynamic object attributes981478
Ref: tutorial/attributes doc981631
Ref: 7ac981631
Ref: tutorial/attributes dynamic-object-attributes981631
Ref: 7ad981631
Node: Defining a category981993
Ref: tutorial/attributes category982124
Ref: 7ae982124
Ref: tutorial/attributes defining-a-category982124
Ref: 7af982124
Node: Importing the category985812
Ref: tutorial/attributes importing985962
Ref: 7b0985962
Ref: tutorial/attributes importing-the-category985962
Ref: 7b1985962
Node: Summary<2>986524
Ref: tutorial/attributes summary986646
Ref: 7b2986646
Node: A reflective class-based system987279
Ref: tutorial/reflection doc987435
Ref: 7b3987435
Ref: tutorial/reflection a-reflective-class-based-system987435
Ref: 7b4987435
Node: Defining the base classes988549
Ref: tutorial/reflection classes988680
Ref: 7b5988680
Ref: tutorial/reflection defining-the-base-classes988680
Ref: 7b6988680
Node: Summary<3>990063
Ref: tutorial/reflection summary990194
Ref: 7b7990194
Node: Profiling programs990792
Ref: tutorial/profiling doc990914
Ref: 7b8990914
Ref: tutorial/profiling profiling-programs990914
Ref: 7b9990914
Node: Messages as events991236
Ref: tutorial/profiling events991358
Ref: 7ba991358
Ref: tutorial/profiling messages-as-events991358
Ref: 7bb991358
Node: Profilers as monitors992490
Ref: tutorial/profiling monitors992631
Ref: 7bc992631
Ref: tutorial/profiling profilers-as-monitors992631
Ref: 7bd992631
Node: Summary<4>995612
Ref: tutorial/profiling summary995726
Ref: 7be995726
Node: FAQ996585
Ref: faq/index doc996688
Ref: 7bf996688
Ref: faq/index faq996688
Ref: 7c0996688
Node: General996896
Ref: faq/general doc996984
Ref: 7c1996984
Ref: faq/general faq-general996984
Ref: 7c2996984
Ref: faq/general general996984
Ref: 7c3996984
Node: Why are all versions of Logtalk numbered 2 x or 3 x?997576
Ref: faq/general faq-general-versions997747
Ref: 7c4997747
Ref: faq/general why-are-all-versions-of-logtalk-numbered-2-x-or-3-x997747
Ref: 7c8997747
Node: Why do I need a Prolog compiler to use Logtalk?998414
Ref: faq/general faq-general-prolog998648
Ref: 7c5998648
Ref: faq/general why-do-i-need-a-prolog-compiler-to-use-logtalk998648
Ref: 7c9998648
Node: Is the Logtalk implementation based on Prolog modules?999273
Ref: faq/general faq-general-modules999506
Ref: 7c6999506
Ref: faq/general is-the-logtalk-implementation-based-on-prolog-modules999506
Ref: 7ca999506
Node: Does the Logtalk implementation use term-expansion?1000160
Ref: faq/general does-the-logtalk-implementation-use-term-expansion1000337
Ref: 7cb1000337
Ref: faq/general faq-general-expansion1000337
Ref: 7c71000337
Node: Compatibility1000560
Ref: faq/compatibility doc1000669
Ref: 7cc1000669
Ref: faq/compatibility compatibility1000669
Ref: 7cd1000669
Ref: faq/compatibility faq-compatibility1000669
Ref: 7ce1000669
Node: What are the backend Prolog compiler requirements to run Logtalk?1001150
Ref: faq/compatibility faq-compatibility-requirements1001342
Ref: 7cf1001342
Ref: faq/compatibility what-are-the-backend-prolog-compiler-requirements-to-run-logtalk1001342
Ref: 7d21001342
Ref: What are the backend Prolog compiler requirements to run Logtalk?-Footnote-11001579
Node: Can I use constraint-based packages with Logtalk?1001633
Ref: faq/compatibility can-i-use-constraint-based-packages-with-logtalk1001896
Ref: 7d31001896
Ref: faq/compatibility faq-compatibility-constraints1001896
Ref: 7d01001896
Node: Can I use Logtalk objects and Prolog modules at the same time?1002537
Ref: faq/compatibility can-i-use-logtalk-objects-and-prolog-modules-at-the-same-time1002726
Ref: 7d41002726
Ref: faq/compatibility faq-compatibility-modules1002726
Ref: 7d11002726
Node: Installation1003314
Ref: faq/installation doc1003427
Ref: 7d51003427
Ref: faq/installation faq-installation1003427
Ref: 7d61003427
Ref: faq/installation installation1003427
Ref: 7d71003427
Node: The integration scripts/shortcuts are not working!1003777
Ref: faq/installation faq-installation-scripts1003980
Ref: 7d81003980
Ref: faq/installation the-integration-scripts-shortcuts-are-not-working1003980
Ref: 7da1003980
Node: I get errors when starting up Logtalk after upgrading to the latest version!1004930
Ref: faq/installation faq-installation-startup-errors1005133
Ref: 7d91005133
Ref: faq/installation i-get-errors-when-starting-up-logtalk-after-upgrading-to-the-latest-version1005133
Ref: 7db1005133
Node: Portability1005702
Ref: faq/portability doc1005813
Ref: 7dc1005813
Ref: faq/portability faq-portability1005813
Ref: 7dd1005813
Ref: faq/portability portability1005813
Ref: 7de1005813
Node: Are my Logtalk applications portable across Prolog compilers?1006160
Ref: faq/portability are-my-logtalk-applications-portable-across-prolog-compilers1006359
Ref: 7e11006359
Ref: faq/portability faq-portability-prolog1006359
Ref: 7df1006359
Node: Are my Logtalk applications portable across operating systems?1007149
Ref: faq/portability are-my-logtalk-applications-portable-across-operating-systems1007348
Ref: 7e21007348
Ref: faq/portability faq-portability-os1007348
Ref: 7e01007348
Node: Programming1007908
Ref: faq/programming doc1008022
Ref: 7e31008022
Ref: faq/programming faq-programming1008022
Ref: 7e41008022
Ref: faq/programming programming1008022
Ref: 7e51008022
Node: Should I use prototypes or classes in my application?1008971
Ref: faq/programming faq-programming-either-prototypes-classes1009162
Ref: 7e61009162
Ref: faq/programming should-i-use-prototypes-or-classes-in-my-application1009162
Ref: 7ec1009162
Node: Can I use both classes and prototypes in the same application?1009665
Ref: faq/programming can-i-use-both-classes-and-prototypes-in-the-same-application1009920
Ref: 7ed1009920
Ref: faq/programming faq-programming-both-prototypes-classes1009920
Ref: 7e71009920
Node: Can I mix classes and prototypes in the same hierarchy?1010156
Ref: faq/programming can-i-mix-classes-and-prototypes-in-the-same-hierarchy1010426
Ref: 7ee1010426
Ref: faq/programming faq-programming-hierarchy1010426
Ref: 7e81010426
Node: Can I use a protocol or a category with both prototypes and classes?1010676
Ref: faq/programming can-i-use-a-protocol-or-a-category-with-both-prototypes-and-classes1010954
Ref: 7ef1010954
Ref: faq/programming faq-programming-protocols-categories1010954
Ref: 7e91010954
Node: What support is provided in Logtalk for defining and using components?1011292
Ref: faq/programming faq-programming-components1011578
Ref: 7ea1011578
Ref: faq/programming what-support-is-provided-in-logtalk-for-defining-and-using-components1011578
Ref: 7f01011578
Node: What support is provided in Logtalk for reflective programming?1012222
Ref: faq/programming faq-programming-reflection1012431
Ref: 7eb1012431
Ref: faq/programming what-support-is-provided-in-logtalk-for-reflective-programming1012431
Ref: 7f11012431
Node: Troubleshooting1012867
Ref: faq/troubleshooting doc1012979
Ref: 7f21012979
Ref: faq/troubleshooting faq-troubleshooting1012979
Ref: 7f31012979
Ref: faq/troubleshooting troubleshooting1012979
Ref: 7f41012979
Node: Using compiler options on calls to the Logtalk compiling and loading predicates do not work!1013911
Ref: faq/troubleshooting faq-troubleshooting-options1014184
Ref: 7f51014184
Ref: faq/troubleshooting using-compiler-options-on-calls-to-the-logtalk-compiling-and-loading-predicates-do-not-work1014184
Ref: 7f81014184
Node: Gecko-based browsers e g Firefox show non-rendered HTML entities when browsing XML documenting files!1014871
Ref: faq/troubleshooting faq-troubleshooting-gecko1015300
Ref: 7f61015300
Ref: faq/troubleshooting gecko-based-browsers-e-g-firefox-show-non-rendered-html-entities-when-browsing-xml-documenting-files1015300
Ref: 7f91015300
Node: Compiling a source file results in errors or warnings but the Logtalk compiler reports a successful compilation with zero errors and zero warnings!1016097
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-warnings1016425
Ref: 7fa1016425
Ref: faq/troubleshooting faq-troubleshooting-warnings1016425
Ref: 7f71016425
Node: Usability1017455
Ref: faq/usability doc1017566
Ref: 7fb1017566
Ref: faq/usability faq-usability1017566
Ref: 7fc1017566
Ref: faq/usability usability1017566
Ref: 7fd1017566
Node: Is there a shortcut for compiling and loading source files?1018045
Ref: faq/usability faq-usability-shortcuts1018251
Ref: 7fe1018251
Ref: faq/usability is-there-a-shortcut-for-compiling-and-loading-source-files1018251
Ref: 8011018251
Node: Is there an equivalent directive to the ensure_loaded/1 Prolog directive?1018655
Ref: faq/usability faq-usability-ensure-loaded1018917
Ref: 7ff1018917
Ref: faq/usability is-there-an-equivalent-directive-to-the-ensure-loaded-1-prolog-directive1018917
Ref: 8021018917
Node: Are there shortcuts for the make functionality?1019276
Ref: faq/usability are-there-shortcuts-for-the-make-functionality1019470
Ref: 8031019470
Ref: faq/usability faq-usability-make1019470
Ref: 8001019470
Node: Deployment1020162
Ref: faq/deployment doc1020272
Ref: 8041020272
Ref: faq/deployment deployment1020272
Ref: 8051020272
Ref: faq/deployment faq-deployment1020272
Ref: 8061020272
Node: Can I create standalone applications with Logtalk?1020437
Ref: faq/deployment can-i-create-standalone-applications-with-logtalk1020553
Ref: 8081020553
Ref: faq/deployment faq-deployment-create1020553
Ref: 8071020553
Ref: Can I create standalone applications with Logtalk?-Footnote-11021158
Node: Performance<3>1021201
Ref: faq/performance doc1021311
Ref: 8091021311
Ref: faq/performance id11021311
Ref: 80a1021311
Ref: faq/performance performance1021311
Ref: 80b1021311
Node: Is Logtalk implemented as a meta-interpreter?1022149
Ref: faq/performance is-logtalk-implemented-as-a-meta-interpreter1022359
Ref: 8101022359
Ref: faq/performance performance-meta-interpreter1022359
Ref: 80c1022359
Node: What kind of code Logtalk generates when compiling objects? Dynamic code? Static code?1022709
Ref: faq/performance performance-code-generated1023018
Ref: 80d1023018
Ref: faq/performance what-kind-of-code-logtalk-generates-when-compiling-objects-dynamic-code-static-code1023018
Ref: 8111023018
Node: How about message-sending performance? Does Logtalk use static binding or dynamic binding?1023581
Ref: faq/performance how-about-message-sending-performance-does-logtalk-use-static-binding-or-dynamic-binding1023922
Ref: 8121023922
Ref: faq/performance performance-binding1023922
Ref: 80e1023922
Node: Which Prolog-dependent factors are most crucial for good Logtalk performance?1024977
Ref: faq/performance which-prolog-dependent-factors-are-most-crucial-for-good-logtalk-performance1025311
Ref: 8131025311
Node: How does Logtalk performance compare with plain Prolog and with Prolog modules?1026076
Ref: faq/performance how-does-logtalk-performance-compare-with-plain-prolog-and-with-prolog-modules1026311
Ref: 8141026311
Ref: faq/performance performance-prolog1026311
Ref: 80f1026311
Ref: How does Logtalk performance compare with plain Prolog and with Prolog modules?-Footnote-11027116
Node: Licensing1027161
Ref: faq/licensing doc1027268
Ref: 8151027268
Ref: faq/licensing faq-licensing1027268
Ref: 8161027268
Ref: faq/licensing licensing1027268
Ref: 8171027268
Node: What’s the Logtalk distribution license?1027722
Ref: faq/licensing faq-licensing-license1027885
Ref: 8181027885
Ref: faq/licensing what-s-the-logtalk-distribution-license1027885
Ref: 81b1027885
Ref: What’s the Logtalk distribution license?-Footnote-11028064
Node: Can Logtalk be used in commercial applications?1028138
Ref: faq/licensing can-logtalk-be-used-in-commercial-applications1028389
Ref: 81c1028389
Ref: faq/licensing faq-licensing-commercial1028389
Ref: 8191028389
Ref: Can Logtalk be used in commercial applications?-Footnote-11028643
Node: What’s the final license for a combination of Logtalk with a Prolog compiler?1028701
Ref: faq/licensing faq-licensing-combining1028901
Ref: 81a1028901
Ref: faq/licensing what-s-the-final-license-for-a-combination-of-logtalk-with-a-prolog-compiler1028901
Ref: 81d1028901
Ref: What’s the final license for a combination of Logtalk with a Prolog compiler?-Footnote-11029174
Node: Support1029217
Ref: faq/support doc1029301
Ref: 81e1029301
Ref: faq/support faq-support1029301
Ref: 81f1029301
Ref: faq/support support1029301
Ref: 8201029301
Node: Are there professional consulting training and supporting services?1029571
Ref: faq/support are-there-professional-consulting-training-and-supporting-services1029701
Ref: 8221029701
Ref: faq/support faq-support-professional1029701
Ref: 8211029701
Ref: Are there professional consulting training and supporting services?-Footnote-11030006
Node: Developer Tools1030033
Ref: devtools/index doc1030137
Ref: 2611030137
Ref: devtools/index developer-tools1030137
Ref: 8231030137
Node: Overview1030532
Ref: devtools/overview doc1030624
Ref: 8241030624
Ref: devtools/overview overview1030624
Ref: 8251030624
Node: Loading the developer tools1031275
Ref: devtools/overview loading-the-developer-tools1031394
Ref: 8261031394
Node: Tools documentation1032451
Ref: devtools/overview tools-documentation1032570
Ref: 8271032570
Node: asdf1033014
Ref: devtools/asdf doc1033125
Ref: 8281033125
Ref: devtools/asdf asdf1033125
Ref: 8291033125
Ref: asdf-Footnote-11033546
Node: assertions1033577
Ref: devtools/assertions doc1033692
Ref: 82a1033692
Ref: devtools/assertions assertions1033692
Ref: 82b1033692
Node: API documentation1034409
Ref: devtools/assertions api-documentation1034508
Ref: 82c1034508
Node: Loading1034651
Ref: devtools/assertions loading1034766
Ref: 82d1034766
Node: Testing1034882
Ref: devtools/assertions testing1035017
Ref: 82e1035017
Node: Adding assertions to your source code1035143
Ref: devtools/assertions adding-assertions-to-your-source-code1035339
Ref: 82f1035339
Node: Automatically adding file and line context information to assertions1035997
Ref: devtools/assertions automatically-adding-file-and-line-context-information-to-assertions1036230
Ref: 8301036230
Node: Suppressing assertion calls from source code1037026
Ref: devtools/assertions suppressing-assertion-calls-from-source-code1037260
Ref: 8311037260
Node: Redirecting assertion failure messages1037756
Ref: devtools/assertions redirecting-assertion-failure-messages1037963
Ref: 8321037963
Node: Converting assertion failures into errors1038569
Ref: devtools/assertions converting-assertion-failures-into-errors1038723
Ref: 8331038723
Node: code_metrics1039668
Ref: devtools/code_metrics doc1039796
Ref: 8341039796
Ref: devtools/code_metrics code-metrics1039796
Ref: 8351039796
Node: API documentation<2>1040795
Ref: devtools/code_metrics api-documentation1040902
Ref: 8361040902
Node: Loading<2>1041047
Ref: devtools/code_metrics loading1041173
Ref: 8371041173
Node: Testing<2>1041291
Ref: devtools/code_metrics testing1041414
Ref: 8381041414
Node: Available metrics1041542
Ref: devtools/code_metrics available-metrics1041660
Ref: 8391041660
Node: Usage1045360
Ref: devtools/code_metrics usage1045488
Ref: 83a1045488
Node: Defining new metrics1045695
Ref: devtools/code_metrics defining-new-metrics1045823
Ref: 83b1045823
Node: Third-party tools1046130
Ref: devtools/code_metrics third-party-tools1046287
Ref: 83c1046287
Node: Applying metrics to Prolog modules1047010
Ref: devtools/code_metrics applying-metrics-to-prolog-modules1047184
Ref: 83d1047184
Node: Applying metrics to plain Prolog code1047645
Ref: devtools/code_metrics applying-metrics-to-plain-prolog-code1047793
Ref: 83e1047793
Node: dead_code_scanner1048718
Ref: devtools/dead_code_scanner doc1048850
Ref: 83f1048850
Ref: devtools/dead_code_scanner dead-code-scanner1048850
Ref: 8401048850
Node: API documentation<3>1050579
Ref: devtools/dead_code_scanner api-documentation1050691
Ref: 8411050691
Node: Loading<3>1050922
Ref: devtools/dead_code_scanner loading1051053
Ref: 8421051053
Node: Testing<3>1051176
Ref: devtools/dead_code_scanner testing1051295
Ref: 8431051295
Node: Usage<2>1051428
Ref: devtools/dead_code_scanner usage1051567
Ref: 8441051567
Node: Integration with the make tool1052604
Ref: devtools/dead_code_scanner integration-with-the-make-tool1052740
Ref: 8451052740
Node: Caveats1053027
Ref: devtools/dead_code_scanner caveats1053178
Ref: 8461053178
Node: Scanning Prolog modules1053622
Ref: devtools/dead_code_scanner scanning-prolog-modules1053770
Ref: 8471053770
Node: Scanning plain Prolog files1054199
Ref: devtools/dead_code_scanner scanning-plain-prolog-files1054331
Ref: 8481054331
Node: debug_messages1055264
Ref: devtools/debug_messages doc1055392
Ref: 31c1055392
Ref: devtools/debug_messages debug-messages1055392
Ref: 8491055392
Node: API documentation<4>1055880
Ref: devtools/debug_messages api-documentation1055989
Ref: 84a1055989
Node: Loading<4>1056314
Ref: devtools/debug_messages loading1056442
Ref: 84b1056442
Node: Testing<4>1056562
Ref: devtools/debug_messages testing1056678
Ref: 84c1056678
Node: Usage<3>1056808
Ref: devtools/debug_messages usage1056905
Ref: 84d1056905
Node: debugger1058448
Ref: devtools/debugger doc1058567
Ref: 2d61058567
Ref: devtools/debugger debugger1058567
Ref: 84e1058567
Node: API documentation<5>1059072
Ref: devtools/debugger api-documentation1059175
Ref: 84f1059175
Node: Loading<5>1059316
Ref: devtools/debugger loading1059438
Ref: 8501059438
Node: Testing<5>1059885
Ref: devtools/debugger testing1059995
Ref: 8511059995
Node: Usage<4>1060119
Ref: devtools/debugger usage1060245
Ref: 8521060245
Node: Alternative debugger tools1061183
Ref: devtools/debugger alternative-debugger-tools1061311
Ref: 8531061311
Node: Known issues1062130
Ref: devtools/debugger known-issues1062241
Ref: 8541062241
Node: diagrams1063064
Ref: devtools/diagrams doc1063175
Ref: 2c71063175
Ref: devtools/diagrams diagrams1063175
Ref: 8551063175
Node: API documentation<6>1065255
Ref: devtools/diagrams api-documentation1065358
Ref: 8561065358
Node: Loading<6>1065580
Ref: devtools/diagrams loading1065702
Ref: 8571065702
Node: Testing<6>1065816
Ref: devtools/diagrams testing1065936
Ref: 8581065936
Node: Supported diagrams1066060
Ref: devtools/diagrams supported-diagrams1066184
Ref: 8591066184
Node: Graph elements1068582
Ref: devtools/diagrams graph-elements1068721
Ref: 85a1068721
Node: Supported graph languages1071814
Ref: devtools/diagrams supported-graph-languages1071948
Ref: 85b1071948
Node: Customization1074953
Ref: devtools/diagrams customization1075089
Ref: 85c1075089
Node: Linking diagrams1085196
Ref: devtools/diagrams linking-diagrams1085355
Ref: 85d1085355
Node: Creating diagrams for Prolog module applications1088445
Ref: devtools/diagrams creating-diagrams-for-prolog-module-applications1088631
Ref: 85e1088631
Node: Creating diagrams for plain Prolog files1089263
Ref: devtools/diagrams creating-diagrams-for-plain-prolog-files1089444
Ref: 85f1089444
Node: Other notes1090283
Ref: devtools/diagrams other-notes1090407
Ref: 8601090407
Node: doclet1091519
Ref: devtools/doclet doc1091626
Ref: 3021091626
Ref: devtools/doclet doclet1091626
Ref: 8611091626
Node: API documentation<7>1092770
Ref: devtools/doclet api-documentation1092871
Ref: 8621092871
Node: Loading<7>1093091
Ref: devtools/doclet loading1093227
Ref: 8631093227
Node: Automating running doclets1093339
Ref: devtools/doclet automating-running-doclets1093488
Ref: 8641093488
Node: Integration with the make tool<2>1093832
Ref: devtools/doclet integration-with-the-make-tool1093962
Ref: 8651093962
Node: help1094244
Ref: devtools/help doc1094349
Ref: 8661094349
Ref: devtools/help help1094349
Ref: 8671094349
Node: API documentation<8>1094775
Ref: devtools/help api-documentation1094874
Ref: 8681094874
Node: Loading<8>1095094
Ref: devtools/help loading1095212
Ref: 8691095212
Node: Testing<7>1095282
Ref: devtools/help testing1095407
Ref: 86a1095407
Node: Supported operating-systems1095529
Ref: devtools/help supported-operating-systems1095652
Ref: 86b1095652
Node: Usage<5>1096019
Ref: devtools/help usage1096147
Ref: 86c1096147
Node: Known issues<2>1096246
Ref: devtools/help known-issues1096338
Ref: 86d1096338
Node: lgtdoc1096735
Ref: devtools/lgtdoc doc1096841
Ref: 2f91096841
Ref: devtools/lgtdoc lgtdoc1096841
Ref: 86e1096841
Node: API documentation<9>1097861
Ref: devtools/lgtdoc api-documentation1097962
Ref: 86f1097962
Node: Loading<9>1098103
Ref: devtools/lgtdoc loading1098223
Ref: 8701098223
Node: Testing<8>1098337
Ref: devtools/lgtdoc testing1098460
Ref: 8711098460
Node: Documenting source code1098584
Ref: devtools/lgtdoc documenting-source-code1098721
Ref: 8721098721
Node: Generating documentation1099708
Ref: devtools/lgtdoc generating-documentation1099826
Ref: 8731099826
Ref: Generating documentation-Footnote-11101689
Node: lgtunit1101748
Ref: devtools/lgtunit doc1101856
Ref: 2d91101856
Ref: devtools/lgtunit lgtunit1101856
Ref: 8741101856
Node: Main files1103657
Ref: devtools/lgtunit main-files1103760
Ref: 8751103760
Node: API documentation<10>1104310
Ref: devtools/lgtunit api-documentation1104433
Ref: 8761104433
Node: Loading<10>1104575
Ref: devtools/lgtunit loading1104698
Ref: 8771104698
Node: Testing<9>1104813
Ref: devtools/lgtunit testing1104940
Ref: 8781104940
Node: Writing and loading tests1105065
Ref: devtools/lgtunit writing-and-loading-tests1105199
Ref: 8791105199
Node: Running unit tests1108280
Ref: devtools/lgtunit running-unit-tests1108427
Ref: 87b1108427
Node: Parametric test objects1110661
Ref: devtools/lgtunit parametric-test-objects1110796
Ref: 87c1110796
Node: Test dialects1111918
Ref: devtools/lgtunit test-dialects1112061
Ref: 87a1112061
Node: User-defined test dialects1117393
Ref: devtools/lgtunit user-defined-test-dialects1117523
Ref: 87d1117523
Node: QuickCheck1118955
Ref: devtools/lgtunit quickcheck1119086
Ref: 87e1119086
Node: Skipping tests1130024
Ref: devtools/lgtunit skipping-tests1130155
Ref: 87f1130155
Node: Checking test goal results1131099
Ref: devtools/lgtunit checking-test-goal-results1131244
Ref: 8801131244
Node: Testing local predicates1133260
Ref: devtools/lgtunit testing-local-predicates1133427
Ref: 8811133427
Node: Testing non-deterministic predicates1134038
Ref: devtools/lgtunit testing-non-deterministic-predicates1134197
Ref: 8821134197
Node: Testing generators1134626
Ref: devtools/lgtunit testing-generators1134792
Ref: 8831134792
Node: Testing input/output predicates1135285
Ref: devtools/lgtunit testing-input-output-predicates1135451
Ref: 8841135451
Node: Suppressing tested predicates output1137871
Ref: devtools/lgtunit suppressing-tested-predicates-output1138044
Ref: 8851138044
Node: Tests with timeout limits1139624
Ref: devtools/lgtunit tests-with-timeout-limits1139789
Ref: 8861139789
Node: Setup and cleanup goals1140510
Ref: devtools/lgtunit setup-and-cleanup-goals1140655
Ref: 8871140655
Node: Test annotations1141570
Ref: devtools/lgtunit test-annotations1141701
Ref: 8881141701
Node: Flaky tests1142688
Ref: devtools/lgtunit flaky-tests1142818
Ref: 8891142818
Node: Debugging failed tests1143510
Ref: devtools/lgtunit debugging-failed-tests1143637
Ref: 88a1143637
Node: Code coverage1145395
Ref: devtools/lgtunit code-coverage1145535
Ref: 88b1145535
Node: Automating running tests1149357
Ref: devtools/lgtunit automating-running-tests1149493
Ref: 88c1149493
Node: Utility predicates1151442
Ref: devtools/lgtunit utility-predicates1151607
Ref: 88d1151607
Node: Exporting test results in xUnit XML format1155221
Ref: devtools/lgtunit exporting-test-results-in-xunit-xml-format1155409
Ref: 88e1155409
Node: Exporting test results in the TAP output format1157192
Ref: devtools/lgtunit exporting-test-results-in-the-tap-output-format1157387
Ref: 88f1157387
Node: Generating Allure reports1158779
Ref: devtools/lgtunit generating-allure-reports1158977
Ref: 8901158977
Ref: Generating Allure reports-Footnote-11162358
Node: Exporting code coverage results in XML format1162391
Ref: devtools/lgtunit exporting-code-coverage-results-in-xml-format1162572
Ref: 8911162572
Node: Minimizing test results output1164908
Ref: devtools/lgtunit minimizing-test-results-output1165079
Ref: 8921165079
Node: Known issues<3>1165385
Ref: devtools/lgtunit known-issues1165502
Ref: 8931165502
Node: linter1165975
Ref: devtools/linter doc1166081
Ref: 28f1166081
Ref: devtools/linter linter1166081
Ref: 8941166081
Ref: linter-Footnote-11169797
Ref: linter-Footnote-21169856
Ref: linter-Footnote-31169909
Ref: linter-Footnote-41169962
Node: make1170018
Ref: devtools/make doc1170131
Ref: 8951170131
Ref: devtools/make make1170131
Ref: 8961170131
Node: API documentation<11>1170381
Ref: devtools/make api-documentation1170462
Ref: 8971170462
Node: ports_profiler1171015
Ref: devtools/ports_profiler doc1171130
Ref: 3221171130
Ref: devtools/ports_profiler ports-profiler1171130
Ref: 8981171130
Node: API documentation<12>1172232
Ref: devtools/ports_profiler api-documentation1172343
Ref: 8991172343
Node: Loading<11>1172573
Ref: devtools/ports_profiler loading1172704
Ref: 89a1172704
Node: Testing<10>1172953
Ref: devtools/ports_profiler testing1173104
Ref: 89b1173104
Node: Compiling source files for port profiling1173236
Ref: devtools/ports_profiler compiling-source-files-for-port-profiling1173401
Ref: 89c1173401
Node: Generating profiling data1174144
Ref: devtools/ports_profiler generating-profiling-data1174329
Ref: 89d1174329
Node: Printing profiling data reports1174530
Ref: devtools/ports_profiler printing-profiling-data-reports1174701
Ref: 89e1174701
Node: Interpreting profiling data1176303
Ref: devtools/ports_profiler interpreting-profiling-data1176473
Ref: 89f1176473
Node: Profiling Prolog modules1177232
Ref: devtools/ports_profiler profiling-prolog-modules1177398
Ref: 8a01177398
Node: Profiling plain Prolog code1177842
Ref: devtools/ports_profiler profiling-plain-prolog-code1177996
Ref: 8a11177996
Node: Known issues<4>1179429
Ref: devtools/ports_profiler known-issues1179550
Ref: 8a21179550
Node: profiler1179708
Ref: devtools/profiler doc1179824
Ref: 8a31179824
Ref: devtools/profiler profiler1179824
Ref: 8a41179824
Node: Loading<12>1180070
Ref: devtools/profiler loading1180165
Ref: 8a51180165
Node: Testing<11>1180360
Ref: devtools/profiler testing1180498
Ref: 8a61180498
Node: Supported backend Prolog compilers1180624
Ref: devtools/profiler supported-backend-prolog-compilers1180786
Ref: 8a71180786
Node: Compiling source code for profiling1182809
Ref: devtools/profiler compiling-source-code-for-profiling1182951
Ref: 8a81182951
Node: tutor1183459
Ref: devtools/tutor doc1183568
Ref: 8a91183568
Ref: devtools/tutor tutor1183568
Ref: 8aa1183568
Node: API documentation<13>1183899
Ref: devtools/tutor api-documentation1184001
Ref: 8ab1184001
Node: Loading<13>1184141
Ref: devtools/tutor loading1184260
Ref: 8ac1184260
Node: Usage<6>1184373
Ref: devtools/tutor usage1184462
Ref: 8ad1184462
Node: wrapper1184552
Ref: devtools/wrapper doc1184644
Ref: 8ae1184644
Ref: devtools/wrapper wrapper1184644
Ref: 8af1184644
Node: API documentation<14>1185751
Ref: devtools/wrapper api-documentation1185855
Ref: 8b01185855
Node: Loading<14>1185997
Ref: devtools/wrapper loading1186119
Ref: 8b11186119
Node: Workflows1186234
Ref: devtools/wrapper workflows1186351
Ref: 8b21186351
Node: Customization<2>1186619
Ref: devtools/wrapper customization1186744
Ref: 8b31186744
Node: Current limitations1188113
Ref: devtools/wrapper current-limitations1188220
Ref: 8b41188220
Node: Libraries1189232
Ref: libraries/index doc1189341
Ref: 8b51189341
Ref: libraries/index libraries1189341
Ref: 8b61189341
Node: Overview<2>1190066
Ref: libraries/overview doc1190160
Ref: 8b71190160
Ref: libraries/overview overview1190160
Ref: 8b81190160
Node: Library documentation1191151
Ref: libraries/overview library-documentation1191265
Ref: 8b91191265
Node: Loading libraries1191723
Ref: libraries/overview loading-libraries1191863
Ref: 8ba1191863
Node: Testing libraries1192831
Ref: libraries/overview testing-libraries1192957
Ref: 8bb1192957
Node: Credits1193615
Ref: libraries/overview credits1193738
Ref: 8bc1193738
Node: Other notes<2>1194490
Ref: libraries/overview other-notes1194587
Ref: 8bd1194587
Node: arbitrary1194749
Ref: libraries/arbitrary doc1194862
Ref: 8be1194862
Ref: libraries/arbitrary arbitrary1194862
Ref: 8bf1194862
Node: API documentation<15>1195524
Ref: libraries/arbitrary api-documentation1195630
Ref: 8c01195630
Node: Loading<15>1195758
Ref: libraries/arbitrary loading1195884
Ref: 8c11195884
Node: Testing<12>1196028
Ref: libraries/arbitrary testing1196141
Ref: 8c21196141
Node: Usage<7>1196282
Ref: libraries/arbitrary usage1196397
Ref: 8c31196397
Node: Examples<157>1198604
Ref: libraries/arbitrary examples1198723
Ref: 8c41198723
Node: Known issues<5>1198832
Ref: libraries/arbitrary known-issues1198934
Ref: 8c51198934
Node: assignvars1199226
Ref: libraries/assignvars doc1199334
Ref: 8c61199334
Ref: libraries/assignvars assignvars1199334
Ref: 8c71199334
Node: API documentation<16>1200307
Ref: libraries/assignvars api-documentation1200414
Ref: 8c81200414
Node: Loading<16>1200543
Ref: libraries/assignvars loading1200670
Ref: 8c91200670
Node: Testing<13>1200815
Ref: libraries/assignvars testing1200912
Ref: 8ca1200912
Node: base641201053
Ref: libraries/base64 doc1201163
Ref: 8cb1201163
Ref: libraries/base64 base641201163
Ref: 8cc1201163
Node: API documentation<17>1201514
Ref: libraries/base64 api-documentation1201617
Ref: 8cd1201617
Node: Loading<17>1201742
Ref: libraries/base64 loading1201865
Ref: 8ce1201865
Node: Testing<14>1202014
Ref: libraries/base64 testing1202124
Ref: 8cf1202124
Node: Encoding1202260
Ref: libraries/base64 encoding1202367
Ref: 8d01202367
Node: Decoding1203415
Ref: libraries/base64 decoding1203502
Ref: 8d11203502
Node: basic_types1204533
Ref: libraries/basic_types doc1204644
Ref: 8d21204644
Ref: libraries/basic_types basic-types1204644
Ref: 8d31204644
Node: API documentation<18>1205063
Ref: libraries/basic_types api-documentation1205171
Ref: 8d41205171
Node: Loading<18>1205295
Ref: libraries/basic_types loading1205423
Ref: 8d51205423
Node: Testing<15>1205569
Ref: libraries/basic_types testing1205667
Ref: 8d61205667
Node: coroutining1205830
Ref: libraries/coroutining doc1205939
Ref: 8d71205939
Ref: libraries/coroutining coroutining1205939
Ref: 8d81205939
Node: API documentation<19>1206483
Ref: libraries/coroutining api-documentation1206591
Ref: 8d91206591
Node: Loading<19>1206721
Ref: libraries/coroutining loading1206849
Ref: 8da1206849
Node: Testing<16>1206995
Ref: libraries/coroutining testing1207093
Ref: 8db1207093
Node: cbor1207234
Ref: libraries/cbor doc1207335
Ref: 8dc1207335
Ref: libraries/cbor cbor1207335
Ref: 8dd1207335
Node: Representation1207866
Ref: libraries/cbor representation1207960
Ref: 8de1207960
Node: Encoding<2>1209815
Ref: libraries/cbor encoding1209929
Ref: 8df1209929
Node: Decoding<2>1210353
Ref: libraries/cbor decoding1210474
Ref: 8e01210474
Node: API documentation<20>1210694
Ref: libraries/cbor api-documentation1210815
Ref: 8e11210815
Node: Loading<20>1210938
Ref: libraries/cbor loading1211059
Ref: 8e21211059
Node: Testing<17>1211198
Ref: libraries/cbor testing1211289
Ref: 8e31211289
Node: csv1211423
Ref: libraries/csv doc1211518
Ref: 8e41211518
Ref: libraries/csv csv1211518
Ref: 8e51211518
Node: API documentation<21>1212463
Ref: libraries/csv api-documentation1212563
Ref: 8e61212563
Node: Loading<21>1212685
Ref: libraries/csv loading1212805
Ref: 8e71212805
Node: Testing<18>1212943
Ref: libraries/csv testing1213050
Ref: 8e81213050
Node: Usage<8>1213183
Ref: libraries/csv usage1213270
Ref: 8e91213270
Node: dates1215606
Ref: libraries/dates doc1215707
Ref: 8ea1215707
Ref: libraries/dates dates1215707
Ref: 8eb1215707
Node: API documentation<22>1216089
Ref: libraries/dates api-documentation1216191
Ref: 8ec1216191
Node: Loading<22>1216315
Ref: libraries/dates loading1216417
Ref: 8ed1216417
Node: dependents1216565
Ref: libraries/dependents doc1216675
Ref: 26a1216675
Ref: libraries/dependents dependents1216675
Ref: 8ee1216675
Node: API documentation<23>1217005
Ref: libraries/dependents api-documentation1217112
Ref: 8ef1217112
Node: Loading<23>1217243
Ref: libraries/dependents loading1217350
Ref: 8f01217350
Node: dictionaries1217505
Ref: libraries/dictionaries doc1217614
Ref: 8f11217614
Ref: libraries/dictionaries dictionaries1217614
Ref: 8f21217614
Node: API documentation<24>1218098
Ref: libraries/dictionaries api-documentation1218207
Ref: 8f31218207
Node: Loading<24>1218340
Ref: libraries/dictionaries loading1218469
Ref: 8f41218469
Node: Testing<19>1218618
Ref: libraries/dictionaries testing1218734
Ref: 8f51218734
Node: Usage<9>1218878
Ref: libraries/dictionaries usage1218993
Ref: 8f61218993
Node: Credits<2>1220656
Ref: libraries/dictionaries credits1220751
Ref: 8f71220751
Node: edcg1221152
Ref: libraries/edcg doc1221257
Ref: 2f61221257
Ref: libraries/edcg edcg1221257
Ref: 8f81221257
Node: API documentation<25>1222772
Ref: libraries/edcg api-documentation1222873
Ref: 8f91222873
Node: Loading<25>1222998
Ref: libraries/edcg loading1223119
Ref: 8fa1223119
Node: Testing<20>1223268
Ref: libraries/edcg testing1223377
Ref: 8fb1223377
Node: Usage<10>1223541
Ref: libraries/edcg usage1223651
Ref: 8fc1223651
Node: Introduction1224390
Ref: libraries/edcg introduction1224495
Ref: 8fd1224495
Node: Syntax1225123
Ref: libraries/edcg syntax1225244
Ref: 8fe1225244
Node: Declaration of Predicates1227139
Ref: libraries/edcg declaration-of-predicates1227275
Ref: 8ff1227275
Node: Declaration of Accumulators1227605
Ref: libraries/edcg declaration-of-accumulators1227766
Ref: 9001227766
Node: Declaration of Passed Arguments1229152
Ref: libraries/edcg declaration-of-passed-arguments1229312
Ref: 9011229312
Node: Additional documentation1229971
Ref: libraries/edcg additional-documentation1230095
Ref: 9021230095
Ref: Additional documentation-Footnote-11230477
Ref: Additional documentation-Footnote-21230527
Ref: Additional documentation-Footnote-31230595
Ref: Additional documentation-Footnote-41230668
Node: events1230741
Ref: libraries/events doc1230860
Ref: 9031230860
Ref: libraries/events events1230860
Ref: 9041230860
Node: API documentation<26>1231515
Ref: libraries/events api-documentation1231618
Ref: 9051231618
Node: Loading<26>1231745
Ref: libraries/events loading1231848
Ref: 9061231848
Node: expand_library_alias_paths1231998
Ref: libraries/expand_library_alias_paths doc1232122
Ref: 9071232122
Ref: libraries/expand_library_alias_paths expand-library-alias-paths1232122
Ref: 9081232122
Node: API documentation<27>1232531
Ref: libraries/expand_library_alias_paths api-documentation1232654
Ref: 9091232654
Node: Loading<27>1232801
Ref: libraries/expand_library_alias_paths loading1232942
Ref: 90a1232942
Node: Usage<11>1233113
Ref: libraries/expand_library_alias_paths usage1233224
Ref: 90b1233224
Node: expecteds1233579
Ref: libraries/expecteds doc1233703
Ref: 2301233703
Ref: libraries/expecteds expecteds1233703
Ref: 90c1233703
Node: API documentation<28>1234542
Ref: libraries/expecteds api-documentation1234648
Ref: 90d1234648
Node: Loading<28>1234778
Ref: libraries/expecteds loading1234904
Ref: 90e1234904
Node: Testing<21>1235050
Ref: libraries/expecteds testing1235164
Ref: 90f1235164
Node: Usage<12>1235305
Ref: libraries/expecteds usage1235416
Ref: 9101235416
Node: See also1236119
Ref: libraries/expecteds see-also1236210
Ref: 9111236210
Node: gensym1236273
Ref: libraries/gensym doc1236374
Ref: 9121236374
Ref: libraries/gensym gensym1236374
Ref: 9131236374
Node: API documentation<29>1236728
Ref: libraries/gensym api-documentation1236831
Ref: 9141236831
Node: Loading<29>1236958
Ref: libraries/gensym loading1237081
Ref: 9151237081
Node: Testing<22>1237224
Ref: libraries/gensym testing1237317
Ref: 9161237317
Node: git1237455
Ref: libraries/git doc1237552
Ref: 9171237552
Ref: libraries/git git1237552
Ref: 9181237552
Node: API documentation<30>1237946
Ref: libraries/git api-documentation1238046
Ref: 9191238046
Node: Loading<30>1238170
Ref: libraries/git loading1238290
Ref: 91a1238290
Node: Testing<23>1238430
Ref: libraries/git testing1238538
Ref: 91b1238538
Node: Usage<13>1238673
Ref: libraries/git usage1238761
Ref: 91c1238761
Node: heaps1240119
Ref: libraries/heaps doc1240221
Ref: 91d1240221
Ref: libraries/heaps heaps1240221
Ref: 91e1240221
Node: API documentation<31>1240429
Ref: libraries/heaps api-documentation1240531
Ref: 91f1240531
Node: Loading<31>1240657
Ref: libraries/heaps loading1240779
Ref: 9201240779
Node: Testing<24>1240921
Ref: libraries/heaps testing1241032
Ref: 9211241032
Node: Credits<3>1241169
Ref: libraries/heaps credits1241260
Ref: 9221241260
Node: hierarchies1241389
Ref: libraries/hierarchies doc1241498
Ref: 9231241498
Ref: libraries/hierarchies hierarchies1241498
Ref: 9241241498
Node: API documentation<32>1241747
Ref: libraries/hierarchies api-documentation1241855
Ref: 9251241855
Node: Loading<32>1241987
Ref: libraries/hierarchies loading1242115
Ref: 9261242115
Node: Testing<25>1242263
Ref: libraries/hierarchies testing1242361
Ref: 9271242361
Node: hook_flows1242504
Ref: libraries/hook_flows doc1242620
Ref: 2f11242620
Ref: libraries/hook_flows hook-flows1242620
Ref: 9281242620
Node: API documentation<33>1243510
Ref: libraries/hook_flows api-documentation1243617
Ref: 9291243617
Node: Loading<33>1243748
Ref: libraries/hook_flows loading1243875
Ref: 92a1243875
Node: Testing<26>1244022
Ref: libraries/hook_flows testing1244137
Ref: 92b1244137
Node: Usage<14>1244279
Ref: libraries/hook_flows usage1244374
Ref: 92c1244374
Node: hook_objects1245807
Ref: libraries/hook_objects doc1245916
Ref: 2f21245916
Ref: libraries/hook_objects hook-objects1245916
Ref: 92d1245916
Node: API documentation<34>1246421
Ref: libraries/hook_objects api-documentation1246530
Ref: 92e1246530
Node: Loading<34>1246663
Ref: libraries/hook_objects loading1246792
Ref: 92f1246792
Node: Testing<27>1247084
Ref: libraries/hook_objects testing1247201
Ref: 9301247201
Node: Usage<15>1247347
Ref: libraries/hook_objects usage1247444
Ref: 9311247444
Node: Using the Prolog backend adapter file expansion rules1248115
Ref: libraries/hook_objects using-the-prolog-backend-adapter-file-expansion-rules1248291
Ref: 9321248291
Node: Restoring the default compiler expansion workflow1248639
Ref: libraries/hook_objects restoring-the-default-compiler-expansion-workflow1248882
Ref: 9331248882
Node: Preventing applying any other user-defined expansion rules1249239
Ref: libraries/hook_objects preventing-applying-any-other-user-defined-expansion-rules1249495
Ref: 9341249495
Node: Expanding grammar rules into clauses independently of the compiler1250389
Ref: libraries/hook_objects expanding-grammar-rules-into-clauses-independently-of-the-compiler1250648
Ref: 9351250648
Node: Using the expansion rules defined in a Prolog module1251046
Ref: libraries/hook_objects using-the-expansion-rules-defined-in-a-prolog-module1251300
Ref: 9361251300
Node: Wrap the contents of a plain Prolog file as an object1251704
Ref: libraries/hook_objects wrap-the-contents-of-a-plain-prolog-file-as-an-object1251937
Ref: 9371251937
Node: Outputting term-expansion results to a stream1252717
Ref: libraries/hook_objects outputting-term-expansion-results-to-a-stream1252958
Ref: 9381252958
Node: Printing entity predicate goals before or after calling them1253331
Ref: libraries/hook_objects printing-entity-predicate-goals-before-or-after-calling-them1253536
Ref: 9391253536
Node: Suppressing goals1254147
Ref: libraries/hook_objects suppressing-goals1254298
Ref: 93a1254298
Node: html1254987
Ref: libraries/html doc1255095
Ref: 93b1255095
Ref: libraries/html html1255095
Ref: 93c1255095
Node: API documentation<35>1256712
Ref: libraries/html api-documentation1256813
Ref: 93d1256813
Node: Loading<35>1256938
Ref: libraries/html loading1257059
Ref: 93e1257059
Node: Testing<28>1257200
Ref: libraries/html testing1257326
Ref: 93f1257326
Node: Generating a HTML document1257462
Ref: libraries/html generating-a-html-document1257603
Ref: 9401257603
Node: Generating a HTML fragment1258338
Ref: libraries/html generating-a-html-fragment1258510
Ref: 9411258510
Node: Working with callbacks to generate content1258980
Ref: libraries/html working-with-callbacks-to-generate-content1259154
Ref: 9421259154
Node: Working with custom elements1260128
Ref: libraries/html working-with-custom-elements1260267
Ref: 9431260267
Node: intervals1260879
Ref: libraries/intervals doc1260979
Ref: 9441260979
Ref: libraries/intervals intervals1260979
Ref: 9451260979
Node: API documentation<36>1261311
Ref: libraries/intervals api-documentation1261417
Ref: 9461261417
Node: Loading<36>1261547
Ref: libraries/intervals loading1261673
Ref: 9471261673
Node: Testing<29>1261819
Ref: libraries/intervals testing1261915
Ref: 9481261915
Node: java1262056
Ref: libraries/java doc1262156
Ref: 9491262156
Ref: libraries/java java1262156
Ref: 94a1262156
Node: API documentation<37>1263339
Ref: libraries/java api-documentation1263440
Ref: 94b1263440
Node: Loading<37>1263565
Ref: libraries/java loading1263686
Ref: 94c1263686
Node: Testing<30>1263827
Ref: libraries/java testing1263936
Ref: 94d1263936
Node: Usage<16>1264072
Ref: libraries/java usage1264185
Ref: 94e1264185
Node: Known issues<6>1264711
Ref: libraries/java known-issues1264804
Ref: 94f1264804
Node: json1265205
Ref: libraries/json doc1265303
Ref: 9501265303
Ref: libraries/json json1265303
Ref: 9511265303
Node: API documentation<38>1265975
Ref: libraries/json api-documentation1266076
Ref: 9521266076
Node: Loading<38>1266201
Ref: libraries/json loading1266322
Ref: 9531266322
Node: Testing<31>1266463
Ref: libraries/json testing1266580
Ref: 9541266580
Node: Representation<2>1266817
Ref: libraries/json representation1266934
Ref: 9551266934
Node: Encoding<3>1271593
Ref: libraries/json encoding1271710
Ref: 9561271710
Node: Decoding<3>1272516
Ref: libraries/json decoding1272607
Ref: 9571272607
Node: logging1273119
Ref: libraries/logging doc1273218
Ref: 9581273218
Ref: libraries/logging logging1273218
Ref: 9591273218
Node: API documentation<39>1273391
Ref: libraries/logging api-documentation1273495
Ref: 95a1273495
Node: Loading<39>1273623
Ref: libraries/logging loading1273727
Ref: 95b1273727
Node: loops1273879
Ref: libraries/loops doc1273978
Ref: 95c1273978
Ref: libraries/loops loops1273978
Ref: 95d1273978
Node: API documentation<40>1274229
Ref: libraries/loops api-documentation1274331
Ref: 95e1274331
Node: Loading<40>1274457
Ref: libraries/loops loading1274579
Ref: 95f1274579
Node: Testing<32>1274726
Ref: libraries/loops testing1274836
Ref: 9601274836
Node: Usage<17>1274973
Ref: libraries/loops usage1275063
Ref: 9611275063
Node: meta1275130
Ref: libraries/meta doc1275235
Ref: 9621275235
Ref: libraries/meta meta1275235
Ref: 9631275235
Node: API documentation<41>1275654
Ref: libraries/meta api-documentation1275755
Ref: 9641275755
Node: Loading<41>1275880
Ref: libraries/meta loading1276001
Ref: 9651276001
Node: Testing<33>1276147
Ref: libraries/meta testing1276256
Ref: 9661276256
Node: Usage<18>1276392
Ref: libraries/meta usage1276481
Ref: 9671276481
Node: meta_compiler1276568
Ref: libraries/meta_compiler doc1276687
Ref: 9681276687
Ref: libraries/meta_compiler meta-compiler1276687
Ref: 9691276687
Node: API documentation<42>1276985
Ref: libraries/meta_compiler api-documentation1277095
Ref: 96a1277095
Node: Loading<42>1277229
Ref: libraries/meta_compiler loading1277359
Ref: 96b1277359
Node: Testing<34>1277514
Ref: libraries/meta_compiler testing1277632
Ref: 96c1277632
Node: Usage<19>1277777
Ref: libraries/meta_compiler usage1277875
Ref: 96d1277875
Node: nested_dictionaries1278495
Ref: libraries/nested_dictionaries doc1278619
Ref: 96e1278619
Ref: libraries/nested_dictionaries nested-dictionaries1278619
Ref: 96f1278619
Node: API documentation<43>1279192
Ref: libraries/nested_dictionaries api-documentation1279308
Ref: 9701279308
Node: Loading<43>1279448
Ref: libraries/nested_dictionaries loading1279584
Ref: 9711279584
Node: Testing<35>1279740
Ref: libraries/nested_dictionaries testing1279864
Ref: 9721279864
Node: Usage<20>1280015
Ref: libraries/nested_dictionaries usage1280153
Ref: 9731280153
Node: Curly term representation1281859
Ref: libraries/nested_dictionaries curly-term-representation1281977
Ref: 9741281977
Node: optionals1282560
Ref: libraries/optionals doc1282678
Ref: 9751282678
Ref: libraries/optionals optionals1282678
Ref: 9761282678
Node: API documentation<44>1283572
Ref: libraries/optionals api-documentation1283678
Ref: 9771283678
Node: Loading<44>1283808
Ref: libraries/optionals loading1283934
Ref: 9781283934
Node: Testing<36>1284080
Ref: libraries/optionals testing1284194
Ref: 9791284194
Node: Usage<21>1284335
Ref: libraries/optionals usage1284449
Ref: 97a1284449
Node: See also<2>1285154
Ref: libraries/optionals see-also1285248
Ref: 97b1285248
Node: options1285311
Ref: libraries/options doc1285412
Ref: 97c1285412
Ref: libraries/options options1285412
Ref: 97d1285412
Node: API documentation<45>1285663
Ref: libraries/options api-documentation1285767
Ref: 97e1285767
Node: Loading<45>1285895
Ref: libraries/options loading1286019
Ref: 97f1286019
Node: Testing<37>1286171
Ref: libraries/options testing1286283
Ref: 9801286283
Node: Usage<22>1286422
Ref: libraries/options usage1286514
Ref: 9811286514
Node: os1287308
Ref: libraries/os doc1287406
Ref: 9821287406
Ref: libraries/os os1287406
Ref: 9831287406
Node: API documentation<46>1287817
Ref: libraries/os api-documentation1287916
Ref: 9841287916
Node: Loading<46>1288039
Ref: libraries/os loading1288158
Ref: 9851288158
Node: Testing<38>1288297
Ref: libraries/os testing1288410
Ref: 9861288410
Node: Known issues<7>1288544
Ref: libraries/os known-issues1288637
Ref: 9871288637
Node: queues1289050
Ref: libraries/queues doc1289147
Ref: 9881289147
Ref: libraries/queues queues1289147
Ref: 9891289147
Node: API documentation<47>1289446
Ref: libraries/queues api-documentation1289549
Ref: 98a1289549
Node: Loading<47>1289676
Ref: libraries/queues loading1289799
Ref: 98b1289799
Node: Testing<39>1289942
Ref: libraries/queues testing1290053
Ref: 98c1290053
Node: Usage<23>1290191
Ref: libraries/queues usage1290282
Ref: 98d1290282
Node: random1291121
Ref: libraries/random doc1291222
Ref: 98e1291222
Ref: libraries/random random1291222
Ref: 98f1291222
Node: API documentation<48>1291527
Ref: libraries/random api-documentation1291630
Ref: 9901291630
Node: Loading<48>1291757
Ref: libraries/random loading1291880
Ref: 9911291880
Node: Testing<40>1292023
Ref: libraries/random testing1292134
Ref: 9921292134
Node: Usage<24>1292272
Ref: libraries/random usage1292363
Ref: 9931292363
Node: reader1294119
Ref: libraries/reader doc1294219
Ref: 9941294219
Ref: libraries/reader reader1294219
Ref: 9951294219
Node: API documentation<49>1294630
Ref: libraries/reader api-documentation1294733
Ref: 9961294733
Node: Loading<49>1294860
Ref: libraries/reader loading1294983
Ref: 9971294983
Node: Testing<41>1295126
Ref: libraries/reader testing1295219
Ref: 9981295219
Node: redis1295357
Ref: libraries/redis doc1295455
Ref: 9991295455
Ref: libraries/redis redis1295455
Ref: 99a1295455
Node: API documentation<50>1295952
Ref: libraries/redis api-documentation1296054
Ref: 99b1296054
Node: Loading<50>1296180
Ref: libraries/redis loading1296302
Ref: 99c1296302
Node: Testing<42>1296428
Ref: libraries/redis testing1296539
Ref: 99d1296539
Node: Credits<4>1297171
Ref: libraries/redis credits1297286
Ref: 99e1297286
Node: Known issues<8>1297396
Ref: libraries/redis known-issues1297491
Ref: 99f1297491
Node: sets1297892
Ref: libraries/sets doc1297994
Ref: 9a01297994
Ref: libraries/sets sets1297994
Ref: 9a11297994
Node: API documentation<51>1298528
Ref: libraries/sets api-documentation1298629
Ref: 9a21298629
Node: Loading<51>1298754
Ref: libraries/sets loading1298875
Ref: 9a31298875
Node: Testing<43>1299016
Ref: libraries/sets testing1299125
Ref: 9a41299125
Node: Usage<25>1299261
Ref: libraries/sets usage1299369
Ref: 9a51299369
Node: Credits<5>1300367
Ref: libraries/sets credits1300455
Ref: 9a61300455
Node: statistics1300552
Ref: libraries/statistics doc1300656
Ref: 9a71300656
Ref: libraries/statistics statistics1300656
Ref: 9a81300656
Node: API documentation<52>1301083
Ref: libraries/statistics api-documentation1301190
Ref: 9a91301190
Node: Loading<52>1301321
Ref: libraries/statistics loading1301448
Ref: 9aa1301448
Node: Testing<44>1301595
Ref: libraries/statistics testing1301692
Ref: 9ab1301692
Node: term_io1301834
Ref: libraries/term_io doc1301941
Ref: 9ac1301941
Ref: libraries/term_io term-io1301941
Ref: 9ad1301941
Node: API documentation<53>1302441
Ref: libraries/term_io api-documentation1302545
Ref: 9ae1302545
Node: Loading<53>1302673
Ref: libraries/term_io loading1302797
Ref: 9af1302797
Node: Testing<45>1302941
Ref: libraries/term_io testing1303035
Ref: 9b01303035
Node: timeout1303174
Ref: libraries/timeout doc1303276
Ref: 9b11303276
Ref: libraries/timeout timeout1303276
Ref: 9b21303276
Node: API documentation<54>1303863
Ref: libraries/timeout api-documentation1303967
Ref: 9b31303967
Node: Loading<54>1304095
Ref: libraries/timeout loading1304219
Ref: 9b41304219
Node: Testing<46>1304363
Ref: libraries/timeout testing1304457
Ref: 9b51304457
Node: types1304596
Ref: libraries/types doc1304703
Ref: 9b61304703
Ref: libraries/types types1304703
Ref: 9b71304703
Node: API documentation<55>1305110
Ref: libraries/types api-documentation1305212
Ref: 9b81305212
Node: Loading<55>1305338
Ref: libraries/types loading1305460
Ref: 9b91305460
Node: Testing<47>1305810
Ref: libraries/types testing1305902
Ref: 9ba1305902
Node: unicode_data1306039
Ref: libraries/unicode_data doc1306143
Ref: 9bb1306143
Ref: libraries/unicode_data unicode-data1306143
Ref: 9bc1306143
Node: Authors1306419
Ref: libraries/unicode_data authors1306510
Ref: 9bd1306510
Node: License1306610
Ref: libraries/unicode_data license1306717
Ref: 9be1306717
Node: Website1307001
Ref: libraries/unicode_data website1307117
Ref: 9bf1307117
Node: Description<156>1307418
Ref: libraries/unicode_data description1307539
Ref: 9c01307539
Node: Requirements1308151
Ref: libraries/unicode_data requirements1308274
Ref: 9c11308274
Node: Usage<26>1308684
Ref: libraries/unicode_data usage1308806
Ref: 9c21308806
Node: Known issues<9>1309254
Ref: libraries/unicode_data known-issues1309380
Ref: 9c31309380
Node: Acknowledgements1310042
Ref: libraries/unicode_data acknowledgements1310180
Ref: 9c41310180
Node: Files and API Summary1310326
Ref: libraries/unicode_data files-and-api-summary1310440
Ref: 9c51310440
Node: unicode_arabic_shaping pl1313620
Ref: libraries/unicode_data unicode-arabic-shaping-pl1313756
Ref: 9c61313756
Ref: libraries/unicode_data unicode-arabic-shapingpl1313756
Ref: 9c71313756
Node: unicode_bidi_mirroring pl1313909
Ref: libraries/unicode_data unicode-bidi-mirroring-pl1314071
Ref: 9c81314071
Ref: libraries/unicode_data unicode-bidi-mirroringpl1314071
Ref: 9c91314071
Node: unicode_blocks pl1314224
Ref: libraries/unicode_data unicode-blocks-pl1314384
Ref: 9ca1314384
Ref: libraries/unicode_data unicode-blockspl1314384
Ref: 9cb1314384
Node: unicode_case_folding pl1314514
Ref: libraries/unicode_data unicode-case-folding-pl1314670
Ref: 9cc1314670
Ref: libraries/unicode_data unicode-case-foldingpl1314670
Ref: 9cd1314670
Node: unicode_categories pl1314817
Ref: libraries/unicode_data unicode-categories-pl1314979
Ref: 9ce1314979
Ref: libraries/unicode_data unicode-categoriespl1314979
Ref: 9cf1314979
Node: unicode_cjk_radicals pl1315159
Ref: libraries/unicode_data unicode-cjk-radicals-pl1315331
Ref: 9d01315331
Ref: libraries/unicode_data unicode-cjk-radicalspl1315331
Ref: 9d11315331
Node: unicode_composition_exclusions pl1315477
Ref: libraries/unicode_data unicode-composition-exclusions-pl1315654
Ref: 9d21315654
Ref: libraries/unicode_data unicode-composition-exclusionspl1315654
Ref: 9d31315654
Node: unicode_core_properties pl1315830
Ref: libraries/unicode_data unicode-core-properties-pl1316013
Ref: 9d41316013
Ref: libraries/unicode_data unicode-core-propertiespl1316013
Ref: 9d51316013
Node: unicode_decomposition_type pl1316896
Ref: libraries/unicode_data unicode-decomposition-type-pl1317068
Ref: 9d61317068
Ref: libraries/unicode_data unicode-decomposition-typepl1317068
Ref: 9d71317068
Node: unicode_derived_age pl1317698
Ref: libraries/unicode_data unicode-derived-age-pl1317873
Ref: 9d81317873
Ref: libraries/unicode_data unicode-derived-agepl1317873
Ref: 9d91317873
Node: unicode_derived_bidi_class pl1318013
Ref: libraries/unicode_data unicode-derived-bidi-class-pl1318193
Ref: 9da1318193
Ref: libraries/unicode_data unicode-derived-bidi-classpl1318193
Ref: 9db1318193
Node: unicode_derived_combining_class pl1318354
Ref: libraries/unicode_data unicode-derived-combining-class-pl1318546
Ref: 9dc1318546
Ref: libraries/unicode_data unicode-derived-combining-classpl1318546
Ref: 9dd1318546
Node: unicode_derived_core_properties pl1318722
Ref: libraries/unicode_data unicode-derived-core-properties-pl1318922
Ref: 9de1318922
Ref: libraries/unicode_data unicode-derived-core-propertiespl1318922
Ref: 9df1318922
Node: unicode_derived_decomposition_type pl1319096
Ref: libraries/unicode_data unicode-derived-decomposition-type-pl1319297
Ref: 9e01319297
Ref: libraries/unicode_data unicode-derived-decomposition-typepl1319297
Ref: 9e11319297
Node: unicode_derived_east_asian_width pl1319482
Ref: libraries/unicode_data unicode-derived-east-asian-width-pl1319681
Ref: 9e21319681
Ref: libraries/unicode_data unicode-derived-east-asian-widthpl1319681
Ref: 9e31319681
Node: unicode_derived_joining_group pl1319860
Ref: libraries/unicode_data unicode-derived-joining-group-pl1320053
Ref: 9e41320053
Ref: libraries/unicode_data unicode-derived-joining-grouppl1320053
Ref: 9e51320053
Node: unicode_derived_joining_type pl1320223
Ref: libraries/unicode_data unicode-derived-joining-type-pl1320410
Ref: 9e61320410
Ref: libraries/unicode_data unicode-derived-joining-typepl1320410
Ref: 9e71320410
Node: unicode_derived_line_break pl1320577
Ref: libraries/unicode_data unicode-derived-line-break-pl1320770
Ref: 9e81320770
Ref: libraries/unicode_data unicode-derived-line-breakpl1320770
Ref: 9e91320770
Node: unicode_derived_normalization_props pl1320931
Ref: libraries/unicode_data unicode-derived-normalization-props-pl1321124
Ref: 9ea1321124
Ref: libraries/unicode_data unicode-derived-normalization-propspl1321124
Ref: 9eb1321124
Node: unicode_derived_numeric_type pl1321823
Ref: libraries/unicode_data unicode-derived-numeric-type-pl1322020
Ref: 9ec1322020
Ref: libraries/unicode_data unicode-derived-numeric-typepl1322020
Ref: 9ed1322020
Node: unicode_derived_numeric_values pl1322187
Ref: libraries/unicode_data unicode-derived-numeric-values-pl1322377
Ref: 9ee1322377
Ref: libraries/unicode_data unicode-derived-numeric-valuespl1322377
Ref: 9ef1322377
Node: unicode_hangul_syllable_type pl1322549
Ref: libraries/unicode_data unicode-hangul-syllable-type-pl1322739
Ref: 9f01322739
Ref: libraries/unicode_data unicode-hangul-syllable-typepl1322739
Ref: 9f11322739
Node: unicode_indic_matra_category pl1322914
Ref: libraries/unicode_data unicode-indic-matra-category-pl1323105
Ref: 9f21323105
Ref: libraries/unicode_data unicode-indic-matra-categorypl1323105
Ref: 9f31323105
Node: unicode_indic_syllabic_category pl1323280
Ref: libraries/unicode_data unicode-indic-syllabic-category-pl1323455
Ref: 9f41323455
Ref: libraries/unicode_data unicode-indic-syllabic-categorypl1323455
Ref: 9f51323455
Node: unicode_jamo pl1323639
Ref: libraries/unicode_data unicode-jamo-pl1323806
Ref: 9f61323806
Ref: libraries/unicode_data unicode-jamopl1323806
Ref: 9f71323806
Node: unicode_name_aliases pl1323931
Ref: libraries/unicode_data unicode-name-aliases-pl1324080
Ref: 9f81324080
Ref: libraries/unicode_data unicode-name-aliasespl1324080
Ref: 9f91324080
Node: unicode_names pl1324227
Ref: libraries/unicode_data unicode-names-pl1324381
Ref: 9fa1324381
Ref: libraries/unicode_data unicode-namespl1324381
Ref: 9fb1324381
Node: unicode_prop_list pl1324544
Ref: libraries/unicode_data unicode-prop-list-pl1324699
Ref: 9fc1324699
Ref: libraries/unicode_data unicode-prop-listpl1324699
Ref: 9fd1324699
Node: unicode_range_scripts pl1325989
Ref: libraries/unicode_data unicode-range-scripts-pl1326156
Ref: 9fe1326156
Ref: libraries/unicode_data unicode-range-scriptspl1326156
Ref: 9ff1326156
Node: unicode_script_extensions pl1326330
Ref: libraries/unicode_data unicode-script-extensions-pl1326495
Ref: a001326495
Ref: libraries/unicode_data unicode-script-extensionspl1326495
Ref: a011326495
Node: unicode_scripts pl1326678
Ref: libraries/unicode_data unicode-scripts-pl1326844
Ref: a021326844
Ref: libraries/unicode_data unicode-scriptspl1326844
Ref: a031326844
Node: unicode_special_casing pl1327009
Ref: libraries/unicode_data unicode-special-casing-pl1327173
Ref: a041327173
Ref: libraries/unicode_data unicode-special-casingpl1327173
Ref: a051327173
Node: unicode_unihan_variants pl1327328
Ref: libraries/unicode_data unicode-unihan-variants-pl1327492
Ref: a061327492
Ref: libraries/unicode_data unicode-unihan-variantspl1327492
Ref: a071327492
Node: unicode_version pl1327651
Ref: libraries/unicode_data unicode-version-pl1327781
Ref: a081327781
Ref: libraries/unicode_data unicode-versionpl1327781
Ref: a091327781
Node: uuid1327915
Ref: libraries/uuid doc1328021
Ref: a0a1328021
Ref: libraries/uuid uuid1328021
Ref: a0b1328021
Node: API documentation<56>1328946
Ref: libraries/uuid api-documentation1329047
Ref: a0c1329047
Node: Loading<56>1329172
Ref: libraries/uuid loading1329293
Ref: a0d1329293
Node: Testing<48>1329434
Ref: libraries/uuid testing1329560
Ref: a0e1329560
Node: Generating version 1 UUIDs1329696
Ref: libraries/uuid generating-version-1-uuids1329837
Ref: a0f1329837
Node: Generating version 4 UUIDs1330722
Ref: libraries/uuid generating-version-4-uuids1330876
Ref: a101330876
Node: Generating the null UUID1331668
Ref: libraries/uuid generating-the-null-uuid1331787
Ref: a111331787
Node: zippers1332004
Ref: libraries/zippers doc1332089
Ref: a121332089
Ref: libraries/zippers zippers1332089
Ref: a131332089
Node: API documentation<57>1332271
Ref: libraries/zippers api-documentation1332375
Ref: a141332375
Node: Loading<57>1332503
Ref: libraries/zippers loading1332627
Ref: a151332627
Node: Testing<49>1332771
Ref: libraries/zippers testing1332865
Ref: a161332865
Node: Glossary1333004
Ref: glossary doc1333106
Ref: a171333106
Ref: glossary glossary1333106
Ref: a181333106
Ref: glossary id11333129
Ref: 3d1333129
Ref: glossary term-abstract-class1333129
Ref: a191333129
Ref: glossary term-abstract-method1333312
Ref: a1b1333312
Ref: glossary term-adapter-file1333517
Ref: 1431333517
Ref: glossary term-ancestor1333692
Ref: a1e1333692
Ref: glossary term-backend-Prolog-compiler1334091
Ref: 321334091
Ref: glossary term-built-in-method1334314
Ref: a201334314
Ref: glossary term-built-in-predicate1334558
Ref: a211334558
Ref: glossary term-category1334743
Ref: a1d1334743
Ref: glossary term-class1335092
Ref: a1a1335092
Ref: glossary term-closed-world-assumption1335361
Ref: 651335361
Ref: glossary term-closure1335691
Ref: 13f1335691
Ref: glossary term-coinductive-predicate1335902
Ref: 29c1335902
Ref: glossary term-complementing-category1336126
Ref: a231336126
Ref: glossary term-component1336248
Ref: 31d1336248
Ref: glossary term-directive1336561
Ref: a241336561
Ref: glossary term-doclet-file1336710
Ref: a251336710
Ref: glossary term-doclet-object1336858
Ref: 5e41336858
Ref: glossary term-dynamic-binding1337035
Ref: 341337035
Ref: glossary term-dynamic-entity1337411
Ref: a261337411
Ref: glossary term-early-binding1337456
Ref: a281337456
Ref: glossary term-encapsulation1337507
Ref: a291337507
Ref: glossary term-entity1337764
Ref: a271337764
Ref: glossary term-entity-directive1338242
Ref: a2b1338242
Ref: glossary term-event1338351
Ref: a2c1338351
Ref: glossary term-expansion-workflow1338660
Ref: a2d1338660
Ref: glossary term-grammar-rule1338850
Ref: a2e1338850
Ref: glossary term-grammar-rule-non-terminal1339273
Ref: a2f1339273
Ref: glossary term-grammar-rule-terminal1339501
Ref: a301339501
Ref: glossary term-hook-object1339568
Ref: 35e1339568
Ref: glossary term-hook-predicate1339951
Ref: 15a1339951
Ref: glossary term-hot-patching1340158
Ref: 1031340158
Ref: glossary term-identity1340501
Ref: a2a1340501
Ref: glossary term-inheritance1340913
Ref: 421340913
Ref: glossary term-instance1341376
Ref: a341341376
Ref: glossary term-instantiation1341583
Ref: a351341583
Ref: glossary term-interface1341844
Ref: a361341844
Ref: glossary term-lambda-expression1341885
Ref: 16e1341885
Ref: glossary term-lambda-free-variable1342237
Ref: 2511342237
Ref: glossary term-lambda-parameter1342440
Ref: 2521342440
Ref: glossary term-late-binding1342690
Ref: a371342690
Ref: glossary term-library1342741
Ref: 691342741
Ref: glossary term-library-alias1342867
Ref: 5f71342867
Ref: glossary term-library-notation1343133
Ref: 2881343133
Ref: glossary term-loader-file1343494
Ref: 1bb1343494
Ref: glossary term-local-predicate1343671
Ref: 511343671
Ref: glossary term-message1344067
Ref: 411344067
Ref: glossary term-message-lookup1344260
Ref: 351344260
Ref: glossary term-message-to-self1344636
Ref: 1681344636
Ref: glossary term-meta-argument1344850
Ref: a381344850
Ref: glossary term-meta-interpreter1345090
Ref: a391345090
Ref: glossary term-meta-predicate1345193
Ref: 4d1345193
Ref: glossary term-metaclass1345372
Ref: 6d1345372
Ref: glossary term-method1345607
Ref: a1c1345607
Ref: glossary term-module1345856
Ref: a3a1345856
Ref: glossary term-monitor1346152
Ref: 2f51346152
Ref: glossary term-multifile-predicate1346390
Ref: 2e81346390
Ref: glossary term-object1346806
Ref: 4e01346806
Ref: glossary term-object-database1347163
Ref: 1941347163
Ref: glossary term-parameter1347242
Ref: a3b1347242
Ref: glossary term-parameter-variable1347432
Ref: 9d1347432
Ref: glossary term-parametric-category1347814
Ref: a3c1347814
Ref: glossary term-parametric-entity1347875
Ref: 6281347875
Ref: glossary term-parametric-object1348436
Ref: 3d81348436
Ref: glossary term-parametric-object-proxy1348495
Ref: 3b61348495
Ref: glossary term-parent1348682
Ref: a3d1348682
Ref: glossary term-polymorphism1348747
Ref: a3e1348747
Ref: glossary term-predicate1349553
Ref: 5c1349553
Ref: glossary term-predicate-alias1349912
Ref: c41349912
Ref: glossary term-predicate-calling-context1350379
Ref: 1401350379
Ref: glossary term-predicate-declaration1350571
Ref: 521350571
Ref: glossary term-predicate-definition1350750
Ref: 531350750
Ref: glossary term-predicate-definition-context1350939
Ref: 1411350939
Ref: glossary term-predicate-directive1351065
Ref: a221351065
Ref: glossary term-predicate-execution-context1351197
Ref: 3081351197
Ref: glossary term-predicate-scope-container1351389
Ref: 3b51351389
Ref: glossary term-predicate-scope-directive1351564
Ref: 1c51351564
Ref: glossary term-predicate-shorthand1351708
Ref: 1501351708
Ref: glossary term-primary-predicate-declaration1352248
Ref: 3531352248
Ref: glossary term-private-inheritance1352321
Ref: a331352321
Ref: glossary term-private-predicate1352510
Ref: 501352510
Ref: glossary term-profiler1352638
Ref: a3f1352638
Ref: glossary term-protected-inheritance1352716
Ref: a321352716
Ref: glossary term-protected-predicate1352936
Ref: 4f1352936
Ref: glossary term-protocol1353115
Ref: 541353115
Ref: glossary term-prototype1353616
Ref: a1f1353616
Ref: glossary term-public-inheritance1353836
Ref: a311353836
Ref: glossary term-public-predicate1354007
Ref: 4e1354007
Ref: glossary term-scratch-directory1354079
Ref: 2741354079
Ref: glossary term-self1354232
Ref: 641354232
Ref: glossary term-sender1354310
Ref: 3b41354310
Ref: glossary term-settings-file1354503
Ref: 471354503
Ref: glossary term-singleton-method1354770
Ref: a401354770
Ref: glossary term-source-file1354981
Ref: 5c41354981
Ref: glossary term-source-file-directive1355395
Ref: a411355395
Ref: glossary term-specialization1355509
Ref: a421355509
Ref: glossary term-static-binding1355650
Ref: 331355650
Ref: glossary term-static-entity1356111
Ref: a431356111
Ref: glossary term-steadfastness1356155
Ref: 2a41356155
Ref: glossary term-subclass1356482
Ref: 5e1356482
Ref: glossary term-super-call1356628
Ref: 10b1356628
Ref: glossary term-superclass1356972
Ref: 5b1356972
Ref: glossary term-synchronized-predicate1357150
Ref: a441357150
Ref: glossary term-template-method1357339
Ref: a451357339
Ref: glossary term-tester-file1357394
Ref: a461357394
Ref: glossary term-this1357505
Ref: 1691357505
Ref: glossary term-threaded-engine1357769
Ref: 29a1357769
Ref: glossary term-top-level-interpreter-shorthand1358086
Ref: a471358086
Ref: glossary term-visible-predicate1358362
Ref: a481358362
Ref: bibliography alexiev931358554
Ref: a491358554
Ref: bibliography belli-et-al-921358738
Ref: a4a1358738
Ref: bibliography block891359015
Ref: a4b1359015
Ref: bibliography bobrow-et-al-881359119
Ref: 1de1359119
Ref: bibliography bratko901359289
Ref: a4c1359289
Ref: bibliography champaux921359393
Ref: 26e1359393
Ref: bibliography clocksin871359546
Ref: a4d1359546
Ref: bibliography cointe871359644
Ref: 981359644
Ref: bibliography cordes911359755
Ref: a4e1359755
Ref: bibliography covington941359854
Ref: a4f1359854
Ref: bibliography cox861359988
Ref: 1b1359988
Ref: bibliography davison891360118
Ref: a501360118
Ref: bibliography davison921360229
Ref: a511360229
Ref: bibliography davison931360452
Ref: a521360452
Ref: bibliography delzanno971360664
Ref: a531360664
Ref: bibliography dony901360831
Ref: a541360831
Ref: bibliography fornarino-et-al-891360958
Ref: 101360958
Ref: bibliography fromherz931361223
Ref: 271361223
Ref: bibliography fukunaga861361328
Ref: a551361328
Ref: bibliography goldberg831361470
Ref: 1a1361470
Ref: bibliography joy-et-al-001361600
Ref: 1c1361600
Ref: bibliography iso951361730
Ref: 2f1361730
Ref: bibliography knuth841361901
Ref: a561361901
Ref: bibliography lieberman861361985
Ref: 171361985
Ref: bibliography maes871362134
Ref: 121362134
Ref: bibliography mccabe921362234
Ref: 261362234
Ref: bibliography moon861362319
Ref: 1021362319
Ref: bibliography moss941362409
Ref: 1dd1362409
Ref: bibliography moura941362551
Ref: 991362551
Ref: bibliography moura991362742
Ref: a571362742
Ref: bibliography moura001362917
Ref: a581362917
Ref: bibliography razek921363031
Ref: 111363031
Ref: bibliography rumbaugh871363123
Ref: e1363123
Ref: bibliography rumbaugh881363250
Ref: f1363250
Ref: bibliography schachte951363381
Ref: a591363381
Ref: bibliography sicstus951363639
Ref: 281363639
Ref: bibliography shan-et-al-931363728
Ref: 1e01363728
Ref: bibliography stefik-et-al-861363891
Ref: 1e31363891
Ref: bibliography stroustrup861364059
Ref: 211364059
Ref: bibliography taenzer891364161
Ref: 1df1364161
Ref: bibliography tanzer951364344
Ref: a5a1364344
Ref: bibliography tanenbaum871364492
Ref: 1e41364492
Ref: bibliography welsch891364603
Ref: a5b1364603
Ref: Glossary-Footnote-11364869
Ref: Glossary-Footnote-21364954
Ref: Glossary-Footnote-31365039
Ref: Glossary-Footnote-41365084
Node: Index<2>1365131
Ref: genindex doc1365229
Ref: a5c1365229
Ref: genindex index1365229
Ref: a5d1365229
Node: Index1365246

End Tag Table


Local Variables:
coding: utf-8
End:
