This is TheLogtalkHandbook-3.27.0.info, produced by makeinfo version 6.6
from TheLogtalkHandbook-3.27.0.texi.

     The Logtalk Handbook v3.27.0, Jun 18, 2019

     Paulo Moura

     Copyright © 2019, Paulo Moura

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


   Generated by Sphinx 2.1.0.


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

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

     The Logtalk Handbook v3.27.0, Jun 18, 2019

     Paulo Moura

     Copyright © 2019, Paulo Moura

* Menu:

* User Manual::
* Reference Manual::
* Tutorial::
* FAQ::
* Developer Tools::
* 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 guide::

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

* Smalltalk nomenclature::
* C++ nomenclature::
* Java 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::

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

Category directives

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

Predicates

* Reserved predicate names::
* Declaring predicates::
* Defining predicates::
* Built-in object predicates (methods): Built-in object predicates methods.
* Predicate properties::
* Finding declared predicates::
* Calling 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::

Defining predicates

* Object predicates::
* Category predicates::
* Meta-predicates::
* Lambda expressions::
* Definite clause grammar rules::

Built-in object predicates (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::
* Compiling Prolog module multifile predicates::

Inheritance

* Protocol inheritance::
* Implementation inheritance::
* Public, protected, and private inheritance: Public protected and private 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

* Generating errors::
* Type-checking::
* 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::
* Goals that are always true or false::
* Trivial fails::
* Suspicious calls::
* Lambda variables::
* Redefinition of predicates declared in uses/2 and 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

* Writing applications::
* Compiling and running applications::

Writing applications

* Source files::
* Portable applications::
* Conditional compilation::
* Avoiding common errors::
* Coding style guidelines::

Compiling and running applications

* Starting Logtalk::
* Compiling and loading your applications::
* Loader files::
* Libraries of source files::
* Compiler linter::
* Compiler flags::
* Reloading and smart compilation of source files::
* Using Logtalk for batch processing::
* Optimizing performance::

Compiler flags

* Version flags::
* Lint flags::
* Optional features compilation flags::
* Back-end 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::
* Hook objects::
* Bypassing expansions::
* Combining multiple expansions::
* Using Prolog defined 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::

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>.
* 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::
* Settings files::
* Compiler and runtime::
* Library::
* Examples::
* Logtalk source files::

Prolog integration and migration guide

* 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::
* Current limitations and workarounds::

Reference Manual

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

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-3::
* dynamic/0::
* end_category/0::
* end_object/0::
* end_protocol/0::
* info/1::
* object/1-5::
* protocol/1-2::
* threaded/0::
* uses/1::

built_in/0

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

category/1-3

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

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<27>.
* Template and modes: Template and modes<21>.
* Examples: Examples<28>.

coinductive/1

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

discontiguous/1

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

dynamic/1

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

info/2

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

meta_predicate/1

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

meta_non_terminal/1

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

mode/2

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

multifile/1

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

private/1

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

protected/1

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

public/1

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

synchronized/1

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

uses/2

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

use_module/2

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

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

Enumerating objects, categories and protocols

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

current_category/1

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

current_object/1

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

current_protocol/1

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

Enumerating objects, categories and protocols properties

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

category_property/2

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

object_property/2

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

protocol_property/2

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

Creating new objects, categories and protocols

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

create_category/4

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

create_object/4

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

create_protocol/3

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

Abolishing objects, categories and protocols

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

abolish_category/1

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

abolish_object/1

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

abolish_protocol/1

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

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

extends_protocol/2-3

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

extends_category/2-3

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

implements_protocol/2-3

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

conforms_to_protocol/2-3

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

complements_object/2

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

imports_category/2-3

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

instantiates_class/2-3

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

specializes_class/2-3

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

Event handling

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

abolish_events/5

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

current_event/5

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

define_events/5

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

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

threaded_call/1-2

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

threaded_once/1-2

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

threaded_ignore/1

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

threaded_exit/1-2

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

threaded_peek/1-2

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

threaded_cancel/1

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

threaded_wait/1

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

threaded_notify/1

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

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

threaded_engine_destroy/1

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

threaded_engine/1

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

threaded_engine_self/1

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

threaded_engine_next/2

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

threaded_engine_next_reified/2

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

threaded_engine_yield/1

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

threaded_engine_post/2

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

threaded_engine_fetch/1

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

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

logtalk_compile/2

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

logtalk_load/1

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

logtalk_load/2

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

logtalk_make/0

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

logtalk_make/1

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

logtalk_make_target_action/1

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

logtalk_library_path/2

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

logtalk_load_context/2

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

Flags

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

current_logtalk_flag/2

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

set_logtalk_flag/2

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

create_logtalk_flag/3

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

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<96>.
* Modes and number of proofs: Modes and number of proofs<61>.
* Errors: Errors<62>.
* Examples: Examples<97>.

parameter/2

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

self/1

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

sender/1

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

this/1

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

Reflection

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

current_op/3

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

current_predicate/1

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

predicate_property/2

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

Database

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

abolish/1

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

asserta/1

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

assertz/1

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

clause/2

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

retract/1

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

retractall/1

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

Meta-calls

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

call/1-N

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

ignore/1

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

once/1

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

\+/1

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

Error handling

* catch/3::
* throw/1::
* instantiation_error/0::
* 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<114>.
* Modes and number of proofs: Modes and number of proofs<79>.
* Errors: Errors<80>.
* Examples: Examples<115>.

throw/1

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

instantiation_error/0

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

type_error/2

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

domain_error/2

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

existence_error/2

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

permission_error/3

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

representation_error/1

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

evaluation_error/1

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

resource_error/1

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

syntax_error/1

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

system_error/0

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

All solutions

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

bagof/3

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

findall/3

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

findall/4

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

forall/2

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

setof/3

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

Event handling

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

before/3

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

after/3

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

Message forwarding

* forward/1::

forward/1

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

Definite clause grammar rules

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

call//1-N

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

eos//0

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

phrase//1

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

phrase/2

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

phrase/3

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

Term and goal expansion

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

expand_term/2

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

term_expansion/2

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

expand_goal/2

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

goal_expansion/2

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

Coinduction hooks

* coinductive_success_hook/1-2::

coinductive_success_hook/1-2

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

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<144>.
* Modes and number of proofs: Modes and number of proofs<109>.
* Errors: Errors<110>.
* Examples: Examples<145>.

message_tokens//2

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

message_hook/4

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

message_prefix_stream/4

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

print_message_tokens/3

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

print_message_token/4

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

Question asking

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

ask_question/5

* Description: Description<150>.
* Modes and number of proofs: Modes and number of proofs<115>.
* Meta-predicate template::
* Errors: Errors<116>.
* Examples: Examples<151>.

question_hook/6

* Description: Description<151>.
* Modes and number of proofs: Modes and number of proofs<116>.
* Meta-predicate template: Meta-predicate template<2>.
* Errors: Errors<117>.
* Examples: Examples<152>.

question_prompt_stream/4

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

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

* asdf::
* assertions::
* code_metrics::
* dead_code_scanner::
* debug_messages::
* debugger::
* diagrams::
* doclet::
* help::
* lgtdoc::
* lgtunit::
* make::
* ports_profiler::
* profiler::
* wrapper::

assertions

* API documentation::
* Loading::
* 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::
* Other notes::

code_metrics

* API documentation: API documentation<2>.
* Loading: Loading<2>.
* Available metrics::
* Defining new metrics::
* Third-party tools::

dead_code_scanner

* API documentation: API documentation<3>.
* Loading: Loading<3>.
* Known issues::
* Other notes: Other notes<2>.

debug_messages

* API documentation: API documentation<4>.
* Loading: Loading<4>.
* Usage::
* Other notes: Other notes<3>.

debugger

* API documentation: API documentation<5>.
* Loading: Loading<5>.
* Usage: Usage<2>.
* Known issues: Known issues<2>.
* Other notes: Other notes<4>.

diagrams

* API documentation: API documentation<6>.
* Loading: Loading<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: Other notes<5>.

doclet

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

help

* API documentation: API documentation<8>.
* Loading: Loading<8>.
* Supported operating-systems::
* Known issues: Known issues<3>.
* Other notes: Other notes<7>.

lgtdoc

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

lgtunit

* Main files::
* API documentation: API documentation<10>.
* Loading: Loading<10>.
* Writing, compiling, and loading unit tests: Writing compiling and loading unit tests.
* Running unit tests::
* Unit test dialects::
* User-defined unit test dialects::
* QuickCheck::
* Skipping unit tests::
* Testing non-deterministic predicates::
* Testing generators::
* Testing input/output predicates::
* Suppressing tested predicates output::
* Unit tests with timeout limits::
* Setup and cleanup goals::
* Test annotations::
* Debugging failed unit tests::
* Code coverage::
* Automating running unit tests::
* Utility predicates::
* Exporting unit test results in xUnit XML format::
* Exporting unit test results in the TAP output format::
* Exporting code coverage results in XML format::
* Known issues: Known issues<4>.
* Other notes: Other notes<9>.

make

* API documentation: API documentation<11>.

ports_profiler

* API documentation: API documentation<12>.
* Loading: Loading<11>.
* Compiling source files for port profiling::
* Generating profiling data::
* Printing profiling data reports::
* Interpreting profiling data::
* Known issues: Known issues<5>.
* Other notes: Other notes<10>.

profiler

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

wrapper

* API documentation: API documentation<13>.
* Loading: Loading<13>.
* Workflows::
* Customization: Customization<2>.
* Current limitations::
* Other notes: Other notes<12>.



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


File: TheLogtalkHandbook-3.27.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.  `class', `instance',
`metaclass', `subclass', `superclass' 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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Nomenclature,  Next: Messages,  Prev: Main features,  Up: User Manual

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

Depending on your 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
Smalltalk, arguably (and somehow sadly) not the most popular OOP
language nowadays.  In this section, we map nomenclatures from popular
OOP languages such as Smalltalk, C++, and Java 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.

* Menu:

* Smalltalk nomenclature::
* C++ nomenclature::
* Java nomenclature::


File: TheLogtalkHandbook-3.27.0.info,  Node: Smalltalk nomenclature,  Next: C++ nomenclature,  Up: Nomenclature

1.3.1 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: 3d. 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: 3e. `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.27.0.info,  Node: C++ nomenclature,  Next: Java nomenclature,  Prev: Smalltalk nomenclature,  Up: Nomenclature

1.3.2 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: 41, which are often a better way to provide
     the functionality of C++ abstract classes.

`base class'

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

`data member'

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

`derived class'

     Logtalk uses the term *note subclass: 45. 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: 46, 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: 47.

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

`member function'

     Logtalk uses *note predicates: 43. 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.

`template'

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

`this'

     Logtalk uses the built-in context method *note self/1: 49. for
     retrieving the current instance.  Logtalk also provides a *note
     this/1: 4a. method but for returning the class containing the
     method being executed.  Why the name clashes?  Well, the notion of
     *note self: 4b. 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: 4c.).


File: TheLogtalkHandbook-3.27.0.info,  Node: Java nomenclature,  Prev: C++ nomenclature,  Up: Nomenclature

1.3.3 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: 43.)
     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.

`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: 41. 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: 4c.).

`callback method'

     Logtalk supports *note event-driven programming: 4f, the most
     common usage context of callback methods.

`class method'

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

`class variable'

     True class variables may be implemented in Logtalk by using a *note
     metaclass: 50. for the class and defining the class variables in
     the class.  I.e.  class variables are simply instance variables of
     the class metaclass.  Shared instance variables may be implemented
     by using the built-in database methods (which can be used to
     implement variable assignment) to access and updated a single
     occurrence of the variable stored in the class (there is no
     ‘static’ keyword in Logtalk).

`constructor'

     There are no special methods for creating new objects in Logtalk.
     Instead, Logtalk provides a built-in predicate, *note
     create_object/4: 44, 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: 43. 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: 51. that allows
     grouping of entities whose source files share a common prefix.

`reflection'

     Logtalk features a `white box' API supporting `structural'
     reflection about *note entity contents: 52, a `black box' API
     supporting `behavioral' reflection about *note object protocols:
     53, and an *note events: 54. API for reasoning about messages
     exchanged at runtime.

`static'

     There is no ‘static’ keyword in Logtalk.  See the entries on `class
     methods' and `class variables'.

`super'

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

`synchronized'

     Logtalk supports *note multi-threading programming: 55. in selected
     Prolog compilers, including a *note synchronized/1: 56. 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: 49. for
     retrieving the current instance.  Logtalk also provides a *note
     this/1: 4a. method but for returning the class containing the
     predicate clause being executed.  Why the name clashes?  Well, the
     notion of *note self: 4b. was inherited from Smalltalk, which
     predates Java.


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

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

Messages allows us to call object predicates.  Logtalk uses the same
nomenclature found in other object-oriented programming languages such
as Smalltalk.  Therefore, the terms `predicate' and `method' are often
used interchangeably when referring to predicates defined inside objects
and categories.  A message must always match a predicate within the
scope of the sender object.

Note that message sending is only the same as calling an object’s
predicate if the object does not inherit (or import) predicate
definitions from other objects (or categories).  Otherwise, the
predicate definition that will be executed may depend on the
relationships of the object with other Logtalk entities.

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


File: TheLogtalkHandbook-3.27.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.27.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:
5e. 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: 4c.).


File: TheLogtalkHandbook-3.27.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: 61. delegation control
construct:

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

This control construct can only be used within objects and categories
(at the interpreter top-level, 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.27.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: 3d. 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 (see the Reference Manual for
details).  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: 4c.).


File: TheLogtalkHandbook-3.27.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.27.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: 3e. 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: 4c.).


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

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

Every message sent using the *note ;;/2: 5e. control construct generates
two events, one before and one after the message execution.  Messages
that are sent using the *note ;;/1: 3d. (message to `self') control
construct or the *note ^^/1: 3e. 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 *note events: 69.
compiler flag (see the *note Event-driven programming: 4f. section for
more details).


File: TheLogtalkHandbook-3.27.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) https://logtalk.org/library/user_0.html#user-0

   (2) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.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.27.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.27.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.27.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).

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: 75. and *note
end_object/0: 76.  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) is always
compiled as 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]: 77, *note [Moura94]: 78.  For example:

     % 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: 79. section for details.


File: TheLogtalkHandbook-3.27.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 for name instead of an atom.
This compound term usually contains free variables that 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: 7b. built-in local method:

     :- object(Functor(Arg1, Arg2, ...)).

         ...

         Predicate :-
             ...,
             parameter(Number, Value),
             ... .

An alternative solution is to use the built-in local method *note
this/1: 4a.  For example:

     :- object(foo(Arg)).

         ...

         bar :-
             ...,
             this(foo(Arg)),
             ... .

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: 5e,
*note ;;/1: 3d, or *note ^^/1: 3e.).

A third alternative to access object parameters is to use *note
parameter variables: 7c.  Although parameter variables introduce a
concept of entity global variables, they allow object parameters to be
added, rearranged, or removed without requiring any changes to the
clauses that refer to them.  Note that using parameter variables doesn’t
change the fact that entity parameters are logical variables.  For
example:

     :- object(foo(_Arg_)).

         ...

         bar :-
             ...,
             baz(_Arg_),
             ... .

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.27.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: 7f. 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.27.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: 44. 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.27.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: 46.
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.27.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.27.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: 88. directive:

     :- initialization(Goal).

The argument can be any valid Prolog or Logtalk goal, including a
message to other object.  For example:

     :- object(foo).

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

         init :-
             ... .

         ...

     :- end_object.

Or:

     :- object(assembler).

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

     :- end_object.

The initialization goal can also be 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:

     :- 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 by initialization we do not necessarily
mean setting an object dynamic state.


File: TheLogtalkHandbook-3.27.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: 8b. 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.27.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: 8e. directive:

     :- info(List).

See the *note Documenting: 8f. section for details.


File: TheLogtalkHandbook-3.27.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: 92. 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.27.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: 95. 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.27.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: 98. 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: 99. 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: 9a. 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: 9b. 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: 9c. and *note conforms_to_protocol/2-3: 9d.
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: 7f. 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: 9e. 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.27.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: a1.:

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

‘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: a2. 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(Predicates)’

     List of public predicates declared by the object

‘protected(Predicates)’

     List of protected predicates declared by the object

‘private(Predicates)’

     List of private predicates declared by the object

‘declares(Predicate, Properties)’

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

‘defines(Predicate, Properties)’

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

‘includes(Predicate, Entity, Properties)’

     List of *note properties: a3. 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
     multifile predicate clause)

‘provides(Predicate, Entity, Properties)’

     List of *note properties: a3. 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
     multifile predicate clause)

‘alias(Predicate, Properties)’

     List of *note properties: a3. for a *note predicate alias: a4.
     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: a3. 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: a3. 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:
     a5. 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:
     a5. 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 of the properties such as line numbers are only available when the
object is defined in a source file compiled with the *note source_data:
a6. flag turned on.

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.27.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.27.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'
..........................................

Logtalk defines a built-in, pseudo-object named user(1) that virtually
contains all user predicate definitions not encapsulated in a Logtalk
entity.  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: 69. 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) https://logtalk.org/library/user_0.html#user-0


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

Logtalk defines a built-in object named ‘logtalk’ that provides
structured message printing mechanism predicates, structured question
asking predicates, debugging event 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.

The following predicates are defined:

‘expand_library_path(Library, Path)’

     Expands a file specification in *note library notation: ad. to a
     full operating-system path.

‘loaded_file(Path)’

     Returns the full path of a currently loaded source file.

‘loaded_file_property(Path, Property)’

     Returns a property for a currently loaded source file.  Valid
     properties are ‘basename/1’, ‘directory/1’, ‘flags/1’ (explicit
     flags used when the file was loaded), ‘text_properties/1’ (list,
     possibly empty, whose possible elements are ‘encoding/1’ and
     ‘bom/1’), ‘target/1’ (full path for the Prolog file generated by
     the compilation of the loaded source file), ‘modified/1’ (time
     stamp that should be treated as an opaque term but that may be used
     for comparisons), ‘parent/1’ (parent file, if it exists, that
     loaded the file; a file may have multiple parents), and ‘library/1’
     (library name when there is a library whose location is the same as
     the loaded file directory).

‘compile_aux_clauses(Clauses)’

     Compiles a list of clauses in the context of the entity under
     compilation.  This method is usually called from ‘goal_expansion/2’
     hooks in order to compile auxiliary clauses generated for
     supporting an expanded goal.  The compilation of the clauses avoids
     the risk of making the predicate whose clause is being
     goal-expanded discontiguous by accident.

‘entity_prefix(Entity, Prefix)’

     Converts an entity identifier into its internal prefix or an
     internal prefix into an entity identifier.

‘compile_predicate_heads(Heads, Entity, TranslatedHeads, ContextArgument)’

     Compiles a predicate head or a list of predicate heads in the
     context of the specified entity or in the context of the entity
     being compiled when ‘Entity’ is not instantiated.

‘compile_predicate_indicators(PredicateIndicators, Entity, TranslatedPredicateIndicators)’

     Compiles a predicate indicator or a list of predicate indicators in
     the context of the specified entity or in the context of the entity
     being compiled when ‘Entity’ is not instantiated.

‘decompile_predicate_heads(TranslatedHeads, Entity, EntityType, Heads)’

     Decompiles a compiled predicate head or a list of compiled
     predicate heads returning the entity, entity type, and source level
     heads.  Requires the entity to be currently loaded.

‘decompile_predicate_indicators(TranslatedPredicateIndicators, Entity, EntityType, PredicateIndicators)’

     Decompiles a compiled predicate indicator or a list of compiled
     predicate indicators returning the entity, entity type, and source
     level predicate indicators.  Requires the entity to be currently
     loaded.

‘execution_context(ExecutionContext, Entity, Sender, This, Self, MetaCallContext, Stack)’

     Allows constructing and accessing execution context components.

‘trace_event(Event, EventExecutionContext)’

     Hook predicate, declared multifile and dynamic, for handling trace
     events generated by the execution of source code compiled in debug
     mode.  The Logtalk runtime calls all defined handlers using a
     failure-driven loop.  Thus, care must be taken that the handlers
     are deterministic to avoid potential termination issues.

‘debug_handler_provider(Provider)’

     Multifile predicate for declaring an object that provides a debug
     handler.  There can only be one debug handler provider loaded at
     the same time.  The Logtalk runtime uses this hook predicate for
     detecting multiple instances of the handler and for better error
     reporting.

‘debug_handler(Event, EventExecutionContext)’

     Multifile predicate for handling debug events generated by the
     execution of source code compiled in debug mode.

To use these predicates, simply send the corresponding message to the
‘logtalk’ object.


File: TheLogtalkHandbook-3.27.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) https://logtalk.org/library/monitoring_0.html#monitoring-0

   (2) https://logtalk.org/library/expanding_0.html#expanding-0

   (3) https://logtalk.org/library/forwarding_0.html#forwarding-0


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

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: b3. and *note end_protocol/0: b4.  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.27.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: b7. 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.27.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: ba.:

     | ?- 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.27.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:
bd. 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.27.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.27.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: 8b.
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.27.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: 8e. directive:

     :- info(List).

See the *note Documenting: 8f. section for details.


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


File: TheLogtalkHandbook-3.27.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: c7. 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: 9c. 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: 7f. or *note
current_category/1: c8. built-in predicates to identify the kind of
entity returned.


File: TheLogtalkHandbook-3.27.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: cb. 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: bd. 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: cc. 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)

‘lines(BeginLine, EndLine)’

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

‘public(Predicates)’

     List of public predicates declared by the protocol

‘protected(Predicates)’

     List of protected predicates declared by the protocol

‘private(Predicates)’

     List of private predicates declared by the protocol

‘declares(Predicate, Properties)’

     List of *note properties: a3. for a predicate declared by the
     protocol

‘alias(Predicate, Properties)’

     List of *note properties: a3. for a *note predicate alias: a4.
     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: a6. flag turned on.


File: TheLogtalkHandbook-3.27.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.27.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.27.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'
.........................................

Logtalk defines a built-in protocol named expanding(1) that declares the
*note term_expansion/2: d3. and *note goal_expansion/2: d4. predicates.
See the description of the *note hook: d5. compiler flag for more
details.

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

   (1) https://logtalk.org/library/expanding_0.html#expanding-0


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

Logtalk defines a built-in protocol named monitoring(1) declares the
*note before/3: d8. and *note after/3: d9. public event handler
predicates.  See the *note Event-driven programming: 4f. section for
more details.

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

   (1) https://logtalk.org/library/monitoring_0.html#monitoring-0


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

Logtalk defines a built-in protocol named forwarding(1) that declares
the *note forward/1: dc. 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: 61.
control construct.

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

   (1) https://logtalk.org/library/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.27.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]: e0. (without necessarily implying
multi-inheritance), and Objective-C categories *note [Cox86]: 1b.
Categories may also `complement' existing objects, thus providing a
*note hot patching: e1. mechanism inspired by the Objective-C categories
functionality.

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


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

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-3: e4. and *note
end_category/0: e5.  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: 3e. 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.27.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: e1. 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:
a4. 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: e8. 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.

Note that *note super calls: e9. 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 unpatched version of the predicate.  This is a
consequence of the lack of a portable solution at the *note backend
Prolog compiler: 32. level for destructively replacing static
predicates.


File: TheLogtalkHandbook-3.27.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: c8. 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.27.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: ee. 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.27.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:
cc. 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.27.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.27.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: 8b.
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.27.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: 8e. directive:

     :- info(List).

See the *note Documenting: 8f. section for details.


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


File: TheLogtalkHandbook-3.27.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: 95. 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.27.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: 9c. and *note
conforms_to_protocol/2-3: 9d. 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: c8. 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: 9b. 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: fd. 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: 9e. built-in predicate:

     | ?- complements_object(Category, Object).

Note that a category may explicitly complement several objects.


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

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

‘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(Predicates)’

     List of public predicates declared by the category

‘protected(Predicates)’

     List of protected predicates declared by the category

‘private(Predicates)’

     List of private predicates declared by the category

‘declares(Predicate, Properties)’

     List of *note properties: a3. for a predicate declared by the
     category

‘defines(Predicate, Properties)’

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

‘includes(Predicate, Entity, Properties)’

     List of *note properties: a3. 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
     multifile predicate clause)

‘provides(Predicate, Entity, Properties)’

     List of *note properties: a3. 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
     multifile predicate clause)

‘alias(Predicate, Properties)’

     List of *note properties: a3. for a *note predicate alias: a4.
     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: a3. 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: a3. 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: a5. 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: a5. 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: a6. flag turned on.

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.27.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.27.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 the predicate definition found in an imported category can
be made using the *note ^^/1: 3e. 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: 105. 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: 4b. (in
both cases a predicate lookup caching mechanism is used).


File: TheLogtalkHandbook-3.27.0.info,  Node: Parametric 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.  The
category parameters can be accessed by calling the *note parameter/2:
7b. or *note this/1: 4a. built-in local methods in the category
predicate clauses or by using *note parameter variables: 7c.  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: 4a. built-in local
method from category predicates always access the importing object
identifier (and thus object parameters, not category parameters).


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

* Menu:

* Reserved predicate names::
* Declaring predicates::
* Defining predicates::
* Built-in object predicates (methods): Built-in object predicates methods.
* Predicate properties::
* Finding declared predicates::
* Calling Prolog predicates::


File: TheLogtalkHandbook-3.27.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: d4. and *note term_expansion/2: d3,
declared in the expanding(1) protocol; *note before/3: d8. and *note
after/3: d9, declared in the monitoring(2) protocol; and *note
forward/1: dc, 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) https://logtalk.org/library/expanding_0.html#expanding-0

   (2) https://logtalk.org/library/monitoring_0.html#monitoring-0

   (3) https://logtalk.org/library/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Declaring predicates,  Next: Defining predicates,  Prev: Reserved predicate names,  Up: Predicates

1.8.2 Declaring predicates
--------------------------

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

* Menu:

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


File: TheLogtalkHandbook-3.27.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.  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: 111. and *note predicate_property/2: 112.)
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:
113, *note protected/1: 114, and *note private/1: 115.  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.


File: TheLogtalkHandbook-3.27.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: 118. 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 (see below).

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: 119. (assuming the
*note source_data: a6. is turned on).  But see also see the description
on *note synchronized predicates: 11a. in the *note multi-threading
programming: 55. section).  In any case, the use of mode directives is a
good starting point for documenting your predicates.


File: TheLogtalkHandbook-3.27.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 closures that will be used for constructing goals.  To
ensure that these goals will be executed in the correct context (i.e.
in the `calling context', not in the meta-predicate `definition
context') we need to use the *note meta_predicate/1: 11c. directive.
For example:

     :- meta_predicate(findall(*, 0, *)).

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
     appending ‘N’ arguments.  The value of ‘N’ must be a positive
     integer.

‘::’

     Argument that is context-aware but that will not be used as a goal
     or a closure.

‘^’

     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: 11d. 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.27.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: 120. 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.27.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: 123. 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.27.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: 126. 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: 127. reflection
method.

When the same operators are used on several entities within the same
source file, the corresponding directives must appear before any entity
that uses them.  However, 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).


File: TheLogtalkHandbook-3.27.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: 12a, which allows us to
simplify the code above.  The usage template 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: a4. 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.

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:
7c. 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 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.27.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: 12d. 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 functor and arity.  We may want to
call the predicate which is masked out by the Logtalk lookup algorithm
(see the *note Inheritance: 12e. 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.27.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: 131. directive:

     :- info(Name/Arity, List).

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


File: TheLogtalkHandbook-3.27.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:
134. 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.
Support for this directive have been added to Logtalk primarily to
support migration of Prolog module code.  Spreading clauses for a
predicate among several Logtalk entities can be handy in some cases but
can also make your code difficult to understand.  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.  In
addition, note 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

Entities containing *note primary multifile predicate declarations: 135.
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.

Multifile predicates may also be declared dynamic using the same
‘Entity::Name/Arity’ notation (multifile predicates are static by
default).

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.

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.27.0.info,  Node: Coinductive 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: 138. 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: 139. is set
to ‘supported’ for the backend Prolog compilers providing that support.


File: TheLogtalkHandbook-3.27.0.info,  Node: Defining predicates,  Next: Built-in object predicates methods,  Prev: Declaring predicates,  Up: Predicates

1.8.3 Defining predicates
-------------------------

* Menu:

* Object predicates::
* Category predicates::
* Meta-predicates::
* Lambda expressions::
* Definite clause grammar rules::


File: TheLogtalkHandbook-3.27.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.27.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: 4b, using
the *note message to self: 140. control structure, *note ;;/1: 3d, or in
the context of *note this: 141. (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.27.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: 11c. 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 entity calling the
meta-predicate.

Some meta-predicates have meta-arguments which are not goals but
closures.  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: 144. built-in predicate to call the closure with the
additional arguments.  For example:

     :- public(all_true/2).
     :- meta_predicate(all_true(1, *)).

     all_true(_, []).
     all_true(Closure, [Arg| Args]) :-
         call(Closure, Arg),
         all_true(Closure, Args).

Note that in this case the meta-predicate directive specifies that the
closure will be extended with exactly one extra argument.

When calling a meta-predicate, a closure can correspond to a
user-defined predicate, a built-in predicate, a *note lambda expression:
145, or a control construct.


File: TheLogtalkHandbook-3.27.0.info,  Node: Lambda expressions,  Next: Definite clause grammar rules,  Prev: Meta-predicates,  Up: Defining predicates

1.8.3.4 Lambda expressions
..........................

The use of lambda expressions(1) as meta-predicate goal and closure
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 *note
Lambda expressions: 148. section of the language grammar.

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.  Unfortunately, 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.  The
compiler also checks if a variable is classified as both a free variable
and a lambda parameter.  An optimizing meta-predicate and lambda
expression compiler, based on the *note term-expansion mechanism: a5, is
provided for practical performance by the standard library.

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

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Definite clause grammar rules,  Prev: Lambda expressions,  Up: Defining predicates

1.8.3.5 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: 14b. 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: 14b. and *note phrase/3: 14c. 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.  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: 14d. 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: 131. directive,
as in the following example:

     :- public(sentence//0).

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Built-in object predicates methods,  Next: Predicate properties,  Prev: Defining predicates,  Up: Predicates

1.8.4 Built-in object predicates (methods)
------------------------------------------

Logtalk defines a set of built-in object predicates or 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.  Similar to Prolog built-in predicates, these
built-in methods should 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.27.0.info,  Node: Execution context methods,  Next: Error handling and throwing methods,  Up: Built-in object predicates methods

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

The method *note this/1: 4a. 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: 7b.
enables us to retrieve current parameter values (see the section on
*note parametric objects: 48. 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: 7c.:

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

1.8.4.2 Error handling and throwing methods
...........................................

Besides the *note catch/3: 156. and *note throw/1: 157. methods
inherited from Prolog, Logtalk also provides a set of convenience
methods to throw standard ‘error/2’ exception terms: *note
instantiation_error/0: 158, *note type_error/2: 159, *note
domain_error/2: 15a, *note existence_error/2: 15b, *note
permission_error/3: 15c, *note representation_error/1: 15d, *note
evaluation_error/1: 15e, *note resource_error/1: 15f, *note
syntax_error/1: 160, and *note system_error/0: 161.


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

1.8.4.3 Database methods
........................

Logtalk provides a set of built-in methods for *note object database:
164. handling similar to the usual database Prolog predicates: *note
abolish/1: 165, *note asserta/1: 166, *note assertz/1: 167, *note
clause/2: 168, *note retract/1: 169, and *note retractall/1: 16a.  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: 12a. or *note use_module/2: 16b. 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: 16c. convert a grammar rule into a
clause that can then be used with the database methods.


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

1.8.4.4 Meta-call methods
.........................

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


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

1.8.4.5 All solutions methods
.............................

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Reflection methods,  Next: Definite clause grammar parsing methods and non-terminals,  Prev: All solutions methods,  Up: Built-in object predicates methods

1.8.4.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: a6. flag turned on.

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


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

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

Logtalk supports two definite clause grammar parsing built-in private
methods, *note phrase/2: 14b. and *note phrase/3: 14c, 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: 17d, *note call//1-N: 17e, and
*note eos//0: 17f. built-in non-terminals.  The ‘call//1-N’
non-terminals takes a closure (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.27.0.info,  Node: Predicate properties,  Next: Finding declared predicates,  Prev: Built-in object predicates methods,  Up: Predicates

1.8.5 Predicate properties
--------------------------

We can find the properties of visible predicates by calling the *note
predicate_property/2: 112. built-in method.  For example:

     | ?- bar::predicate_property(foo(_), Property).

Note that this method respects the predicate’s scope declarations.  For
instance, the above 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 several 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: 4c.)

‘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: a6. 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:
     a5.

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Finding declared predicates,  Next: Calling Prolog predicates,  Prev: Predicate properties,  Up: Predicates

1.8.6 Finding declared predicates
---------------------------------

We can find, by backtracking, all visible user predicates by calling the
*note current_predicate/1: 111. built-in method.  This method respects
the predicate’s scope declarations.  For instance, 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.27.0.info,  Node: Calling Prolog predicates,  Prev: Finding declared predicates,  Up: Predicates

1.8.7 Calling Prolog predicates
-------------------------------

Logtalk is designed for both `robusteness' and `portability'.  In the
context of calling Prolog predicates, robusteness 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::
* Compiling Prolog module multifile predicates::


File: TheLogtalkHandbook-3.27.0.info,  Node: Calling Prolog built-in predicates,  Next: Calling Prolog non-standard built-in meta-predicates,  Up: Calling Prolog predicates

1.8.7.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 definition for
the called predicate, or a dynamic declaration for it.  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 dynamic 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: 187. to
generate warnings for calls to non-standard predicates and arithmetic
functions.  We can also document those calls using the *note uses/2:
12a. 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.27.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.7.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 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.27.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.7.3 Calling Prolog user-defined plain predicates
....................................................

Prolog user-defined plain predicates 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: 12a. 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: 14d. compiler bypass control construct.  For example:

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

But note that in this case the *note reflection API: 119. 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.27.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.7.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: 16b. 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’, 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: 18e.  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
     autoloading mechanism).

The module identifier argument can also be a *note parameter variable:
7c. 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.27.0.info,  Node: Calling Prolog module meta-predicates,  Next: Compiling Prolog module multifile predicates,  Prev: Calling Prolog module predicates,  Up: Calling Prolog predicates

1.8.7.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(bar(*, *)).

or:

     :- meta_predicate(bar(*, 0)).

depending on the true meaning of the second meta-argument.  The second
alternative is to simply use the *note {}/1: 14d. 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.27.0.info,  Node: Compiling Prolog module multifile predicates,  Prev: Calling Prolog module meta-predicates,  Up: Calling Prolog predicates

1.8.7.6 Compiling Prolog module 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 compilation of such clauses within 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.27.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 predicates 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 lookup procedure for finding predicate
declarations and predicate definitions, as explained below.  The lookup
procedures locate the entities holding the predicate declaration and the
predicate definition using the predicate template.  The *note alias/2:
12d. predicate directive may be used for defining alternative names for
inherited predicates, for solving inheritance conflicts, and for giving
access to all inherited definitions (thus overriding the default lookup
procedure).

* Menu:

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


File: TheLogtalkHandbook-3.27.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: 195.).  These can be contained in objects, in
protocols, or in 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.27.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.27.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), third 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.27.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.27.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.27.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.27.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 other object,
the inherited definitions are hidden by the new definitions.  This is
called overriding inheritance: 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.27.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 uses the
inherited definitions, adding new code.  This is accomplished by calling
the *note ^^/1: 3e. `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.27.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: 3e. `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.27.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:
3e. `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.27.0.info,  Node: Public protected and private inheritance,  Next: Composition versus multiple inheritance,  Prev: Implementation inheritance,  Up: Inheritance

1.9.3 Public, protected, and private inheritance
------------------------------------------------

To make all *note public predicates: 1a9. declared via implemented
protocols, imported categories, or ancestor objects *note protected
predicates: 1aa. or to make all public and protected predicates *note
private predicates: 1ab. 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.27.0.info,  Node: Composition versus multiple inheritance,  Prev: Public protected and private inheritance,  Up: Inheritance

1.9.4 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]: 1ae. and
to the sophisticated algorithms of CLOS *note [Bobrow_et_al_88]: 1af,
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]: 1b0.  Multiple
inheritance is best used as an analysis and project abstraction, rather
than as an implementation technique *note [Shan_et_al_93]: 1b1.  Logtalk
provides first-class support for composition using *note categories: df.

Nevertheless, Logtalk supports multi-inheritance by enabling an object
to extend, instantiate, or specialize more than one object.  The *note
alias/2: 12d. 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.27.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]: 78. 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]: 1b4, *note [Moon86]: e0, operative
systems *note [Tanenbaum87]: 1b5, 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: 69.
     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.

* Menu:

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


File: TheLogtalkHandbook-3.27.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.27.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.27.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).

The execution of actions, defined in a monitor, associated to each event, never affects the term that denotes the message involved

     In other words, if the message contains uninstantiated variables,
     these are not affected by the acting of monitors associated to the
     event.

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

   (1) https://logtalk.org/library/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Event generation,  Next: Communicating events to monitors,  Prev: Definitions,  Up: Event-driven programming

1.10.2 Event generation
-----------------------

For each message that is sent (using the *note ;;/2: 5e. 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.


File: TheLogtalkHandbook-3.27.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) https://logtalk.org/library/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.27.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: 69. 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.27.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.27.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.27.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.27.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: 1ca. 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.27.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: 1cd. 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.27.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: 1d0. 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.27.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: d8. and *note after/3: d9, 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) .
         :- public(foo/1) .

         bar(bar).

         foo(foo).

     :- end_object.

After compiling and loading both objects and setting the *note events:
69. to ‘allow’ flag, we can start tracing every message sent to any
object by calling the *note define_events/5: 1ca. built-in predicate:

     | ?- set_logtalk_flag(events, allow).

     yes

     | ?- define_events(_, _, _, _, tracer).

     yes

From now on, every message sent 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: 1cd. 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: ce. 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) https://logtalk.org/library/monitoring_0.html#monitoring-0

   (2) https://logtalk.org/library/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.27.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 details of creating, synchronizing, or
communicating with threads.  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.27.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: 1d7. compiler flag to ‘supported’.


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

     :- threaded.


File: TheLogtalkHandbook-3.27.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:
1dd. 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.27.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: 1dd.  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.27.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: 1e2. 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 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: 1e3. 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: 1e4. 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: 1e5. 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 severely
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_exit/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.  Nevertheless, you can easily use a tag
the calls by using in alternative *note threaded_call/2: 1e2, *note
threaded_once/2: 1e4, and *note threaded_exit/2: 1e3. 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: 1e6. predicate.


File: TheLogtalkHandbook-3.27.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: 1e9.  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.27.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: 164.  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: 56. 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
‘random’ object defining a ‘random/1’ predicate that generates random
numbers, using side effects on its implementation (e.g.  for storing the
generator seed).  We can specify and define e.g.  a ‘sync_random/1’
predicate as follows:

     :- synchronized(sync_random/1).

     sync_random(Random) :-
         random::random(Random).

and then always use the ‘sync_random/1’ predicate instead of the
predicate ‘random/1’ from multi-threaded code.

The synchronization entity and predicate directives may be used when
defining objects that may be reused in both single-threaded and
multi-threaded Logtalk applications.  The directives are simply ignored
(i.e.  the synchronized predicates are interpreted as normal predicates)
when the objects are used in a single-threaded application.


File: TheLogtalkHandbook-3.27.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: 1ed. 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: 1ee.  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.27.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: 1f1.
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: 1f2. 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: 1f3, 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_reifeid(Reified, Engine, Answers),
         ...

     collect_all_reifeid(no, _, []).
     collect_all_reifeid(the(Answer), Engine, [Answer| Answers]) :-
         threaded_engine_next_reified(Engine, Reified),
         collect_all_reifeid(Reified, Engine, Answers).

Engines must be explicitly terminated using the *note
threaded_engine_destroy/1: 1f4. 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: 1f5. built-in predicate fetches a
task for the engine term queue.  The engine clients would use the *note
threaded_engine_post/2: 1f6. 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: 1f7. built-in predicate to make the task
results available for consumption using the ‘threaded_engine_next/2’
built-in predicate.  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.27.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.27.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:

* Generating errors::
* Type-checking::
* Compiler warnings and errors::
* Runtime errors::

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

   (1) 
https://logtalk.org/library/logtalk_0.html#logtalk-0-execution-context-7


File: TheLogtalkHandbook-3.27.0.info,  Node: Generating errors,  Next: Type-checking,  Up: Error handling

1.12.1 Generating errors
------------------------

The *note error handling section: 1fe. 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 type:

     ...,
     type_error(atom, 42).

The provided error built-in methods cover all standard error types as
notably found in the ISO Prolog Core standard.


File: TheLogtalkHandbook-3.27.0.info,  Node: Type-checking,  Next: Compiler warnings and errors,  Prev: Generating errors,  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 `temparatures'
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: 105. turned on, thus enabling efficient
type-checking.

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

   (1) https://logtalk.org/library/type_0.html#type-0

   (2) https://logtalk.org/library/type_0.html#type-0-valid-2

   (3) https://logtalk.org/library/type_0.html#type-0-check-2

   (4) https://logtalk.org/library/type_0.html#type-0-check-3


File: TheLogtalkHandbook-3.27.0.info,  Node: Compiler warnings and errors,  Next: Runtime errors,  Prev: Type-checking,  Up: Error handling

1.12.3 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: 201. 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::
* Goals that are always true or false::
* Trivial fails::
* Suspicious calls::
* Lambda variables::
* Redefinition of predicates declared in uses/2 and use_module/2 directives::
* Other warnings and errors::


File: TheLogtalkHandbook-3.27.0.info,  Node: Unknown entities,  Next: Singleton variables,  Up: Compiler warnings and errors

1.12.3.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.27.0.info,  Node: Singleton variables,  Next: Redefinition of Prolog built-in predicates,  Prev: Unknown entities,  Up: Compiler warnings and errors

1.12.3.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.27.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.3.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.27.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.3.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.27.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.3.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.27.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.3.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.27.0.info,  Node: Portability warnings,  Next: Deprecated elements,  Prev: Misspell calls of local predicates,  Up: Compiler warnings and errors

1.12.3.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.27.0.info,  Node: Deprecated elements,  Next: Missing directives,  Prev: Portability warnings,  Up: Compiler warnings and errors

1.12.3.8 Deprecated elements
............................

A warning will be reported if a deprecated directive or control
construct 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.27.0.info,  Node: Missing directives,  Next: Duplicated directives,  Prev: Deprecated elements,  Up: Compiler warnings and errors

1.12.3.9 Missing directives
...........................

A warning will be reported for any missing dynamic, discontiguous,
meta-predicate, and public predicate directive.


File: TheLogtalkHandbook-3.27.0.info,  Node: Duplicated directives,  Next: Goals that are always true or false,  Prev: Missing directives,  Up: Compiler warnings and errors

1.12.3.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.27.0.info,  Node: Goals that are always true or false,  Next: Trivial fails,  Prev: Duplicated directives,  Up: Compiler warnings and errors

1.12.3.11 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.27.0.info,  Node: Trivial fails,  Next: Suspicious calls,  Prev: Goals that are always true or false,  Up: Compiler warnings and errors

1.12.3.12 Trivial fails
.......................

A warning will be reported for any call to a local static predicate with
no matching clause.


File: TheLogtalkHandbook-3.27.0.info,  Node: Suspicious calls,  Next: Lambda variables,  Prev: Trivial fails,  Up: Compiler warnings and errors

1.12.3.13 Suspicious calls
..........................

A warning will be reported for calls that are syntactically correct but
most likely a semantic error.  An example is *note ;;/1: 3d. 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.27.0.info,  Node: Lambda variables,  Next: Redefinition of predicates declared in uses/2 and use_module/2 directives,  Prev: Suspicious calls,  Up: Compiler warnings and errors

1.12.3.14 Lambda variables
..........................

A warning will be reported for *note lambda expressions: 145. with
unclassified variables (not listed as either *note lambda free: 21e. or
*note lambda parameter: 21f. variables) or where variables play a dual
role (as both lambda free and lambda parameter variables).


File: TheLogtalkHandbook-3.27.0.info,  Node: Redefinition of predicates declared in uses/2 and use_module/2 directives,  Next: Other warnings and errors,  Prev: Lambda variables,  Up: Compiler warnings and errors

1.12.3.15 Redefinition of predicates declared in ‘uses/2’ and ‘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: 12a. or *note use_module/2:
16b. directive.


File: TheLogtalkHandbook-3.27.0.info,  Node: Other warnings and errors,  Prev: Redefinition of predicates declared in uses/2 and use_module/2 directives,  Up: Compiler warnings and errors

1.12.3.16 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 of the offending entity.


File: TheLogtalkHandbook-3.27.0.info,  Node: Runtime errors,  Prev: Compiler warnings and errors,  Up: Error handling

1.12.4 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.27.0.info,  Node: Logtalk built-in predicates,  Next: Logtalk built-in methods,  Up: Runtime errors

1.12.4.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.27.0.info,  Node: Logtalk built-in methods,  Next: Message sending,  Prev: Logtalk built-in predicates,  Up: Runtime errors

1.12.4.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.27.0.info,  Node: Message sending,  Prev: Logtalk built-in methods,  Up: Runtime errors

1.12.4.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: dc, 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) https://logtalk.org/library/forwarding_0.html#forwarding-0


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

* Menu:

* Structural reflection::
* Behavioral reflection::


File: TheLogtalkHandbook-3.27.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.  It is materialized by an API
that supports all the developer tools, which are regular applications.
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.27.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.

For entities, built-in predicates are provided for *note enumerating
entities: 231, *note enumerating entity properties: 52. (including
entity declared, defined, called, and updated predicates), and *note
enumerating entity relations: 232.  For a detailed description of the
supported entity properties, see the sections on *note object
properties: a0, *note protocol properties: ca, and *note category
properties: fe.  For examples of querying entity relations, see the
sections on *note object relations: 97, *note protocol relations: c6,
and *note category relations: fb.

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

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

   (1) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.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 respects entity encapsulation
and thus only allow querying predicates and operators that are within
scope of the entity calling the reflection methods.

Built-in methods are provided for querying the *note predicates that are
declared and can be called or used as messages: 111. and for querying
the *note predicate properties: 112.  It is also possible to enumerate
defined entity *note entity operators: 127.  See the sections on *note
finding declared predicates: 183. and on *note predicate properties:
181. for more details.


File: TheLogtalkHandbook-3.27.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: 4f. for details.  In addition, the logtalk(1) built-in
object provides predicates for handling debug events.

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

   (1) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Writing and running applications,  Next: Printing messages and asking questions,  Prev: Reflection,  Up: User Manual

1.14 Writing and running applications
=====================================

* Menu:

* Writing applications::
* Compiling and running applications::


File: TheLogtalkHandbook-3.27.0.info,  Node: Writing applications,  Next: Compiling and running applications,  Up: Writing and running applications

1.14.1 Writing 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]: 23b. 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:

* Source files::
* Portable applications::
* Conditional compilation::
* Avoiding common errors::
* Coding style guidelines::


File: TheLogtalkHandbook-3.27.0.info,  Node: Source files,  Next: Portable applications,  Up: Writing applications

1.14.1.1 Source files
.....................

Logtalk source files may define any number of entities (objects,
categories, or protocols) and Prolog code.  If you prefer to define each
entity in its own source file, then 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.  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 an object named ‘vehicle’ and save it in a
‘vehicle.lgt’ source file that will be compiled to a ‘vehicle_lgt.pl’
Prolog file.  If we have a ‘sort(_)’ parametric object we can save it on
a ‘sort_1.lgt’ source file that will be compiled to a ‘sort_1_lgt.pl’
Prolog file.  This name scheme helps avoid file name conflicts (remember
that all Logtalk entities share the same namespace).  To further prevent
file name conflicts, specially when embedding applications, and
depending on the *note backend compiler: 32, the names of the
intermediate Prolog files may include a directory hash.

Logtalk source files may 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: a5.).  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 ‘initialization/1’ Prolog directive may be used for defining an
initialization goal to be executed when loading a source file.  Most
calls to Logtalk built-in predicates from file ‘initialization/1’
directives are compiled for better performance.

The text encoding used in a source file may be declared using the *note
encoding/1: 23e. directive when running Logtalk with backend Prolog
compilers that support multiple encodings (check the *note
encoding_directive: 23f. flag in the adapter file of your Prolog
compiler).

Logtalk source files can include the text of other files by using the
*note include/1: 92. 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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Portable applications,  Next: Conditional compilation,  Prev: Source files,  Up: Writing applications

1.14.1.2 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: 187. compiler flag.


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

1.14.1.3 Conditional compilation
................................

Logtalk supports conditional compilation within source files using the
*note if/1: 244, *note elif/1: 245, *note else/0: 246, and *note
endif/0: 247. 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.27.0.info,  Node: Avoiding common errors,  Next: Coding style guidelines,  Prev: Conditional compilation,  Up: Writing applications

1.14.1.4 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: df.).
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.27.0.info,  Node: Coding style guidelines,  Prev: Avoiding common errors,  Up: Writing applications

1.14.1.5 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.27.0.info,  Node: Compiling and running applications,  Prev: Writing applications,  Up: Writing and running applications

1.14.2 Compiling and running applications
-----------------------------------------

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.

* Menu:

* Starting Logtalk::
* Compiling and loading your applications::
* Loader files::
* Libraries of source files::
* Compiler linter::
* Compiler flags::
* Reloading and smart compilation of source files::
* Using Logtalk for batch processing::
* Optimizing performance::


File: TheLogtalkHandbook-3.27.0.info,  Node: Starting Logtalk,  Next: Compiling and loading your applications,  Up: Compiling and running applications

1.14.2.1 Starting Logtalk
.........................

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.

If no scripts or shortcuts are available for your installation,
operating-system, or Prolog compiler, you can always start a Logtalk
session by performing the following steps:

  1. Start your Prolog compiler.

  2. Load the appropriate adapter file for your compiler.  Adapter files
     for most common Prolog compilers can be found in the ‘adapters’
     subdirectory.

  3. Load the library paths file corresponding to your Logtalk
     installation contained in the ‘paths’ subdirectory.

  4. Load the Logtalk compiler/runtime files contained in the ‘core’
     subdirectory.

Note that the adapter files, compiler/runtime files, and library paths
file are Prolog source files.  The predicate called to load (and
compile) them depends on your Prolog compiler.  In case of doubt,
consult your Prolog compiler reference manual or take a look at the
definition of the predicate ‘'$lgt_load_prolog_code'/3’ in the
corresponding adapter file.

Most Prolog compilers support automatic loading of an initialization
file, which can include the necessary directives to load both the Prolog
adapter file and the Logtalk compiler.  This feature, when available,
allows automatic loading of Logtalk when you start your Prolog compiler.


File: TheLogtalkHandbook-3.27.0.info,  Node: Compiling and loading your applications,  Next: Loader files,  Prev: Starting Logtalk,  Up: Compiling and running applications

1.14.2.2 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: 252. 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: 253. 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
loader 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: 254. can be used to reload
all modified source files.  Files are also reloaded when the compilation
mode changes.  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 queries:

     | ?- set_logtalk_flag(debug, on).
     ...

     | ?- logtalk_make.
     ...

After debugging and fixing the bugs, you can reload the files in normal
(or optimized) mode by turning the *note debug: 255. flag off and
calling the ‘logtalk_make/0’ predicate again.  With most backend Prolog
compilers, you can also use the ‘{*}’ top-level shortcut.

An extended version of this predicate, *note logtalk_make/1: 256,
accepts multiple targets including ‘all’, ‘clean’, ‘check’, ‘circular’,
‘documentation’, and ‘caches’.  See the Reference Manual 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.27.0.info,  Node: Loader files,  Next: Libraries of source files,  Prev: Compiling and loading your applications,  Up: Compiling and running applications

1.14.2.3 Loader files
.....................

Most examples directories contain a Logtalk utility file that can be
used to load all included source files.  These loader files are usually
named ‘loader.lgt’ or contain the word “loader” in their name.  Loader
files are ordinary source file and thus compiled and loaded like any
source file.  For an example loader file named ‘loader.lgt’ we would
type:

     | ?- logtalk_load(loader).

Usually these files contain a call to the built-in predicates *note
set_logtalk_flag/2: 259. (e.g.  for setting global, `project-specific',
flag values) and *note logtalk_load/1: 253. or *note logtalk_load/2:
25a. (for loading project files), wrapped inside a Prolog
‘initialization/1’ directive.  For instance, if your code is split in
three Logtalk 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
application.  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 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.

A common mistake is to try to set compiler flags using ‘logtalk_load/2’
with 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.27.0.info,  Node: Libraries of source files,  Next: Compiler linter,  Prev: Loader files,  Up: Compiling and running applications

1.14.2.4 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: 25d.  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.  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.

The library notation provides functionality inspired by the
‘file_search_path/2’ mechanism introduced by Quintus Prolog and later
adopted by some other Prolog compilers.


File: TheLogtalkHandbook-3.27.0.info,  Node: Compiler linter,  Next: Compiler flags,  Prev: Libraries of source files,  Up: Compiling and running applications

1.14.2.5 Compiler linter
........................

The compiler includes a linter 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, tautology and falsehood goals (i.e.  goals that are can be
replaced by ‘true’ or ‘fail’), and trivial fails (i.e.  calls to
predicates with no match clauses).  Some of the linter warnings are
controlled by compiler flags.  See the next section for details.


File: TheLogtalkHandbook-3.27.0.info,  Node: Compiler flags,  Next: Reloading and smart compilation of source files,  Prev: Compiler linter,  Up: Compiling and running applications

1.14.2.6 Compiler flags
.......................

The *note logtalk_load/1: 253. and *note logtalk_compile/1: 252. 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: 259.
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: 25a. or the *note logtalk_compile/2: 261. 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: 259. 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: 262. built-in predicate:

     | ?- current_logtalk_flag(unknown_entities, Value).

     Value = silent
     yes

Logtalk also implements a *note set_logtalk_flag/2: 263. 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 file, in the entity, or in the loader file.

* Menu:

* Version flags::
* Lint flags::
* Optional features compilation flags::
* Back-end Prolog compiler and loader flags::
* Other flags::
* User-defined flags::


File: TheLogtalkHandbook-3.27.0.info,  Node: Version flags,  Next: Lint flags,  Up: Compiler flags

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

1.14.2.8 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 calls to
     declared but undefined predicates (or non-terminals) fail 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: 26b.
     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).

‘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’ (the usual default)
     and ‘silent’.  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.

‘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 curent limitation to ASCII names and the
     computational cost of the checks).


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

1.14.2.9 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: 166. or *note assertz/1: 167. 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: 4f. 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.27.0.info,  Node: Back-end Prolog compiler and loader flags,  Next: Other flags,  Prev: Optional features compilation flags,  Up: Compiler flags

1.14.2.10 Back-end 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: 27b. 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.27.0.info,  Node: Other flags,  Next: User-defined flags,  Prev: Back-end Prolog compiler and loader flags,  Up: Compiler flags

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

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

‘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: 255.
     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: 119. 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: 105. flag.

‘reload(Option)’

     Defines the reloading behavior for source files.  Possible option
     values are ‘skip’ (skip loading 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 the 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, this flag also
     forces recompilation of all source files, disregarding any existing
     intermediate files.  Thus, it is strong advisable to turn on this
     flag when switching backend Prolog compilers as the intermediate
     files generated by the compilation of source files may not be
     portable (due to differences in the implementation of the standard
     ‘write_canonical/2’ predicate).

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

   (1) https://logtalk.org/library/user_0.html#user-0

   (2) https://logtalk.org/library/expanding_0.html#expanding-0


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

1.14.2.12 User-defined flags
............................

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Reloading and smart compilation of source files,  Next: Using Logtalk for batch processing,  Prev: Compiler flags,  Up: Compiling and running applications

1.14.2.13 Reloading and smart compilation of 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: 280. compiler flag to ‘skip’.  For code under
development, you can turn off the *note clean: 282. 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 smart compilation 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.27.0.info,  Node: Using Logtalk for batch processing,  Next: Optimizing performance,  Prev: Reloading and smart compilation of source files,  Up: Compiling and running applications

1.14.2.14 Using Logtalk for batch processing
............................................

If you use Logtalk for batch processing, you probably want to turn off
the *note report: 27e. 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.27.0.info,  Node: Optimizing performance,  Prev: Using Logtalk for batch processing,  Up: Compiling and running applications

1.14.2.15 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: a6.
flag off.  To optimize runtime performance, turn on the *note optimize:
105. 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/load your files taking into account file dependencies
to enable *note static binding: 33. optimizations.  The easiest way to
find the dependencies and thus the best compilation/loading order is to
use the diagrams(1) 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: 167. and *note retract/1: 169.) that
modify the predicate.

Sending a *note message to self: 140. implies *note dynamic binding: 34.
but there are often cases where *note ;;/1: 3d. 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: e9, *note ^^/1: 3e, 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: 28b. for a detailed discusion on
Logtalk performance.

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

   (1) https://logtalk.org/tools.html#diagrams


File: TheLogtalkHandbook-3.27.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 in
the debugger tool.

* Menu:

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

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

   (1) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.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: 291.  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: 27e.
     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: 27e. 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: 27e. 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:
     255. flag is turned on; these messages are suppressed by the
     compiler when the *note optimize: 105. 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’ is new to Logtalk and
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 simplify programming-in-the-large by
allowing easy filtering of all messages from a specific component or
library 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 ‘lgtunit’ 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.27.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: 293. 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.27.0.info,  Node: Meta-messages,  Next: Intercepting messages,  Prev: Message tokenization,  Up: Printing messages and asking questions

1.15.3 Meta-messages
--------------------

Define 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: 295.
section and the logtalk built-in object(1) remarks section for details.

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

   (1) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.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: 291. predicate can be
intercepted by defining clauses for the *note logtalk;;message_hook/4:
297. 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: 298. 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.27.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: 29b, 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).

         logtalk::message_tokens(ultimate_answer, hitchhikers) -->
             ['The answer to the ultimate question of life, the universe and everything is'-[]].

        :- multifile(logtalk::question_prompt_stream/4).
        :- dynamic(logtalk::question_prompt_stream/4).

        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_answer, integer, N).

     The answer to the ultimate question of life, the universe and everything is: 42.

     N = 42
     yes

Note that the fourth argument, ‘integer’ in our example, is a closure
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.

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.27.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: 29b. predicate can be
intercepted by defining clauses for the *note logtalk;;question_hook/6:
29d. 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_answer, 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_answer, integer, N).

     N = 42
     yes


File: TheLogtalkHandbook-3.27.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 the `term and goal expansion mechanism' also found in
some Prolog systems.  This macro mechanism is used to define
source-to-source transformations.  Two common uses are the definition of
language extensions and domain-specific languages.

* Menu:

* Defining expansions::
* Expanding grammar rules::
* Hook objects::
* Bypassing expansions::
* Combining multiple expansions::
* Using Prolog defined expansions::


File: TheLogtalkHandbook-3.27.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: d3. and *note goal_expansion/2: d4, which are
declared in the expanding(1) built-in protocol.  For example:

     :- 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:
16c. and *note expand_goal/2: 2a1. built-in methods.

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.

Term and goal expansion predicates can also be used when compiling a
source file as described below.

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

   (1) https://logtalk.org/library/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Expanding grammar rules,  Next: Hook objects,  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 overriden by
defining clauses for the *note term_expansion/2: d3. predicate.


File: TheLogtalkHandbook-3.27.0.info,  Node: Hook objects,  Next: Bypassing expansions,  Prev: Expanding grammar rules,  Up: Term and goal expansion

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

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

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

In alternative, we can use a *note set_logtalk_flag/2: 263. 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: 259.
predicate.  For example:

     | ?- set_logtalk_flag(hook, hook_object).

     yes

When compiling a source file, the compiler will first try the source
file specific hook object, if defined.  If that fails, it tries the
default hook object, if defined.  If that also fails, the compiler tries
the Prolog dialect specific expansion predicate definitions if defined
in the *note adapter file: 11d.

     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.

When using an 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: 2a4. built-in
predicate that can be used to access the compilation/loading context
when performing expansions.  The *note logtalk: ab. 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.

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

   (1) https://logtalk.org/library/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Bypassing expansions,  Next: Combining multiple expansions,  Prev: Hook objects,  Up: Term and goal expansion

1.16.4 Bypassing expansions
---------------------------

Terms and goals wrapped by the *note {}/1: 14d. 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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Combining multiple expansions,  Next: Using Prolog defined expansions,  Prev: Bypassing expansions,  Up: Term and goal expansion

1.16.5 Combining multiple expansions
------------------------------------

Sometimes we have multiple hook objects that we need to use in the
compilation of a source file.  The Logtalk library includes support for
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.

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

   (1) https://logtalk.org/library/hook_pipeline_1.html#hook-pipeline-1

   (2) https://logtalk.org/library/hook_set_1.html#hook-set-1


File: TheLogtalkHandbook-3.27.0.info,  Node: Using Prolog defined expansions,  Prev: Combining multiple expansions,  Up: Term and goal expansion

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


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

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

Assuming that the *note source_data: a6. flag is turned on, the compiler
saves all relevant documenting information collected when compiling a
source file.  The provided lgtdoc(1) tool can access this information by
using the *note reflection: 119. 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 next.

* Menu:

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

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

   (1) https://logtalk.org/tools.html#documenting


File: TheLogtalkHandbook-3.27.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: 118. directive.

* Menu:

* Entity directives::
* Predicate directives::


File: TheLogtalkHandbook-3.27.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: 8e. directive:

     :- info([
         Key1 is Value1,
         Key2 is Value2,
         ...
     ]).

In this pattern, keys should be atoms and values should be ground terms.
The following keys are predefined and may be processed specially by
Logtalk tools:

‘comment’

     Comment describing the entity purpose (an atom).

‘author’

     Entity author(s) (an atom or a compound term ‘{entity}’ where
     ‘entity’ is the name of an XML entity defined in the ‘custom.ent’
     file).

‘version’

     Version number (a number).

‘date’

     Date of last modification (formatted as ‘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 the ‘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 defined in the ‘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,
         author is 'Paulo Moura',
         date is 2000/04/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: 119. and
are visible to the lgtdoc(1) tool.

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

   (1) https://logtalk.org/tools.html#documenting


File: TheLogtalkHandbook-3.27.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: 131. 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 purpose (an atom).

‘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 term' pairs.  The description must be an
     atom.  The exception term must be a non-variable term.

‘examples’

     List of typical predicate call examples using the format
     `Description-Goal-Bindings'.  The description must be an atom.  The
     predicate call term must be a non-variable term.  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.

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: 119. and are visible to the lgtdoc(1)
tool.

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

   (1) https://logtalk.org/tools.html#documenting


File: TheLogtalkHandbook-3.27.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 lgtdoc(1) 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 lgtdoc(2) 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). See the ‘NOTES’ file included in the directory for details.  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,
         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 lgtdoc(3) 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 doclet(4) tool that allows
automating the steps required to generate the documentation for an
application.

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

   (1) https://logtalk.org/tools.html#documenting

   (2) https://logtalk.org/tools.html#documenting

   (3) https://logtalk.org/tools.html#documenting

   (4) https://logtalk.org/tools.html#documenting


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


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

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

The diagrams(1) 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: 119. as the ‘lgtdoc’ tool
and thus have access to the same source data.  See the tool
documentation for details.

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

   (1) https://logtalk.org/tools.html#diagrams


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

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

The Logtalk distribution includes a command-line debugger(1) 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: 2b8.  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, implementation of spy points allows the
user to specify the execution context 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::

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

   (1) https://logtalk.org/tools.html#debugging


File: TheLogtalkHandbook-3.27.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: 255. 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: 256. built-in predicate can also be used to
recompile all loaded files (that were compiled without using explicit
values for the *note debug: 255. and *note optimize: 105. compiler flags
in a ‘logtalk_load/2’ call or in a loader 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: 282. compiler flag should be turned on whenever the
*note debug: 255. 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: 263. directive inside the entity.


File: TheLogtalkHandbook-3.27.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 compilers.  The traditional Prolog procedure box model defines
four ports (`call', `exit', `redo', and `fail') for describing control
flow when a predicate clause is used during program execution:

     ‘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 compilers, 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.27.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 file line
numbers or predicates should be spied, as in most Prolog debuggers, or
by fully 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.27.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.27.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 execution context is true and when
the spy point goal unifies with the goal currently being executed.
Variable bindings resulting from the unification between the current
goal and the goal argument are discarded.  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 by setting the
condition:

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

     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: 4b.
matches the atom ‘foo’.


File: TheLogtalkHandbook-3.27.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.27.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.27.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.27.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.27.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: a2, 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: 278. compiler flag (its default value is
defined in the adapter files of the backend Prolog compilers).


File: TheLogtalkHandbook-3.27.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: 291. predicate where the
message kind is either ‘debug’ or ‘debug(Group)’ are only printed, by
default, when the *note debug: 255. flag is turned on.  Moreover, these
calls are suppressed by the compiler when the *note optimize: 105. 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.27.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: 293. grammar rules
for translating each and every debug message, Logtalk provides default
tokenization for four `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 value is printed as passed to the ‘writeq/1’
     predicate.

‘List’

     By default, the list items are printed indented one per line.  The
     items are preceded by a dash and printed as passed to the
     ‘writeq/1’ predicate.

‘Title::List’

     By default, the title is printed followed by a newline and the
     indented list items, one per line.  The items are preceded by a
     dash and printed as passed to the ‘writeq/1’ predicate.

These print messages goals can always be combined with hooks as
described in the previous section to remove them in production ready
code.  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, [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: 298.
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.27.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: 255. and *note optimize: 105. flags.  When the code
is not compiled in optimal mode, the debug_messages(1) tool allows
selectively enabling of debug messages per *note component: 2cc. 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.

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

   (1) https://logtalk.org/tools.html#debugging


File: TheLogtalkHandbook-3.27.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: a5. for
conditional compilation of debugging goals.  For example, assuming a
‘debug/1’ predicate is used to wrap debug goals, we can define a hook
object containing the following definition for ‘goal_expansion/2’:

     goal_expansion(debug(Goal), Goal).

When not debugging, we can use a second hook object to discard the
‘debug/1’ calls by defining the predicate ‘goal_expansion/2’ as follows:

     goal_expansion(debug(_), true).

The Logtalk compiler automatically removes any redundant calls to the
built-in predicate ‘true/0’ when compiling entity predicates.


File: TheLogtalkHandbook-3.27.0.info,  Node: Ports profiling,  Prev: Using the term-expansion mechanism for debugging,  Up: Debugging

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

The Logtalk distribution includes a ports_profiler(1) 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.

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

   (1) https://logtalk.org/tools.html#ports-profiler


File: TheLogtalkHandbook-3.27.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 adds an 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: 3d. 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>.
* Inlining::
* Generated code simplification and optimizations::
* Size of the generated code::
* Debug mode overhead::
* Other considerations::


File: TheLogtalkHandbook-3.27.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: 105. and *note debug: 255. 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 `debug events' that enable tools such as the
command-line debugger and the ports profiler.


File: TheLogtalkHandbook-3.27.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.27.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: 105. flag is turned on and a static
predicate, *note ^^/1: 3e. calls have zero overhead in terms of number
of inferences.


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Messages<2>,  Next: Inlining,  Prev: Calls to module predicates,  Up: Performance<2>

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

Logtalk implements static binding and dynamic binding 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.  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: 105. 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: 69. flag set to ‘deny’ (setting this flag to ‘allow’ adds
an overhead of 5 inferences to the results above).

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: 3d. calls) always use dynamic
binding as the object that receives the message is only know at runtime.


File: TheLogtalkHandbook-3.27.0.info,  Node: Inlining,  Next: Generated code simplification and optimizations,  Prev: Messages<2>,  Up: Performance<2>

1.19.6 Inlining
---------------

When the *note optimize: 105. flag is turned on, the Logtalk compiler
performs `inlining' of predicate calls whenever possible.  This includes
calls to built-in methods such as *note once/1: 170, *note ignore/1:
16f, *note phrase/2: 14b, and *note phrase/3: 14c. but also 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: 151, calls
are inlined independently of the ‘optimize’ flag value.


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

1.19.7 Generated code simplification and optimizations
------------------------------------------------------

When the *note optimize: 105. 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.27.0.info,  Node: Size of the generated code,  Next: Debug mode overhead,  Prev: Generated code simplification and optimizations,  Up: Performance<2>

1.19.8 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: a5. 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: 12e. and *note reflection: 119.  The size of these tables
is proportional to the number of entities, entity relations, and
predicate declarations and definitions.  When the *note source_data: a6.
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.27.0.info,  Node: Debug mode overhead,  Next: Other considerations,  Prev: Size of the generated code,  Up: Performance<2>

1.19.9 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:
2bb.  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 proporcional to the number of passes on the call and
unification ports; deterministic code often results in a larger overhead
compared with code performing significant backtracking).

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

   (1) 
https://logtalk.org/library/logtalk_0.html#logtalk-0-trace-event-2

   (2) 
https://logtalk.org/library/logtalk_0.html#logtalk-0-debug-handler-2


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

1.19.10 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 results(3) for a
subset of the supported systems is also available in the Logtalk
website.

   ---------- 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.27.0.info,  Node: Installing Logtalk,  Next: Prolog integration and migration guide,  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.27.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.27.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.27.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.27.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.27.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.27.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::
* Settings files::
* Compiler and runtime::
* Library::
* Examples::
* Logtalk source files::


File: TheLogtalkHandbook-3.27.0.info,  Node: Adapter files,  Next: Settings files,  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
compiler flags.  Most of these compiler flags are described in the *note
next section: 201.  A few of these flags have read-only values and
cannot be changed at runtime.  These are:

‘settings_file’

     Allows or disables loading of a *note settings file: 2b8. 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, and in the
     user home directory.  With a value of ‘restrict’, settings files
     are only searched in the Logtalk user directory and in the user
     home directory.

‘prolog_dialect’

     Name of the *note backend Prolog compiler: 32. (an atom).  This
     flag can be used for *note conditional compilation: 2f0. of Prolog
     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.

‘prolog_conformance’

     Level of conformance of the *note backend Prolog compiler: 32. with
     the ISO Prolog Core standard.  The possible values are ‘strict’ for
     compilers claiming strict conformance and ‘lax’ for compilers
     claiming only broad conformance.

‘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: 23e. 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: 2f7.  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: 55.  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’ (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: 2f9.  Possible flag values are
     ‘unsupported’ and ‘supported’.


File: TheLogtalkHandbook-3.27.0.info,  Node: Settings files,  Next: Compiler and runtime,  Prev: Adapter files,  Up: Distribution overview

1.20.4.2 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 edit the ‘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 startup directory (assuming that the
read-only *note settings_file: 2ee. flag is set to ‘allow’).  If not
found, Logtalk tries to load a ‘settings.lgt’ file from the Logtalk user
folder.  If still not found, Logtalk tries to load a ‘settings.lgt’ file
from the user home folder.  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 silently with any
errors being simply ignored).  The usual contents is an
‘initialization/1’ Prolog directive containing calls to the *note
set_logtalk_flag/2: 259. Logtalk built-in predicate and asserting
clauses for the *note logtalk_library_path/2: 25d. multifile dynamic
predicate.  Note that the *note set_logtalk_flag/2: 263. directive
cannot be used as its scope is local to the source file being compiled.
For example, one of the troubles of writing portable applications is the
different feature sets of Prolog compilers.  A typical issue is the lack
of support for tabling.  Using the Logtalk support for conditional
compilation you could write:

     :- if(current_logtalk_flag(tabling, supported)).

         % add tabling directives to the source code
         :- table(foo/1).
         :- table(bar/2).

     :- endif.

The *note prolog_dialect: 2ef. flag may also be used with the
conditional compilation directives in order to define a single settings
file that can be used with several *note backend Prolog compilers: 32.
For example:

     :- 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.27.0.info,  Node: Compiler and runtime,  Next: Library,  Prev: Settings files,  Up: Distribution overview

1.20.4.3 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.27.0.info,  Node: Library,  Next: Examples,  Prev: Compiler and runtime,  Up: Distribution overview

1.20.4.4 Library
................

Starting from version 2.7.0, Logtalk contains a standard library of
useful objects, categories, and protocols.  Read the corresponding
‘NOTES.md’ file for details about the library contents.


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples,  Next: Logtalk source files,  Prev: Library,  Up: Distribution overview

1.20.4.5 Examples
.................

Logtalk 2.x and 3.x contain new implementations of some of the examples
provided with previous 1.x versions.  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 a
file named ‘SCRIPT.txt’ that contains cases of simple utilization.  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.27.0.info,  Node: Logtalk source files,  Prev: Examples,  Up: Distribution overview

1.20.4.6 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.27.0.info,  Node: Prolog integration and migration guide,  Prev: Installing Logtalk,  Up: User Manual

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

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

Logtalk supports the compilation of source files containing both plain
Prolog and Prolog modules.  This guide 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 guide 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.27.0.info,  Node: Source files with both Prolog code and Logtalk code,  Next: Encapsulating plain Prolog code in objects,  Up: Prolog integration and migration guide

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.27.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 guide

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: 75,
to the beginning of the file and an ending object directive, *note
end_object/0: 76, 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: 113.
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: 12a. 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: 12a. directives.  The Logtalk ‘wrapper’ tool can also help
in detecting cross predicate calls.  Compiling the resulting objects
with the Logtalk *note unknown_predicates: 268. and *note portability:
187. 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.27.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: 135, add a *note predicate scope directive: 10f.
and a *note multifile/1: 133. 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: 48. for more details.


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

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: 75, 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: 113. predicate directives.

  2. Add a closing object directive, *note end_object/0: 76, 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: 12a.
     directives.  If the referenced modules are not being converted into
     objects, simply keep the ‘use_module/2’ directives unchanged.

  6. Convert any ‘meta_predicate/1’ directives into Logtalk *note
     meta_predicate/1: 11c. 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.

  7. Convert any explicit qualified calls to module predicates to
     messages by replacing the ‘:/2’ operator with the *note ;;/2: 5e.
     message sending operator, assuming that the referenced modules are
     also being converted into objects.  Calls in the pseudo-module
     ‘user’ can simply be encapsulated using the *note {}/1: 14d.
     Logtalk external call control construct.  You can also use instead
     an *note uses/2: 12a. 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.

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

  9. If your module declares or defines clauses for multifile module
     predicates, replace the ‘:/2’ functor by ‘::/2’ in the
     ‘multifile/1’ directives and in the clause heads (assuming that all
     modules defining the multifile predicates are converted into
     objects; if that is not the case, just keep the ‘multifile/1’
     directives and the clause heads as-is).

  10. Compile the resulting objects with the Logtalk *note
     unknown_predicates: 268, and *note portability: 187. 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: 252. 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.27.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 guide

1.21.4 Compiling Prolog modules as objects
------------------------------------------

An alternative to convert Prolog modules into objects is to just compile
the Prolog source files using the ‘logtalk_load/1-2’ and
‘logtalk_compile/1-2’ predicates (set the Logtalk *note portability:
187. flag set to ‘warning’ to help you catch any unnoticed cross-module
predicate calls).  This allows you to reuse existing module code as
objects.  This has the advantage of requiring little if any code
changes.  There are, however, some limitations that you must be aware.
These limitations are a consequence of the lack of standardization of
Prolog module systems and consequent proliferation of proprietary
extensions.

* Menu:

* Supported module directives::
* Current limitations and workarounds::


File: TheLogtalkHandbook-3.27.0.info,  Node: Supported module directives,  Next: Current limitations and workarounds,  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: 12a.
     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.

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

‘meta_predicate/1’

     Module meta-predicates become object meta-predicates.  Only
     predicate arguments marked as goals or closures (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: 26c. flag to ‘warning’).

When compiling modules as objects, you probably don’t need event support
turned on.  You may use the *note events: 69. 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.27.0.info,  Node: Current limitations and workarounds,  Prev: Supported module directives,  Up: Compiling Prolog modules as objects

1.21.4.2 Current limitations and workarounds
............................................

The ‘reexport/1’ and ‘use_module/1’ directives are not directly
supported by the Logtalk compiler.  But most Prolog adapter files
provide support for compiling these directives using Logtalk’s first
stage of its *note term-expansion mechanism: a5.  Nevertheless, these
directives can be converted, respectively, into ‘reexport/2’ and
‘use_module/2’ directives by finding which predicates exported by the
specified modules are reexported or imported into the module containing
the directive.  Finding the names of the imported predicates that are
actually used is easy.  First, comment out the ‘use_module/1’ directives
and compile the file (making sure that the *note unknown_predicates:
268. 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 ‘reexport/1’ and ‘use_module/1’ directives
by, respectively, ‘reexport/2’ and ‘use_module/2’ directives.  You
should then be able to compile the modified Prolog module as an object.

Although Logtalk supports *note term and goal expansion mechanisms: a5,
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: 315.


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

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: 187. 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.27.0.info,  Node: Calling Prolog module predicates<2>,  Prev: Dealing with proprietary Prolog directives and predicates,  Up: Prolog integration and migration guide

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: 12a. 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: a4. 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: 185. section.


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


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Entities,  Next: Object definition,  Up: Grammar

2.1.1 Entities
--------------

     entity ::= 
          object | 
          category | 
          protocol 


File: TheLogtalkHandbook-3.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.0.info,  Node: Module identifiers,  Prev: Protocol identifiers,  Up: Entity identifiers

2.1.6.4 Module identifiers
..........................

     module_identifier ::= 
          `atom' 


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Terms,  Next: Directives,  Prev: Source file names,  Up: Grammar

2.1.8 Terms
-----------

* Menu:

* Object terms::
* Category terms::


File: TheLogtalkHandbook-3.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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.27.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_' 

     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 “‘]’” 

     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.27.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.27.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.27.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(’” predicate_indicator_list “‘)’” | 
          “‘protected(’” predicate_indicator_list “‘)’” | 
          “‘private(’” predicate_indicator_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(’” predicate_indicator_list “‘)’” | 
          “‘protected(’” predicate_indicator_list “‘)’” | 
          “‘private(’” predicate_indicator_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(’” predicate_indicator_list “‘)’” | 
          “‘protected(’” predicate_indicator_list “‘)’” | 
          “‘private(’” predicate_indicator_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.27.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.27.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.27.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.27.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.27.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.27.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: 113. predicate of the receiver object.  When the message
corresponds to a *note protected: 114. or *note private: 115. predicate,
the call is only valid if the *note sender: 36b. matches the *note
predicate scope container: 36c.  When the predicate is declared but not
defined, the message simply fails (as per the *note closed-world
assumption: 4c.).

The ‘{Proxy}::Message’ syntax allows simplified access to *note
parametric object proxies: 36d.  Its operational semantics is equivalent
to the goal conjunction ‘(call(Proxy), Proxy::Message)’.  I.e.  ‘Proxy’
is proved within the context of the pseudo-object *note user: a9. 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 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: 105. 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: 28b. for details.


File: TheLogtalkHandbook-3.27.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.27.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.27.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: 3d, *note ^^/1: 3e, *note []/1: 61.


File: TheLogtalkHandbook-3.27.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.27.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: 4b.  Can only used in the body of a
predicate definition.  The argument should match a *note public: 113. or
*note protected: 114. predicate of `self'.  It may also match a *note
private: 115. 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: 4c.).

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: 28b. for details.


File: TheLogtalkHandbook-3.27.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.27.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.27.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: 5e, *note ^^/1: 3e, *note []/1: 61.


File: TheLogtalkHandbook-3.27.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.27.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.27.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: 5e. 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.27.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.27.0.info,  Node: Errors<3>,  Next: Examples<4>,  Prev: Modes and number of proofs<3>,  Up: []/1

2.2.2.4 Errors
..............

     Object and the original sender are the same object: 
          ‘permission_error(access, object, Sender)’ 
           
     Either Object or Message is a variable: 
          ‘instantiation_error’ 
     Object is neither a variable nor an 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 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)’ 


File: TheLogtalkHandbook-3.27.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: 5e, *note ;;/1: 3d, *note ^^/1: 3e, *note forward/1: dc.


File: TheLogtalkHandbook-3.27.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.27.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.27.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: 4c.).
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: 4b. and *note sender: 36b. 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: 105. 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: 28b. 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: 113. or *note
protected: 114.  It may also be declared *note private: 115. 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.27.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.27.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.27.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: 5e, *note ;;/1: 3d, *note []/1: 61.


File: TheLogtalkHandbook-3.27.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.27.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.27.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: a5.
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: a9.  It is also possible to use ‘{Closure}’ as the first
argument of *note call/1-N: 144. 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: 38f. when their
identifiers correspond to predicates defined in ‘user’.


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Errors<5>,  Next: Examples<6>,  Prev: Modes and number of proofs<5>,  Up: {}/1

2.2.4.4 Errors
..............

     Term or Goal is a variable: 
          ‘instantiation_error’ 
     Term is neither a variable nor a callable term: 
          ‘type_error(callable, Term)’ 
     Goal is neither a variable nor a callable term: 
          ‘type_error(callable, Goal)’ 


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Context switching calls,  Prev: Calling external predicates,  Up: Control constructs

2.2.5 Context switching calls
-----------------------------

* Menu:

* <</2::


File: TheLogtalkHandbook-3.27.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.27.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: 36b, *note this: 141, and *note self: 4b.) 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: 278. 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: 36d.  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: a9. 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.27.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.27.0.info,  Node: Errors<6>,  Next: Examples<7>,  Prev: Modes and number of proofs<6>,  Up: <</2

2.2.5.4 Errors
..............

     Either Object or Goal is a variable: 
          ‘instantiation_error’ 
     Object is neither a variable nor a valid object identifier: 
          ‘type_error(object_identifier, Object)’ 
     Goal is neither a variable nor a callable term: 
          ‘type_error(callable, Goal)’ 
     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)’ 


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

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

The backend Prolog compiler adapter files define a table that translates
between the Logtalk and Prolog specific atoms that represent each
supported encoding.

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

   (1) 
http://www.iana.org/assignments/character-sets/character-sets.xhtml


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Examples<8>,  Prev: Template and modes,  Up: encoding/1

2.3.1.4 Examples
................

     :- encoding('UTF-8').


File: TheLogtalkHandbook-3.27.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.27.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: ad. and is
expanded as a source file name.  Relative paths are interpreted as
relative to the path of the file containing the directive.

When using the *note reflection API: 119, predicates from an included
file can be distinguished from predicates from the main file by looking
for the ‘include/1’ predicate declaration or 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).

     Warning: When using this directive as an argument in calls to the
     *note create_object/4: 44. and *note create_category/4: ee.
     predicates, the objects and categories will not be recreated or
     redefined when the included file(s) are modified and the *note
     logtalk_make/0: 254. predicate or the *note logtalk_make/1: 256.
     (with target ‘all’) predicates are called.


File: TheLogtalkHandbook-3.27.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.27.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
     % current directory:
     :- include('factbase.pl').

     % include a file given its absolute path:
     :- include('/home/me/databases/countries.pl').

     % create a wrapper object for a Prolog file:
     | ?- create_object(cities, [], [public(city/4), include('cities.pl')], []).


File: TheLogtalkHandbook-3.27.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.27.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 loaded into memory.  When used at a global
level within a source file, this directive defines a goal to be called
after the compiled source file is loaded into memory.

Multiple initialization directives can be used in a source file or in an
object.  Their goals will be called in order at loading time.

     Note: Categories and protocols cannot contain ‘initialization/1’
     directives as the initialization goals would lack a complete
     execution context 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 performance and providing better support
for embedded applications.

     Warning: Some backend Prolog compilers declare ‘initialization’ as
     an operator for a lighter syntax.  But this makes the code
     non-portable and is a practice best avoided.


File: TheLogtalkHandbook-3.27.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.27.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).


File: TheLogtalkHandbook-3.27.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.27.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.27.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.27.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: 127.


File: TheLogtalkHandbook-3.27.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.27.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: 259. built-in predicate called from an *note
initialization/1: 88. directive.  For a description of the predefined
compiler flags, please see the *note Compiler flags: 201. section in the
User Manual.


File: TheLogtalkHandbook-3.27.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.27.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.27.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 the source file:
     :- set_logtalk_flag(unknown_entities, silent).


     :- object(...).

         % generate events for messages sent from this object:
         :- set_logtalk_flag(events, allow).
         ...


File: TheLogtalkHandbook-3.27.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.27.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.27.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: a5. when the directive occurs in a source file.  Conditional
compilation directives can be nested.

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 fully compiled and loaded).


File: TheLogtalkHandbook-3.27.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.27.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: 245, *note else/0: 246, *note endif/0: 247.


File: TheLogtalkHandbook-3.27.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.27.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: a5. when the directive occurs
in a source file.

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 fully compiled and loaded).


File: TheLogtalkHandbook-3.27.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.27.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: 246, *note endif/0: 247, *note if/1: 244.


File: TheLogtalkHandbook-3.27.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.27.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: 244. directive is false.


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Examples<15>,  Prev: Template and modes<8>,  Up: else/0

2.3.2.12 Examples
.................

An example where an 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: 245, *note endif/0: 247, *note if/1: 244.


File: TheLogtalkHandbook-3.27.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.27.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: 244.
directive.


File: TheLogtalkHandbook-3.27.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.27.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: 245, *note else/0: 246, *note if/1: 244.


File: TheLogtalkHandbook-3.27.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-3::
* dynamic/0::
* end_category/0::
* end_object/0::
* end_protocol/0::
* info/1::
* object/1-5::
* protocol/1-2::
* threaded/0::
* uses/1::


File: TheLogtalkHandbook-3.27.0.info,  Node: built_in/0,  Next: category/1-3,  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.27.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.


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Examples<17>,  Prev: Template and modes<10>,  Up: built_in/0

2.3.3.4 Examples
................

     :- built_in.


File: TheLogtalkHandbook-3.27.0.info,  Node: category/1-3,  Next: dynamic/0,  Prev: built_in/0,  Up: Entity directives<2>

2.3.3.5 category/1-3
....................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<17>,  Next: Template and modes<11>,  Up: category/1-3

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.27.0.info,  Node: Template and modes<11>,  Next: Examples<18>,  Prev: Description<17>,  Up: category/1-3

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.27.0.info,  Node: Examples<18>,  Prev: Template and modes<11>,  Up: category/1-3

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


File: TheLogtalkHandbook-3.27.0.info,  Node: dynamic/0,  Next: end_category/0,  Prev: category/1-3,  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.27.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.


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Examples<19>,  Prev: Template and modes<12>,  Up: dynamic/0

2.3.3.12 Examples
.................

     :- dynamic.

See also
........

*note dynamic/1: 123, *note object_property/2: a1, *note
protocol_property/2: cb, *note category_property/2: 100.


File: TheLogtalkHandbook-3.27.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.27.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.27.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.27.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-3: e4.


File: TheLogtalkHandbook-3.27.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.27.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.27.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.27.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: 75.


File: TheLogtalkHandbook-3.27.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.27.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.27.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.27.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: b3.


File: TheLogtalkHandbook-3.27.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.27.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: 2ac. section for a description of the
default keys.


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Examples<23>,  Prev: Template and modes<16>,  Up: info/1

2.3.3.28 Examples
.................

     :- info([
         version is 1.0,
         author is 'Paulo Moura',
         date is 2000/4/20,
         comment is 'List protocol.'
     ]).

See also
........

*note info/2: 131, *note object_property/2: a1, *note
protocol_property/2: cb, *note category_property/2: 100.


File: TheLogtalkHandbook-3.27.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.27.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.27.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.27.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: 76.


File: TheLogtalkHandbook-3.27.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.27.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.27.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.27.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: b4.


File: TheLogtalkHandbook-3.27.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.27.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: a9.
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.).


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Examples<26>,  Prev: Template and modes<19>,  Up: threaded/0

2.3.3.40 Examples
.................

     :- threaded.

See also
........

*note synchronized/1: 56, *note object_property/2: a1.


File: TheLogtalkHandbook-3.27.0.info,  Node: uses/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.27.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 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: 7c. 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 are 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 static binding, and thus optimal message sending
performance, the objects should be loaded before compiling the entities
that call their predicates.


File: TheLogtalkHandbook-3.27.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.27.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: 12a, *note use_module/2: 16b.


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: alias/2,  Next: coinductive/1,  Up: Predicate directives<3>

2.3.4.1 alias/2
...............

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<27>,  Next: Template and modes<21>,  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.27.0.info,  Node: Template and modes<21>,  Next: Examples<28>,  Prev: Description<27>,  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.27.0.info,  Node: Examples<28>,  Prev: Template and modes<21>,  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: 12a, *note use_module/2: 16b, *note uses/1: 95.


File: TheLogtalkHandbook-3.27.0.info,  Node: coinductive/1,  Next: discontiguous/1,  Prev: alias/2,  Up: Predicate directives<3>

2.3.4.5 coinductive/1
.....................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<28>,  Next: Template and modes<22>,  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: 417. 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.27.0.info,  Node: Template and modes<22>,  Next: Examples<29>,  Prev: Description<28>,  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.27.0.info,  Node: Examples<29>,  Prev: Template and modes<22>,  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: 417, *note predicate_property/2:
112.


File: TheLogtalkHandbook-3.27.0.info,  Node: discontiguous/1,  Next: dynamic/1,  Prev: coinductive/1,  Up: Predicate directives<3>

2.3.4.9 discontiguous/1
.......................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<29>,  Next: Template and modes<23>,  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 ‘discontiguous’ as
     an operator for a lighter syntax.  But this makes the code
     non-portable and is a practice best avoided.


File: TheLogtalkHandbook-3.27.0.info,  Node: Template and modes<23>,  Next: Examples<30>,  Prev: Description<29>,  Up: discontiguous/1

2.3.4.11 Template and modes
...........................

     discontiguous(+predicate_indicator_term)
     discontiguous(+non_terminal_indicator_term)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<30>,  Prev: Template and modes<23>,  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.27.0.info,  Node: dynamic/1,  Next: info/2,  Prev: discontiguous/1,  Up: Predicate directives<3>

2.3.4.13 dynamic/1
..................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<30>,  Next: Template and modes<24>,  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: 115. 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: 134.

Note that dynamic predicates cannot be declared synchronized (when
necessary, declare the predicates updating the dynamic predicates as
*note synchronized: 56.).

     Warning: Some backend Prolog compilers declare ‘dynamic’ as an
     operator for a lighter syntax.  But this makes the code
     non-portable and is a practice best avoided.


File: TheLogtalkHandbook-3.27.0.info,  Node: Template and modes<24>,  Next: Examples<31>,  Prev: Description<30>,  Up: dynamic/1

2.3.4.15 Template and modes
...........................

     dynamic(+qualified_predicate_indicator_term)
     dynamic(+qualified_non_terminal_indicator_term)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<31>,  Prev: Template and modes<24>,  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: 8b, *note predicate_property/2: 112.


File: TheLogtalkHandbook-3.27.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<31>.
* Template and modes: Template and modes<25>.
* Examples: Examples<32>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<31>,  Next: Template and modes<25>,  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: 2ae.
section for a description of the default keys.


File: TheLogtalkHandbook-3.27.0.info,  Node: Template and modes<25>,  Next: Examples<32>,  Prev: Description<31>,  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.27.0.info,  Node: Examples<32>,  Prev: Template and modes<25>,  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: 8e, *note mode/2: 118, *note predicate_property/2: 112.


File: TheLogtalkHandbook-3.27.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<32>.
* Template and modes: Template and modes<26>.
* Examples: Examples<33>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<32>,  Next: Template and modes<26>,  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 `closure' instead of a
goal if the meta-predicate uses the *note call/1-N: 144. 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.  Normal arguments are represented by the atom ‘*’.
Meta-arguments are always called in the meta-predicate calling context,
not in the meta-predicate definition context.

Logtalk allows the use of this directive to override the original
meta-predicate directive.  This is sometimes necessary when calling
Prolog module meta-predicates due to the lack of standardization of the
syntax of the meta-predicate templates.

     Warning: Some backend Prolog compilers declare ‘meta_predicate’ as
     an operator for a lighter syntax.  But this makes the code
     non-portable and is a practice best avoided.


File: TheLogtalkHandbook-3.27.0.info,  Node: Template and modes<26>,  Next: Examples<33>,  Prev: Description<32>,  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.27.0.info,  Node: Examples<33>,  Prev: Template and modes<26>,  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: 42e, *note predicate_property/2: 112.


File: TheLogtalkHandbook-3.27.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<33>.
* Template and modes: Template and modes<27>.
* Examples: Examples<34>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<33>,  Next: Template and modes<27>,  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 `closure' instead of a goal if the non-terminal
uses the *note call//1-N: 17e. 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.27.0.info,  Node: Template and modes<27>,  Next: Examples<34>,  Prev: Description<33>,  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.27.0.info,  Node: Examples<34>,  Prev: Template and modes<27>,  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: 11c, *note predicate_property/2: 112.


File: TheLogtalkHandbook-3.27.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<34>.
* Template and modes: Template and modes<28>.
* Examples: Examples<35>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<34>,  Next: Template and modes<28>,  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.27.0.info,  Node: Template and modes<28>,  Next: Examples<35>,  Prev: Description<34>,  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.27.0.info,  Node: Examples<35>,  Prev: Template and modes<28>,  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: 131, *note predicate_property/2: 112.


File: TheLogtalkHandbook-3.27.0.info,  Node: multifile/1,  Next: private/1,  Prev: mode/2,  Up: Predicate directives<3>

2.3.4.33 multifile/1
....................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<35>,  Next: Template and modes<29>,  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: 195. 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 ‘multifile’ as an
     operator for a lighter syntax.  But this makes the code
     non-portable and is a practice best avoided.


File: TheLogtalkHandbook-3.27.0.info,  Node: Template and modes<29>,  Next: Examples<36>,  Prev: Description<35>,  Up: multifile/1

2.3.4.35 Template and modes
...........................

     multifile(+qualified_predicate_indicator_term)
     multifile(+qualified_non_terminal_indicator_term)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<36>,  Prev: Template and modes<29>,  Up: multifile/1

2.3.4.36 Examples
.................

     :- multifile(table/3).
     :- multifile(user::hook/2).

See also
........

*note public/1: 113, *note protected/1: 114, *note private/1: 115, *note
predicate_property/2: 112.


File: TheLogtalkHandbook-3.27.0.info,  Node: private/1,  Next: protected/1,  Prev: multifile/1,  Up: Predicate directives<3>

2.3.4.37 private/1
..................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<36>,  Next: Template and modes<30>,  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: 14b. and *note phrase/3:
14c. methods from the object containing the private directive.


File: TheLogtalkHandbook-3.27.0.info,  Node: Template and modes<30>,  Next: Examples<37>,  Prev: Description<36>,  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.27.0.info,  Node: Examples<37>,  Prev: Template and modes<30>,  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: 114, *note public/1: 113, *note predicate_property/2:
112.


File: TheLogtalkHandbook-3.27.0.info,  Node: protected/1,  Next: public/1,  Prev: private/1,  Up: Predicate directives<3>

2.3.4.41 protected/1
....................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<37>,  Next: Template and modes<31>,  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: 14b. and *note phrase/3: 14c. calls from the object
containing the directive or from an object that inherits the directive.
Protected operators are not inherited but declaring them provides useful
information for defining descendant objects.


File: TheLogtalkHandbook-3.27.0.info,  Node: Template and modes<31>,  Next: Examples<38>,  Prev: Description<37>,  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.27.0.info,  Node: Examples<38>,  Prev: Template and modes<31>,  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: 115, *note public/1: 113, *note predicate_property/2:
112.


File: TheLogtalkHandbook-3.27.0.info,  Node: public/1,  Next: synchronized/1,  Prev: protected/1,  Up: Predicate directives<3>

2.3.4.45 public/1
.................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<38>,  Next: Template and modes<32>,  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: 14b.
and *note phrase/3: 14c. calls from any object.  Public operators are
not exported but declaring them provides useful information for defining
client objects.


File: TheLogtalkHandbook-3.27.0.info,  Node: Template and modes<32>,  Next: Examples<39>,  Prev: Description<38>,  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.27.0.info,  Node: Examples<39>,  Prev: Template and modes<32>,  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: 115, *note protected/1: 114, *note
predicate_property/2: 112.


File: TheLogtalkHandbook-3.27.0.info,  Node: synchronized/1,  Next: uses/2,  Prev: public/1,  Up: Predicate directives<3>

2.3.4.49 synchronized/1
.......................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<39>,  Next: Template and modes<33>,  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: 170. meta-predicate.

Note that synchronized predicates cannot be declared *note dynamic: 123.
(when necessary, declare the predicates updating the dynamic predicates
as synchronized).


File: TheLogtalkHandbook-3.27.0.info,  Node: Template and modes<33>,  Next: Examples<40>,  Prev: Description<39>,  Up: synchronized/1

2.3.4.51 Template and modes
...........................

     synchronized(+predicate_indicator_term)
     synchronized(+non_terminal_indicator_term)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<40>,  Prev: Template and modes<33>,  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: 112.


File: TheLogtalkHandbook-3.27.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<40>.
* Template and modes: Template and modes<34>.
* Examples: Examples<41>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<40>,  Next: Template and modes<34>,  Up: uses/2

2.3.4.54 Description
....................

     uses(Object, [Name/Arity, ...])
     uses(Object, [Name/Arity as Alias/Arity, ...])

     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 used when compiling calls to the database and
*note reflection: 119. built-in methods by looking into these methods
predicate arguments.

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.

To enable the use of static binding, 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:
7c. when using the directive in a parametric object or a parametric
category defined in a source file (the common case).  In this case,
dynamic binding 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.27.0.info,  Node: Template and modes<34>,  Next: Examples<41>,  Prev: Description<40>,  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, +non_terminal_indicator_list)
     uses(+object_identifier, +non_terminal_indicator_alias_list)

     uses(+object_identifier, +operator_list)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<41>,  Prev: Template and modes<34>,  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 using a *note parameter variable: 7c. 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 use_module/2: 16b, *note uses/1: 95, *note alias/2: 12d.


File: TheLogtalkHandbook-3.27.0.info,  Node: use_module/2,  Prev: uses/2,  Up: Predicate directives<3>

2.3.4.57 use_module/2
.....................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<41>,  Next: Template and modes<35>,  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, [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 used when compiling calls to the database and
*note reflection: 119. built-in methods by examining these methods
predicate arguments.

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: 12a. directives or for giving more meaningful names considering
the calling context of the predicates.

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
loader 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:
7c. when using the directive in a parametric object or a parametric
category defined in a source file (the common case).  In this case,
dynamic binding 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.27.0.info,  Node: Template and modes<35>,  Next: Examples<42>,  Prev: Description<41>,  Up: use_module/2

2.3.4.59 Template and modes
...........................

     use_module(+module_identifier, +predicate_indicator_list)
     use_module(+module_identifier, +predicate_indicator_alias_list)

     use_module(+module_identifier, +non_terminal_indicator_list)
     use_module(+module_identifier, +non_terminal_indicator_alias_list)

     use_module(+module_identifier, +operator_list)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<42>,  Prev: Template and modes<35>,  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(_)),
         ...

An example of using a *note parameter variable: 7c. 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 uses/2: 12a, *note uses/1: 95, *note alias/2: 12d.


File: TheLogtalkHandbook-3.27.0.info,  Node: Built-in predicates,  Next: Built-in methods,  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::


File: TheLogtalkHandbook-3.27.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.27.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<42>.
* Modes and number of proofs: Modes and number of proofs<7>.
* Errors: Errors<8>.
* Examples: Examples<43>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<42>,  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.27.0.info,  Node: Modes and number of proofs<7>,  Next: Errors<8>,  Prev: Description<42>,  Up: current_category/1

2.4.1.3 Modes and number of proofs
..................................

     current_category(?category_identifier) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<8>,  Next: Examples<43>,  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.27.0.info,  Node: Examples<43>,  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: cc, *note category_property/2: 100, *note
create_category/4: ee, *note complements_object/2: 9e, *note
extends_category/2-3: fd, *note imports_category/2-3: 9b.


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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<43>,  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.27.0.info,  Node: Modes and number of proofs<8>,  Next: Errors<9>,  Prev: Description<43>,  Up: current_object/1

2.4.1.8 Modes and number of proofs
..................................

     current_object(?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<9>,  Next: Examples<44>,  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.27.0.info,  Node: Examples<44>,  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: 46, *note create_object/4: 44, *note
object_property/2: a1, *note extends_object/2-3: 9a, *note
instantiates_class/2-3: 98, *note specializes_class/2-3: 99, *note
complements_object/2: 9e.


File: TheLogtalkHandbook-3.27.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<44>.
* Modes and number of proofs: Modes and number of proofs<9>.
* Errors: Errors<10>.
* Examples: Examples<45>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<44>,  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.27.0.info,  Node: Modes and number of proofs<9>,  Next: Errors<10>,  Prev: Description<44>,  Up: current_protocol/1

2.4.1.13 Modes and number of proofs
...................................

     current_protocol(?protocol_identifier) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<10>,  Next: Examples<45>,  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.27.0.info,  Node: Examples<45>,  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: bd, *note create_protocol/3: ba, *note
protocol_property/2: cb, *note conforms_to_protocol/2-3: 9d, *note
extends_protocol/2-3: c7, *note implements_protocol/2-3: 9c.


File: TheLogtalkHandbook-3.27.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.27.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<45>.
* Modes and number of proofs: Modes and number of proofs<10>.
* Errors: Errors<11>.
* Examples: Examples<46>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<45>,  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 gramar
section on *note entity properties: a3. and described in the User Manual
section on *note category properties: fe.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<10>,  Next: Errors<11>,  Prev: Description<45>,  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.27.0.info,  Node: Errors<11>,  Next: Examples<46>,  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.27.0.info,  Node: Examples<46>,  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: cc, *note create_category/4: ee, *note
current_category/1: c8, *note complements_object/2: 9e, *note
extends_category/2-3: fd, *note imports_category/2-3: 9b.


File: TheLogtalkHandbook-3.27.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<46>.
* Modes and number of proofs: Modes and number of proofs<11>.
* Errors: Errors<12>.
* Examples: Examples<47>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<46>,  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 gramar section
on *note entity properties: a3. and described in the User Manual section
on *note object properties: a0.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<11>,  Next: Errors<12>,  Prev: Description<46>,  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.27.0.info,  Node: Errors<12>,  Next: Examples<47>,  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.27.0.info,  Node: Examples<47>,  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: 46, *note create_object/4: 44, *note
current_object/1: 7f, *note extends_object/2-3: 9a, *note
instantiates_class/2-3: 98, *note specializes_class/2-3: 99, *note
complements_object/2: 9e.


File: TheLogtalkHandbook-3.27.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<47>.
* Modes and number of proofs: Modes and number of proofs<12>.
* Errors: Errors<13>.
* Examples: Examples<48>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<47>,  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 gramar section on *note entity properties: a3. and described in
the User Manual section on *note protocol properties: ca.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<12>,  Next: Errors<13>,  Prev: Description<47>,  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.27.0.info,  Node: Errors<13>,  Next: Examples<48>,  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.27.0.info,  Node: Examples<48>,  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: bd, *note create_protocol/3: ba, *note
current_protocol/1: b7, *note conforms_to_protocol/2-3: 9d, *note
extends_protocol/2-3: c7, *note implements_protocol/2-3: 9c.


File: TheLogtalkHandbook-3.27.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.27.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<48>.
* Modes and number of proofs: Modes and number of proofs<13>.
* Errors: Errors<14>.
* Examples: Examples<49>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<48>,  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 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.27.0.info,  Node: Modes and number of proofs<13>,  Next: Errors<14>,  Prev: Description<48>,  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.27.0.info,  Node: Errors<14>,  Next: Examples<49>,  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.27.0.info,  Node: Examples<49>,  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: cc, *note category_property/2: 100, *note
current_category/1: c8, *note complements_object/2: 9e, *note
extends_category/2-3: fd, *note imports_category/2-3: 9b.


File: TheLogtalkHandbook-3.27.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<49>.
* Modes and number of proofs: Modes and number of proofs<14>.
* Errors: Errors<15>.
* Examples: Examples<50>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<49>,  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: 492. 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 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.27.0.info,  Node: Modes and number of proofs<14>,  Next: Errors<15>,  Prev: Description<49>,  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.27.0.info,  Node: Errors<15>,  Next: Examples<50>,  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.27.0.info,  Node: Examples<50>,  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: 46, *note current_object/1: 7f, *note
object_property/2: a1, *note extends_object/2-3: 9a, *note
instantiates_class/2-3: 98, *note specializes_class/2-3: 99, *note
complements_object/2: 9e.


File: TheLogtalkHandbook-3.27.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<50>.
* Modes and number of proofs: Modes and number of proofs<15>.
* Errors: Errors<16>.
* Examples: Examples<51>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<50>,  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.27.0.info,  Node: Modes and number of proofs<15>,  Next: Errors<16>,  Prev: Description<50>,  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.27.0.info,  Node: Errors<16>,  Next: Examples<51>,  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.27.0.info,  Node: Examples<51>,  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: bd, *note current_protocol/1: b7, *note
protocol_property/2: cb, *note conforms_to_protocol/2-3: 9d, *note
extends_protocol/2-3: c7, *note implements_protocol/2-3: 9c.


File: TheLogtalkHandbook-3.27.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.27.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<51>.
* Modes and number of proofs: Modes and number of proofs<16>.
* Errors: Errors<17>.
* Examples: Examples<52>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<51>,  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.27.0.info,  Node: Modes and number of proofs<16>,  Next: Errors<17>,  Prev: Description<51>,  Up: abolish_category/1

2.4.4.3 Modes and number of proofs
..................................

     abolish_category(+category_identifier) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<17>,  Next: Examples<52>,  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.27.0.info,  Node: Examples<52>,  Prev: Errors<17>,  Up: abolish_category/1

2.4.4.5 Examples
................

     | ?- abolish_category(monitoring).

See also
........

*note category_property/2: 100, *note create_category/4: ee, *note
current_category/1: c8. *note complements_object/2: 9e, *note
extends_category/2-3: fd, *note imports_category/2-3: 9b.


File: TheLogtalkHandbook-3.27.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<52>.
* Modes and number of proofs: Modes and number of proofs<17>.
* Errors: Errors<18>.
* Examples: Examples<53>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<52>,  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.27.0.info,  Node: Modes and number of proofs<17>,  Next: Errors<18>,  Prev: Description<52>,  Up: abolish_object/1

2.4.4.8 Modes and number of proofs
..................................

     abolish_object(+object_identifier) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<18>,  Next: Examples<53>,  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.27.0.info,  Node: Examples<53>,  Prev: Errors<18>,  Up: abolish_object/1

2.4.4.10 Examples
.................

     | ?- abolish_object(list).

See also
........

*note create_object/4: 44, *note current_object/1: 7f, *note
object_property/2: a1, *note extends_object/2-3: 9a, *note
instantiates_class/2-3: 98, *note specializes_class/2-3: 99, *note
complements_object/2: 9e.


File: TheLogtalkHandbook-3.27.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<53>.
* Modes and number of proofs: Modes and number of proofs<18>.
* Errors: Errors<19>.
* Examples: Examples<54>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<53>,  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.27.0.info,  Node: Modes and number of proofs<18>,  Next: Errors<19>,  Prev: Description<53>,  Up: abolish_protocol/1

2.4.4.13 Modes and number of proofs
...................................

     abolish_protocol(@protocol_identifier) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<19>,  Next: Examples<54>,  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.27.0.info,  Node: Examples<54>,  Prev: Errors<19>,  Up: abolish_protocol/1

2.4.4.15 Examples
.................

     | ?- abolish_protocol(listp).

See also
........

*note create_protocol/3: ba, *note current_protocol/1: b7, *note
protocol_property/2: cb, *note conforms_to_protocol/2-3: 9d, *note
extends_protocol/2-3: c7, *note implements_protocol/2-3: 9c.


File: TheLogtalkHandbook-3.27.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.27.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<54>.
* Modes and number of proofs: Modes and number of proofs<19>.
* Errors: Errors<20>.
* Examples: Examples<55>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<54>,  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.27.0.info,  Node: Modes and number of proofs<19>,  Next: Errors<20>,  Prev: Description<54>,  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.27.0.info,  Node: Errors<20>,  Next: Examples<55>,  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.27.0.info,  Node: Examples<55>,  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: 7f, *note instantiates_class/2-3: 98, *note
specializes_class/2-3: 99.


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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<55>,  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.27.0.info,  Node: Modes and number of proofs<20>,  Next: Errors<21>,  Prev: Description<55>,  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.27.0.info,  Node: Errors<21>,  Next: Examples<56>,  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.27.0.info,  Node: Examples<56>,  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: b7, *note implements_protocol/2-3: 9c, *note
conforms_to_protocol/2-3: 9d.


File: TheLogtalkHandbook-3.27.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<56>.
* Modes and number of proofs: Modes and number of proofs<21>.
* Errors: Errors<22>.
* Examples: Examples<57>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<56>,  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.27.0.info,  Node: Modes and number of proofs<21>,  Next: Errors<22>,  Prev: Description<56>,  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.27.0.info,  Node: Errors<22>,  Next: Examples<57>,  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.27.0.info,  Node: Examples<57>,  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: c8, *note complements_object/2: 9e, *note
imports_category/2-3: 9b.


File: TheLogtalkHandbook-3.27.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<57>.
* Modes and number of proofs: Modes and number of proofs<22>.
* Errors: Errors<23>.
* Examples: Examples<58>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<57>,  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.27.0.info,  Node: Modes and number of proofs<22>,  Next: Errors<23>,  Prev: Description<57>,  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.27.0.info,  Node: Errors<23>,  Next: Examples<58>,  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.27.0.info,  Node: Examples<58>,  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: 7f, *note current_protocol/1: b7, *note
current_category/1: c8, *note conforms_to_protocol/2-3: 9d.


File: TheLogtalkHandbook-3.27.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<58>.
* Modes and number of proofs: Modes and number of proofs<23>.
* Errors: Errors<24>.
* Examples: Examples<59>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<58>,  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.27.0.info,  Node: Modes and number of proofs<23>,  Next: Errors<24>,  Prev: Description<58>,  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.27.0.info,  Node: Errors<24>,  Next: Examples<59>,  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.27.0.info,  Node: Examples<59>,  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: 7f, *note current_protocol/1: b7, *note
current_category/1: c8, *note implements_protocol/2-3: 9c.


File: TheLogtalkHandbook-3.27.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<59>.
* Modes and number of proofs: Modes and number of proofs<24>.
* Errors: Errors<25>.
* Examples: Examples<60>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<59>,  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.27.0.info,  Node: Modes and number of proofs<24>,  Next: Errors<25>,  Prev: Description<59>,  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.27.0.info,  Node: Errors<25>,  Next: Examples<60>,  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.27.0.info,  Node: Examples<60>,  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: c8, *note imports_category/2-3: 9b.


File: TheLogtalkHandbook-3.27.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<60>.
* Modes and number of proofs: Modes and number of proofs<25>.
* Errors: Errors<26>.
* Examples: Examples<61>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<60>,  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.27.0.info,  Node: Modes and number of proofs<25>,  Next: Errors<26>,  Prev: Description<60>,  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.27.0.info,  Node: Errors<26>,  Next: Examples<61>,  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.27.0.info,  Node: Examples<61>,  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: c8, *note complements_object/2: 9e.


File: TheLogtalkHandbook-3.27.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<61>.
* Modes and number of proofs: Modes and number of proofs<26>.
* Errors: Errors<27>.
* Examples: Examples<62>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<61>,  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.27.0.info,  Node: Modes and number of proofs<26>,  Next: Errors<27>,  Prev: Description<61>,  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.27.0.info,  Node: Errors<27>,  Next: Examples<62>,  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.27.0.info,  Node: Examples<62>,  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: 7f, *note extends_object/2-3: 9a, *note
specializes_class/2-3: 99.


File: TheLogtalkHandbook-3.27.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<62>.
* Modes and number of proofs: Modes and number of proofs<27>.
* Errors: Errors<28>.
* Examples: Examples<63>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<62>,  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.27.0.info,  Node: Modes and number of proofs<27>,  Next: Errors<28>,  Prev: Description<62>,  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.27.0.info,  Node: Errors<28>,  Next: Examples<63>,  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.27.0.info,  Node: Examples<63>,  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: 7f, *note extends_object/2-3: 9a, *note
instantiates_class/2-3: 98.


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: abolish_events/5,  Next: current_event/5,  Up: Event handling<2>

2.4.6.1 abolish_events/5
........................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<63>,  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.27.0.info,  Node: Modes and number of proofs<28>,  Next: Errors<29>,  Prev: Description<63>,  Up: abolish_events/5

2.4.6.3 Modes and number of proofs
..................................

     abolish_events(@term, @term, @term, @term, @term) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<29>,  Next: Examples<64>,  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.27.0.info,  Node: Examples<64>,  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: 1d0, *note define_events/5: 1ca, *note before/3:
d8, *note after/3: d9.


File: TheLogtalkHandbook-3.27.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<64>.
* Modes and number of proofs: Modes and number of proofs<29>.
* Errors: Errors<30>.
* Examples: Examples<65>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<64>,  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.27.0.info,  Node: Modes and number of proofs<29>,  Next: Errors<30>,  Prev: Description<64>,  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.27.0.info,  Node: Errors<30>,  Next: Examples<65>,  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.27.0.info,  Node: Examples<65>,  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: 1cd, *note define_events/5: 1ca, *note before/3:
d8, *note after/3: d9.


File: TheLogtalkHandbook-3.27.0.info,  Node: define_events/5,  Prev: current_event/5,  Up: Event handling<2>

2.4.6.11 define_events/5
........................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<65>,  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.27.0.info,  Node: Modes and number of proofs<30>,  Next: Errors<31>,  Prev: Description<65>,  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.27.0.info,  Node: Errors<31>,  Next: Examples<66>,  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: 
          ‘existence_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.27.0.info,  Node: Examples<66>,  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: 1cd, *note current_event/5: 1d0, *note before/3:
d8, *note after/3: d9.


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: threaded/1,  Next: threaded_call/1-2,  Up: Multi-threading

2.4.7.1 threaded/1
..................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<66>,  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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<31>,  Next: Errors<32>,  Prev: Description<66>,  Up: threaded/1

2.4.7.3 Modes and number of proofs
..................................

     threaded(+callable) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<32>,  Next: Examples<67>,  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.27.0.info,  Node: Examples<67>,  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: 1e2, *note threaded_once/1-2: 1e4, *note
threaded_ignore/1: 1e9, *note synchronized/1: 56.


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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<67>,  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: 141.) and can be retrieved by calling the *note threaded_exit/1:
1e3. predicate.

The ‘threaded_call/2’ variant returns a threaded call identifier tag
that can be used with the *note threaded_exit/2: 1e3. and *note
threaded_cancel/1: 1e6. predicates.  Tags shall be regarded as opaque
terms; users shall not rely on its type.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<32>,  Next: Errors<33>,  Prev: Description<67>,  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.27.0.info,  Node: Errors<33>,  Next: Examples<68>,  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.27.0.info,  Node: Examples<68>,  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: 1e3, *note threaded_ignore/1: 1e9, *note
threaded_once/1-2: 1e4, *note threaded_peek/1-2: 1e5, *note
threaded_cancel/1: 1e6, *note threaded/1: 1dd, *note synchronized/1: 56.


File: TheLogtalkHandbook-3.27.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<68>.
* Modes and number of proofs: Modes and number of proofs<33>.
* Errors: Errors<34>.
* Examples: Examples<69>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<68>,  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: 141.).

The ‘threaded_once/2’ variant returns a threaded call identifier tag
that can be used with the *note threaded_exit/2: 1e3. and *note
threaded_cancel/1: 1e6. predicates.  Tags shall be regarded as opaque
terms; users shall not rely on its type.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<33>,  Next: Errors<34>,  Prev: Description<68>,  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.27.0.info,  Node: Errors<34>,  Next: Examples<69>,  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.27.0.info,  Node: Examples<69>,  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: 1e2, *note threaded_exit/1-2: 1e3, *note
threaded_ignore/1: 1e9, *note threaded_peek/1-2: 1e5, *note
threaded_cancel/1: 1e6, *note threaded/1: 1dd, *note synchronized/1: 56.


File: TheLogtalkHandbook-3.27.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<69>.
* Modes and number of proofs: Modes and number of proofs<34>.
* Errors: Errors<35>.
* Examples: Examples<70>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<69>,  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: 141.).


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<34>,  Next: Errors<35>,  Prev: Description<69>,  Up: threaded_ignore/1

2.4.7.18 Modes and number of proofs
...................................

     threaded_ignore(@callable) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<35>,  Next: Examples<70>,  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.27.0.info,  Node: Examples<70>,  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: 1e2, *note threaded_exit/1-2: 1e3, *note
threaded_once/1-2: 1e4, *note threaded_peek/1-2: 1e5, *note threaded/1:
1dd, *note synchronized/1: 56.


File: TheLogtalkHandbook-3.27.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<70>.
* Modes and number of proofs: Modes and number of proofs<35>.
* Errors: Errors<36>.
* Examples: Examples<71>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<70>,  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: 141. 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: 1e2. or *note threaded_once/1:
1e4. 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: 1e2. and *note
threaded_once/2: 1e4. predicates.  Tags shall be regarded as an opaque
term; users shall not rely on its type.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<35>,  Next: Errors<36>,  Prev: Description<70>,  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.27.0.info,  Node: Errors<36>,  Next: Examples<71>,  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.27.0.info,  Node: Examples<71>,  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: 1e2, *note threaded_ignore/1: 1e9, *note
threaded_once/1-2: 1e4, *note threaded_peek/1-2: 1e5, *note
threaded_cancel/1: 1e6, *note threaded/1: 1dd.


File: TheLogtalkHandbook-3.27.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<71>.
* Modes and number of proofs: Modes and number of proofs<36>.
* Errors: Errors<37>.
* Examples: Examples<72>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<71>,  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: 1e2. or *note threaded_once/1:
1e4. 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: 1e2. and *note
threaded_once/2: 1e4. predicates.  Tags shall be regarded as an opaque
term; users shall not rely on its type.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<36>,  Next: Errors<37>,  Prev: Description<71>,  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.27.0.info,  Node: Errors<37>,  Next: Examples<72>,  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.27.0.info,  Node: Examples<72>,  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: 1e2, *note threaded_exit/1-2: 1e3, *note
threaded_ignore/1: 1e9, *note threaded_once/1-2: 1e4, *note
threaded_cancel/1: 1e6, *note threaded/1: 1dd.


File: TheLogtalkHandbook-3.27.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<72>.
* Modes and number of proofs: Modes and number of proofs<37>.
* Errors: Errors<38>.
* Examples: Examples<73>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<72>,  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: 1e2. and *note
threaded_once/2: 1e4. predicates.  Tags shall be regarded as an opaque
term; users shall not rely on its type.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<37>,  Next: Errors<38>,  Prev: Description<72>,  Up: threaded_cancel/1

2.4.7.33 Modes and number of proofs
...................................

     threaded_cancel(+nonvar) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<38>,  Next: Examples<73>,  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.27.0.info,  Node: Examples<73>,  Prev: Errors<38>,  Up: threaded_cancel/1

2.4.7.35 Examples
.................

(none)

See also
........

*note threaded_call/1-2: 1e2, *note threaded_exit/1-2: 1e3, *note
threaded_ignore/1: 1e9, *note threaded_once/1-2: 1e4, *note threaded/1:
1dd.


File: TheLogtalkHandbook-3.27.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<73>.
* Modes and number of proofs: Modes and number of proofs<38>.
* Errors: Errors<39>.
* Examples: Examples<74>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<73>,  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: 141.) containing the calls to the *note threaded_notify/1:
1ee. 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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<38>,  Next: Errors<39>,  Prev: Description<73>,  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.27.0.info,  Node: Errors<39>,  Next: Examples<74>,  Prev: Modes and number of proofs<38>,  Up: threaded_wait/1

2.4.7.39 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<74>,  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: 1ee.


File: TheLogtalkHandbook-3.27.0.info,  Node: threaded_notify/1,  Prev: threaded_wait/1,  Up: Multi-threading

2.4.7.41 threaded_notify/1
..........................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<74>,  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: 141.) containing the calls to the *note threaded_wait/1: 1ed.
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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<39>,  Next: Errors<40>,  Prev: Description<74>,  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.27.0.info,  Node: Errors<40>,  Next: Examples<75>,  Prev: Modes and number of proofs<39>,  Up: threaded_notify/1

2.4.7.44 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<75>,  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: 1ed.


File: TheLogtalkHandbook-3.27.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.27.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<75>.
* Modes and number of proofs: Modes and number of proofs<40>.
* Errors: Errors<41>.
* Examples: Examples<76>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<75>,  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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<40>,  Next: Errors<41>,  Prev: Description<75>,  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.27.0.info,  Node: Errors<41>,  Next: Examples<76>,  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.27.0.info,  Node: Examples<76>,  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: 1f4, *note threaded_engine_self/1: 53f,
*note threaded_engine/1: 540, *note threaded_engine_next/2: 1f2, *note
threaded_engine_next_reified/2: 1f3.


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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<76>,  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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<41>,  Next: Errors<42>,  Prev: Description<76>,  Up: threaded_engine_destroy/1

2.4.8.8 Modes and number of proofs
..................................

     threaded_engine_destroy(@nonvar) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<42>,  Next: Examples<77>,  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.27.0.info,  Node: Examples<77>,  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: 1f1, *note threaded_engine_self/1: 53f,
*note threaded_engine/1: 540.


File: TheLogtalkHandbook-3.27.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<77>.
* Modes and number of proofs: Modes and number of proofs<42>.
* Errors: Errors<43>.
* Examples: Examples<78>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<77>,  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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<42>,  Next: Errors<43>,  Prev: Description<77>,  Up: threaded_engine/1

2.4.8.13 Modes and number of proofs
...................................

     threaded_engine(?nonvar) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<43>,  Next: Examples<78>,  Prev: Modes and number of proofs<42>,  Up: threaded_engine/1

2.4.8.14 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<78>,  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: 1f1, *note threaded_engine_self/1: 53f,
*note threaded_engine_destroy/1: 1f4.


File: TheLogtalkHandbook-3.27.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<78>.
* Modes and number of proofs: Modes and number of proofs<43>.
* Errors: Errors<44>.
* Examples: Examples<79>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<78>,  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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<43>,  Next: Errors<44>,  Prev: Description<78>,  Up: threaded_engine_self/1

2.4.8.18 Modes and number of proofs
...................................

     threaded_engine_self(?nonvar) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<44>,  Next: Examples<79>,  Prev: Modes and number of proofs<43>,  Up: threaded_engine_self/1

2.4.8.19 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<79>,  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: 1f1, *note threaded_engine_destroy/1:
1f4, *note threaded_engine/1: 540.


File: TheLogtalkHandbook-3.27.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<79>.
* Modes and number of proofs: Modes and number of proofs<44>.
* Errors: Errors<45>.
* Examples: Examples<80>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<79>,  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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<44>,  Next: Errors<45>,  Prev: Description<79>,  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.27.0.info,  Node: Errors<45>,  Next: Examples<80>,  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.27.0.info,  Node: Examples<80>,  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: 1f1, *note
threaded_engine_next_reified/2: 1f3, *note threaded_engine_yield/1: 1f7.


File: TheLogtalkHandbook-3.27.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<80>.
* Modes and number of proofs: Modes and number of proofs<45>.
* Errors: Errors<46>.
* Examples: Examples<81>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<80>,  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)’.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<45>,  Next: Errors<46>,  Prev: Description<80>,  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.27.0.info,  Node: Errors<46>,  Next: Examples<81>,  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.27.0.info,  Node: Examples<81>,  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: 1f1, *note threaded_engine_next/2: 1f2,
*note threaded_engine_yield/1: 1f7.


File: TheLogtalkHandbook-3.27.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<81>.
* Modes and number of proofs: Modes and number of proofs<46>.
* Errors: Errors<47>.
* Examples: Examples<82>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<81>,  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]))’.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<46>,  Next: Errors<47>,  Prev: Description<81>,  Up: threaded_engine_yield/1

2.4.8.33 Modes and number of proofs
...................................

     threaded_engine_yield(@term) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<47>,  Next: Examples<82>,  Prev: Modes and number of proofs<46>,  Up: threaded_engine_yield/1

2.4.8.34 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<82>,  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: 1f1, *note threaded_engine_next/2: 1f2,
*note threaded_engine_next_reified/2: 1f3.


File: TheLogtalkHandbook-3.27.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<82>.
* Modes and number of proofs: Modes and number of proofs<47>.
* Errors: Errors<48>.
* Examples: Examples<83>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<82>,  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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<47>,  Next: Errors<48>,  Prev: Description<82>,  Up: threaded_engine_post/2

2.4.8.38 Modes and number of proofs
...................................

     threaded_engine_post(@nonvar, @term) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<48>,  Next: Examples<83>,  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.27.0.info,  Node: Examples<83>,  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: 1f5.


File: TheLogtalkHandbook-3.27.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<83>.
* Modes and number of proofs: Modes and number of proofs<48>.
* Errors: Errors<49>.
* Examples: Examples<84>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<83>,  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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<48>,  Next: Errors<49>,  Prev: Description<83>,  Up: threaded_engine_fetch/1

2.4.8.43 Modes and number of proofs
...................................

     threaded_engine_fetch(?term) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<49>,  Next: Examples<84>,  Prev: Modes and number of proofs<48>,  Up: threaded_engine_fetch/1

2.4.8.44 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<84>,  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: 1f6.


File: TheLogtalkHandbook-3.27.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.27.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<84>.
* Modes and number of proofs: Modes and number of proofs<49>.
* Errors: Errors<50>.
* Examples: Examples<85>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<84>,  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: 577. 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: ad.  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.

When this predicate is called from the top-level, 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 when errors are found during
compilation of a source file.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<49>,  Next: Errors<50>,  Prev: Description<84>,  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.27.0.info,  Node: Errors<50>,  Next: Examples<85>,  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: 
          ‘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.27.0.info,  Node: Examples<85>,  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: 261, *note logtalk_load/1: 253, *note
logtalk_load/2: 25a, *note logtalk_make/0: 254, *note logtalk_make/1:
256, *note logtalk_library_path/2: 25d.


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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<85>,  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: 577. 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: ad.
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: 201. section in the
User Manual.

When this predicate is called from the top-level, 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:
281. flag is passed).

Note that only the errors related to problems in the predicate argument
are listed below.  This predicate fails when errors are found during
compilation of a source file.

     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: 18e, the flags only apply to the
     loader file itself.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<50>,  Next: Errors<51>,  Prev: Description<85>,  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.27.0.info,  Node: Errors<51>,  Next: Examples<86>,  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.27.0.info,  Node: Examples<86>,  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 supressed:
     | ?- logtalk_compile(file_system, [portability(silent)]).

See also
........

*note logtalk_compile/1: 252, *note logtalk_load/1: 253, *note
logtalk_load/2: 25a, *note logtalk_make/0: 254, *note logtalk_make/1:
256, *note logtalk_library_path/2: 25d.


File: TheLogtalkHandbook-3.27.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<86>.
* Modes and number of proofs: Modes and number of proofs<51>.
* Errors: Errors<52>.
* Examples: Examples<87>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<86>,  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: 577. 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: ad.  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.

When this predicate is called from the top-level, 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 when errors are found during
compilation of a source file.

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.27.0.info,  Node: Modes and number of proofs<51>,  Next: Errors<52>,  Prev: Description<86>,  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.27.0.info,  Node: Errors<52>,  Next: Examples<87>,  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.27.0.info,  Node: Examples<87>,  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: 252, *note logtalk_compile/2: 261, *note
logtalk_load/2: 25a, *note logtalk_make/0: 254, *note logtalk_make/1:
256, *note logtalk_library_path/2: 25d.


File: TheLogtalkHandbook-3.27.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<87>.
* Modes and number of proofs: Modes and number of proofs<52>.
* Errors: Errors<53>.
* Examples: Examples<88>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<87>,  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: 577. 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: ad.  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: 201.
section in the User Manual.

When this predicate is called from the top-level, 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:
281. flag is passed).

Note that only the errors related to problems in the predicate argument
are listed below.  This predicate fails when errors are found during
compilation of a source file.

     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: 18e, the flags only apply to the
     loader file itself and not to the files loaded by it.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<52>,  Next: Errors<53>,  Prev: Description<87>,  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.27.0.info,  Node: Errors<53>,  Next: Examples<88>,  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.27.0.info,  Node: Examples<88>,  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 supressed:
     | ?- logtalk_load(file_system, [portability(silent)]).

See also
........

*note logtalk_compile/1: 252, *note logtalk_compile/2: 261, *note
logtalk_load/1: 253, *note logtalk_make/0: 254, *note logtalk_make/1:
256, *note logtalk_library_path/2: 25d.


File: TheLogtalkHandbook-3.27.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<88>.
* Modes and number of proofs: Modes and number of proofs<53>.
* Errors: Errors<54>.
* Examples: Examples<89>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<88>,  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: 253. and *note logtalk_load/2: 25a. 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: 255. or *note optimize: 105. 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: 92. directive).

Depending on the *note backend Prolog compiler: 32, the shortcut ‘{*}’
may be used in alternative.  Check the *note adapter files: 11d. 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: 590. multifile and dynamic hook
predicate using the argument ‘all’.  The additional user defined actions
are run after the default one.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<53>,  Next: Errors<54>,  Prev: Description<88>,  Up: logtalk_make/0

2.4.9.23 Modes and number of proofs
...................................

     logtalk_make - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<54>,  Next: Examples<89>,  Prev: Modes and number of proofs<53>,  Up: logtalk_make/0

2.4.9.24 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<89>,  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: 252, *note logtalk_compile/2: 261, *note
logtalk_load/1: 253, *note logtalk_load/2: 25a, *note logtalk_make/1:
256, *note logtalk_make_target_action/1: 590.


File: TheLogtalkHandbook-3.27.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<89>.
* Modes and number of proofs: Modes and number of proofs<54>.
* Errors: Errors<55>.
* Examples: Examples<90>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<89>,  Next: Modes and number of proofs<54>,  Up: logtalk_make/1

2.4.9.27 Description
....................

     logtalk_make(Target)

Runs a make target.  Fails of 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: 255. and *note optimize: 105.
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: 253. and *note logtalk_load/2: 25a. 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: 255. or *note optimize: 105. 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: 92. directive).

When using the ‘check’ or ‘circular’ targets, be sure to compile your
source files with the *note source_data: a6. flag turned on for complete
and detailed reports.

When using the ‘check’ target, 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.

The ‘documentation’ target requires the ‘doclet’ tool and a single
`doclet' object to be loaded.  See the ‘doclet’ tool 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: 11d. 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 ‘logtalk_make_target_action(Target)’ where
‘Target’ is one of the targets listed above.  The additional user
defined actions are run after the default ones.

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

   (1) https://logtalk.org/library/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<54>,  Next: Errors<55>,  Prev: Description<89>,  Up: logtalk_make/1

2.4.9.28 Modes and number of proofs
...................................

     logtalk_make(+atom) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<55>,  Next: Examples<90>,  Prev: Modes and number of proofs<54>,  Up: logtalk_make/1

2.4.9.29 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<90>,  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: 252, *note logtalk_compile/2: 261, *note
logtalk_load/1: 253, *note logtalk_load/2: 25a, *note logtalk_make/0:
254, *note logtalk_make_target_action/1: 590.


File: TheLogtalkHandbook-3.27.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<90>.
* Modes and number of proofs: Modes and number of proofs<55>.
* Errors: Errors<56>.
* Examples: Examples<91>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<90>,  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: 256. targets.  The user defined actions
are run after the default ones using a failure driven loop.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<55>,  Next: Errors<56>,  Prev: Description<90>,  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.27.0.info,  Node: Errors<56>,  Next: Examples<91>,  Prev: Modes and number of proofs<55>,  Up: logtalk_make_target_action/1

2.4.9.34 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<91>,  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: 256, *note logtalk_make/0: 254.


File: TheLogtalkHandbook-3.27.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<91>.
* Modes and number of proofs: Modes and number of proofs<56>.
* Errors: Errors<57>.
* Examples: Examples<92>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<91>,  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: 51. 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 (‘'/'’).

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: 2a4. predicate with the ‘directory’ key and
using the returned value to define the ‘logtalk_library_path/2’
predicate.  On a settings file, simply use an *note initialization/1:
88. 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: 5a3. 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: ab. 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) 
https://logtalk.org/library/logtalk_0.html#logtalk-0-expand-library-path-2


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<56>,  Next: Errors<57>,  Prev: Description<91>,  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.27.0.info,  Node: Errors<57>,  Next: Examples<92>,  Prev: Modes and number of proofs<56>,  Up: logtalk_library_path/2

2.4.9.39 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<92>,  Prev: Errors<57>,  Up: logtalk_library_path/2

2.4.9.40 Examples
.................

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

See also
........

*note logtalk_compile/1: 252, *note logtalk_compile/2: 261, *note
logtalk_load/1: 253, *note logtalk_load/2: 25a.


File: TheLogtalkHandbook-3.27.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<92>.
* Modes and number of proofs: Modes and number of proofs<57>.
* Errors: Errors<58>.
* Examples: Examples<93>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<92>,  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’)

   * ‘variable_names’ - the variable names of the term being compiled
     (‘[Name1=Variable1, ...]’)

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.

The ‘logtalk_load_context/2’ predicate can also be called *note
initialization/1: 88. directives in a source file.  A common scenario is
to use the ‘directory’ key to define *note library aliases: 5aa.

Currently, any variables in the values of the ‘term’ and
‘variable_names’ keys are not shared with, respectively, the term and
goal arguments of the *note term_expansion/2: d3. and *note
goal_expansion/2: d4. methods.

Using the ‘variable_names’ key requires 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 those 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.27.0.info,  Node: Modes and number of proofs<57>,  Next: Errors<58>,  Prev: Description<92>,  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.27.0.info,  Node: Errors<58>,  Next: Examples<93>,  Prev: Modes and number of proofs<57>,  Up: logtalk_load_context/2

2.4.9.44 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<93>,  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: d3, *note goal_expansion/2: d4.


File: TheLogtalkHandbook-3.27.0.info,  Node: Flags,  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.27.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<93>.
* Modes and number of proofs: Modes and number of proofs<58>.
* Errors: Errors<59>.
* Examples: Examples<94>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<93>,  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: 201. section in the User Manual.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<58>,  Next: Errors<59>,  Prev: Description<93>,  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.27.0.info,  Node: Errors<59>,  Next: Examples<94>,  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.27.0.info,  Node: Examples<94>,  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: 284, *note set_logtalk_flag/2: 259.


File: TheLogtalkHandbook-3.27.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<94>.
* Modes and number of proofs: Modes and number of proofs<59>.
* Errors: Errors<60>.
* Examples: Examples<95>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<94>,  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: 263. 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: 88. directive.
For a description of the predefined compiler flags, please see the *note
Compiler flags: 201. section in the User Manual.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<59>,  Next: Errors<60>,  Prev: Description<94>,  Up: set_logtalk_flag/2<2>

2.4.10.8 Modes and number of proofs
...................................

     set_logtalk_flag(+atom, +nonvar) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<60>,  Next: Examples<95>,  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.27.0.info,  Node: Examples<95>,  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: 284, *note current_logtalk_flag/2: 262.


File: TheLogtalkHandbook-3.27.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<95>.
* Modes and number of proofs: Modes and number of proofs<60>.
* Errors: Errors<61>.
* Examples: Examples<96>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<95>,  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: 262. and *note
set_logtalk_flag/2: 259. built-in predicates.  For a description of the
predefined compiler flags, please see the *note Compiler flags: 201.
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.27.0.info,  Node: Modes and number of proofs<60>,  Next: Errors<61>,  Prev: Description<95>,  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.27.0.info,  Node: Errors<61>,  Next: Examples<96>,  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 a Type term 
          type_error(Type, Value) 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<96>,  Prev: Errors<61>,  Up: create_logtalk_flag/3

2.4.10.15 Examples
..................

     % create a new booloean flag with default value set to false:
     | ?- create_logtalk_flag(pretty_print_blobs, false, []).

See also
........

*note current_logtalk_flag/2: 262, *note set_logtalk_flag/2: 259.


File: TheLogtalkHandbook-3.27.0.info,  Node: Built-in methods,  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.27.0.info,  Node: Execution context,  Next: Reflection<2>,  Up: Built-in methods

2.5.1 Execution context
-----------------------

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: context/1,  Next: parameter/2,  Up: Execution context

2.5.1.1 context/1
.................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<96>,  Next: Modes and number of proofs<61>,  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) 
https://logtalk.org/library/logtalk_0.html#logtalk-0-execution-context-7


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<61>,  Next: Errors<62>,  Prev: Description<96>,  Up: context/1

2.5.1.3 Modes and number of proofs
..................................

     context(--callable) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<62>,  Next: Examples<97>,  Prev: Modes and number of proofs<61>,  Up: context/1

2.5.1.4 Errors
..............

     Context is not a variable: 
          ‘type_error(var, Context)’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<97>,  Prev: Errors<62>,  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: 7b, *note self/1: 49, *note sender/1: 152, *note
this/1: 4a.


File: TheLogtalkHandbook-3.27.0.info,  Node: parameter/2,  Next: self/1,  Prev: context/1,  Up: Execution context

2.5.1.6 parameter/2
...................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<97>,  Next: Modes and number of proofs<62>,  Up: parameter/2

2.5.1.7 Description
...................

     parameter(Number, Term)

Used in *note parametric objects: 5d1. (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 entity clauses.  Parameter variables
allows us to abstract parameter positions thus simplifying code
maintenance.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<62>,  Next: Errors<63>,  Prev: Description<97>,  Up: parameter/2

2.5.1.8 Modes and number of proofs
..................................

     parameter(+integer, ?term) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<63>,  Next: Examples<98>,  Prev: Modes and number of proofs<62>,  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.27.0.info,  Node: Examples<98>,  Prev: Errors<63>,  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: 153, *note self/1: 49, *note sender/1: 152, *note
this/1: 4a.


File: TheLogtalkHandbook-3.27.0.info,  Node: self/1,  Next: sender/1,  Prev: parameter/2,  Up: Execution context

2.5.1.11 self/1
...............

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<98>,  Next: Modes and number of proofs<63>,  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.27.0.info,  Node: Modes and number of proofs<63>,  Next: Errors<64>,  Prev: Description<98>,  Up: self/1

2.5.1.13 Modes and number of proofs
...................................

     self(?object_identifier) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<64>,  Next: Examples<99>,  Prev: Modes and number of proofs<63>,  Up: self/1

2.5.1.14 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<99>,  Prev: Errors<64>,  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: 153, *note parameter/2: 7b, *note sender/1: 152, *note
this/1: 4a.


File: TheLogtalkHandbook-3.27.0.info,  Node: sender/1,  Next: this/1,  Prev: self/1,  Up: Execution context

2.5.1.16 sender/1
.................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<99>,  Next: Modes and number of proofs<64>,  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.27.0.info,  Node: Modes and number of proofs<64>,  Next: Errors<65>,  Prev: Description<99>,  Up: sender/1

2.5.1.18 Modes and number of proofs
...................................

     sender(?object_identifier) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<65>,  Next: Examples<100>,  Prev: Modes and number of proofs<64>,  Up: sender/1

2.5.1.19 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<100>,  Prev: Errors<65>,  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: 153, *note parameter/2: 7b, *note self/1: 49, *note
this/1: 4a.


File: TheLogtalkHandbook-3.27.0.info,  Node: this/1,  Prev: sender/1,  Up: Execution context

2.5.1.21 this/1
...............

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<100>,  Next: Modes and number of proofs<65>,  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.27.0.info,  Node: Modes and number of proofs<65>,  Next: Errors<66>,  Prev: Description<100>,  Up: this/1

2.5.1.23 Modes and number of proofs
...................................

     this(?object_identifier) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<66>,  Next: Examples<101>,  Prev: Modes and number of proofs<65>,  Up: this/1

2.5.1.24 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<101>,  Prev: Errors<66>,  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: 153, *note parameter/2: 7b, *note self/1: 49, *note
sender/1: 152.


File: TheLogtalkHandbook-3.27.0.info,  Node: Reflection<2>,  Next: Database,  Prev: Execution context,  Up: Built-in methods

2.5.2 Reflection
----------------

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: current_op/3,  Next: current_predicate/1,  Up: Reflection<2>

2.5.2.1 current_op/3
....................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<101>,  Next: Modes and number of proofs<66>,  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.27.0.info,  Node: Modes and number of proofs<66>,  Next: Errors<67>,  Prev: Description<101>,  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.27.0.info,  Node: Errors<67>,  Next: Examples<102>,  Prev: Modes and number of proofs<66>,  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.27.0.info,  Node: Examples<102>,  Prev: Errors<67>,  Up: current_op/3

2.5.2.5 Examples
................

     To enumerate, by backtracking, the local operators or the operators visible in *note this: 141.: 
          ‘current_op(Priority, Specifier, Operator)’ 
     To enumerate, by backtracking, the public and protected operators visible in *note self: 4b.: 
          ‘::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: 111, *note predicate_property/2: 112, *note
op/3: 126.


File: TheLogtalkHandbook-3.27.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<102>.
* Modes and number of proofs: Modes and number of proofs<67>.
* Errors: Errors<68>.
* Examples: Examples<103>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<102>,  Next: Modes and number of proofs<67>,  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: 12a. and *note use_module/2:
16b. 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.27.0.info,  Node: Modes and number of proofs<67>,  Next: Errors<68>,  Prev: Description<102>,  Up: current_predicate/1

2.5.2.8 Modes and number of proofs
..................................

     current_predicate(?predicate_indicator) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<68>,  Next: Examples<103>,  Prev: Modes and number of proofs<67>,  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.27.0.info,  Node: Examples<103>,  Prev: Errors<68>,  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: 141.: 
          ‘current_predicate(Predicate)’ 
     To enumerate, by backtracking, the public and protected user predicates visible in *note self: 4b.: 
          ‘::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: 127, *note predicate_property/2: 112, *note uses/2:
12a, *note use_module/2: 16b.


File: TheLogtalkHandbook-3.27.0.info,  Node: predicate_property/2,  Prev: current_predicate/1,  Up: Reflection<2>

2.5.2.11 predicate_property/2
.............................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<103>,  Next: Modes and number of proofs<68>,  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 gramar section on *note predicate properties: 35f. and
described in the User Manual section on *note predicate properties: 181.

When ‘Predicate’ is ground at compile time and its predicate indicator
is listed in a *note uses/2: 12a. or *note use_module/2: 16b. 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.27.0.info,  Node: Modes and number of proofs<68>,  Next: Errors<69>,  Prev: Description<103>,  Up: predicate_property/2

2.5.2.13 Modes and number of proofs
...................................

     predicate_property(+callable, ?predicate_property) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<69>,  Next: Examples<104>,  Prev: Modes and number of proofs<68>,  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.27.0.info,  Node: Examples<104>,  Prev: Errors<69>,  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: 141.: 
          ‘predicate_property(Predicate, Property)’ 
     To enumerate, by backtracking, the properties of a public or protected predicate visible in *note self: 4b.: 
          ‘::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: 127, *note current_predicate/1: 111, *note uses/2:
12a, *note use_module/2: 16b.


File: TheLogtalkHandbook-3.27.0.info,  Node: Database,  Next: Meta-calls,  Prev: Reflection<2>,  Up: Built-in methods

2.5.3 Database
--------------

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: abolish/1,  Next: asserta/1,  Up: Database

2.5.3.1 abolish/1
.................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<104>,  Next: Modes and number of proofs<69>,  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: 166. or *note assertz/1:
167. built-in methods) can be abolished.

When the predicate indicator is declared in a *note uses/2: 12a. or
*note use_module/2: 16b. directive, the predicate is abolished in the
referenced object or module.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<69>,  Next: Errors<70>,  Prev: Description<104>,  Up: abolish/1

2.5.3.3 Modes and number of proofs
..................................

     abolish(@predicate_indicator) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<70>,  Next: Examples<105>,  Prev: Modes and number of proofs<69>,  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.27.0.info,  Node: Examples<105>,  Prev: Errors<70>,  Up: abolish/1

2.5.3.5 Examples
................

     To abolish a local dynamic predicate or a dynamic predicate in *note this: 141.: 
          ‘abolish(Predicate)’ 
     To abolish a public or protected dynamic predicate in *note self: 4b.: 
          ‘::abolish(Predicate)’ 
     To abolish a public dynamic predicate in an explicit object: 
          ‘Object::abolish(Predicate)’ 

See also
........

*note asserta/1: 166, *note assertz/1: 167, *note clause/2: 168, *note
retract/1: 169, *note retractall/1: 16a. *note dynamic/0: 8b, *note
dynamic/1: 123, *note uses/2: 12a, *note use_module/2: 16b.


File: TheLogtalkHandbook-3.27.0.info,  Node: asserta/1,  Next: assertz/1,  Prev: abolish/1,  Up: Database

2.5.3.6 asserta/1
.................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<105>,  Next: Modes and number of proofs<70>,  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: 277.
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:
12a. or *note use_module/2: 16b. directive, the clause is asserted in
the referenced object or module.

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: 141.  This allows easy initialization of
dynamically created objects when writing constructors.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<70>,  Next: Errors<71>,  Prev: Description<105>,  Up: asserta/1

2.5.3.8 Modes and number of proofs
..................................

     asserta(+clause) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<71>,  Next: Examples<106>,  Prev: Modes and number of proofs<70>,  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.27.0.info,  Node: Examples<106>,  Prev: Errors<71>,  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: 141.: 
          ‘asserta(Clause)’ 
     To assert a clause as the first one for any public or protected dynamic predicate in *note self: 4b.: 
          ‘::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: 165, *note assertz/1: 167, *note clause/2: 168, *note
retract/1: 169, *note retractall/1: 16a. *note dynamic/0: 8b, *note
dynamic/1: 123, *note uses/2: 12a, *note use_module/2: 16b.


File: TheLogtalkHandbook-3.27.0.info,  Node: assertz/1,  Next: clause/2,  Prev: asserta/1,  Up: Database

2.5.3.11 assertz/1
..................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<106>,  Next: Modes and number of proofs<71>,  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: 277.
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:
12a. or *note use_module/2: 16b. directive, the clause is asserted in
the referenced object or module.

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: 141.  This allows easy initialization of
dynamically created objects when writing constructors.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<71>,  Next: Errors<72>,  Prev: Description<106>,  Up: assertz/1

2.5.3.13 Modes and number of proofs
...................................

     assertz(+clause) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<72>,  Next: Examples<107>,  Prev: Modes and number of proofs<71>,  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.27.0.info,  Node: Examples<107>,  Prev: Errors<72>,  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: 141.: 
          ‘assertz(Clause)’ 
     To assert a clause as the last one for any public or protected dynamic predicate in *note self: 4b.: 
          ‘::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: 165, *note asserta/1: 166, *note clause/2: 168, *note
retract/1: 169, *note retractall/1: 16a. *note dynamic/0: 8b, *note
dynamic/1: 123, *note uses/2: 12a, *note use_module/2: 16b.


File: TheLogtalkHandbook-3.27.0.info,  Node: clause/2,  Next: retract/1,  Prev: assertz/1,  Up: Database

2.5.3.16 clause/2
.................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<107>,  Next: Modes and number of proofs<72>,  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:
12a. or *note use_module/2: 16b. directive, the predicate enumerates the
clauses in the referenced object or module.

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<72>,  Next: Errors<73>,  Prev: Description<107>,  Up: clause/2

2.5.3.18 Modes and number of proofs
...................................

     clause(+callable, ?body) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<73>,  Next: Examples<108>,  Prev: Modes and number of proofs<72>,  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.27.0.info,  Node: Examples<108>,  Prev: Errors<73>,  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: 141.: 
          ‘clause(Head, Body)’ 
     To retrieve a matching clause of a public or protected dynamic predicate in *note self: 4b.: 
          ‘::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: 165, *note asserta/1: 166, *note assertz/1: 167, *note
retract/1: 169, *note retractall/1: 16a. *note dynamic/0: 8b, *note
dynamic/1: 123, *note uses/2: 12a, *note use_module/2: 16b.


File: TheLogtalkHandbook-3.27.0.info,  Node: retract/1,  Next: retractall/1,  Prev: clause/2,  Up: Database

2.5.3.21 retract/1
..................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<108>,  Next: Modes and number of proofs<73>,  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:
12a. or *note use_module/2: 16b. directive, the clause is retracted in
the referenced object or module.

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<73>,  Next: Errors<74>,  Prev: Description<108>,  Up: retract/1

2.5.3.23 Modes and number of proofs
...................................

     retract(+clause) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<74>,  Next: Examples<109>,  Prev: Modes and number of proofs<73>,  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.27.0.info,  Node: Examples<109>,  Prev: Errors<74>,  Up: retract/1

2.5.3.25 Examples
.................

     To retract a matching clause of a dynamic predicate in *note this: 141.: 
          ‘retract(Clause)’ 
     To retract a matching clause of a public or protected dynamic predicate in *note self: 4b.: 
          ‘::retract(Clause)’ 
     To retract a matching clause of a public dynamic predicate in an explicit object: 
          ‘Object::retract(Clause)’ 

See also
........

*note abolish/1: 165, *note asserta/1: 166, *note assertz/1: 167, *note
clause/2: 168, *note retractall/1: 16a, *note dynamic/0: 8b, *note
dynamic/1: 123, *note uses/2: 12a, *note use_module/2: 16b.


File: TheLogtalkHandbook-3.27.0.info,  Node: retractall/1,  Prev: retract/1,  Up: Database

2.5.3.26 retractall/1
.....................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<109>,  Next: Modes and number of proofs<74>,  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:
12a. or *note use_module/2: 16b. directive, the clauses are retracted in
the referenced object or module.

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<74>,  Next: Errors<75>,  Prev: Description<109>,  Up: retractall/1

2.5.3.28 Modes and number of proofs
...................................

     retractall(@callable) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<75>,  Next: Examples<110>,  Prev: Modes and number of proofs<74>,  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.27.0.info,  Node: Examples<110>,  Prev: Errors<75>,  Up: retractall/1

2.5.3.30 Examples
.................

     To retract all clauses with a matching head of a dynamic predicate in *note this: 141.: 
          ‘retractall(Head)’ 
     To retract all clauses with a matching head of a public or protected dynamic predicate in *note self: 4b.: 
          ‘::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: 165, *note asserta/1: 166, *note assertz/1: 167, *note
clause/2: 168, *note retract/1: 169, *note dynamic/0: 8b, *note
dynamic/1: 123, *note uses/2: 12a, *note use_module/2: 16b.


File: TheLogtalkHandbook-3.27.0.info,  Node: Meta-calls,  Next: Error handling<2>,  Prev: Database,  Up: Built-in methods

2.5.4 Meta-calls
----------------

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: call/1-N,  Next: ignore/1,  Up: Meta-calls

2.5.4.1 call/1-N
................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<110>,  Next: Modes and number of proofs<75>,  Up: call/1-N

2.5.4.2 Description
...................

     call(Goal)
     call(Closure, Arg1, ...)

Calls a goal, which might be constructed by appending additional
arguments to a closure.  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.27.0.info,  Node: Modes and number of proofs<75>,  Next: Errors<76>,  Prev: Description<110>,  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.27.0.info,  Node: Errors<76>,  Next: Examples<111>,  Prev: Modes and number of proofs<75>,  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.27.0.info,  Node: Examples<111>,  Prev: Errors<76>,  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: 4b.: 
          ‘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: 16f, *note once/1: 170, *note \+/1: 171.


File: TheLogtalkHandbook-3.27.0.info,  Node: ignore/1,  Next: once/1,  Prev: call/1-N,  Up: Meta-calls

2.5.4.6 ignore/1
................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<111>,  Next: Modes and number of proofs<76>,  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.27.0.info,  Node: Modes and number of proofs<76>,  Next: Errors<77>,  Prev: Description<111>,  Up: ignore/1

2.5.4.8 Modes and number of proofs
..................................

     ignore(+callable) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<77>,  Next: Examples<112>,  Prev: Modes and number of proofs<76>,  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.27.0.info,  Node: Examples<112>,  Prev: Errors<77>,  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: 4b.: 
          ‘ignore(::Goal)’ 
     To send a message succeeding even if it fails to an explicit object: 
          ‘ignore(Object::Goal)’ 

See also
........

*note call/1-N: 144, *note once/1: 170, *note \+/1: 171.


File: TheLogtalkHandbook-3.27.0.info,  Node: once/1,  Next: \+/1,  Prev: ignore/1,  Up: Meta-calls

2.5.4.11 once/1
...............

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<112>,  Next: Modes and number of proofs<77>,  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.27.0.info,  Node: Modes and number of proofs<77>,  Next: Errors<78>,  Prev: Description<112>,  Up: once/1

2.5.4.13 Modes and number of proofs
...................................

     once(+callable) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<78>,  Next: Examples<113>,  Prev: Modes and number of proofs<77>,  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.27.0.info,  Node: Examples<113>,  Prev: Errors<78>,  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: 4b.: 
          ‘once(::Goal)’ 
     To send a goal as a non-backtracable message to an explicit object: 
          ‘once(Object::Goal)’ 

See also
........

*note call/1-N: 144, *note ignore/1: 16f, *note \+/1: 171.


File: TheLogtalkHandbook-3.27.0.info,  Node: \+/1,  Prev: once/1,  Up: Meta-calls

2.5.4.16 \+/1
.............

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<113>,  Next: Modes and number of proofs<78>,  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.27.0.info,  Node: Modes and number of proofs<78>,  Next: Errors<79>,  Prev: Description<113>,  Up: \+/1

2.5.4.18 Modes and number of proofs
...................................

     \+ +callable - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<79>,  Next: Examples<114>,  Prev: Modes and number of proofs<78>,  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.27.0.info,  Node: Examples<114>,  Prev: Errors<79>,  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: 4b.: 
          ‘\+ ::Goal’ 
     Not-provable goal sent as a message to an explicit object: 
          ‘\+ Object::Goal’ 

See also
........

*note call/1-N: 144, *note ignore/1: 16f, *note once/1: 170.


File: TheLogtalkHandbook-3.27.0.info,  Node: Error handling<2>,  Next: All solutions,  Prev: Meta-calls,  Up: Built-in methods

2.5.5 Error handling
--------------------

* Menu:

* catch/3::
* throw/1::
* instantiation_error/0::
* 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.27.0.info,  Node: catch/3,  Next: throw/1,  Up: Error handling<2>

2.5.5.1 catch/3
...............

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<114>,  Next: Modes and number of proofs<79>,  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.27.0.info,  Node: Modes and number of proofs<79>,  Next: Errors<80>,  Prev: Description<114>,  Up: catch/3

2.5.5.3 Modes and number of proofs
..................................

     catch(?callable, ?term, ?term) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<80>,  Next: Examples<115>,  Prev: Modes and number of proofs<79>,  Up: catch/3

2.5.5.4 Errors
..............

     Goal is a variable: 
          ‘instantiation_error’ 
     Goal is neither a variable nor a callable term: 
          ‘type_error(callable, Goal)’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<115>,  Prev: Errors<80>,  Up: catch/3

2.5.5.5 Examples
................

(none)

See also
........

*note throw/1: 157, *note context/1: 153, *note instantiation_error/0:
158, *note type_error/2: 159, *note domain_error/2: 15a, *note
existence_error/2: 15b, *note permission_error/3: 15c, *note
evaluation_error/1: 15e, *note representation_error/1: 15d. *note
resource_error/1: 15f, *note syntax_error/1: 160, *note system_error/0:
161.


File: TheLogtalkHandbook-3.27.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<115>.
* Modes and number of proofs: Modes and number of proofs<80>.
* Errors: Errors<81>.
* Examples: Examples<116>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<115>,  Next: Modes and number of proofs<80>,  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.27.0.info,  Node: Modes and number of proofs<80>,  Next: Errors<81>,  Prev: Description<115>,  Up: throw/1

2.5.5.8 Modes and number of proofs
..................................

     throw(+nonvar) - error


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<81>,  Next: Examples<116>,  Prev: Modes and number of proofs<80>,  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: 156.: 
          ‘system_error’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<116>,  Prev: Errors<81>,  Up: throw/1

2.5.5.10 Examples
.................

(none)

See also
........

*note catch/3: 156, *note context/1: 153, *note instantiation_error/0:
158, *note type_error/2: 159, *note domain_error/2: 15a, *note
existence_error/2: 15b, *note permission_error/3: 15c, *note
evaluation_error/1: 15e, *note representation_error/1: 15d. *note
resource_error/1: 15f, *note syntax_error/1: 160, *note system_error/0:
161.


File: TheLogtalkHandbook-3.27.0.info,  Node: instantiation_error/0,  Next: type_error/2,  Prev: throw/1,  Up: Error handling<2>

2.5.5.11 instantiation_error/0
..............................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<116>,  Next: Modes and number of proofs<81>,  Up: instantiation_error/0

2.5.5.12 Description
....................

     instantiation_error

Throws an instantiation error.  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.27.0.info,  Node: Modes and number of proofs<81>,  Next: Errors<82>,  Prev: Description<116>,  Up: instantiation_error/0

2.5.5.13 Modes and number of proofs
...................................

     instantiation_error - error


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<82>,  Next: Examples<117>,  Prev: Modes and number of proofs<81>,  Up: instantiation_error/0

2.5.5.14 Errors
...............

     When called: 
          ‘instantiation_error’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<117>,  Prev: Errors<82>,  Up: instantiation_error/0

2.5.5.15 Examples
.................

     ...,
     var(Handler),
     instantiation_error.

See also
........

*note catch/3: 156, *note throw/1: 157, *note context/1: 153, *note
type_error/2: 159, *note domain_error/2: 15a, *note existence_error/2:
15b, *note permission_error/3: 15c, *note representation_error/1: 15d,
*note evaluation_error/1: 15e, *note resource_error/1: 15f, *note
syntax_error/1: 160, *note system_error/0: 161.


File: TheLogtalkHandbook-3.27.0.info,  Node: type_error/2,  Next: domain_error/2,  Prev: instantiation_error/0,  Up: Error handling<2>

2.5.5.16 type_error/2
.....................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<117>,  Next: Modes and number of proofs<82>,  Up: type_error/2

2.5.5.17 Description
....................

     type_error(Type, Culprit)

Throws a type error.  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(type_error(Type,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<82>,  Next: Errors<83>,  Prev: Description<117>,  Up: type_error/2

2.5.5.18 Modes and number of proofs
...................................

     type_error(@nonvar, @term) - error


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<83>,  Next: Examples<118>,  Prev: Modes and number of proofs<82>,  Up: type_error/2

2.5.5.19 Errors
...............

     When called: 
          ‘type_error(Type, Culprit)’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<118>,  Prev: Errors<83>,  Up: type_error/2

2.5.5.20 Examples
.................

     ...,
     \+ atom(Name),
     type_error(atom, Name).

See also
........

*note catch/3: 156, *note throw/1: 157, *note context/1: 153, *note
instantiation_error/0: 158, *note domain_error/2: 15a, *note
existence_error/2: 15b, *note permission_error/3: 15c, *note
representation_error/1: 15d. *note evaluation_error/1: 15e, *note
resource_error/1: 15f, *note syntax_error/1: 160, *note system_error/0:
161,


File: TheLogtalkHandbook-3.27.0.info,  Node: domain_error/2,  Next: existence_error/2,  Prev: type_error/2,  Up: Error handling<2>

2.5.5.21 domain_error/2
.......................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<118>,  Next: Modes and number of proofs<83>,  Up: domain_error/2

2.5.5.22 Description
....................

     domain_error(Domain, Culprit)

Throws a domain error.  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(domain_error(Domain,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<83>,  Next: Errors<84>,  Prev: Description<118>,  Up: domain_error/2

2.5.5.23 Modes and number of proofs
...................................

     domain_error(+atom, @nonvar) - error


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<84>,  Next: Examples<119>,  Prev: Modes and number of proofs<83>,  Up: domain_error/2

2.5.5.24 Errors
...............

     When called: 
          ‘domain_error(Domain, Culprit)’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<119>,  Prev: Errors<84>,  Up: domain_error/2

2.5.5.25 Examples
.................

     ...,
     atom(Color),
     \+ color(Color),
     domain_error(color, Color).

See also
........

*note catch/3: 156, *note throw/1: 157, *note context/1: 153, *note
instantiation_error/0: 158, *note type_error/2: 159, *note
existence_error/2: 15b, *note permission_error/3: 15c, *note
representation_error/1: 15d, *note evaluation_error/1: 15e, *note
resource_error/1: 15f, *note syntax_error/1: 160, *note system_error/0:
161.


File: TheLogtalkHandbook-3.27.0.info,  Node: existence_error/2,  Next: permission_error/3,  Prev: domain_error/2,  Up: Error handling<2>

2.5.5.26 existence_error/2
..........................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<119>,  Next: Modes and number of proofs<84>,  Up: existence_error/2

2.5.5.27 Description
....................

     existence_error(Thing, Culprit)

Throws an existence error.  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(existence_error(Thing,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<84>,  Next: Errors<85>,  Prev: Description<119>,  Up: existence_error/2

2.5.5.28 Modes and number of proofs
...................................

     existence_error(@nonvar, @nonvar) - error


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<85>,  Next: Examples<120>,  Prev: Modes and number of proofs<84>,  Up: existence_error/2

2.5.5.29 Errors
...............

     When called: 
          ‘existence_error(Thing, Culprit)’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<120>,  Prev: Errors<85>,  Up: existence_error/2

2.5.5.30 Examples
.................

     ...,
     \+ current_object(payroll),
     existence_error(object, payroll).

See also
........

*note catch/3: 156, *note throw/1: 157, *note context/1: 153, *note
instantiation_error/0: 158, *note type_error/2: 159, *note
domain_error/2: 15a, *note evaluation_error/1: 15e, *note
permission_error/3: 15c, *note representation_error/1: 15d, *note
resource_error/1: 15f, *note syntax_error/1: 160, *note system_error/0:
161.


File: TheLogtalkHandbook-3.27.0.info,  Node: permission_error/3,  Next: representation_error/1,  Prev: existence_error/2,  Up: Error handling<2>

2.5.5.31 permission_error/3
...........................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<120>,  Next: Modes and number of proofs<85>,  Up: permission_error/3

2.5.5.32 Description
....................

     permission_error(Operation, Permission, Culprit)

Throws an evaluation error.  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(permission_error(Operation,Permission,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<85>,  Next: Errors<86>,  Prev: Description<120>,  Up: permission_error/3

2.5.5.33 Modes and number of proofs
...................................

     permission_error(@nonvar, @nonvar, @nonvar) - error


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<86>,  Next: Examples<121>,  Prev: Modes and number of proofs<85>,  Up: permission_error/3

2.5.5.34 Errors
...............

     When called: 
          ‘permission_error(Operation, Permission, Culprit)’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<121>,  Prev: Errors<86>,  Up: permission_error/3

2.5.5.35 Examples
.................

     ...,
     \+ writable(File),
     permission_error(modify, file, File).

See also
........

*note catch/3: 156, *note throw/1: 157, *note context/1: 153, *note
instantiation_error/0: 158, *note type_error/2: 159, *note
domain_error/2: 15a, *note existence_error/2: 15b, *note
representation_error/1: 15d, *note evaluation_error/1: 15e, *note
resource_error/1: 15f, *note syntax_error/1: 160, *note system_error/0:
161.


File: TheLogtalkHandbook-3.27.0.info,  Node: representation_error/1,  Next: evaluation_error/1,  Prev: permission_error/3,  Up: Error handling<2>

2.5.5.36 representation_error/1
...............................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<121>,  Next: Modes and number of proofs<86>,  Up: representation_error/1

2.5.5.37 Description
....................

     representation_error(Flag)

Throws a representation error.  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(representation_error(Flag), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<86>,  Next: Errors<87>,  Prev: Description<121>,  Up: representation_error/1

2.5.5.38 Modes and number of proofs
...................................

     representation_error(+atom) - error


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<87>,  Next: Examples<122>,  Prev: Modes and number of proofs<86>,  Up: representation_error/1

2.5.5.39 Errors
...............

     When called: 
          ‘representation_error(Flag)’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<122>,  Prev: Errors<87>,  Up: representation_error/1

2.5.5.40 Examples
.................

     ...,
     Code > 127,
     representation_error(character_code).

See also
........

*note catch/3: 156, *note throw/1: 157, *note context/1: 153, *note
instantiation_error/0: 158, *note type_error/2: 159, *note
domain_error/2: 15a, *note existence_error/2: 15b, *note
permission_error/3: 15c, *note evaluation_error/1: 15e, *note
resource_error/1: 15f, *note syntax_error/1: 160, *note system_error/0:
161.


File: TheLogtalkHandbook-3.27.0.info,  Node: evaluation_error/1,  Next: resource_error/1,  Prev: representation_error/1,  Up: Error handling<2>

2.5.5.41 evaluation_error/1
...........................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<122>,  Next: Modes and number of proofs<87>,  Up: evaluation_error/1

2.5.5.42 Description
....................

     evaluation_error(Exception)

Throws an evaluation error.  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(evaluation_error(Exception), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<87>,  Next: Errors<88>,  Prev: Description<122>,  Up: evaluation_error/1

2.5.5.43 Modes and number of proofs
...................................

     evaluation_error(@nonvar) - error


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<88>,  Next: Examples<123>,  Prev: Modes and number of proofs<87>,  Up: evaluation_error/1

2.5.5.44 Errors
...............

     When called: 
          ‘evaluation_error(Exception)’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<123>,  Prev: Errors<88>,  Up: evaluation_error/1

2.5.5.45 Examples
.................

     ...,
     Divisor =:= 0,
     evaluation_error(zero_divisor).

See also
........

*note catch/3: 156, *note throw/1: 157, *note context/1: 153, *note
instantiation_error/0: 158, *note type_error/2: 159, *note
domain_error/2: 15a, *note existence_error/2: 15b, *note
permission_error/3: 15c, *note representation_error/1: 15d, *note
resource_error/1: 15f, *note syntax_error/1: 160, *note system_error/0:
161.


File: TheLogtalkHandbook-3.27.0.info,  Node: resource_error/1,  Next: syntax_error/1,  Prev: evaluation_error/1,  Up: Error handling<2>

2.5.5.46 resource_error/1
.........................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<123>,  Next: Modes and number of proofs<88>,  Up: resource_error/1

2.5.5.47 Description
....................

     resource_error(Resource)

Throws a resource error.  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(resource_error(Resource), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<88>,  Next: Errors<89>,  Prev: Description<123>,  Up: resource_error/1

2.5.5.48 Modes and number of proofs
...................................

     resource_error(@nonvar) - error


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<89>,  Next: Examples<124>,  Prev: Modes and number of proofs<88>,  Up: resource_error/1

2.5.5.49 Errors
...............

     When called: 
          ‘resource_error(Resource)’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<124>,  Prev: Errors<89>,  Up: resource_error/1

2.5.5.50 Examples
.................

     ...,
     empty(Tank),
     resource_error(gas).

See also
........

*note catch/3: 156, *note throw/1: 157, *note context/1: 153, *note
instantiation_error/0: 158, *note type_error/2: 159, *note
domain_error/2: 15a, *note existence_error/2: 15b, *note
permission_error/3: 15c, *note representation_error/1: 15d, *note
instantiation_error/0: 158, *note syntax_error/1: 160, *note
system_error/0: 161.


File: TheLogtalkHandbook-3.27.0.info,  Node: syntax_error/1,  Next: system_error/0,  Prev: resource_error/1,  Up: Error handling<2>

2.5.5.51 syntax_error/1
.......................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<124>,  Next: Modes and number of proofs<89>,  Up: syntax_error/1

2.5.5.52 Description
....................

     syntax_error(Description)

Throws a syntax error.  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(syntax_error(Description), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<89>,  Next: Errors<90>,  Prev: Description<124>,  Up: syntax_error/1

2.5.5.53 Modes and number of proofs
...................................

     syntax_error(@nonvar) - error


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<90>,  Next: Examples<125>,  Prev: Modes and number of proofs<89>,  Up: syntax_error/1

2.5.5.54 Errors
...............

     When called: 
          ‘syntax_error(Description)’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<125>,  Prev: Errors<90>,  Up: syntax_error/1

2.5.5.55 Examples
.................

(none)

See also
........

*note catch/3: 156, *note throw/1: 157, *note context/1: 153, *note
instantiation_error/0: 158, *note type_error/2: 159, *note
domain_error/2: 15a, *note existence_error/2: 15b, *note
permission_error/3: 15c, *note representation_error/1: 15d, *note
instantiation_error/0: 158, *note system_error/0: 161. *note
resource_error/1: 15f.


File: TheLogtalkHandbook-3.27.0.info,  Node: system_error/0,  Prev: syntax_error/1,  Up: Error handling<2>

2.5.5.56 system_error/0
.......................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<125>,  Next: Modes and number of proofs<90>,  Up: system_error/0

2.5.5.57 Description
....................

     system_error

Throws a system error.  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(system_error, Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<90>,  Next: Errors<91>,  Prev: Description<125>,  Up: system_error/0

2.5.5.58 Modes and number of proofs
...................................

     system_error - error


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<91>,  Next: Examples<126>,  Prev: Modes and number of proofs<90>,  Up: system_error/0

2.5.5.59 Errors
...............

     When called: 
          ‘system_error’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<126>,  Prev: Errors<91>,  Up: system_error/0

2.5.5.60 Examples
.................

(none)

See also
........

*note catch/3: 156, *note throw/1: 157, *note context/1: 153, *note
instantiation_error/0: 158, *note type_error/2: 159, *note
domain_error/2: 15a, *note existence_error/2: 15b, *note
permission_error/3: 15c, *note representation_error/1: 15d. *note
evaluation_error/1: 15e, *note resource_error/1: 15f, *note
syntax_error/1: 160,


File: TheLogtalkHandbook-3.27.0.info,  Node: All solutions,  Next: Event handling<3>,  Prev: Error handling<2>,  Up: Built-in methods

2.5.6 All solutions
-------------------

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: bagof/3,  Next: findall/3,  Up: All solutions

2.5.6.1 bagof/3
...............

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<126>,  Next: Modes and number of proofs<91>,  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.27.0.info,  Node: Modes and number of proofs<91>,  Next: Errors<92>,  Prev: Description<126>,  Up: bagof/3

2.5.6.3 Modes and number of proofs
..................................

     bagof(@term, +callable, -list) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<92>,  Next: Examples<127>,  Prev: Modes and number of proofs<91>,  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.27.0.info,  Node: Examples<127>,  Prev: Errors<92>,  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: 4b.: 
          ‘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: 175, *note findall/4: 176, *note forall/2: 178, *note
setof/3: 177.


File: TheLogtalkHandbook-3.27.0.info,  Node: findall/3,  Next: findall/4,  Prev: bagof/3,  Up: All solutions

2.5.6.6 findall/3
.................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<127>,  Next: Modes and number of proofs<92>,  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.27.0.info,  Node: Modes and number of proofs<92>,  Next: Errors<93>,  Prev: Description<127>,  Up: findall/3

2.5.6.8 Modes and number of proofs
..................................

     findall(?term, +callable, ?list) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<93>,  Next: Examples<128>,  Prev: Modes and number of proofs<92>,  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.27.0.info,  Node: Examples<128>,  Prev: Errors<93>,  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: 4b.: 
          ‘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: 174, *note findall/4: 176, *note forall/2: 178, *note
setof/3: 177.


File: TheLogtalkHandbook-3.27.0.info,  Node: findall/4,  Next: forall/2,  Prev: findall/3,  Up: All solutions

2.5.6.11 findall/4
..................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<128>,  Next: Modes and number of proofs<93>,  Up: findall/4

2.5.6.12 Description
....................

     findall(Template, Goal, List, Tail)

Variant of the *note findall/3: 175. 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.27.0.info,  Node: Modes and number of proofs<93>,  Next: Errors<94>,  Prev: Description<128>,  Up: findall/4

2.5.6.13 Modes and number of proofs
...................................

     findall(?term, +callable, ?list, ?term) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<94>,  Next: Examples<129>,  Prev: Modes and number of proofs<93>,  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.27.0.info,  Node: Examples<129>,  Prev: Errors<94>,  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: 4b.: 
          ‘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: 174, *note findall/3: 175, *note forall/2: 178, *note
setof/3: 177.


File: TheLogtalkHandbook-3.27.0.info,  Node: forall/2,  Next: setof/3,  Prev: findall/4,  Up: All solutions

2.5.6.16 forall/2
.................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<129>,  Next: Modes and number of proofs<94>,  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.27.0.info,  Node: Modes and number of proofs<94>,  Next: Errors<95>,  Prev: Description<129>,  Up: forall/2

2.5.6.18 Modes and number of proofs
...................................

     forall(@callable, @callable) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<95>,  Next: Examples<130>,  Prev: Modes and number of proofs<94>,  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.27.0.info,  Node: Examples<130>,  Prev: Errors<95>,  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: 4b.: 
          ‘forall(::Generator, ::Test)’ 
     To send both goals as messages to explicit objects: 
          ‘forall(Object1::Generator, Object2::Test)’ 

See also
........

*note bagof/3: 174, *note findall/3: 175, *note findall/4: 176, *note
setof/3: 177.


File: TheLogtalkHandbook-3.27.0.info,  Node: setof/3,  Prev: forall/2,  Up: All solutions

2.5.6.21 setof/3
................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<130>,  Next: Modes and number of proofs<95>,  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.27.0.info,  Node: Modes and number of proofs<95>,  Next: Errors<96>,  Prev: Description<130>,  Up: setof/3

2.5.6.23 Modes and number of proofs
...................................

     setof(@term, +callable, -list) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<96>,  Next: Examples<131>,  Prev: Modes and number of proofs<95>,  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.27.0.info,  Node: Examples<131>,  Prev: Errors<96>,  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: 4b.: 
          ‘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: 174, *note findall/3: 175, *note findall/4: 176, *note
forall/2: 178.


File: TheLogtalkHandbook-3.27.0.info,  Node: Event handling<3>,  Next: Message forwarding,  Prev: All solutions,  Up: Built-in methods

2.5.7 Event handling
--------------------

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: before/3,  Next: after/3,  Up: Event handling<3>

2.5.7.1 before/3
................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<131>,  Next: Modes and number of proofs<96>,  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: 5e. control construct from within objects compiled with the
*note events: 69. flag set to ‘allow’.

Note that you can make this predicate scope protected or private by
using, respectively, *note protected or private implementation: 79. of
the ‘monitoring’ protocol.

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

   (1) https://logtalk.org/library/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<96>,  Next: Errors<97>,  Prev: Description<131>,  Up: before/3

2.5.7.3 Modes and number of proofs
..................................

     before(?object_identifier, ?callable, ?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<97>,  Next: Examples<132>,  Prev: Modes and number of proofs<96>,  Up: before/3

2.5.7.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<132>,  Prev: Errors<97>,  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: d9, *note abolish_events/5: 1cd, *note current_event/5:
1d0, *note define_events/5: 1ca.


File: TheLogtalkHandbook-3.27.0.info,  Node: after/3,  Prev: before/3,  Up: Event handling<3>

2.5.7.6 after/3
...............

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<132>,  Next: Modes and number of proofs<97>,  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: 5e. control construct from within objects compiled with the
*note events: 69. flag set to ‘allow’.

Note that you can make this predicate scope protected or private by
using, respectively, *note protected or private implementation: 79. of
the ‘monitoring’ protocol.

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

   (1) https://logtalk.org/library/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<97>,  Next: Errors<98>,  Prev: Description<132>,  Up: after/3

2.5.7.8 Modes and number of proofs
..................................

     after(?object_identifier, ?callable, ?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<98>,  Next: Examples<133>,  Prev: Modes and number of proofs<97>,  Up: after/3

2.5.7.9 Errors
..............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<133>,  Prev: Errors<98>,  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: d8, *note abolish_events/5: 1cd, *note current_event/5:
1d0, *note define_events/5: 1ca.


File: TheLogtalkHandbook-3.27.0.info,  Node: Message forwarding,  Next: Definite clause grammar rules<2>,  Prev: Event handling<3>,  Up: Built-in methods

2.5.8 Message forwarding
------------------------

* Menu:

* forward/1::


File: TheLogtalkHandbook-3.27.0.info,  Node: forward/1,  Up: Message forwarding

2.5.8.1 forward/1
.................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<133>,  Next: Modes and number of proofs<98>,  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: 5e. control construct), automatically called by
the runtime when defined.  This method is declared in the forwarding(1)
built-in protocol as a *note public: 113. predicate.  Note that you can
make its scope protected or private by using, respectively, *note
protected or private implementation: 79. of the ‘forwarding’ protocol.

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

   (1) https://logtalk.org/library/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<98>,  Next: Errors<99>,  Prev: Description<133>,  Up: forward/1

2.5.8.3 Modes and number of proofs
..................................

     forward(+callable) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<99>,  Next: Examples<134>,  Prev: Modes and number of proofs<98>,  Up: forward/1

2.5.8.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<134>,  Prev: Errors<99>,  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: 61.


File: TheLogtalkHandbook-3.27.0.info,  Node: Definite clause grammar rules<2>,  Next: Term and goal expansion<2>,  Prev: Message forwarding,  Up: Built-in methods

2.5.9 Definite clause grammar rules
-----------------------------------

* Menu:

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


File: TheLogtalkHandbook-3.27.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<134>.
* Modes and number of proofs: Modes and number of proofs<99>.
* Errors: Errors<100>.
* Examples: Examples<135>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<134>,  Next: Modes and number of proofs<99>,  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 closure 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: 145, 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.27.0.info,  Node: Modes and number of proofs<99>,  Next: Errors<100>,  Prev: Description<134>,  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.27.0.info,  Node: Errors<100>,  Next: Examples<135>,  Prev: Modes and number of proofs<99>,  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.27.0.info,  Node: Examples<135>,  Prev: Errors<100>,  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: 4b.: 
          ‘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: 17f, *note phrase//1: 17d, *note phrase/2: 14b, *note
phrase/3: 14c.


File: TheLogtalkHandbook-3.27.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<135>.
* Modes and number of proofs: Modes and number of proofs<100>.
* Errors: Errors<101>.
* Examples: Examples<136>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<135>,  Next: Modes and number of proofs<100>,  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.27.0.info,  Node: Modes and number of proofs<100>,  Next: Errors<101>,  Prev: Description<135>,  Up: eos//0

2.5.9.8 Modes and number of proofs
..................................

     eos - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<101>,  Next: Examples<136>,  Prev: Modes and number of proofs<100>,  Up: eos//0

2.5.9.9 Errors
..............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<136>,  Prev: Errors<101>,  Up: eos//0

2.5.9.10 Examples
.................

     abc --> a, b, c, eos.

See also
........

*note call//1-N: 17e, *note phrase//1: 17d, *note phrase/2: 14b, *note
phrase/3: 14c.


File: TheLogtalkHandbook-3.27.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<136>.
* Modes and number of proofs: Modes and number of proofs<101>.
* Errors: Errors<102>.
* Examples: Examples<137>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<136>,  Next: Modes and number of proofs<101>,  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.27.0.info,  Node: Modes and number of proofs<101>,  Next: Errors<102>,  Prev: Description<136>,  Up: phrase//1

2.5.9.13 Modes and number of proofs
...................................

     phrase(+callable) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<102>,  Next: Examples<137>,  Prev: Modes and number of proofs<101>,  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.27.0.info,  Node: Examples<137>,  Prev: Errors<102>,  Up: phrase//1

2.5.9.15 Examples
.................

     (none)

See also
........

*note call//1-N: 17e, *note phrase/2: 14b, *note phrase/3: 14c.


File: TheLogtalkHandbook-3.27.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<137>.
* Modes and number of proofs: Modes and number of proofs<102>.
* Errors: Errors<103>.
* Examples: Examples<138>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<137>,  Next: Modes and number of proofs<102>,  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.27.0.info,  Node: Modes and number of proofs<102>,  Next: Errors<103>,  Prev: Description<137>,  Up: phrase/2

2.5.9.18 Modes and number of proofs
...................................

     phrase(+callable, ?list) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<103>,  Next: Examples<138>,  Prev: Modes and number of proofs<102>,  Up: phrase/2

2.5.9.19 Errors
...............

     NonTerminal is a variable: 
          ‘instantiation_error’ 
     NonTerminal is neither a variable nor a callable term: 
          ‘type_error(callable, NonTerminal)’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<138>,  Prev: Errors<103>,  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: 4b.: 
          ‘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: 17e, *note phrase//1: 17d, *note phrase/3: 14c.


File: TheLogtalkHandbook-3.27.0.info,  Node: phrase/3,  Prev: phrase/2,  Up: Definite clause grammar rules<2>

2.5.9.21 phrase/3
.................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<138>,  Next: Modes and number of proofs<103>,  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.27.0.info,  Node: Modes and number of proofs<103>,  Next: Errors<104>,  Prev: Description<138>,  Up: phrase/3

2.5.9.23 Modes and number of proofs
...................................

     phrase(+callable, ?list, ?list) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<104>,  Next: Examples<139>,  Prev: Modes and number of proofs<103>,  Up: phrase/3

2.5.9.24 Errors
...............

     NonTerminal is a variable: 
          ‘instantiation_error’ 
     NonTerminal is neither a variable nor a callable term: 
          ‘type_error(callable, NonTerminal)’ 


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<139>,  Prev: Errors<104>,  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: 4b.: 
          ‘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: 17e, *note phrase/2: 14b, *note phrase/3: 14c.


File: TheLogtalkHandbook-3.27.0.info,  Node: Term and goal expansion<2>,  Next: Coinduction hooks,  Prev: Definite clause grammar rules<2>,  Up: Built-in methods

2.5.10 Term and goal expansion
------------------------------

* Menu:

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


File: TheLogtalkHandbook-3.27.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<139>.
* Modes and number of proofs: Modes and number of proofs<104>.
* Errors: Errors<105>.
* Examples: Examples<140>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<139>,  Next: Modes and number of proofs<104>,  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: d3. 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: 315.
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.27.0.info,  Node: Modes and number of proofs<104>,  Next: Errors<105>,  Prev: Description<139>,  Up: expand_term/2

2.5.10.3 Modes and number of proofs
...................................

     expand_term(?term, ?term) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<105>,  Next: Examples<140>,  Prev: Modes and number of proofs<104>,  Up: expand_term/2

2.5.10.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<140>,  Prev: Errors<105>,  Up: expand_term/2

2.5.10.5 Examples
.................

(none)

See also
........

*note expand_goal/2: 2a1, *note goal_expansion/2: d4, *note
term_expansion/2: d3.


File: TheLogtalkHandbook-3.27.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<140>.
* Modes and number of proofs: Modes and number of proofs<105>.
* Errors: Errors<106>.
* Examples: Examples<141>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<140>,  Next: Modes and number of proofs<105>,  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: 16c.
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: 315.  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: 14d. 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: 79. to restrict the scope of this predicate.

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

   (1) https://logtalk.org/library/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<105>,  Next: Errors<106>,  Prev: Description<140>,  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.27.0.info,  Node: Errors<106>,  Next: Examples<141>,  Prev: Modes and number of proofs<105>,  Up: term_expansion/2

2.5.10.9 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<141>,  Prev: Errors<106>,  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: 2a1, *note expand_term/2: 16c, *note
goal_expansion/2: d4, *note logtalk_load_context/2: 2a4.


File: TheLogtalkHandbook-3.27.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<141>.
* Modes and number of proofs: Modes and number of proofs<106>.
* Errors: Errors<107>.
* Examples: Examples<142>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<141>,  Next: Modes and number of proofs<106>,  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: 315.  This predicate can be used by the user
to manually perform goal expansion at runtime (for example, before
asserting a clause).


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<106>,  Next: Errors<107>,  Prev: Description<141>,  Up: expand_goal/2

2.5.10.13 Modes and number of proofs
....................................

     expand_goal(?term, ?term) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<107>,  Next: Examples<142>,  Prev: Modes and number of proofs<106>,  Up: expand_goal/2

2.5.10.14 Errors
................

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<142>,  Prev: Errors<107>,  Up: expand_goal/2

2.5.10.15 Examples
..................

(none)

See also
........

*note expand_term/2: 16c, *note goal_expansion/2: d4, *note
term_expansion/2: d3.


File: TheLogtalkHandbook-3.27.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<142>.
* Modes and number of proofs: Modes and number of proofs<107>.
* Errors: Errors<108>.
* Examples: Examples<143>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<142>,  Next: Modes and number of proofs<107>,  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: 2a1. 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: 315.  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: 14d. 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: 79. to restrict the scope of this
predicate.

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

   (1) https://logtalk.org/library/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<107>,  Next: Errors<108>,  Prev: Description<142>,  Up: goal_expansion/2

2.5.10.18 Modes and number of proofs
....................................

     goal_expansion(+callable, -callable) - zero_or_one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<108>,  Next: Examples<143>,  Prev: Modes and number of proofs<107>,  Up: goal_expansion/2

2.5.10.19 Errors
................

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<143>,  Prev: Errors<108>,  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: 2a1, *note expand_term/2: 16c, *note
term_expansion/2: d3, *note logtalk_load_context/2: 2a4.


File: TheLogtalkHandbook-3.27.0.info,  Node: Coinduction hooks,  Next: Message printing,  Prev: Term and goal expansion<2>,  Up: Built-in methods

2.5.11 Coinduction hooks
------------------------

* Menu:

* coinductive_success_hook/1-2::


File: TheLogtalkHandbook-3.27.0.info,  Node: coinductive_success_hook/1-2,  Up: Coinduction hooks

2.5.11.1 coinductive_success_hook/1-2
.....................................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<143>,  Next: Modes and number of proofs<108>,  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.27.0.info,  Node: Modes and number of proofs<108>,  Next: Errors<109>,  Prev: Description<143>,  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.27.0.info,  Node: Errors<109>,  Next: Examples<144>,  Prev: Modes and number of proofs<108>,  Up: coinductive_success_hook/1-2

2.5.11.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<144>,  Prev: Errors<109>,  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: 138.


File: TheLogtalkHandbook-3.27.0.info,  Node: Message printing,  Next: Question asking,  Prev: Coinduction hooks,  Up: Built-in methods

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.27.0.info,  Node: print_message/3,  Next: message_tokens//2,  Up: Message printing

2.5.12.1 print_message/3
........................

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<144>,  Next: Modes and number of proofs<109>,  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): 293. 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): 298.
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): 297. hook predicate.  If this predicate succeeds, the
‘print_message/3’ predicate assumes that the message have been
successfully printed.

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

   (1) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<109>,  Next: Errors<110>,  Prev: Description<144>,  Up: print_message/3

2.5.12.3 Modes and number of proofs
...................................

     print_message(+nonvar, +nonvar, +nonvar) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<110>,  Next: Examples<145>,  Prev: Modes and number of proofs<109>,  Up: print_message/3

2.5.12.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<145>,  Prev: Errors<110>,  Up: print_message/3

2.5.12.5 Examples
.................

     ..., logtalk::print_message(information, core, redefining_entity(object, foo)), ...

See also
........

*note message_hook/4: 297, *note message_prefix_stream/4: 298, *note
message_tokens//2: 293, *note print_message_tokens/3: 70e, *note
print_message_token/4: 70f, *note ask_question/5: 29b, *note
question_hook/6: 29d, *note question_prompt_stream/4: 710.


File: TheLogtalkHandbook-3.27.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<145>.
* Modes and number of proofs: Modes and number of proofs<110>.
* Errors: Errors<111>.
* Examples: Examples<146>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<145>,  Next: Modes and number of proofs<110>,  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: 70e. method.  This
non-terminal hook is automatically called by the *note print_message/3:
291. method.

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

   (1) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<110>,  Next: Errors<111>,  Prev: Description<145>,  Up: message_tokens//2

2.5.12.8 Modes and number of proofs
...................................

     message_tokens(+nonvar, +nonvar) - zero_or_more


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<111>,  Next: Examples<146>,  Prev: Modes and number of proofs<110>,  Up: message_tokens//2

2.5.12.9 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<146>,  Prev: Errors<111>,  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: 297, *note message_prefix_stream/4: 298, *note
print_message/3: 291, *note print_message_tokens/3: 70e, *note
print_message_token/4: 70f, *note ask_question/5: 29b, *note
question_hook/6: 29d, *note question_prompt_stream/4: 710.


File: TheLogtalkHandbook-3.27.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<146>.
* Modes and number of proofs: Modes and number of proofs<111>.
* Errors: Errors<112>.
* Examples: Examples<147>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<146>,  Next: Modes and number of proofs<111>,  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: 291. method.  When the call succeeds, the
‘print_message/3’ method assumes that the message have been successfully
printed.

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

   (1) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<111>,  Next: Errors<112>,  Prev: Description<146>,  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.27.0.info,  Node: Errors<112>,  Next: Examples<147>,  Prev: Modes and number of proofs<111>,  Up: message_hook/4

2.5.12.14 Errors
................

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<147>,  Prev: Errors<112>,  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: 298, *note message_tokens//2: 293, *note
print_message/3: 291, *note print_message_tokens/3: 70e, *note
print_message_token/4: 70f, *note ask_question/5: 29b, *note
question_hook/6: 29d, *note question_prompt_stream/4: 710.


File: TheLogtalkHandbook-3.27.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<147>.
* Modes and number of proofs: Modes and number of proofs<112>.
* Errors: Errors<113>.
* Examples: Examples<148>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<147>,  Next: Modes and number of proofs<112>,  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: 2cc.  This
method is declared in the logtalk(1) built-in object as a public,
multifile, and dynamic predicate.

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

   (1) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<112>,  Next: Errors<113>,  Prev: Description<147>,  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.27.0.info,  Node: Errors<113>,  Next: Examples<148>,  Prev: Modes and number of proofs<112>,  Up: message_prefix_stream/4

2.5.12.19 Errors
................

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<148>,  Prev: Errors<113>,  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: 297, *note message_tokens//2: 293, *note
print_message/3: 291, *note print_message_tokens/3: 70e, *note
print_message_token/4: 70f, *note ask_question/5: 29b, *note
question_hook/6: 29d, *note question_prompt_stream/4: 710.


File: TheLogtalkHandbook-3.27.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<148>.
* Modes and number of proofs: Modes and number of proofs<113>.
* Errors: Errors<114>.
* Examples: Examples<149>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<148>,  Next: Modes and number of proofs<113>,  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: 291. method (assuming
that the message was not intercepted by a *note message_hook/4: 297.
definition) and calls the user-defined hook predicate *note
print_message_token/4: 70f. 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) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<113>,  Next: Errors<114>,  Prev: Description<148>,  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.27.0.info,  Node: Errors<114>,  Next: Examples<149>,  Prev: Modes and number of proofs<113>,  Up: print_message_tokens/3

2.5.12.24 Errors
................

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<149>,  Prev: Errors<114>,  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: 297, *note message_prefix_stream/4: 298, *note
message_tokens//2: 293, *note print_message/3: 291, *note
print_message_token/4: 70f, *note ask_question/5: 29b, *note
question_hook/6: 29d, *note question_prompt_stream/4: 710.


File: TheLogtalkHandbook-3.27.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<149>.
* Modes and number of proofs: Modes and number of proofs<114>.
* Errors: Errors<115>.
* Examples: Examples<150>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<149>,  Next: Modes and number of proofs<114>,  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: 70e. built-in method for each token.

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

   (1) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<114>,  Next: Errors<115>,  Prev: Description<149>,  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.27.0.info,  Node: Errors<115>,  Next: Examples<150>,  Prev: Modes and number of proofs<114>,  Up: print_message_token/4

2.5.12.29 Errors
................

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<150>,  Prev: Errors<115>,  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: 297, *note message_prefix_stream/4: 298, *note
message_tokens//2: 293, *note print_message/3: 291, *note
print_message_tokens/3: 70e, *note ask_question/5: 29b, *note
question_hook/6: 29d, *note question_prompt_stream/4: 710.


File: TheLogtalkHandbook-3.27.0.info,  Node: Question asking,  Prev: Message printing,  Up: Built-in methods

2.5.13 Question asking
----------------------

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: ask_question/5,  Next: question_hook/6,  Up: Question asking

2.5.13.1 ask_question/5
.......................

* Menu:

* Description: Description<150>.
* Modes and number of proofs: Modes and number of proofs<115>.
* Meta-predicate template::
* Errors: Errors<116>.
* Examples: Examples<151>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<150>,  Next: Modes and number of proofs<115>,  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): 293. 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): 710.
hook predicate.  The ‘Check’ argument is a closure 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): 29d.
hook predicate.  If this predicate succeeds, the ‘ask_question/5’
predicate assumes that the question have been successfully asked and
replied.


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<115>,  Next: Meta-predicate template,  Prev: Description<150>,  Up: ask_question/5

2.5.13.3 Modes and number of proofs
...................................

     ask_question(+nonvar, +nonvar, +nonvar, +callable, -term) - one


File: TheLogtalkHandbook-3.27.0.info,  Node: Meta-predicate template,  Next: Errors<116>,  Prev: Modes and number of proofs<115>,  Up: ask_question/5

2.5.13.4 Meta-predicate template
................................

     ask_question(*, *, *, 1, *)


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<116>,  Next: Examples<151>,  Prev: Meta-predicate template,  Up: ask_question/5

2.5.13.5 Errors
...............

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<151>,  Prev: Errors<116>,  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: 29d, *note question_prompt_stream/4: 710, *note
message_hook/4: 297, *note message_prefix_stream/4: 298, *note
message_tokens//2: 293, *note print_message/3: 291, *note
print_message_tokens/3: 70e, *note print_message_token/4: 70f.


File: TheLogtalkHandbook-3.27.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<151>.
* Modes and number of proofs: Modes and number of proofs<116>.
* Meta-predicate template: Meta-predicate template<2>.
* Errors: Errors<117>.
* Examples: Examples<152>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<151>,  Next: Modes and number of proofs<116>,  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: 29b. method.  When the call succeeds, the
‘ask_question/5’ method assumes that the question have been successfully
asked and replied.

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

   (1) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<116>,  Next: Meta-predicate template<2>,  Prev: Description<151>,  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.27.0.info,  Node: Meta-predicate template<2>,  Next: Errors<117>,  Prev: Modes and number of proofs<116>,  Up: question_hook/6

2.5.13.10 Meta-predicate template
.................................

     question_hook(*, *, *, *, 1, *)


File: TheLogtalkHandbook-3.27.0.info,  Node: Errors<117>,  Next: Examples<152>,  Prev: Meta-predicate template<2>,  Up: question_hook/6

2.5.13.11 Errors
................

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<152>,  Prev: Errors<117>,  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, _, float, 3.7).

See also
........

*note ask_question/5: 29b, *note question_prompt_stream/4: 710. *note
message_hook/4: 297, *note message_prefix_stream/4: 298, *note
message_tokens//2: 293, *note print_message/3: 291, *note
print_message_tokens/3: 70e, *note print_message_token/4: 70f,


File: TheLogtalkHandbook-3.27.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<152>.
* Modes and number of proofs: Modes and number of proofs<117>.
* Errors: Errors<118>.
* Examples: Examples<153>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Description<152>,  Next: Modes and number of proofs<117>,  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: 2cc.
This method is declared in the logtalk(1) built-in object as a public,
multifile, and dynamic predicate.

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

   (1) https://logtalk.org/library/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Modes and number of proofs<117>,  Next: Errors<118>,  Prev: Description<152>,  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.27.0.info,  Node: Errors<118>,  Next: Examples<153>,  Prev: Modes and number of proofs<117>,  Up: question_prompt_stream/4

2.5.13.16 Errors
................

(none)


File: TheLogtalkHandbook-3.27.0.info,  Node: Examples<153>,  Prev: Errors<118>,  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: 29b, *note question_hook/6: 29d, *note
message_hook/4: 297, *note message_prefix_stream/4: 298, *note
message_tokens//2: 293, *note print_message/3: 291, *note
print_message_tokens/3: 70e, *note print_message_token/4: 70f.


File: TheLogtalkHandbook-3.27.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.27.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.27.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: 75. and *note end_object/0: 76, 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: 113. 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: 2de. section on the User Manual), we can compile and load the
object using the *note logtalk_load/1: 253. 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: 5e. 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 occured.


File: TheLogtalkHandbook-3.27.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:
b3. and *note end_protocol/0: b4. 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: 118. 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.27.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.27.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.27.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: 167. or *note retract/1: 169.) must be made either in
the context of `self', using the `message to self' control structure,
*note ;;/1: 3d, 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-3: e4. and *note
end_category/0: e5, 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.27.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.27.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.27.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]: 77.  This extension provides, along with root objects
for the instantiation and specialization hierarchies, explicit support
for abstract classes *note [Moura94]: 78.

* Menu:

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


File: TheLogtalkHandbook-3.27.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.27.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.27.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.27.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: 5e. operator.


File: TheLogtalkHandbook-3.27.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: d8.
for ‘before’ events and *note after/3: d9. 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: 1ca.
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: 1cd. 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.27.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:
     d8. and *note after/3: d9, that are automatically called by the
     runtime engine when a spied event occurs.

   - Three built-in predicates, *note define_events/5: 1ca, *note
     current_event/5: 1d0, and *note abolish_events/5: 1cd, enables us
     define, query, and abolish both events and monitors.


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: General,  Next: Compatibility,  Up: FAQ

4.1 General
===========

   * *note Why are all versions of Logtalk numbered 2.x or 3.x?: 767.

   * *note Why do I need a Prolog compiler to use Logtalk?: 768.

   * *note Is the Logtalk implementation based on Prolog modules?: 769.

   * *note Does the Logtalk implementation use term-expansion?: 76a.

* 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.27.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.27.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.27.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 guide: 305. for details).


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Compatibility,  Next: Installation,  Prev: General,  Up: FAQ

4.2 Compatibility
=================

   * *note What are the backend Prolog compiler requirements to run
     Logtalk?: 772.

   * *note Can I use constraint-based packages with Logtalk?: 773.

   * *note Can I use Logtalk objects and Prolog modules at the same
     time?: 774.

* 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.27.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.27.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: 14d. control construct (thus
bypassing the Logtalk compiler).


File: TheLogtalkHandbook-3.27.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: 16b. directive or use
explicit module qualification (possibly wrapping the call using the
Logtalk control construct *note {}/1: 14d. 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 guide: 305. for details).


File: TheLogtalkHandbook-3.27.0.info,  Node: Installation,  Next: Portability,  Prev: Compatibility,  Up: FAQ

4.3 Installation
================

   * *note The integration scripts/shortcuts are not working!: 77b.

   * *note I get errors when starting up Logtalk after upgrading to the
     latest version!: 77c.

* Menu:

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


File: TheLogtalkHandbook-3.27.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.27.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.27.0.info,  Node: Portability,  Next: Programming,  Prev: Installation,  Up: FAQ

4.4 Portability
===============

   * *note Are my Logtalk applications portable across Prolog
     compilers?: 782.

   * *note Are my Logtalk applications portable across operating
     systems?: 783.

* Menu:

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


File: TheLogtalkHandbook-3.27.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: 187.
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.27.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.27.0.info,  Node: Programming,  Next: Troubleshooting,  Prev: Portability,  Up: FAQ

4.5 Programming
===============

   * *note Should I use prototypes or classes in my application?: 789.

   * *note Can I use both classes and prototypes in the same
     application?: 78a.

   * *note Can I mix classes and prototypes in the same hierarchy?: 78b.

   * *note Can I use a protocol or a category with both prototypes and
     classes?: 78c.

   * *note What support is provided in Logtalk for defining and using
     components?: 78d.

   * *note What support is provided in Logtalk for reflective
     programming?: 78e.

* 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.27.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.27.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.27.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.27.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.27.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: df. section and the examples provided with the
distribution.


File: TheLogtalkHandbook-3.27.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.27.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!: 798.

   * *note Gecko-based browsers (e.g.  Firefox) show non-rendered HTML
     entities when browsing XML documenting files!: 799.

   * *note Compiling a source file results in errors or warnings but the
     Logtalk compiler reports a successful compilation with zero errors
     and zero warnings!: 79a.

* 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.27.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:
261. and *note logtalk_load/2: 25a. built-in predicates only apply the
file being compiled.  If the first argument is a *note loader file: 18e,
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.27.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.27.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.27.0.info,  Node: Usability,  Next: Deployment,  Prev: Troubleshooting,  Up: FAQ

4.7 Usability
=============

   * *note Is there a shortcut for compiling and loading source files?:
     7a1.

   * *note Is there an equivalent directive to the ensure_loaded/1
     Prolog directive?: 7a2.

   * *note Are there shortcuts for the make functionality?: 7a3.

* 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.27.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: 253. predicate for details.


File: TheLogtalkHandbook-3.27.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: 25a. predicate for details.


File: TheLogtalkHandbook-3.27.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: 256. predicate for details.


File: TheLogtalkHandbook-3.27.0.info,  Node: Deployment,  Next: Performance<3>,  Prev: Usability,  Up: FAQ

4.8 Deployment
==============

   * *note Can I create standalone applications with Logtalk?: 7aa.

* Menu:

* Can I create standalone applications with Logtalk?::


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Performance<3>,  Next: Licensing,  Prev: Deployment,  Up: FAQ

4.9 Performance
===============

   * *note Is Logtalk implemented as a meta-interpreter?: 7af.

   * *note What kind of code Logtalk generates when compiling objects?
     Dynamic code?  Static code?: 7b0.

   * *note How about message-sending performance?  Does Logtalk use
     static binding or dynamic binding?: 7b1.

   * *note How does Logtalk performance compare with plain Prolog and
     with Prolog modules?: 7b2.

* 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.27.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.27.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.27.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: 28b. for
more details.


File: TheLogtalkHandbook-3.27.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.27.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.27.0.info,  Node: Licensing,  Next: Support,  Prev: Performance<3>,  Up: FAQ

4.10 Licensing
==============

   * *note What’s the Logtalk distribution license?: 7bb.

   * *note Can Logtalk be used in commercial applications?: 7bc.

   * *note What’s the final license for a combination of Logtalk with a
     Prolog compiler?: 7bd.

* 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.27.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.27.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.27.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.27.0.info,  Node: Support,  Prev: Licensing,  Up: FAQ

4.11 Support
============

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

* Menu:

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


File: TheLogtalkHandbook-3.27.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.27.0.info,  Node: Developer Tools,  Next: Glossary,  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:

* asdf::
* assertions::
* code_metrics::
* dead_code_scanner::
* debug_messages::
* debugger::
* diagrams::
* doclet::
* help::
* lgtdoc::
* lgtunit::
* make::
* ports_profiler::
* profiler::
* wrapper::


File: TheLogtalkHandbook-3.27.0.info,  Node: asdf,  Next: assertions,  Up: Developer Tools

5.1 ‘asdf’
==========

A Logtalk plugin for the ‘asdf’ 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’.


File: TheLogtalkHandbook-3.27.0.info,  Node: assertions,  Next: code_metrics,  Prev: asdf,  Up: Developer Tools

5.2 ‘assertions’
================

The ‘assertions.lgt’ file contains definitions for two meta-predicates,
‘assertion/1-2’, which allows using of assertions on your source code
(e.g.  when writing unit tests).  The ‘assertions_messages.lgt’ file
defines the default message translations generated on assertions
succeed, fail, or throw an exception.  For more information on these
entities, open the ‘docs/tools.html’ file in a web browser.

* Menu:

* API documentation::
* Loading::
* 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::
* Other notes::


File: TheLogtalkHandbook-3.27.0.info,  Node: API documentation,  Next: Loading,  Up: assertions

5.2.1 API documentation
-----------------------

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#assertions(1)

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

   (1) https://logtalk.org/docs/library_index.html#assertions


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading,  Next: Adding assertions to your source code,  Prev: API documentation,  Up: assertions

5.2.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(assertions(loader)).


File: TheLogtalkHandbook-3.27.0.info,  Node: Adding assertions to your source code,  Next: Automatically adding file and line context information to assertions,  Prev: Loading,  Up: assertions

5.2.3 Adding assertions to your source code
-------------------------------------------

The ‘assertion/1’ predicate takes a goal as argument.  For example,
assuming that you’re writing a unit test:

     test(assertions_1) :-
         assertions::assertion(ground(x)),
         2 is 1 + 1.

The ‘assertion/2’ predicate takes as arguments a term for passing
context information and a goal.  Using again a unit test as an example:

     test(assertions_1) :-
         assertions::assertion(assertions_1, ground(x)),
         2 is 1 + 1.

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.27.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.2.4 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.27.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.2.5 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.27.0.info,  Node: Redirecting assertion failure messages,  Next: Converting assertion failures into errors,  Prev: Suppressing assertion calls from source code,  Up: assertions

5.2.6 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.27.0.info,  Node: Converting assertion failures into errors,  Next: Other notes,  Prev: Redirecting assertion failure messages,  Up: assertions

5.2.7 Converting assertion failures into errors
-----------------------------------------------

If you want an assertion failure to result in 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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Other notes,  Prev: Converting assertion failures into errors,  Up: assertions

5.2.8 Other notes
-----------------

All source files are formatted using tabs (the recommended setting is a
tab width equivalent to 4 spaces).


File: TheLogtalkHandbook-3.27.0.info,  Node: code_metrics,  Next: dead_code_scanner,  Prev: assertions,  Up: Developer Tools

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

* Menu:

* API documentation: API documentation<2>.
* Loading: Loading<2>.
* Available metrics::
* Defining new metrics::
* Third-party tools::


File: TheLogtalkHandbook-3.27.0.info,  Node: API documentation<2>,  Next: Loading<2>,  Up: code_metrics

5.3.1 API documentation
-----------------------

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#code-metrics(1)

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.

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

   (1) https://logtalk.org/docs/library_index.html#code-metrics


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading<2>,  Next: Available metrics,  Prev: API documentation<2>,  Up: code_metrics

5.3.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(code_metrics(loader)).


File: TheLogtalkHandbook-3.27.0.info,  Node: Available metrics,  Next: Defining new metrics,  Prev: Loading<2>,  Up: code_metrics

5.3.3 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’)

All metrics require the source code to be analyzed to be loaded with the
‘source_data’ flag turned on.

A helper object, ‘code_metrics’, is also provided allowing running all
loaded individual metrics.

For usage examples, see the ‘SCRIPT.txt’ file in the tool directory.

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",
     }


File: TheLogtalkHandbook-3.27.0.info,  Node: Defining new metrics,  Next: Third-party tools,  Prev: Available metrics,  Up: code_metrics

5.3.4 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.27.0.info,  Node: Third-party tools,  Prev: Defining new metrics,  Up: code_metrics

5.3.5 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.27.0.info,  Node: dead_code_scanner,  Next: debug_messages,  Prev: code_metrics,  Up: Developer Tools

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

  1. There is no scope directive for them.

  2. They are not called, directly or indirectly, by any predicate with
     a (local or inherited) scope directive.

Predicates (and non-terminals) listed in ‘uses/2’ and ‘use_module/2’
directives but that are not used are also classified as dead code.

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>.
* Known issues::
* Other notes: Other notes<2>.


File: TheLogtalkHandbook-3.27.0.info,  Node: API documentation<3>,  Next: Loading<3>,  Up: dead_code_scanner

5.4.1 API documentation
-----------------------

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#dead-code-scanner(1)

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.

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

   (1) https://logtalk.org/docs/library_index.html#dead-code-scanner


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading<3>,  Next: Known issues,  Prev: API documentation<3>,  Up: dead_code_scanner

5.4.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(dead_code_scanner(loader)).


File: TheLogtalkHandbook-3.27.0.info,  Node: Known issues,  Next: Other notes<2>,  Prev: Loading<3>,  Up: dead_code_scanner

5.4.3 Known issues
------------------

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, it can be helpful to compile the source files with the
‘optimize’ flag turned on so that the meta-calls may 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.27.0.info,  Node: Other notes<2>,  Prev: Known issues,  Up: dead_code_scanner

5.4.4 Other notes
-----------------

All source files are formatted using tabs (the recommended setting is a
tab width equivalent to 4 spaces).


File: TheLogtalkHandbook-3.27.0.info,  Node: debug_messages,  Next: debugger,  Prev: dead_code_scanner,  Up: Developer Tools

5.5 ‘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>.
* Usage::
* Other notes: Other notes<3>.


File: TheLogtalkHandbook-3.27.0.info,  Node: API documentation<4>,  Next: Loading<4>,  Up: debug_messages

5.5.1 API documentation
-----------------------

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#debug_messages(1)

For general information on debugging, open in a web browser the
following file and consult the debugging section of the User Manual:

manuals/userman/debugging.html(2)

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

   (1) https://logtalk.org/docs/library_index.html#debug_messages

   (2) https://logtalk.org/manuals/userman/debugging.html


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading<4>,  Next: Usage,  Prev: API documentation<4>,  Up: debug_messages

5.5.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(debug_messages(loader)).


File: TheLogtalkHandbook-3.27.0.info,  Node: Usage,  Next: Other notes<3>,  Prev: Loading<4>,  Up: debug_messages

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

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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Other notes<3>,  Prev: Usage,  Up: debug_messages

5.5.4 Other notes
-----------------

All source files are formatted using tabs (the recommended setting is a
tab width equivalent to 4 spaces).


File: TheLogtalkHandbook-3.27.0.info,  Node: debugger,  Next: diagrams,  Prev: debug_messages,  Up: Developer Tools

5.6 ‘debugger’
==============

This tool provides the default Logtalk command-line debugger.

* Menu:

* API documentation: API documentation<5>.
* Loading: Loading<5>.
* Usage: Usage<2>.
* Known issues: Known issues<2>.
* Other notes: Other notes<4>.


File: TheLogtalkHandbook-3.27.0.info,  Node: API documentation<5>,  Next: Loading<5>,  Up: debugger

5.6.1 API documentation
-----------------------

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#debugger(1)

For more information on using the debugger, consult the debugging
section of the User Manual:

manuals/userman/debugging.html(2)

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

   (1) https://logtalk.org/docs/library_index.html#debugger

   (2) https://logtalk.org/manuals/userman/debugging.html


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading<5>,  Next: Usage<2>,  Prev: API documentation<5>,  Up: debugger

5.6.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.27.0.info,  Node: Usage<2>,  Next: Known issues<2>,  Prev: Loading<5>,  Up: debugger

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

Logtalk also provides basic support for the SWI-Prolog graphical tracer.
The required settings are described in the ‘settings-sample.lgt’ file.

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.27.0.info,  Node: Known issues<2>,  Next: Other notes<4>,  Prev: Usage<2>,  Up: debugger

5.6.4 Known issues
------------------

Line number spy points require a Prolog backend compiler that supports
accessing read term starting line but only some systems (B-Prolog,
JIProlog, Lean 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.27.0.info,  Node: Other notes<4>,  Prev: Known issues<2>,  Up: debugger

5.6.5 Other notes
-----------------

All source files are formatted using tabs (the recommended setting is a
tab width equivalent to 4 spaces).


File: TheLogtalkHandbook-3.27.0.info,  Node: diagrams,  Next: doclet,  Prev: debugger,  Up: Developer Tools

5.7 ‘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 navigating complex code by 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 access entity code complexity.

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>.
* Supported diagrams::
* Graph elements::
* Supported graph languages::
* Customization::
* Linking diagrams::
* Creating diagrams for Prolog module applications::
* Creating diagrams for plain Prolog files::
* Other notes: Other notes<5>.


File: TheLogtalkHandbook-3.27.0.info,  Node: API documentation<6>,  Next: Loading<6>,  Up: diagrams

5.7.1 API documentation
-----------------------

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#diagrams(1)

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.

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

   (1) https://logtalk.org/docs/library_index.html#diagrams


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading<6>,  Next: Supported diagrams,  Prev: API documentation<6>,  Up: diagrams

5.7.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(diagrams(loader)).


File: TheLogtalkHandbook-3.27.0.info,  Node: Supported diagrams,  Next: Graph elements,  Prev: Loading<6>,  Up: diagrams

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

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

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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Graph elements,  Next: Supported graph languages,  Prev: Supported diagrams,  Up: diagrams

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Supported graph languages,  Next: Customization,  Prev: Graph elements,  Up: diagrams

5.7.5 Supported graph languages
-------------------------------

Currently only the DOT graph language is supported (tested with Graphviz
version 2.40.1 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, stable version 2.40.1 have a bug (fixed in the current git
version) 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.pdf
     circo -Tsvg diagram.dot > diagram.pdf

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).  See
the relevant diagram options below in order to take advantage of these
features.

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 ‘dot’ executable is available from the
system path.  Due to the lack of a Graphviz installer for Windows,
limited test is performed in Windows operating-systems.  Use if possible
the bash script in a POSIX system (macOS, Linux, BSD, …).

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 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.27.0.info,  Node: Customization,  Next: Linking diagrams,  Prev: Supported graph languages,  Up: diagrams

5.7.6 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/omit current date and time (‘true’ or ‘false’; default is ‘true’) 

   - 
          ‘interface(Boolean)’ 
          print/omit public predicates (‘true’ or ‘false’; default is ‘true’) 

   - 
          ‘file_labels(Boolean)’ 
          print/omit file labels (‘true’ or ‘false’; default is ‘true’) 

   - 
          ‘file_extensions(Boolean)’ 
          print/omit file name extensions (‘true’ or ‘false’; default is ‘true’) 

   - 
          ‘relation_labels(Boolean)’ 
          print/omit entity relation labels (‘true’ or ‘false’; default is ‘true’) 

   - 
          ‘externals(Boolean)’ 
          print/omit external nodes (‘true’ or ‘false’; default is ‘true’) 

   - 
          ‘node_type_captions(Boolean)’ 
          print/omit node type captions (‘true’ or ‘false’; default is ‘true’) 

   - 
          ‘inheritance_relations(Boolean)’ 
          print/omit inheritance relations (‘true’ or ‘false’; default is ‘true’ for entity inheritance diagrams and ‘false’ for other entity diagrams) 

   - 
          ‘provide_relations(Boolean)’ 
          print/omit provide relations (‘true’ or ‘false’; default is ‘false’) 

   - 
          ‘xref_relations(Boolean)’ 
          print/omit predicate call cross-reference relations (‘true’ or ‘false’; default depends on the specific diagram) 

   - 
          ‘xref_calls(Boolean)’ 
          print/omit 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 (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/omit current date and time (‘true’ or ‘false’; default is ‘true’) 

   - 
          ‘directory_paths(Boolean)’ 
          print/omit file directory paths (‘true’ or ‘false’; default is ‘false’) 

   - 
          ‘file_extensions(Boolean)’ 
          print/omit 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 (a list of atoms; default is an empty list) 

   - 
          ‘relation_labels(Boolean)’ 
          print/omit entity relation labels (‘true’ or ‘false’; default is ‘false’) 

   - 
          ‘externals(Boolean)’ 
          print/omit external nodes (‘true’ or ‘false’; default is ‘true’) 

   - 
          ‘node_type_captions(Boolean)’ 
          print/omit 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/omit current date and time (‘true’ or ‘false’; default is ‘true’) 

   - 
          ‘directory_paths(Boolean)’ 
          print/omit 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 (a list of atoms; default is an empty list) 

   - 
          ‘relation_labels(Boolean)’ 
          print/omit entity relation labels (‘true’ or ‘false’; default is ‘false’) 

   - 
          ‘externals(Boolean)’ 
          print/omit external nodes (‘true’ or ‘false’; default is ‘true’) 

   - 
          ‘node_type_captions(Boolean)’ 
          print/omit 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 be used together with the option
‘directory_paths(true)’, in particular when generating library,
directory, or file diagrams that reference external libraries,
directories, or files.

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.27.0.info,  Node: Linking diagrams,  Next: Creating diagrams for Prolog module applications,  Prev: Customization,  Up: diagrams

5.7.7 Linking diagrams
----------------------

When using SVG output, it’s possible to generate diagrams that link to
other diagrams and also diagrams that link to API documentation and
source code repositories.

For generating links between diagrams, use the ‘zoom(true)’ option.
This option allows (1) linking library diagrams to entity diagrams to
predicate cross-referencing diagrams and (2) linking directory diagrams
to file diagrams.  The sub-diagrams are automatically generated.  E.g.
using the predicates that generate library diagrams will automatically
also generate the entity and predicate cross-referencing diagrams.  This
feature allows using diagrams for navigating complex code by zooming
into details.

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.  See the
‘SCRIPT.txt’ file in the tool directory for some usage examples.


File: TheLogtalkHandbook-3.27.0.info,  Node: Creating diagrams for Prolog module applications,  Next: Creating diagrams for plain Prolog files,  Prev: Linking diagrams,  Up: diagrams

5.7.8 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.27.0.info,  Node: Creating diagrams for plain Prolog files,  Next: Other notes<5>,  Prev: Creating diagrams for Prolog module applications,  Up: diagrams

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Other notes<5>,  Prev: Creating diagrams for plain Prolog files,  Up: diagrams

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

All source files are formatted using tabs (the recommended setting is a
tab width equivalent to 4 spaces).


File: TheLogtalkHandbook-3.27.0.info,  Node: doclet,  Next: help,  Prev: diagrams,  Up: Developer Tools

5.8 ‘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::
* Other notes: Other notes<6>.


File: TheLogtalkHandbook-3.27.0.info,  Node: API documentation<7>,  Next: Loading<7>,  Up: doclet

5.8.1 API documentation
-----------------------

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#doclet(1)

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.

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

   (1) https://logtalk.org/docs/library_index.html#doclet


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading<7>,  Next: Automating running doclets,  Prev: API documentation<7>,  Up: doclet

5.8.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(doclet(loader)).


File: TheLogtalkHandbook-3.27.0.info,  Node: Automating running doclets,  Next: Integration with the make tool,  Prev: Loading<7>,  Up: doclet

5.8.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.27.0.info,  Node: Integration with the make tool,  Next: Other notes<6>,  Prev: Automating running doclets,  Up: doclet

5.8.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 checks that a single doclet object
is loaded and, if true, sends an ‘update/0’ message to it.


File: TheLogtalkHandbook-3.27.0.info,  Node: Other notes<6>,  Prev: Integration with the make tool,  Up: doclet

5.8.5 Other notes
-----------------

All source files are formatted using tabs (the recommended setting is a
tab width equivalent to 4 spaces).


File: TheLogtalkHandbook-3.27.0.info,  Node: help,  Next: lgtdoc,  Prev: doclet,  Up: Developer Tools

5.9 ‘help’
==========

This tool provides basic on-line help for Logtalk when running in a
limited set of operating-systems.

* Menu:

* API documentation: API documentation<8>.
* Loading: Loading<8>.
* Supported operating-systems::
* Known issues: Known issues<3>.
* Other notes: Other notes<7>.


File: TheLogtalkHandbook-3.27.0.info,  Node: API documentation<8>,  Next: Loading<8>,  Up: help

5.9.1 API documentation
-----------------------

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#help(1)

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.

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

   (1) https://logtalk.org/docs/library_index.html#help


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading<8>,  Next: Supported operating-systems,  Prev: API documentation<8>,  Up: help

5.9.2 Loading
-------------

     | ?- logtalk_load(help(loader)).


File: TheLogtalkHandbook-3.27.0.info,  Node: Supported operating-systems,  Next: Known issues<3>,  Prev: Loading<8>,  Up: help

5.9.3 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.27.0.info,  Node: Known issues<3>,  Next: Other notes<7>,  Prev: Supported operating-systems,  Up: help

5.9.4 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.27.0.info,  Node: Other notes<7>,  Prev: Known issues<3>,  Up: help

5.9.5 Other notes
-----------------

All source files are formatted using tabs (the recommended setting is a
tab width equivalent to 4 spaces).


File: TheLogtalkHandbook-3.27.0.info,  Node: lgtdoc,  Next: lgtunit,  Prev: help,  Up: Developer Tools

5.10 ‘lgtdoc’
=============

This folder provides the default Logtalk documenting tool, which is
focused on generating API documentation for applications.

This documenting tool uses Logtalk’s structural reflection support to
extract and output in XML format relevant documentation about a source
code file, a library or directory of source files, or all loaded source
files.  The tool predicates allows you to set several options for the
XML files, including the output directory.

The ‘lgtdoc/xml’ directory includes 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.  See
also the ‘lgtdoc/xml/NOTES.md’ for details.

For information on documenting your source code, consult the documenting
section of the User Manual:

manuals/userman/documenting.html(1)

* Menu:

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

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

   (1) https://logtalk.org/manuals/userman/documenting.html


File: TheLogtalkHandbook-3.27.0.info,  Node: API documentation<9>,  Next: Loading<9>,  Up: lgtdoc

5.10.1 API documentation
------------------------

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#lgtdoc(1)

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

   (1) https://logtalk.org/docs/library_index.html#lgtdoc


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading<9>,  Next: Documenting source code,  Prev: API documentation<9>,  Up: lgtdoc

5.10.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(lgtdoc(loader)).


File: TheLogtalkHandbook-3.27.0.info,  Node: Documenting source code,  Next: Generating documentation,  Prev: Loading<9>,  Up: lgtdoc

5.10.3 Documenting source code
------------------------------

Documenting Logtalk source code (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.  The source files to be documented `must' be loaded prior to
using this tool predicates to generate the documentation.


File: TheLogtalkHandbook-3.27.0.info,  Node: Generating documentation,  Next: Other notes<8>,  Prev: Documenting source code,  Up: lgtdoc

5.10.4 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 application directory.  For example, assuming that we
want to generate HTML documentation:

     $ cd xml_docs
     $ lgt2html -t "My app"

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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Other notes<8>,  Prev: Generating documentation,  Up: lgtdoc

5.10.5 Other notes
------------------

All source files are formatted using tabs (the recommended setting is a
tab width equivalent to 4 spaces).


File: TheLogtalkHandbook-3.27.0.info,  Node: lgtunit,  Next: make,  Prev: lgtdoc,  Up: Developer Tools

5.11 ‘lgtunit’
==============

The ‘lgtunit’ tool provides testing support for Logtalk.  It can also be
used for testing Prolog 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>.
* Writing, compiling, and loading unit tests: Writing compiling and loading unit tests.
* Running unit tests::
* Unit test dialects::
* User-defined unit test dialects::
* QuickCheck::
* Skipping unit tests::
* Testing non-deterministic predicates::
* Testing generators::
* Testing input/output predicates::
* Suppressing tested predicates output::
* Unit tests with timeout limits::
* Setup and cleanup goals::
* Test annotations::
* Debugging failed unit tests::
* Code coverage::
* Automating running unit tests::
* Utility predicates::
* Exporting unit test results in xUnit XML format::
* Exporting unit test results in the TAP output format::
* Exporting code coverage results in XML format::
* Known issues: Known issues<4>.
* Other notes: Other notes<9>.


File: TheLogtalkHandbook-3.27.0.info,  Node: Main files,  Next: API documentation<10>,  Up: lgtunit

5.11.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.27.0.info,  Node: API documentation<10>,  Next: Loading<10>,  Prev: Main files,  Up: lgtunit

5.11.2 API documentation
------------------------

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#lgtunit(1)

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

   (1) https://logtalk.org/docs/library_index.html#lgtunit


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading<10>,  Next: Writing compiling and loading unit tests,  Prev: API documentation<10>,  Up: lgtunit

5.11.3 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(lgtunit(loader)).


File: TheLogtalkHandbook-3.27.0.info,  Node: Writing compiling and loading unit tests,  Next: Running unit tests,  Prev: Loading<10>,  Up: lgtunit

5.11.4 Writing, compiling, and loading unit tests
-------------------------------------------------

In order to write your own unit tests, define objects extending the
‘lgtunit’ object.  You may start from the ‘../../tests-sample.lgt’ file.
For example:

     :- object(tests,
         extends(lgtunit)).

         ...

     :- end_object.

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(my_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.

See the ‘../../tester-sample.lgt’ file for an example of a loader file
for compiling and loading the ‘lgtunit’ tool, the source code under
testing, the unit tests, and for automatically run all the tests after
loading.  See e.g.  the ‘../../tests’ directory for examples of unit
tests.

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.27.0.info,  Node: Running unit tests,  Next: Unit test dialects,  Prev: Writing compiling and loading unit tests,  Up: lgtunit

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

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).  In this case, you can run all test subsets using the goal:

     | ?- lgtunit::run_test_sets([...])

where the ‘run_test_sets/1’ predicate argument is a list of 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:

     make(check).

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.27.0.info,  Node: Unit test dialects,  Next: User-defined unit test dialects,  Prev: Running unit tests,  Up: lgtunit

5.11.6 Unit test dialects
-------------------------

Multiple test `dialects' are supported by default.  See the next section
on how to define your own test dialects.

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,
‘Test’, is an atom that identifies it and 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 

   - 
          ‘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.  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 a ‘n/1’
option to specify the number of random tests that will be generated/run
(default is 100) and a ‘s/1’ option to specify the maximum number of
shrink operations (default is 64).

In all dialects, ‘Test’ is a callable term, usually an atom, that
uniquely identifies a test.  This simplifies reporting failed tests and
running tests selectively.  An error message is printed if 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.

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.

Parameterized unit tests can be easily defined by using parametric
objects.

Note: when using the ‘(<<)/2’ debugging control construct to access and
test an object local (i.e.  non-public) predicates, make sure that the
compiler flag ‘context_switching_calls’ is set to ‘allow’ for those
objects.


File: TheLogtalkHandbook-3.27.0.info,  Node: User-defined unit test dialects,  Next: QuickCheck,  Prev: Unit test dialects,  Up: lgtunit

5.11.7 User-defined unit 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
idiom 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.  When that is not required, a simpler alternative
is to change the expansion of the ‘begin_of_file’ virtual term to:

     term_expansion(
         begin_of_file,
         [
             (:- set_logtalk_flag(hook,lgtunit)),
             (:- object(tests,extends(lgtunit)))
         ]
     ).

This allows simplifying the driver file to:

     :- initialization((
         set_logtalk_flag(report, warnings),
         logtalk_load(lgtunit(loader)),
         logtalk_load(simple_dialect),
         logtalk_load(tests, [hook(simple_dialect)]),
         tests::run
     )).


File: TheLogtalkHandbook-3.27.0.info,  Node: QuickCheck,  Next: Skipping unit tests,  Prev: User-defined unit test dialects,  Up: lgtunit

5.11.8 QuickCheck
-----------------

QuickCheck was originally developed for Haskell.  Implementations for
several other programming languages soon followed.  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 ‘quick_check/3’ predicate returns results in reified form:

   - ‘passed’,

   - ‘failed(Goal)’ with Goal being the random test that failed

   - ‘error(Error, Template)’ or ‘error(Error, Goal)’

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 1 shrink):
     *       random::random(0.09230089279334841)
     no

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
     yes

Properties are expressed using predicates.  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 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-parametrizable) 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.

An optional argument, ‘n/1’, allows the specification of the number of
random tests that will be generated and run.  The maximum number of
shrink operations can be specified using the option ‘s/1’.

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.

Note that is possible to complement the random tests performed by
QuickCheck by defining a surrogate predicate that calls the predicate
being tested and performs additional checks on the generated random
values.


File: TheLogtalkHandbook-3.27.0.info,  Node: Skipping unit tests,  Next: Testing non-deterministic predicates,  Prev: QuickCheck,  Up: lgtunit

5.11.9 Skipping unit tests
--------------------------

A unit 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.27.0.info,  Node: Testing non-deterministic predicates,  Next: Testing generators,  Prev: Skipping unit tests,  Up: lgtunit

5.11.10 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.  Ground results can be
compared using the ‘==/2’ predicate.  Non-ground results can be compared
using the ‘variant/2’ predicate provided by ‘lgtunit’.


File: TheLogtalkHandbook-3.27.0.info,  Node: Testing generators,  Next: Testing input/output predicates,  Prev: Testing non-deterministic predicates,  Up: lgtunit

5.11.11 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(solution(X,Y,Z), my_test(X,Y,Z))
         ).


File: TheLogtalkHandbook-3.27.0.info,  Node: Testing input/output predicates,  Next: Suppressing tested predicates output,  Prev: Testing generators,  Up: lgtunit

5.11.12 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.  There
is also a small set of helper predicates for dealing with stream handles
and stream positions.

For practical examples, check the included tests for Prolog conformance
of standard input/output predicates.


File: TheLogtalkHandbook-3.27.0.info,  Node: Suppressing tested predicates output,  Next: Unit tests with timeout limits,  Prev: Testing input/output predicates,  Up: lgtunit

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Unit tests with timeout limits,  Next: Setup and cleanup goals,  Prev: Suppressing tested predicates output,  Up: lgtunit

5.11.14 Unit 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.27.0.info,  Node: Setup and cleanup goals,  Next: Test annotations,  Prev: Unit tests with timeout limits,  Up: lgtunit

5.11.15 Setup and cleanup goals
-------------------------------

A unit 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.

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.27.0.info,  Node: Test annotations,  Next: Debugging failed unit tests,  Prev: Setup and cleanup goals,  Up: lgtunit

5.11.16 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.27.0.info,  Node: Debugging failed unit tests,  Next: Code coverage,  Prev: Test annotations,  Up: lgtunit

5.11.17 Debugging failed unit tests
-----------------------------------

Debugging of failed unit tests is usually easy if you use assertions as
the reason for the assertion failures is printed out.  Thus, use
preferably the ‘test/2-3’ dialects with ‘true(Assertion)’ or
‘deterministic(Assertion)’ outcomes.  If a test checks multiple
assertions, you can use the predicate ‘assertion/2’ in the test body.

In order 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’ files that load code and tests
in debug mode and also load the debugger.


File: TheLogtalkHandbook-3.27.0.info,  Node: Code coverage,  Next: Automating running unit tests,  Prev: Debugging failed unit tests,  Up: lgtunit

5.11.18 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 unit 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 the two
clauses:

     cover(foo).
     cover(bar).

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Automating running unit tests,  Next: Utility predicates,  Prev: Code coverage,  Up: lgtunit

5.11.19 Automating running unit 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.  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

An HTML version of this man page can be found at:

‘https://logtalk.org/man/logtalk_tester.html’

Additional advice on testing and on automating testing using continuous
integration servers can be found at:

‘https://logtalk.org/testing.html’


File: TheLogtalkHandbook-3.27.0.info,  Node: Utility predicates,  Next: Exporting unit test results in xUnit XML format,  Prev: Automating running unit tests,  Up: lgtunit

5.11.20 Utility predicates
--------------------------

The ‘lgtunit’ tool provides several public utility predicates to
simplify writing unit tests:

   - 
          ‘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(Name, Goal)’ 
          to generate an exception in case the goal argument fails or throws an error 

   - 
          ‘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 also 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 to the tests object, you must
call ‘assertion/1-2’ using an implicit or explicit message instead of a
using `super' call.  The reason is that the ‘assertion/1-2’ predicates
are declared as meta-predicates and thus calls the assertion goal in the
`sender', which would be the ‘lgtunit’ object in the case of a ‘^^/2’
call (as they preserve 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-3’ and ‘deterministic/1-2’ 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.

Consult the ‘lgtunit’ object documentation (‘docs/tools.html’) for
further details on these predicates.


File: TheLogtalkHandbook-3.27.0.info,  Node: Exporting unit test results in xUnit XML format,  Next: Exporting unit test results in the TAP output format,  Prev: Utility predicates,  Up: lgtunit

5.11.21 Exporting unit test results in xUnit XML format
-------------------------------------------------------

To output test results in the xUnit XML format, 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, the single
xUnit report is created in the directory of the first test suite object
in the set.


File: TheLogtalkHandbook-3.27.0.info,  Node: Exporting unit test results in the TAP output format,  Next: Exporting code coverage results in XML format,  Prev: Exporting unit test results in xUnit XML format,  Up: lgtunit

5.11.22 Exporting unit 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 ‘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.


File: TheLogtalkHandbook-3.27.0.info,  Node: Exporting code coverage results in XML format,  Next: Known issues<4>,  Prev: Exporting unit test results in the TAP output format,  Up: lgtunit

5.11.23 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 URL should be a permanent link (i.e.  it should include
the commit SHA1).  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:

     $ 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 on your own servers, the
‘url’ parameter may not contain a ‘bitbucket’, ‘github’, or ‘gitlab’
string.  In this case, you can use the XSLT parameter ‘host’ to indicate
which service are you running.


File: TheLogtalkHandbook-3.27.0.info,  Node: Known issues<4>,  Next: Other notes<9>,  Prev: Exporting code coverage results in XML format,  Up: lgtunit

5.11.24 Known issues
--------------------

Parameter variables (‘_VariableName_’) cannot currently be used in the
definition of test options (e.g.  ‘condition/1’).

Deterministic unit tests are currently not available when using Lean
Prolog or Quintus Prolog as backend compilers do the lack of a required
built-in support that cannot be sensibly defined in Prolog.

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 by using ‘include/1’ directives.
These two 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.27.0.info,  Node: Other notes<9>,  Prev: Known issues<4>,  Up: lgtunit

5.11.25 Other notes
-------------------

All source files are formatted using tabs (the recommended setting is a
tab width equivalent to 4 spaces).


File: TheLogtalkHandbook-3.27.0.info,  Node: make,  Next: ports_profiler,  Prev: lgtunit,  Up: Developer Tools

5.12 ‘make’
===========

Logtalk provides a make tool supporting several targets using the
‘logtalk_make/0-1’ built-in predicates.

* Menu:

* API documentation: API documentation<11>.


File: TheLogtalkHandbook-3.27.0.info,  Node: API documentation<11>,  Up: make

5.12.1 API documentation
------------------------

To consult the documentation of the ‘logtalk_make/0-1’ built-in
predicates, open in a web browser the links:

   - manuals/refman/logtalk_make_0.html(1)

   - manuals/refman/logtalk_make_1.html(2)

   - manuals/refman/logtalk_make_target_action_1.html(3)

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

   (1) https://logtalk.org/manuals/refman/logtalk_make_0.html

   (2) https://logtalk.org/manuals/refman/logtalk_make_1.html

   (3) 
https://logtalk.org/manuals/refman/logtalk_make_target_action_1.html


File: TheLogtalkHandbook-3.27.0.info,  Node: ports_profiler,  Next: profiler,  Prev: make,  Up: Developer Tools

5.13 ‘ports_profiler’
=====================

The ‘ports_profiler.lgt’ source file defines a simple predicate
execution box model port profiler tool (inspired by the ECLiPSe
‘port_profiler’ tool).  The box model is the same used in the debugger
tool.

The Logtalk predicate execution box model 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 counts and
reports the number of times each port is traversed during the execution
of queries.  It 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>.
* Compiling source files for port profiling::
* Generating profiling data::
* Printing profiling data reports::
* Interpreting profiling data::
* Known issues: Known issues<5>.
* Other notes: Other notes<10>.


File: TheLogtalkHandbook-3.27.0.info,  Node: API documentation<12>,  Next: Loading<11>,  Up: ports_profiler

5.13.1 API documentation
------------------------

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#ports_profiler(1)

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.

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

   (1) https://logtalk.org/docs/library_index.html#ports_profiler


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading<11>,  Next: Compiling source files for port profiling,  Prev: API documentation<12>,  Up: ports_profiler

5.13.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.27.0.info,  Node: Compiling source files for port profiling,  Next: Generating profiling data,  Prev: Loading<11>,  Up: ports_profiler

5.13.3 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.27.0.info,  Node: Generating profiling data,  Next: Printing profiling data reports,  Prev: Compiling source files for port profiling,  Up: ports_profiler

5.13.4 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.27.0.info,  Node: Printing profiling data reports,  Next: Interpreting profiling data,  Prev: Generating profiling data,  Up: ports_profiler

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Interpreting profiling data,  Next: Known issues<5>,  Prev: Printing profiling data reports,  Up: ports_profiler

5.13.6 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.27.0.info,  Node: Known issues<5>,  Next: Other notes<10>,  Prev: Interpreting profiling data,  Up: ports_profiler

5.13.7 Known issues
-------------------

Determinism information is currently not available when using Lean
Prolog or Quintus Prolog as backend compilers.


File: TheLogtalkHandbook-3.27.0.info,  Node: Other notes<10>,  Prev: Known issues<5>,  Up: ports_profiler

5.13.8 Other notes
------------------

All source files are formatted using tabs (the recommended setting is a
tab width equivalent to 4 spaces).


File: TheLogtalkHandbook-3.27.0.info,  Node: profiler,  Next: wrapper,  Prev: ports_profiler,  Up: Developer Tools

5.14 ‘profiler’
===============

This tool contains simple wrappers for selected Prolog profiler tools.

* Menu:

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


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading<12>,  Next: Supported backend Prolog compilers,  Up: profiler

5.14.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.27.0.info,  Node: Supported backend Prolog compilers,  Next: Compiling source code for profiling,  Prev: Loading<12>,  Up: profiler

5.14.2 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) by typing:

     | ?- logtalk << (prolog_statistics:profile(... :: ...)).

Given that ‘prolog_statistics:profile/1’ is a meta-predicate, Logtalk
will compile its argument before calling it.  Don’t forget, however, to
load the ‘prolog_statistics’ module `before' using or compiling calls to
the ‘profile/1’ predicate by typing:

     | ?- use_module(library(statistics)).

The profiler support makes no attempt to conceal the internal Logtalk
compiler/runtime predicates or the generated 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 be listed when your code uses dynamic binding.


File: TheLogtalkHandbook-3.27.0.info,  Node: Compiling source code for profiling,  Next: Other notes<11>,  Prev: Supported backend Prolog compilers,  Up: profiler

5.14.3 Compiling source code for profiling
------------------------------------------

In order to get user-level object and predicate names instead of
compiler generated names when using the SWI-Prolog and YAP profilers you
must set ‘code_prefix’ flag to a value other than the default ‘$’.  For
example:

     | ?- set_logtalk_flag(code_prefix, '.').

See also the ‘settings-sample’ file for automating the necessary setup
at Logtalk startup.


File: TheLogtalkHandbook-3.27.0.info,  Node: Other notes<11>,  Prev: Compiling source code for profiling,  Up: profiler

5.14.4 Other notes
------------------

All source files are formatted using tabs (the recommended setting is a
tab width equivalent to 4 spaces).


File: TheLogtalkHandbook-3.27.0.info,  Node: wrapper,  Prev: profiler,  Up: Developer Tools

5.15 ‘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<13>.
* Loading: Loading<13>.
* Workflows::
* Customization: Customization<2>.
* Current limitations::
* Other notes: Other notes<12>.


File: TheLogtalkHandbook-3.27.0.info,  Node: API documentation<13>,  Next: Loading<13>,  Up: wrapper

5.15.1 API documentation
------------------------

To consult this tool API documentation, open in a web browser the link:

docs/library_index.html#wrapper(1)

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

   (1) https://logtalk.org/docs/library_index.html#wrapper


File: TheLogtalkHandbook-3.27.0.info,  Node: Loading<13>,  Next: Workflows,  Prev: API documentation<13>,  Up: wrapper

5.15.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(wrapper(loader)).


File: TheLogtalkHandbook-3.27.0.info,  Node: Workflows,  Next: Customization<2>,  Prev: Loading<13>,  Up: wrapper

5.15.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.27.0.info,  Node: Customization<2>,  Next: Current limitations,  Prev: Workflows,  Up: wrapper

5.15.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.27.0.info,  Node: Current limitations,  Next: Other notes<12>,  Prev: Customization<2>,  Up: wrapper

5.15.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.27.0.info,  Node: Other notes<12>,  Prev: Current limitations,  Up: wrapper

5.15.6 Other notes
------------------

All source files are formatted using tabs (the recommended setting is a
tab width equivalent to 4 spaces).


File: TheLogtalkHandbook-3.27.0.info,  Node: Glossary,  Next: Index<2>,  Prev: Developer Tools,  Up: Top

6 Glossary
**********

abstract class

     A *note class: 84a. that cannot be instantiated.  Usually used to
     contain common predicates that are inherited by other classes.

abstract method

     A *note method: 84c. implementing an algorithm whose step
     corresponds to calls to methods defined in the descendants of the
     object (or *note category: 84d.) 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: 84a. or a parent *note prototype: 84f. 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: 84c. that can be called from within any
     object or *note category: 84d.  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 objects and *note categories:
     84d.

category

     A set of predicates directives 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: e1.
     of existing objects.  A category should be functionally-cohesive,
     defining a single functionality.

class

     An *note object: 492. that specializes another object, interpreted
     as its superclass.  Classes 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: 852. 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.

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: e1. 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: 577. whose main purpose is to generate
     documentation for e.g.  a *note library: 51. 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: 857. and *note
     predicate definition: 858. to verify the validity of a *note
     message: 852. (or a *note super call: e9.) 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.

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

entity

     Generic name for Logtalk compilation units: *note objects: 492,
     *note categories: 84d, and *note protocols: 41.  Entities share a
     single namespace (i.e.  entity *note identifiers: 85c. must be
     unique).

entity directive

     A directive that affects how Logtalk entities (*note objects: 492,
     *note categories: 84d, or *note protocols: 41.) are used or
     compiled.

event

     The sending of a *note message: 852. 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.

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: d5. compiler flag.  It can also
     be specified using a *note set_logtalk_flag/2: 263. directive in
     the source files to be expanded.

hot patching

     The act of fixing entity directives and predicates or adding new
     entity directives and predicates to loaded entities in a running
     application without requiring access to the entities source code or
     restarting the application.

identity

     Property of an entity 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: 84d.
     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 entity inherits predicate directives 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: 863,
     *note protected inheritance: 864, and *note private inheritance:
     865.

instance

     An object that instantiates one another object, interpreted as its
     *note class: 84a.  An object may instantiate multiple objects (also
     known as multiple instantiation).

instantiation

     The process of creating a new class instance.  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: 41.

lambda expression

     A compound term that can be used in place of a goal or closure
     meta-argument and that abstracts a *note predicate definition: 858.
     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: 145.  All
     used global variables must be explicitly listed in a lambda
     expression.

lambda parameter

     A term (usually a variable or a non-ground compound term) that is
     local to a *note lambda expression: 145.  All lambda parameters
     must be explicitly enumerated in a lambda expression.

late binding

     See *note dynamic binding: 34.

library

     A directory containing source files.  See also *note library alias:
     5aa. and *note library notation: ad.

library alias

     An atom that can be used as an alias for a *note library: 51. full
     path.  Library aliases and their corresponding paths can be defined
     using the *note logtalk_library_path/2: 25d. predicate.  See also
     *note library notation: ad.

library notation

     A compound term where the name is a *note library alias: 5aa. and
     the single argument is a *note source file: 577. 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: 577. whose main purpose is to load a set of
     source files.

local predicate

     A predicate that is defined in an object (or in a *note category:
     84d.) but that is not listed in a *note scope directive: 195.
     These predicates behave like private predicates but are invisible
     to the reflection *note built-in methods: 850.  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: 857, to check if the message is within the
     scope of the sender, and a lookup for the *note predicate
     definition: 858. 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 closure 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: 86b.  For
     example, *note call/1-N: 144. and *note findall/3: 175. are
     built-in meta-predicates.

metaclass

     The *note class: 84a. 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: 858. used to answer a *note
     message: 852. 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 predicate
     directives 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: 85e. 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: 85b. and *note source files: 577.  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: 195. and a *note
     multifile/1: 134. directive for the predicate.

object

     An entity characterized by an *note identity: 85c. and a set of
     predicate directives 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 ‘_VariableName_’.  Occurrences of
     parameter variables in entity clauses are implicitly unified with
     the corresponding entity parameters.

parametric category

     See *note parametric entity: 5d1.

parametric entity

     An *note object: 492. or *note category: 84d. whose *note
     identifier: 85c. 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: 5d1.

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: 5d1.
     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: 492. or *note categories: 84d.
     they are also referred to as *note methods: 84c.

predicate alias

     An alternative functor (‘Name/Arity’) for a predicate.  Predicate
     aliases can be defined for any inherited predicate using the *note
     alias/2: 12d. directive and for predicates listed in *note uses/2:
     12a. and *note use_module/2: 16b. 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 declaration

     A predicate declaration is composed by a set of predicate
     directives, which must include ar least a *note scope directive:
     195.

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 directive

     A directive that specifies a predicate property that affects how
     predicates are called or compiled.

predicate scope container

     The object that inherits a *note predicate declaration: 857. from
     an imported *note category: 84d. or an implemented *note protocol:
     41.

predicate scope directive

     A directive that declares a predicate by specifying its visibility
     as `public', `protected', or `private'.

primary predicate declaration

     See *note multifile predicate: 870.

private inheritance

     All public and protected predicates are inherited as private
     predicates.  See also *note public inheritance: 863. and *note
     protected inheritance: 864.

private predicate

     A predicate that can only be called from the object that contains
     its *note scope directive: 195.

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: 863. and *note private inheritance: 865.

protected predicate

     A predicate that can only be called from the object containing its
     *note scope directive: 195. or from an object that inherits the
     predicate.

protocol

     An entity that contains *note predicate declarations: 857.  A
     predicate is declared using a *note scope directive: 195.  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: 864. and *note private inheritance:
     865.

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

self

     The object that received the *note message: 852. under processing.

sender

     An object that sends a *note message: 852. to other object.  When a
     message is sent from within a *note category: 84d, the `sender' is
     the object importing the category.

settings file

     A *note source file: 577, compiled and loaded at Logtalk startup,
     mainly defining default values for compiler flags that override the
     defaults found on the backend Prolog compiler *note adapter files:
     11d.

singleton method

     A *note method: 84c. defined in an *note instance: 866. 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: 23e. directive as the first
     term in the first line in the file.

source file directive

     A directive that affects how a *note source file: 577. is compiled.

specialization

     A *note class: 84a. 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: 857. and
     *note predicate definition: 858. when compiling a *note message:
     852. sending call (or a *note super call: e9.).  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.

steadfastness

     A predicate definition is `steadfast' when it still generates only
     correct answers when called with unexpected arguments.  Typically,
     a predicate may not be steadfast when output argument unifications
     can occur before a cut in a predicate clause.

subclass

     A *note class: 84a. that is a specialization, direct or indirectly,
     of another class.

super call

     Call of an inherited (or imported) *note predicate definition: 858.
     Mainly used when redefining an inherited (or imported) predicate to
     call the overridden definition while making additional calls.
     Super calls preserve *note self: 4b. and may require *note dynamic
     binding: 34. if the predicate is dynamic.

superclass

     A *note class: 84a. 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: 84b.

tester file

     A *note source file: 577. 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: 84d,
     `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.

visible predicate

     A predicate that is within scope, a locally defined predicate, a
     *note built-in method: 850, 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) https://logtalk.org/library/expanding_0.html#expanding-0

   (4) https://logtalk.org/library/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.27.0.info,  Node: Index<2>,  Next: Index,  Prev: Glossary,  Up: Top

7 Index
*******


File: TheLogtalkHandbook-3.27.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<113>.       (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<52>.        (line  14)
* abolish_protocol/1; Built-in predicate: Examples<53>.       (line  15)
* abstract class:                        Glossary.            (line   6)
* abstract method:                       Glossary.            (line   9)
* adapter file:                          Glossary.            (line  15)
* after/3; Built-in method:              Examples<132>.       (line  20)
* alias/2; Directive:                    Predicate directives<3>.
                                                              (line   6)
* always_true_or_false_goals; Flag:      Lint flags.          (line  65)
* ancestor:                              Glossary.            (line  21)
* ask_question/5; Built-in method:       Question asking.     (line   6)
* asserta/1; Built-in method:            Examples<105>.       (line  19)
* assertz/1; Built-in method:            Examples<106>.       (line  19)
* backend Prolog compiler:               Glossary.            (line  30)
* 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  41)
* behavioral reflection:                 Black-box view.      (line  16)
* black-box view:                        Transparent-box view.
                                                              (line  22)
* built-in method:                       Glossary.            (line  36)
* built-in predicate:                    Glossary.            (line  42)
* 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  48)
* category/1-3; Directive:               Examples<17>.        (line   7)
* category_property/2; Built-in predicate: Enumerating objects categories and protocols properties.
                                                              (line   6)
* class:                                 Glossary.            (line  56)
* clause/2; Built-in method:             Examples<107>.       (line  19)
* clean; Flag:                           Other flags.         (line 101)
* closed-world assumption:               Glossary.            (line  63)
* code_prefix; Flag:                     Other flags.         (line  25)
* coinduction; Flag:                     Adapter files.       (line 115)
* coinductive predicate:                 Glossary.            (line  71)
* coinductive/1; Directive:              Examples<28>.        (line  17)
* coinductive_success_hook/1-2; Built-in method: Coinduction hooks.
                                                              (line   6)
* complementing category:                Glossary.            (line  77)
* complements; Flag:                     Optional features compilation flags.
                                                              (line   6)
* complements_object/2; Built-in predicate: Examples<59>.     (line  23)
* component:                             Glossary.            (line  82)
* conforms_to_protocol/2-3; Built-in predicate: Examples<58>. (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<95>.    (line  14)
* create_object/4; Built-in predicate:   Examples<49>.        (line  19)
* create_protocol/3; Built-in predicate: Examples<50>.        (line  61)
* current_category/1; Built-in predicate: Enumerating objects categories and protocols.
                                                              (line   6)
* current_event/5; Built-in predicate:   Examples<64>.        (line  15)
* current_logtalk_flag/2; Built-in predicate: Flags.          (line   6)
* current_object/1; Built-in predicate:  Examples<43>.        (line  18)
* current_op/3; Built-in method:         Reflection<2>.       (line   6)
* current_predicate/1; Built-in method:  Examples<102>.       (line  18)
* current_protocol/1; Built-in predicate: Examples<44>.       (line  20)
* debug; Flag:                           Other flags.         (line  66)
* define_events/5; Built-in predicate:   Examples<65>.        (line  14)
* directive:                             Glossary.            (line  90)
* discontiguous/1; Directive:            Examples<29>.        (line  15)
* doclet file:                           Glossary.            (line  95)
* doclet object:                         Glossary.            (line 100)
* domain_error/2; Built-in method:       Examples<118>.       (line  19)
* duplicated_directives; Flag:           Lint flags.          (line  51)
* dynamic binding:                       Glossary.            (line 106)
* dynamic/0; Directive:                  Examples<18>.        (line  25)
* dynamic/1; Directive:                  Examples<30>.        (line  11)
* dynamic_declarations; Flag:            Optional features compilation flags.
                                                              (line  18)
* early binding:                         Glossary.            (line 115)
* elif/1; Directive:                     Examples<13>.        (line  30)
* else/0; Directive:                     Examples<14>.        (line  24)
* encapsulation:                         Glossary.            (line 119)
* encoding/1; Directive:                 Source file directives<2>.
                                                              (line   6)
* encoding_directive; Flag:              Adapter files.       (line  79)
* 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:                         Adapter files.       (line  94)
* entity:                                Glossary.            (line 126)
* entity directive:                      Glossary.            (line 133)
* eos//0; Built-in method:               Examples<135>.       (line  20)
* evaluation_error/1; Built-in method:   Examples<122>.       (line  19)
* event:                                 Glossary.            (line 139)
* events; Flag:                          Optional features compilation flags.
                                                              (line  29)
* existence_error/2; Built-in method:    Examples<119>.       (line  20)
* expand_goal/2; Built-in method:        Examples<141>.       (line  14)
* expand_term/2; Built-in method:        Term and goal expansion<2>.
                                                              (line   6)
* extends_category/2-3; Built-in predicate: Examples<56>.     (line  17)
* extends_object/2-3; Built-in predicate: Objects categories and protocols relations.
                                                              (line   6)
* extends_protocol/2-3; Built-in predicate: Examples<55>.     (line  17)
* findall/3; Built-in method:            Examples<127>.       (line  18)
* findall/4; Built-in method:            Examples<128>.       (line  18)
* forall/2; Built-in method:             Examples<129>.       (line  18)
* forward/1; Built-in method:            Message forwarding.  (line   6)
* goal_expansion/2; Built-in method:     Examples<142>.       (line  13)
* grammar rule:                          Glossary.            (line 146)
* grammar rule non-terminal:             Glossary.            (line 155)
* grammar rule terminal:                 Glossary.            (line 161)
* hook object:                           Glossary.            (line 165)
* hook; Flag:                            Other flags.         (line  92)
* hot patching:                          Glossary.            (line 174)
* identity:                              Glossary.            (line 181)
* if/1; Directive:                       Conditional compilation directives<2>.
                                                              (line   6)
* ignore/1; Built-in method:             Examples<111>.       (line  17)
* implements_protocol/2-3; Built-in predicate: Examples<57>.  (line  17)
* imports_category/2-3; Built-in predicate: Examples<60>.     (line  13)
* include/1; Directive:                  Examples<8>.         (line   7)
* info/1; Directive:                     Examples<22>.        (line  12)
* info/2; Directive:                     Examples<31>.        (line  16)
* inheritance:                           Glossary.            (line 190)
* initialization/1; Directive:           Examples<9>.         (line  19)
* instance:                              Glossary.            (line 200)
* instantiates_class/2-3; Built-in predicate: Examples<61>.   (line  16)
* instantiation:                         Glossary.            (line 206)
* instantiation_error/0; Built-in method: Examples<116>.      (line  17)
* interface:                             Glossary.            (line 213)
* lambda expression:                     Glossary.            (line 217)
* lambda free variable:                  Glossary.            (line 225)
* lambda parameter:                      Glossary.            (line 231)
* lambda_variables; Flag:                Lint flags.          (line  71)
* late binding:                          Glossary.            (line 237)
* library:                               Glossary.            (line 241)
* library alias:                         Glossary.            (line 246)
* library notation:                      Glossary.            (line 253)
* loader file:                           Glossary.            (line 261)
* local predicate:                       Glossary.            (line 266)
* logtalk_compile/1; Built-in predicate: Compiling and loading source files.
                                                              (line   6)
* logtalk_compile/2; Built-in predicate: Examples<85>.        (line  24)
* logtalk_library_path/2; Built-in predicate: Examples<91>.   (line  18)
* logtalk_load/1; Built-in predicate:    Examples<86>.        (line  24)
* logtalk_load/2; Built-in predicate:    Examples<87>.        (line  24)
* logtalk_load_context/2; Built-in predicate: Examples<92>.   (line  37)
* logtalk_make/0; Built-in predicate:    Examples<88>.        (line  24)
* logtalk_make/1; Built-in predicate:    Examples<89>.        (line  15)
* logtalk_make_target_action/1; Built-in predicate: Examples<90>.
                                                              (line  22)
* message:                               Glossary.            (line 275)
* message lookup:                        Glossary.            (line 281)
* message to self:                       Glossary.            (line 290)
* message_hook/4; Built-in method:       Examples<146>.       (line  19)
* message_prefix_stream/4; Built-in method: Examples<147>.    (line  21)
* message_tokens//2; Built-in method:    Examples<145>.       (line  15)
* meta-argument:                         Glossary.            (line 296)
* meta-interpreter:                      Glossary.            (line 302)
* meta-predicate:                        Glossary.            (line 307)
* metaclass:                             Glossary.            (line 313)
* meta_non_terminal/1; Directive:        Examples<33>.        (line  21)
* meta_predicate/1; Directive:           Examples<32>.        (line  19)
* method:                                Glossary.            (line 320)
* missing_directives; Flag:              Lint flags.          (line  45)
* mode/2; Directive:                     Examples<34>.        (line  13)
* module:                                Glossary.            (line 327)
* modules; Flag:                         Adapter files.       (line 108)
* monitor:                               Glossary.            (line 334)
* multifile predicate:                   Glossary.            (line 341)
* multifile/1; Directive:                Examples<35>.        (line  17)
* naming; Flag:                          Lint flags.          (line 108)
* object:                                Glossary.            (line 350)
* object database:                       Glossary.            (line 358)
* object/1-5; Directive:                 Examples<23>.        (line  18)
* object_property/2; Built-in predicate: Examples<46>.        (line  20)
* once/1; Built-in method:               Examples<112>.       (line  17)
* op/3; Directive:                       Examples<10>.        (line   9)
* optimize; Flag:                        Other flags.         (line  37)
* parameter:                             Glossary.            (line 362)
* parameter variable:                    Glossary.            (line 368)
* parameter/2; Built-in method:          Examples<97>.        (line  19)
* parametric category:                   Glossary.            (line 375)
* parametric entity:                     Glossary.            (line 379)
* parametric object:                     Glossary.            (line 390)
* parametric object proxy:               Glossary.            (line 394)
* parent:                                Glossary.            (line 400)
* permission_error/3; Built-in method:   Examples<120>.       (line  19)
* phrase//1; Built-in method:            Examples<136>.       (line  13)
* phrase/2; Built-in method:             Examples<137>.       (line  12)
* phrase/3; Built-in method:             Examples<138>.       (line  17)
* polymorphism:                          Glossary.            (line 404)
* portability; Flag:                     Lint flags.          (line  37)
* predicate:                             Glossary.            (line 419)
* predicate alias:                       Glossary.            (line 427)
* predicate declaration:                 Glossary.            (line 437)
* predicate definition:                  Glossary.            (line 443)
* predicate directive:                   Glossary.            (line 449)
* predicate scope container:             Glossary.            (line 454)
* predicate scope directive:             Glossary.            (line 460)
* predicate_property/2; Built-in method: Examples<103>.       (line  18)
* primary predicate declaration:         Glossary.            (line 465)
* print_message/3; Built-in method:      Message printing.    (line   6)
* print_message_token/4; Built-in method: Examples<149>.      (line  17)
* print_message_tokens/3; Built-in method: Examples<148>.     (line  18)
* private inheritance:                   Glossary.            (line 469)
* private predicate:                     Glossary.            (line 475)
* private/1; Directive:                  Examples<36>.        (line  14)
* profiler:                              Glossary.            (line 480)
* prolog_compatible_version; Flag:       Adapter files.       (line  56)
* prolog_compiler; Flag:                 Back-end Prolog compiler and loader flags.
                                                              (line   6)
* prolog_conformance; Flag:              Adapter files.       (line  65)
* prolog_dialect; Flag:                  Adapter files.       (line  42)
* prolog_loader; Flag:                   Back-end Prolog compiler and loader flags.
                                                              (line  15)
* prolog_version; Flag:                  Adapter files.       (line  48)
* protected inheritance:                 Glossary.            (line 484)
* protected predicate:                   Glossary.            (line 490)
* protected/1; Directive:                Examples<37>.        (line  17)
* protocol:                              Glossary.            (line 496)
* protocol/1-2; Directive:               Examples<24>.        (line  33)
* protocol_property/2; Built-in predicate: Examples<47>.      (line  23)
* prototype:                             Glossary.            (line 506)
* public inheritance:                    Glossary.            (line 512)
* public predicate:                      Glossary.            (line 518)
* public/1; Directive:                   Examples<38>.        (line  17)
* question_hook/6; Built-in method:      Examples<151>.       (line  17)
* question_prompt_stream/4; Built-in method: Examples<152>.   (line  19)
* redefined_built_ins; Flag:             Lint flags.          (line  83)
* reflection:                            Message sending.     (line  26)
* relative_to; Flag:                     Other flags.         (line  86)
* reload; Flag:                          Other flags.         (line  75)
* report; Flag:                          Other flags.         (line  17)
* representation_error/1; Built-in method: Examples<121>.     (line  19)
* resource_error/1; Built-in method:     Examples<123>.       (line  19)
* retract/1; Built-in method:            Examples<108>.       (line  19)
* retractall/1; Built-in method:         Examples<109>.       (line  19)
* scratch directory:                     Glossary.            (line 522)
* scratch_directory; Flag:               Other flags.         (line   6)
* self:                                  Glossary.            (line 527)
* self/1; Built-in method:               Examples<98>.        (line  40)
* sender:                                Glossary.            (line 531)
* sender/1; Built-in method:             Examples<99>.        (line  18)
* setof/3; Built-in method:              Examples<130>.       (line  18)
* settings file:                         Glossary.            (line 537)
* settings_file; Flag:                   Adapter files.       (line  29)
* set_logtalk_flag/2; Built-in predicate: Examples<94>.       (line  13)
* set_logtalk_flag/2; Directive:         Examples<11>.        (line  15)
* singleton method:                      Glossary.            (line 544)
* singleton_variables; Flag:             Lint flags.          (line  92)
* source file:                           Glossary.            (line 550)
* source file directive:                 Glossary.            (line 559)
* source_data; Flag:                     Other flags.         (line  54)
* specialization:                        Glossary.            (line 564)
* specializes_class/2-3; Built-in predicate: Examples<62>.    (line  18)
* static binding:                        Glossary.            (line 568)
* steadfastness:                         Glossary.            (line 578)
* steadfastness; Flag:                   Lint flags.          (line  29)
* structural reflection:                 Reflection.          (line  11)
* subclass:                              Glossary.            (line 585)
* super call:                            Glossary.            (line 590)
* superclass:                            Glossary.            (line 598)
* suspicious_calls; Flag:                Lint flags.          (line  77)
* synchronized predicate:                Glossary.            (line 604)
* synchronized/1; Directive:             Examples<39>.        (line  17)
* syntax_error/1; Built-in method:       Examples<124>.       (line  19)
* system_error/0; Built-in method:       Examples<125>.       (line  17)
* tabling; Flag:                         Adapter files.       (line  88)
* template method:                       Glossary.            (line 610)
* term_expansion/2; Built-in method:     Examples<140>.       (line  13)
* tester file:                           Glossary.            (line 614)
* this:                                  Glossary.            (line 619)
* this/1; Built-in method:               Examples<100>.       (line  18)
* threaded engine:                       Glossary.            (line 626)
* threaded/0; Directive:                 Examples<25>.        (line  18)
* threaded/1; Built-in predicate:        Multi-threading.     (line   6)
* threaded_call/1-2; Built-in predicate: Examples<67>.        (line  16)
* threaded_cancel/1; Built-in predicate: Examples<72>.        (line  19)
* threaded_engine/1; Built-in predicate: Examples<77>.        (line  20)
* threaded_engine_create/3; Built-in predicate: Multi-threading engines.
                                                              (line   6)
* threaded_engine_destroy/1; Built-in predicate: Examples<76>.
                                                              (line  15)
* threaded_engine_fetch/1; Built-in predicate: Examples<83>.  (line  13)
* threaded_engine_next/2; Built-in predicate: Examples<79>.   (line  17)
* threaded_engine_next_reified/2; Built-in predicate: Examples<80>.
                                                              (line  14)
* threaded_engine_post/2; Built-in predicate: Examples<82>.   (line  14)
* threaded_engine_self/1; Built-in predicate: Examples<78>.   (line  20)
* threaded_engine_yield/1; Built-in predicate: Examples<81>.  (line  14)
* threaded_exit/1-2; Built-in predicate: Examples<70>.        (line  19)
* threaded_ignore/1; Built-in predicate: Examples<69>.        (line  19)
* threaded_notify/1; Built-in predicate: Examples<74>.        (line  13)
* threaded_once/1-2; Built-in predicate: Examples<68>.        (line  19)
* threaded_peek/1-2; Built-in predicate: Examples<71>.        (line  19)
* threaded_wait/1; Built-in predicate:   Examples<73>.        (line  14)
* threads; Flag:                         Adapter files.       (line 101)
* throw/1; Built-in method:              Examples<115>.       (line  17)
* transparent-box view:                  Structural reflection.
                                                              (line  12)
* trivial_goal_fails; Flag:              Lint flags.          (line  59)
* type_error/2; Built-in method:         Examples<117>.       (line  18)
* undefined_predicates; Flag:            Lint flags.          (line  21)
* underscore_variables; Flag:            Lint flags.          (line  97)
* unicode; Flag:                         Adapter files.       (line  72)
* unknown_entities; Flag:                Lint flags.          (line   6)
* unknown_predicates; Flag:              Lint flags.          (line  13)
* uses/1; Directive:                     Examples<26>.        (line  12)
* uses/2; Directive:                     Examples<40>.        (line  16)
* use_module/2; Directive:               Examples<41>.        (line  53)
* version_data; Flag:                    Version flags.       (line   6)
* visible predicate:                     Glossary.            (line 634)



Tag Table:
Node: Top457
Ref: index doc688
Ref: 0688
Node: User Manual47048
Ref: userman/index doc47155
Ref: 147155
Ref: userman/index the-logtalk-handbook47155
Ref: 247155
Ref: userman/index user-manual47155
Ref: 347155
Node: Declarative object-oriented programming47688
Ref: userman/declarative doc47816
Ref: 447816
Ref: userman/declarative declarative-declarative47816
Ref: 547816
Ref: userman/declarative declarative-object-oriented-programming47816
Ref: 647816
Node: Main features51345
Ref: userman/features doc51494
Ref: 751494
Ref: userman/features features-features51494
Ref: 851494
Ref: userman/features main-features51494
Ref: 951494
Node: Integration of logic and object-oriented programming53436
Ref: userman/features features-logic53625
Ref: a53625
Ref: userman/features integration-of-logic-and-object-oriented-programming53625
Ref: b53625
Node: Integration of event-driven and object-oriented programming54677
Ref: userman/features features-events54914
Ref: c54914
Ref: userman/features integration-of-event-driven-and-object-oriented-programming54914
Ref: d54914
Node: Support for component-based programming56183
Ref: userman/features features-categories56418
Ref: 1356418
Ref: userman/features support-for-component-based-programming56418
Ref: 1456418
Node: Support for both prototype and class-based systems57254
Ref: userman/features features-both57469
Ref: 1557469
Ref: userman/features support-for-both-prototype-and-class-based-systems57469
Ref: 1657469
Node: Support for multiple object hierarchies58479
Ref: userman/features features-multiple58702
Ref: 1858702
Ref: userman/features support-for-multiple-object-hierarchies58702
Ref: 1958702
Node: Separation between interface and implementation59523
Ref: userman/features features-interface59736
Ref: 1d59736
Ref: userman/features separation-between-interface-and-implementation59736
Ref: 1e59736
Node: Private protected and public inheritance60236
Ref: userman/features features-inheritance60456
Ref: 1f60456
Ref: userman/features private-protected-and-public-inheritance60456
Ref: 2060456
Node: Private protected and public object predicates60802
Ref: userman/features features-predicates60993
Ref: 2260993
Ref: userman/features private-protected-and-public-object-predicates60993
Ref: 2360993
Node: Parametric objects61485
Ref: userman/features features-parametric61682
Ref: 2461682
Ref: userman/features parametric-objects61682
Ref: 2561682
Node: High level multi-threading programming support62426
Ref: userman/features features-threading62598
Ref: 2962598
Ref: userman/features high-level-multi-threading-programming-support62598
Ref: 2a62598
Node: Smooth learning curve63154
Ref: userman/features features-learning63367
Ref: 2b63367
Ref: userman/features smooth-learning-curve63367
Ref: 2c63367
Node: Compatibility with most Prolog systems and the ISO standard63587
Ref: userman/features compatibility-with-most-prolog-systems-and-the-iso-standard63765
Ref: 2d63765
Ref: userman/features features-compatibility63765
Ref: 2e63765
Node: Performance64140
Ref: userman/features features-performance64310
Ref: 3064310
Ref: userman/features performance64310
Ref: 3164310
Node: Logtalk scope65534
Ref: userman/features features-scope65636
Ref: 3665636
Ref: userman/features logtalk-scope65636
Ref: 3765636
Node: Nomenclature68309
Ref: userman/nomenclature doc68427
Ref: 3868427
Ref: userman/nomenclature nomenclature68427
Ref: 3968427
Ref: userman/nomenclature nomenclature-nomenclature68427
Ref: 3a68427
Node: Smalltalk nomenclature69252
Ref: userman/nomenclature nomenclature-smalltalk69367
Ref: 3b69367
Ref: userman/nomenclature smalltalk-nomenclature69367
Ref: 3c69367
Node: C++ nomenclature74626
Ref: userman/nomenclature c-nomenclature74767
Ref: 3f74767
Ref: userman/nomenclature nomenclature-cpp74767
Ref: 4074767
Node: Java nomenclature77824
Ref: userman/nomenclature java-nomenclature77934
Ref: 4d77934
Ref: userman/nomenclature nomenclature-java77934
Ref: 4e77934
Node: Messages82860
Ref: userman/messages doc82972
Ref: 5782972
Ref: userman/messages messages82972
Ref: 5882972
Ref: userman/messages messages-messages82972
Ref: 5982972
Node: Operators used in message sending83949
Ref: userman/messages messages-operators84085
Ref: 5a84085
Ref: userman/messages operators-used-in-message-sending84085
Ref: 5b84085
Node: Sending a message to an object84640
Ref: userman/messages messages-sending84818
Ref: 5c84818
Ref: userman/messages sending-a-message-to-an-object84818
Ref: 5d84818
Node: Delegating a message to an object85344
Ref: userman/messages delegating-a-message-to-an-object85514
Ref: 5f85514
Ref: userman/messages messages-delegating85514
Ref: 6085514
Node: Sending a message to self86040
Ref: userman/messages sending-a-message-to-self86192
Ref: 6286192
Node: Broadcasting86995
Ref: userman/messages broadcasting87155
Ref: 6387155
Ref: userman/messages messages-broadcasting87155
Ref: 6487155
Node: Calling imported and inherited predicates87924
Ref: userman/messages calling-imported-and-inherited-predicates88095
Ref: 6588095
Ref: userman/messages messages-super88095
Ref: 6688095
Node: Message sending and event generation89263
Ref: userman/messages message-sending-and-event-generation89413
Ref: 6789413
Ref: userman/messages messages-events89413
Ref: 6889413
Node: Objects90976
Ref: userman/objects doc91085
Ref: 6a91085
Ref: userman/objects objects91085
Ref: 6b91085
Ref: userman/objects objects-objects91085
Ref: 6c91085
Ref: Objects-Footnote-192024
Ref: Objects-Footnote-292079
Node: Objects prototypes classes and instances92140
Ref: userman/objects objects-kind92273
Ref: 6d92273
Ref: userman/objects objects-prototypes-classes-and-instances92273
Ref: 6e92273
Node: Prototypes93901
Ref: userman/objects objects-prototypes94023
Ref: 6f94023
Ref: userman/objects prototypes94023
Ref: 7094023
Node: Classes94642
Ref: userman/objects classes94764
Ref: 7194764
Ref: userman/objects objects-classes94764
Ref: 7294764
Node: Defining a new object95229
Ref: userman/objects defining-a-new-object95392
Ref: 7395392
Ref: userman/objects objects-defining95392
Ref: 7495392
Node: Parametric objects<2>100859
Ref: userman/objects objects-parametric101005
Ref: 48101005
Ref: userman/objects parametric-objects101005
Ref: 7a101005
Node: Finding defined objects104383
Ref: userman/objects finding-defined-objects104540
Ref: 7d104540
Ref: userman/objects objects-finding104540
Ref: 7e104540
Node: Creating a new object in runtime104968
Ref: userman/objects creating-a-new-object-in-runtime105133
Ref: 80105133
Ref: userman/objects objects-creating105133
Ref: 81105133
Node: Abolishing an existing object106388
Ref: userman/objects abolishing-an-existing-object106547
Ref: 82106547
Ref: userman/objects objects-abolishing106547
Ref: 83106547
Node: Object directives106847
Ref: userman/objects object-directives106994
Ref: 84106994
Ref: userman/objects objects-directives106994
Ref: 85106994
Node: Object initialization107381
Ref: userman/objects object-initialization107499
Ref: 86107499
Ref: userman/objects objects-initialization107499
Ref: 87107499
Node: Dynamic objects108690
Ref: userman/objects dynamic-objects108837
Ref: 89108837
Ref: userman/objects objects-dynamic108837
Ref: 8a108837
Node: Object documentation109563
Ref: userman/objects object-documentation109717
Ref: 8c109717
Ref: userman/objects objects-documentation109717
Ref: 8d109717
Node: Loading files into an object109961
Ref: userman/objects loading-files-into-an-object110124
Ref: 90110124
Ref: userman/objects objects-include110124
Ref: 91110124
Node: Declaring object aliases110870
Ref: userman/objects declaring-object-aliases111004
Ref: 93111004
Ref: userman/objects objects-object-aliases111004
Ref: 94111004
Node: Object relationships111418
Ref: userman/objects object-relationships111553
Ref: 96111553
Ref: userman/objects objects-relationships111553
Ref: 97111553
Node: Object properties113667
Ref: userman/objects object-properties113801
Ref: 9f113801
Ref: userman/objects objects-properties113801
Ref: a0113801
Node: Built-in objects120446
Ref: userman/objects built-in-objects120551
Ref: a7120551
Ref: userman/objects objects-built-in120551
Ref: a8120551
Node: The built-in pseudo-object user120764
Ref: userman/objects objects-user120903
Ref: a9120903
Ref: userman/objects the-built-in-pseudo-object-user120903
Ref: aa120903
Ref: The built-in pseudo-object user-Footnote-1121845
Node: The built-in object logtalk121900
Ref: userman/objects objects-logtalk122039
Ref: ab122039
Ref: userman/objects the-built-in-object-logtalk122039
Ref: ac122039
Node: Protocols126488
Ref: userman/protocols doc126599
Ref: ae126599
Ref: userman/protocols protocols126599
Ref: af126599
Ref: userman/protocols protocols-protocols126599
Ref: b0126599
Ref: Protocols-Footnote-1127493
Ref: Protocols-Footnote-2127560
Ref: Protocols-Footnote-3127625
Node: Defining a new protocol127692
Ref: userman/protocols defining-a-new-protocol127814
Ref: b1127814
Ref: userman/protocols protocols-defining127814
Ref: b2127814
Node: Finding defined protocols129774
Ref: userman/protocols finding-defined-protocols129939
Ref: b5129939
Ref: userman/protocols protocols-finding129939
Ref: b6129939
Node: Creating a new protocol in runtime130307
Ref: userman/protocols creating-a-new-protocol-in-runtime130480
Ref: b8130480
Ref: userman/protocols protocols-creating130480
Ref: b9130480
Node: Abolishing an existing protocol131523
Ref: userman/protocols abolishing-an-existing-protocol131690
Ref: bb131690
Ref: userman/protocols protocols-abolishing131690
Ref: bc131690
Node: Protocol directives132004
Ref: userman/protocols protocol-directives132159
Ref: be132159
Node: Dynamic protocols132384
Ref: userman/protocols dynamic-protocols132507
Ref: bf132507
Ref: userman/protocols protocols-dynamic132507
Ref: c0132507
Node: Protocol documentation133150
Ref: userman/protocols protocol-documentation133311
Ref: c1133311
Ref: userman/protocols protocols-documentation133311
Ref: c2133311
Node: Loading files into a protocol133560
Ref: userman/protocols loading-files-into-a-protocol133695
Ref: c3133695
Ref: userman/protocols protocols-include133695
Ref: c4133695
Node: Protocol relationships133944
Ref: userman/protocols protocol-relationships134087
Ref: c5134087
Ref: userman/protocols protocols-relationships134087
Ref: c6134087
Node: Protocol properties135131
Ref: userman/protocols protocol-properties135277
Ref: c9135277
Ref: userman/protocols protocols-properties135277
Ref: ca135277
Node: Implementing protocols137446
Ref: userman/protocols implementing-protocols137588
Ref: cd137588
Ref: userman/protocols protocols-implementing137588
Ref: ce137588
Node: Built-in protocols138582
Ref: userman/protocols built-in-protocols138696
Ref: cf138696
Ref: userman/protocols protocols-built-in138696
Ref: d0138696
Node: The built-in protocol expanding138959
Ref: userman/protocols protocols-expanding139105
Ref: d1139105
Ref: userman/protocols the-built-in-protocol-expanding139105
Ref: d2139105
Ref: The built-in protocol expanding-Footnote-1139447
Node: The built-in protocol monitoring139512
Ref: userman/protocols protocols-monitoring139699
Ref: d6139699
Ref: userman/protocols the-built-in-protocol-monitoring139699
Ref: d7139699
Ref: The built-in protocol monitoring-Footnote-1140039
Node: The built-in protocol forwarding140106
Ref: userman/protocols protocols-forwarding140253
Ref: da140253
Ref: userman/protocols the-built-in-protocol-forwarding140253
Ref: db140253
Ref: The built-in protocol forwarding-Footnote-1140683
Node: Categories140750
Ref: userman/categories doc140864
Ref: dd140864
Ref: userman/categories categories140864
Ref: de140864
Ref: userman/categories categories-categories140864
Ref: df140864
Node: Defining a new category142138
Ref: userman/categories categories-defining142248
Ref: e2142248
Ref: userman/categories defining-a-new-category142248
Ref: e3142248
Node: Hot patching147392
Ref: userman/categories categories-patching147537
Ref: e6147537
Ref: userman/categories hot-patching147537
Ref: e7147537
Node: Finding defined categories149815
Ref: userman/categories categories-finding149971
Ref: ea149971
Ref: userman/categories finding-defined-categories149971
Ref: eb149971
Node: Creating a new category in runtime150361
Ref: userman/categories categories-creating150536
Ref: ec150536
Ref: userman/categories creating-a-new-category-in-runtime150536
Ref: ed150536
Node: Abolishing an existing category151783
Ref: userman/categories abolishing-an-existing-category151951
Ref: ef151951
Ref: userman/categories categories-abolishing151951
Ref: f0151951
Node: Category directives152266
Ref: userman/categories categories-directives152422
Ref: f1152422
Ref: userman/categories category-directives152422
Ref: f2152422
Node: Dynamic categories152801
Ref: userman/categories categories-dynamic152925
Ref: f3152925
Ref: userman/categories dynamic-categories152925
Ref: f4152925
Node: Category documentation153583
Ref: userman/categories categories-documentation153745
Ref: f5153745
Ref: userman/categories category-documentation153745
Ref: f6153745
Node: Loading files into a category153994
Ref: userman/categories categories-include154165
Ref: f7154165
Ref: userman/categories loading-files-into-a-category154165
Ref: f8154165
Node: Declaring object aliases<2>154414
Ref: userman/categories categories-object-aliases154554
Ref: f9154554
Ref: userman/categories declaring-object-aliases154554
Ref: fa154554
Node: Category relationships154886
Ref: userman/categories categories-relationships155030
Ref: fb155030
Ref: userman/categories category-relationships155030
Ref: fc155030
Node: Category properties156688
Ref: userman/categories categories-properties156833
Ref: fe156833
Ref: userman/categories category-properties156833
Ref: ff156833
Node: Importing categories162660
Ref: userman/categories categories-importing162810
Ref: 101162810
Ref: userman/categories importing-categories162810
Ref: 102162810
Node: Calling category predicates163634
Ref: userman/categories calling-category-predicates163786
Ref: 103163786
Ref: userman/categories categories-predicates163786
Ref: 104163786
Node: Parametric categories165576
Ref: userman/categories categories-parametric165699
Ref: 106165699
Ref: userman/categories parametric-categories165699
Ref: 107165699
Node: Predicates166574
Ref: userman/predicates doc166690
Ref: 108166690
Ref: userman/predicates predicates166690
Ref: 109166690
Ref: userman/predicates predicates-predicates166690
Ref: 10a166690
Node: Reserved predicate names167334
Ref: userman/predicates predicates-reserved167453
Ref: 10b167453
Ref: userman/predicates reserved-predicate-names167453
Ref: 10c167453
Ref: Reserved predicate names-Footnote-1168121
Ref: Reserved predicate names-Footnote-2168186
Ref: Reserved predicate names-Footnote-3168253
Node: Declaring predicates168320
Ref: userman/predicates declaring-predicates168467
Ref: 10d168467
Ref: userman/predicates predicates-declaring168467
Ref: 10e168467
Node: Scope directives169101
Ref: userman/predicates predicates-scope169216
Ref: 10f169216
Ref: userman/predicates scope-directives169216
Ref: 110169216
Node: Mode directive171314
Ref: userman/predicates mode-directive171462
Ref: 116171462
Ref: userman/predicates predicates-mode171462
Ref: 117171462
Node: Meta-predicate directive175110
Ref: userman/predicates meta-predicate-directive175265
Ref: 11b175265
Ref: userman/predicates predicates-meta175265
Ref: 47175265
Node: Discontiguous directive177344
Ref: userman/predicates discontiguous-directive177502
Ref: 11e177502
Ref: userman/predicates predicates-discontiguous177502
Ref: 11f177502
Node: Dynamic directive178165
Ref: userman/predicates dynamic-directive178317
Ref: 121178317
Ref: userman/predicates predicates-dynamic178317
Ref: 122178317
Node: Operator directive179312
Ref: userman/predicates operator-directive179455
Ref: 124179455
Ref: userman/predicates predicates-op179455
Ref: 125179455
Node: Uses directive180890
Ref: userman/predicates predicates-uses181031
Ref: 128181031
Ref: userman/predicates uses-directive181031
Ref: 129181031
Node: Alias directive183640
Ref: userman/predicates alias-directive183784
Ref: 12b183784
Ref: userman/predicates predicates-alias183784
Ref: 12c183784
Node: Documenting directive187949
Ref: userman/predicates documenting-directive188098
Ref: 12f188098
Ref: userman/predicates predicates-info188098
Ref: 130188098
Node: Multifile directive188419
Ref: userman/predicates multifile-directive188574
Ref: 132188574
Ref: userman/predicates predicates-multifile188574
Ref: 133188574
Node: Coinductive directive192254
Ref: userman/predicates coinductive-directive192379
Ref: 136192379
Ref: userman/predicates predicates-coinductive192379
Ref: 137192379
Node: Defining predicates192872
Ref: userman/predicates defining-predicates193029
Ref: 13a193029
Ref: userman/predicates predicates-defining193029
Ref: 13b193029
Node: Object predicates193215
Ref: userman/predicates object-predicates193335
Ref: 13c193335
Ref: userman/predicates predicates-objects193335
Ref: 13d193335
Node: Category predicates194500
Ref: userman/predicates category-predicates194644
Ref: 13e194644
Ref: userman/predicates predicates-categories194644
Ref: 13f194644
Node: Meta-predicates196137
Ref: userman/predicates meta-predicates196282
Ref: 142196282
Ref: userman/predicates predicates-metadef196282
Ref: 143196282
Node: Lambda expressions197548
Ref: userman/predicates lambda-expressions197703
Ref: 146197703
Ref: userman/predicates predicates-lambdas197703
Ref: 147197703
Ref: Lambda expressions-Footnote-1201676
Node: Definite clause grammar rules201730
Ref: userman/predicates definite-clause-grammar-rules201861
Ref: 149201861
Ref: userman/predicates predicates-dcgs201861
Ref: 14a201861
Node: Built-in object predicates methods207760
Ref: userman/predicates built-in-object-predicates-methods207917
Ref: 14e207917
Ref: userman/predicates predicates-methods207917
Ref: 14f207917
Node: Execution context methods208553
Ref: userman/predicates execution-context-methods208712
Ref: 150208712
Ref: userman/predicates predicates-context208712
Ref: 151208712
Node: Error handling and throwing methods213158
Ref: userman/predicates error-handling-and-throwing-methods213342
Ref: 154213342
Ref: userman/predicates predicates-errors213342
Ref: 155213342
Node: Database methods213919
Ref: userman/predicates database-methods214095
Ref: 162214095
Ref: userman/predicates predicates-database214095
Ref: 163214095
Node: Meta-call methods215260
Ref: userman/predicates meta-call-methods215422
Ref: 16d215422
Ref: userman/predicates predicates-metacalls215422
Ref: 16e215422
Node: All solutions methods215863
Ref: userman/predicates all-solutions-methods216027
Ref: 172216027
Ref: userman/predicates predicates-solutions216027
Ref: 173216027
Node: Reflection methods216398
Ref: userman/predicates predicates-reflection216602
Ref: 179216602
Ref: userman/predicates reflection-methods216602
Ref: 17a216602
Node: Definite clause grammar parsing methods and non-terminals217834
Ref: userman/predicates definite-clause-grammar-parsing-methods-and-non-terminals218008
Ref: 17b218008
Ref: userman/predicates predicates-parsing218008
Ref: 17c218008
Node: Predicate properties218799
Ref: userman/predicates predicate-properties218964
Ref: 180218964
Ref: userman/predicates predicates-properties218964
Ref: 181218964
Node: Finding declared predicates223947
Ref: userman/predicates finding-declared-predicates224103
Ref: 182224103
Ref: userman/predicates predicates-finding224103
Ref: 183224103
Node: Calling Prolog predicates224993
Ref: userman/predicates calling-prolog-predicates225120
Ref: 184225120
Ref: userman/predicates predicates-prolog225120
Ref: 185225120
Node: Calling Prolog built-in predicates226208
Ref: userman/predicates calling-prolog-built-in-predicates226384
Ref: 186226384
Node: Calling Prolog non-standard built-in meta-predicates228334
Ref: userman/predicates calling-prolog-non-standard-built-in-meta-predicates228563
Ref: 188228563
Ref: userman/predicates predicates-prolog-meta228563
Ref: 189228563
Node: Calling Prolog user-defined plain predicates229794
Ref: userman/predicates calling-prolog-user-defined-plain-predicates230021
Ref: 18a230021
Ref: userman/predicates predicates-prolog-user230021
Ref: 18b230021
Node: Calling Prolog module predicates231055
Ref: userman/predicates calling-prolog-module-predicates231267
Ref: 18c231267
Ref: userman/predicates predicates-prolog-module231267
Ref: 18d231267
Node: Calling Prolog module meta-predicates234224
Ref: userman/predicates calling-prolog-module-meta-predicates234436
Ref: 18f234436
Node: Compiling Prolog module multifile predicates237011
Ref: userman/predicates compiling-prolog-module-multifile-predicates237182
Ref: 190237182
Node: Inheritance238367
Ref: userman/inheritance doc238497
Ref: 191238497
Ref: userman/inheritance inheritance238497
Ref: 192238497
Ref: userman/inheritance inheritance-inheritance238497
Ref: 12e238497
Node: Protocol inheritance239726
Ref: userman/inheritance inheritance-protocol239848
Ref: 193239848
Ref: userman/inheritance protocol-inheritance239848
Ref: 194239848
Node: Search order for prototype hierarchies240331
Ref: userman/inheritance inheritance-protocol-prototype240488
Ref: 196240488
Ref: userman/inheritance search-order-for-prototype-hierarchies240488
Ref: 197240488
Node: Search order for class hierarchies241021
Ref: userman/inheritance inheritance-protocol-class241178
Ref: 198241178
Ref: userman/inheritance search-order-for-class-hierarchies241178
Ref: 199241178
Node: Implementation inheritance241784
Ref: userman/inheritance implementation-inheritance241955
Ref: 19a241955
Ref: userman/inheritance inheritance-implementation241955
Ref: 19b241955
Node: Search order for prototype hierarchies<2>242678
Ref: userman/inheritance id1242847
Ref: 19c242847
Ref: userman/inheritance inheritance-implementation-prototype242847
Ref: 19d242847
Node: Search order for class hierarchies<2>243133
Ref: userman/inheritance id2243353
Ref: 19e243353
Ref: userman/inheritance inheritance-implementation-class243353
Ref: 19f243353
Node: Redefining inherited predicate definitions243830
Ref: userman/inheritance inheritance-implementation-redefinition244053
Ref: 1a0244053
Ref: userman/inheritance redefining-inherited-predicate-definitions244053
Ref: 1a1244053
Node: Specializing inherited predicate definitions245051
Ref: userman/inheritance inheritance-specialization245287
Ref: 1a2245287
Ref: userman/inheritance specializing-inherited-predicate-definitions245287
Ref: 1a3245287
Node: Union of inherited and local predicate definitions246091
Ref: userman/inheritance inheritance-union246331
Ref: 1a4246331
Ref: userman/inheritance union-of-inherited-and-local-predicate-definitions246331
Ref: 1a5246331
Node: Selective inheritance of predicate definitions247230
Ref: userman/inheritance inheritance-selective247417
Ref: 1a6247417
Ref: userman/inheritance selective-inheritance-of-predicate-definitions247417
Ref: 1a7247417
Node: Public protected and private inheritance248250
Ref: userman/inheritance inheritance-scope248440
Ref: 79248440
Ref: userman/inheritance public-protected-and-private-inheritance248440
Ref: 1a8248440
Node: Composition versus multiple inheritance249741
Ref: userman/inheritance composition-versus-multiple-inheritance249896
Ref: 1ac249896
Ref: userman/inheritance inheritance-composition249896
Ref: 1ad249896
Node: Event-driven programming251955
Ref: userman/events doc252102
Ref: 1b2252102
Ref: userman/events event-driven-programming252102
Ref: 1b3252102
Ref: userman/events events-events252102
Ref: 4f252102
Node: Definitions253807
Ref: userman/events definitions253923
Ref: 1b6253923
Ref: userman/events events-definitions253923
Ref: 1b7253923
Node: Event254150
Ref: userman/events event254238
Ref: 1b8254238
Ref: userman/events events-event254238
Ref: 1b9254238
Node: Monitor256100
Ref: userman/events events-monitor256188
Ref: 1ba256188
Ref: userman/events monitor256188
Ref: 1bb256188
Ref: Monitor-Footnote-1257804
Node: Event generation257871
Ref: userman/events event-generation258028
Ref: 1bc258028
Ref: userman/events events-generation258028
Ref: 1bd258028
Node: Communicating events to monitors258379
Ref: userman/events communicating-events-to-monitors258545
Ref: 1be258545
Ref: userman/events events-communicating258545
Ref: 1bf258545
Ref: Communicating events to monitors-Footnote-1259069
Node: Performance concerns259136
Ref: userman/events events-performance259303
Ref: 1c0259303
Ref: userman/events performance-concerns259303
Ref: 1c1259303
Node: Monitor semantics260207
Ref: userman/events events-semantics260370
Ref: 1c2260370
Ref: userman/events monitor-semantics260370
Ref: 1c3260370
Node: Activation order of monitors261257
Ref: userman/events activation-order-of-monitors261414
Ref: 1c4261414
Ref: userman/events events-order261414
Ref: 1c5261414
Node: Event handling262582
Ref: userman/events event-handling262713
Ref: 1c6262713
Ref: userman/events events-handling262713
Ref: 1c7262713
Node: Defining new events263180
Ref: userman/events defining-new-events263303
Ref: 1c8263303
Ref: userman/events events-defining263303
Ref: 1c9263303
Node: Abolishing defined events263705
Ref: userman/events abolishing-defined-events263859
Ref: 1cb263859
Ref: userman/events events-abolishing263859
Ref: 1cc263859
Node: Finding defined events264183
Ref: userman/events events-finding264341
Ref: 1ce264341
Ref: userman/events finding-defined-events264341
Ref: 1cf264341
Node: Defining event handlers264731
Ref: userman/events defining-event-handlers264855
Ref: 1d1264855
Ref: userman/events events-handlers264855
Ref: 1d2264855
Ref: Defining event handlers-Footnote-1267519
Ref: Defining event handlers-Footnote-2267586
Node: Multi-threading programming267653
Ref: userman/threads doc267803
Ref: 1d3267803
Ref: userman/threads multi-threading-programming267803
Ref: 1d4267803
Ref: userman/threads threads-threads267803
Ref: 55267803
Node: Enabling multi-threading support268947
Ref: userman/threads enabling-multi-threading-support269117
Ref: 1d5269117
Ref: userman/threads threads-enabling269117
Ref: 1d6269117
Node: Enabling objects to make multi-threading calls269400
Ref: userman/threads enabling-objects-to-make-multi-threading-calls269614
Ref: 1d8269614
Ref: userman/threads threads-directive269614
Ref: 1d9269614
Node: Multi-threading built-in predicates269846
Ref: userman/threads multi-threading-built-in-predicates270054
Ref: 1db270054
Ref: userman/threads threads-predicates270054
Ref: 1dc270054
Node: Proving goals concurrently using threads270818
Ref: userman/threads proving-goals-concurrently-using-threads271000
Ref: 1de271000
Ref: userman/threads threads-threaded271000
Ref: 1df271000
Node: Proving goals asynchronously using threads273357
Ref: userman/threads proving-goals-asynchronously-using-threads273539
Ref: 1e0273539
Ref: userman/threads threads-call273539
Ref: 1e1273539
Node: One-way asynchronous calls277977
Ref: userman/threads one-way-asynchronous-calls278185
Ref: 1e7278185
Ref: userman/threads threads-ignore278185
Ref: 1e8278185
Node: Asynchronous calls and synchronized predicates278860
Ref: userman/threads asynchronous-calls-and-synchronized-predicates279076
Ref: 1ea279076
Ref: userman/threads threads-synchronized-predicates279076
Ref: 11a279076
Node: Synchronizing threads through notifications282495
Ref: userman/threads synchronizing-threads-through-notifications282701
Ref: 1eb282701
Ref: userman/threads threads-notifications282701
Ref: 1ec282701
Node: Threaded engines284118
Ref: userman/threads threaded-engines284305
Ref: 1ef284305
Ref: userman/threads threads-engines284305
Ref: 1f0284305
Node: Multi-threading performance288140
Ref: userman/threads multi-threading-performance288275
Ref: 1f8288275
Ref: userman/threads threads-performance288275
Ref: 1f9288275
Node: Error handling289339
Ref: userman/errors doc289475
Ref: 1fa289475
Ref: userman/errors error-handling289475
Ref: 1fb289475
Ref: userman/errors errors-errors289475
Ref: 1fc289475
Ref: Error handling-Footnote-1290676
Node: Generating errors290758
Ref: userman/errors generating-errors290867
Ref: 1fd290867
Node: Type-checking291433
Ref: userman/errors type-checking291579
Ref: 1ff291579
Ref: Type-checking-Footnote-1294220
Ref: Type-checking-Footnote-2294275
Ref: Type-checking-Footnote-3294338
Ref: Type-checking-Footnote-4294401
Node: Compiler warnings and errors294464
Ref: userman/errors compiler-warnings-and-errors294607
Ref: 200294607
Node: Unknown entities296024
Ref: userman/errors errors-unknown296152
Ref: 202296152
Ref: userman/errors unknown-entities296152
Ref: 203296152
Node: Singleton variables296536
Ref: userman/errors errors-singletons296715
Ref: 204296715
Ref: userman/errors singleton-variables296715
Ref: 205296715
Node: Redefinition of Prolog built-in predicates297145
Ref: userman/errors errors-prolog297351
Ref: 206297351
Ref: userman/errors redefinition-of-prolog-built-in-predicates297351
Ref: 207297351
Node: Redefinition of Logtalk built-in predicates297881
Ref: userman/errors errors-redefinion-predicates298108
Ref: 208298108
Ref: userman/errors redefinition-of-logtalk-built-in-predicates298108
Ref: 209298108
Node: Redefinition of Logtalk built-in methods298427
Ref: userman/errors errors-redefinion-methods298646
Ref: 20a298646
Ref: userman/errors redefinition-of-logtalk-built-in-methods298646
Ref: 20b298646
Node: Misspell calls of local predicates298938
Ref: userman/errors errors-misspell299134
Ref: 20c299134
Ref: userman/errors misspell-calls-of-local-predicates299134
Ref: 20d299134
Node: Portability warnings299475
Ref: userman/errors errors-portability299650
Ref: 20e299650
Ref: userman/errors portability-warnings299650
Ref: 20f299650
Node: Deprecated elements300009
Ref: userman/errors deprecated-elements300168
Ref: 210300168
Ref: userman/errors errors-deprecated300168
Ref: 211300168
Node: Missing directives300450
Ref: userman/errors errors-missing-directives300610
Ref: 212300610
Ref: userman/errors missing-directives300610
Ref: 213300610
Node: Duplicated directives300783
Ref: userman/errors duplicated-directives300959
Ref: 214300959
Ref: userman/errors errors-duplicated-directives300959
Ref: 215300959
Node: Goals that are always true or false301281
Ref: userman/errors errors-always-true-or-false-goals301452
Ref: 216301452
Ref: userman/errors goals-that-are-always-true-or-false301452
Ref: 217301452
Node: Trivial fails301721
Ref: userman/errors errors-trivial-fails301887
Ref: 218301887
Ref: userman/errors trivial-fails301887
Ref: 219301887
Node: Suspicious calls302030
Ref: userman/errors errors-suspicious-calls302177
Ref: 21a302177
Ref: userman/errors suspicious-calls302177
Ref: 21b302177
Node: Lambda variables302522
Ref: userman/errors errors-lambda-variables302729
Ref: 21c302729
Ref: userman/errors lambda-variables302729
Ref: 21d302729
Node: Redefinition of predicates declared in uses/2 and use_module/2 directives303054
Ref: userman/errors errors-predicate-redefinition303270
Ref: 220303270
Ref: userman/errors redefinition-of-predicates-declared-in-uses-2-and-use-module-2-directives303270
Ref: 221303270
Node: Other warnings and errors303616
Ref: userman/errors errors-others303807
Ref: 222303807
Ref: userman/errors other-warnings-and-errors303807
Ref: 223303807
Node: Runtime errors304087
Ref: userman/errors errors-runtime304208
Ref: 224304208
Ref: userman/errors runtime-errors304208
Ref: 225304208
Node: Logtalk built-in predicates304584
Ref: userman/errors errors-predicates304714
Ref: 226304714
Ref: userman/errors logtalk-built-in-predicates304714
Ref: 227304714
Node: Logtalk built-in methods304915
Ref: userman/errors errors-methods305069
Ref: 228305069
Ref: userman/errors logtalk-built-in-methods305069
Ref: 229305069
Node: Message sending305260
Ref: userman/errors errors-sending305378
Ref: 22a305378
Ref: userman/errors message-sending305378
Ref: 22b305378
Ref: Message sending-Footnote-1306294
Node: Reflection306361
Ref: userman/reflection doc306502
Ref: 22c306502
Ref: userman/reflection reflection306502
Ref: 22d306502
Ref: userman/reflection reflection-reflection306502
Ref: 119306502
Node: Structural reflection306835
Ref: userman/reflection reflection-structural306952
Ref: 22e306952
Ref: userman/reflection structural-reflection306952
Ref: 22f306952
Node: Transparent-box view307400
Ref: userman/reflection transparent-box-view307520
Ref: 230307520
Ref: Transparent-box view-Footnote-1308475
Node: Black-box view308536
Ref: userman/reflection black-box-view308656
Ref: 233308656
Node: Behavioral reflection309276
Ref: userman/reflection behavioral-reflection309393
Ref: 234309393
Ref: userman/reflection reflection-behavioral309393
Ref: 235309393
Ref: Behavioral reflection-Footnote-1309819
Node: Writing and running applications309880
Ref: userman/programming doc310045
Ref: 236310045
Ref: userman/programming programming-programming310045
Ref: 237310045
Ref: userman/programming writing-and-running-applications310045
Ref: 238310045
Node: Writing applications310196
Ref: userman/programming programming-writing310347
Ref: 239310347
Ref: userman/programming writing-applications310347
Ref: 23a310347
Node: Source files311656
Ref: userman/programming programming-source-files311774
Ref: 23c311774
Ref: userman/programming source-files311774
Ref: 23d311774
Node: Portable applications314514
Ref: userman/programming portable-applications314664
Ref: 240314664
Ref: userman/programming programming-portability314664
Ref: 241314664
Node: Conditional compilation315606
Ref: userman/programming conditional-compilation315766
Ref: 242315766
Ref: userman/programming programming-cc315766
Ref: 243315766
Node: Avoiding common errors316139
Ref: userman/programming avoiding-common-errors316301
Ref: 248316301
Ref: userman/programming programming-errors316301
Ref: 249316301
Node: Coding style guidelines318016
Ref: userman/programming coding-style-guidelines318146
Ref: 24a318146
Ref: userman/programming programming-style318146
Ref: 24b318146
Node: Compiling and running applications318942
Ref: userman/programming compiling-and-running-applications319093
Ref: 24c319093
Ref: userman/programming programming-session319093
Ref: 24d319093
Node: Starting Logtalk319749
Ref: userman/programming programming-starting319903
Ref: 24e319903
Ref: userman/programming starting-logtalk319903
Ref: 24f319903
Node: Compiling and loading your applications321539
Ref: userman/programming compiling-and-loading-your-applications321714
Ref: 250321714
Ref: userman/programming programming-compiling321714
Ref: 251321714
Node: Loader files324721
Ref: userman/programming loader-files324905
Ref: 257324905
Ref: userman/programming programming-loaders324905
Ref: 258324905
Node: Libraries of source files327577
Ref: userman/programming libraries-of-source-files327737
Ref: 25b327737
Ref: userman/programming programming-libraries327737
Ref: 25c327737
Node: Compiler linter330021
Ref: userman/programming compiler-linter330183
Ref: 25e330183
Ref: userman/programming programming-linter330183
Ref: 25f330183
Node: Compiler flags330925
Ref: userman/programming compiler-flags331109
Ref: 260331109
Ref: userman/programming programming-flags331109
Ref: 201331109
Node: Version flags333682
Ref: userman/programming version-flags333784
Ref: 264333784
Ref: userman/programming flag-version-data333831
Ref: 265333831
Node: Lint flags334348
Ref: userman/programming lint-flags334494
Ref: 266334494
Ref: userman/programming flag-unknown-entities334535
Ref: 267334535
Ref: userman/programming flag-unknown-predicates334927
Ref: 268334927
Ref: userman/programming flag-undefined-predicates335281
Ref: 269335281
Ref: userman/programming flag-steadfastness335673
Ref: 26a335673
Ref: userman/programming flag-portability336005
Ref: 187336005
Ref: userman/programming flag-missing-directives336325
Ref: 26c336325
Ref: userman/programming flag-duplicated-directives336524
Ref: 26d336524
Ref: userman/programming flag-trivial-goal-fails336857
Ref: 26e336857
Ref: userman/programming flag-always-true-or-false-goals337111
Ref: 26f337111
Ref: userman/programming flag-lambda-variables337342
Ref: 270337342
Ref: userman/programming flag-suspicious-calls337546
Ref: 271337546
Ref: userman/programming flag-redefined-built-ins337743
Ref: 272337743
Ref: userman/programming flag-singleton-variables338162
Ref: 273338162
Ref: userman/programming flag-underscore-variables338348
Ref: 274338348
Ref: userman/programming flag-naming338913
Ref: 275338913
Node: Optional features compilation flags339389
Ref: userman/programming optional-features-compilation-flags339563
Ref: 276339563
Ref: userman/programming flag-complements339654
Ref: e8339654
Ref: userman/programming flag-dynamic-declarations340341
Ref: 277340341
Ref: userman/programming flag-events340946
Ref: 69340946
Ref: userman/programming flag-context-switching-calls341504
Ref: 278341504
Node: Back-end Prolog compiler and loader flags341830
Ref: userman/programming back-end-prolog-compiler-and-loader-flags342005
Ref: 279342005
Ref: userman/programming flag-prolog-compiler342110
Ref: 27a342110
Ref: userman/programming flag-prolog-loader342611
Ref: 27b342611
Node: Other flags342956
Ref: userman/programming other-flags343114
Ref: 27c343114
Ref: userman/programming flag-scratch-directory343159
Ref: 27d343159
Ref: userman/programming flag-report343796
Ref: 27e343796
Ref: userman/programming flag-code-prefix344174
Ref: 27f344174
Ref: userman/programming flag-optimize344815
Ref: 105344815
Ref: userman/programming flag-source-data345764
Ref: a6345764
Ref: userman/programming flag-debug346413
Ref: 255346413
Ref: userman/programming flag-reload346837
Ref: 280346837
Ref: userman/programming flag-relative-to347395
Ref: 281347395
Ref: userman/programming flag-hook347578
Ref: d5347578
Ref: userman/programming flag-clean348001
Ref: 282348001
Ref: Other flags-Footnote-1348671
Ref: Other flags-Footnote-2348726
Node: User-defined flags348791
Ref: userman/programming user-defined-flags348899
Ref: 283348899
Node: Reloading and smart compilation of source files349063
Ref: userman/programming programming-smart349266
Ref: 285349266
Ref: userman/programming reloading-and-smart-compilation-of-source-files349266
Ref: 286349266
Node: Using Logtalk for batch processing351801
Ref: userman/programming programming-batch352012
Ref: 287352012
Ref: userman/programming using-logtalk-for-batch-processing352012
Ref: 288352012
Node: Optimizing performance352452
Ref: userman/programming optimizing-performance352607
Ref: 289352607
Ref: userman/programming programming-performance352607
Ref: 28a352607
Ref: Optimizing performance-Footnote-1354563
Node: Printing messages and asking questions354611
Ref: userman/printing doc354789
Ref: 28c354789
Ref: userman/printing printing-messages-and-asking-questions354789
Ref: 28d354789
Ref: userman/printing printing-printing354789
Ref: 28e354789
Ref: Printing messages and asking questions-Footnote-1357917
Node: Printing messages357978
Ref: userman/printing id1358118
Ref: 28f358118
Ref: userman/printing printing-messages358118
Ref: 290358118
Node: Message tokenization361747
Ref: userman/printing message-tokenization361909
Ref: 292361909
Node: Meta-messages364034
Ref: userman/printing meta-messages364200
Ref: 294364200
Ref: Meta-messages-Footnote-1364624
Node: Intercepting messages364685
Ref: userman/printing intercepting-messages364847
Ref: 296364847
Node: Asking questions366699
Ref: userman/printing asking-questions366870
Ref: 299366870
Ref: userman/printing printing-questions366870
Ref: 29a366870
Node: Intercepting questions369143
Ref: userman/printing intercepting-questions369284
Ref: 29c369284
Node: Term and goal expansion370149
Ref: userman/expansion doc370306
Ref: 29e370306
Ref: userman/expansion expansion-expansion370306
Ref: a5370306
Ref: userman/expansion term-and-goal-expansion370306
Ref: 29f370306
Node: Defining expansions370796
Ref: userman/expansion defining-expansions370926
Ref: 2a0370926
Ref: Defining expansions-Footnote-1373463
Node: Expanding grammar rules373528
Ref: userman/expansion expanding-grammar-rules373679
Ref: 2a2373679
Node: Hook objects374279
Ref: userman/expansion hook-objects374431
Ref: 2a3374431
Ref: Hook objects-Footnote-1377647
Node: Bypassing expansions377712
Ref: userman/expansion bypassing-expansions377870
Ref: 2a5377870
Node: Combining multiple expansions378239
Ref: userman/expansion combining-multiple-expansions378416
Ref: 2a6378416
Ref: Combining multiple expansions-Footnote-1379043
Ref: Combining multiple expansions-Footnote-2379116
Node: Using Prolog defined expansions379179
Ref: userman/expansion using-prolog-defined-expansions379327
Ref: 2a7379327
Node: Documenting380699
Ref: userman/documenting doc380827
Ref: 2a8380827
Ref: userman/documenting documenting380827
Ref: 2a9380827
Ref: userman/documenting documenting-documenting380827
Ref: 8f380827
Ref: Documenting-Footnote-1381798
Node: Documenting directives381849
Ref: userman/documenting documenting-directives381987
Ref: 2aa381987
Ref: userman/documenting id1381987
Ref: 2ab381987
Node: Entity directives382379
Ref: userman/documenting documenting-entity382503
Ref: 2ac382503
Ref: userman/documenting entity-directives382503
Ref: 2ad382503
Ref: Entity directives-Footnote-1384914
Node: Predicate directives384965
Ref: userman/documenting documenting-predicate385089
Ref: 2ae385089
Ref: userman/documenting predicate-directives385089
Ref: 2af385089
Ref: Predicate directives-Footnote-1387800
Node: Processing and viewing documenting files387851
Ref: userman/documenting documenting-processing388032
Ref: 2b0388032
Ref: userman/documenting processing-and-viewing-documenting-files388032
Ref: 2b1388032
Ref: Processing and viewing documenting files-Footnote-1390680
Ref: Processing and viewing documenting files-Footnote-2390731
Ref: Processing and viewing documenting files-Footnote-3390782
Ref: Processing and viewing documenting files-Footnote-4390833
Node: Inline formatting in comments text390884
Ref: userman/documenting documenting-formatting391051
Ref: 2b2391051
Ref: userman/documenting inline-formatting-in-comments-text391051
Ref: 2b3391051
Node: Diagrams391378
Ref: userman/documenting diagrams391496
Ref: 2b4391496
Ref: Diagrams-Footnote-1392155
Node: Debugging392203
Ref: userman/debugging doc392322
Ref: 2b5392322
Ref: userman/debugging debugging392322
Ref: 2b6392322
Ref: userman/debugging debugging-debugging392322
Ref: 2b7392322
Ref: Debugging-Footnote-1393929
Node: Compiling source files in debug mode393978
Ref: userman/debugging compiling-source-files-in-debug-mode394107
Ref: 2b9394107
Ref: userman/debugging debugging-debug-mode394107
Ref: 2ba394107
Node: Procedure box model395756
Ref: userman/debugging debugging-box-model395913
Ref: 2bb395913
Ref: userman/debugging procedure-box-model395913
Ref: 2bc395913
Node: Defining spy points397819
Ref: userman/debugging defining-spy-points397965
Ref: 2bd397965
Node: Defining line number and predicate spy points398699
Ref: userman/debugging defining-line-number-and-predicate-spy-points398855
Ref: 2be398855
Node: Defining context spy points399758
Ref: userman/debugging defining-context-spy-points399946
Ref: 2bf399946
Node: Removing all spy points401149
Ref: userman/debugging removing-all-spy-points401283
Ref: 2c0401283
Node: Tracing program execution401624
Ref: userman/debugging programming-trace401777
Ref: 2c1401777
Ref: userman/debugging tracing-program-execution401777
Ref: 2c2401777
Node: Debugging using spy points403795
Ref: userman/debugging debugging-debug403947
Ref: 2c3403947
Ref: userman/debugging debugging-using-spy-points403947
Ref: 2c4403947
Node: Debugging commands404599
Ref: userman/debugging debugging-commands404749
Ref: 2c5404749
Ref: userman/debugging id1404749
Ref: 2c6404749
Node: Context-switching calls407647
Ref: userman/debugging context-switching-calls407789
Ref: 2c7407789
Ref: userman/debugging debugging-context407789
Ref: 2c8407789
Node: Debugging messages409728
Ref: userman/debugging debugging-messages409900
Ref: 295409900
Ref: userman/debugging id2409900
Ref: 2c9409900
Node: Meta-messages<2>410480
Ref: userman/debugging meta-messages410615
Ref: 2ca410615
Node: Selective printing of debug messages412740
Ref: userman/debugging selective-printing-of-debug-messages412875
Ref: 2cb412875
Ref: Selective printing of debug messages-Footnote-1413980
Node: Using the term-expansion mechanism for debugging414029
Ref: userman/debugging debugging-hooks414193
Ref: 2cd414193
Ref: userman/debugging using-the-term-expansion-mechanism-for-debugging414193
Ref: 2ce414193
Node: Ports profiling415090
Ref: userman/debugging debugging-ports-profiling415227
Ref: 2cf415227
Ref: userman/debugging ports-profiling415227
Ref: 2d0415227
Ref: Ports profiling-Footnote-1415595
Node: Performance<2>415649
Ref: userman/performance doc415775
Ref: 2d1415775
Ref: userman/performance performance415775
Ref: 2d2415775
Ref: userman/performance performance-performance415775
Ref: 28b415775
Node: Source code compilation modes417176
Ref: userman/performance source-code-compilation-modes417305
Ref: 2d3417305
Node: Local predicate calls417992
Ref: userman/performance local-predicate-calls418171
Ref: 2d4418171
Node: Calls to imported or inherited predicates418378
Ref: userman/performance calls-to-imported-or-inherited-predicates418554
Ref: 2d5418554
Node: Calls to module predicates418805
Ref: userman/performance calls-to-module-predicates418971
Ref: 2d6418971
Node: Messages<2>419195
Ref: userman/performance messages419328
Ref: 2d7419328
Node: Inlining420652
Ref: userman/performance inlining420806
Ref: 2d8420806
Node: Generated code simplification and optimizations421470
Ref: userman/performance generated-code-simplification-and-optimizations421639
Ref: 2d9421639
Node: Size of the generated code422102
Ref: userman/performance size-of-the-generated-code422282
Ref: 2da422282
Node: Debug mode overhead423451
Ref: userman/performance debug-mode-overhead423604
Ref: 2db423604
Ref: Debug mode overhead-Footnote-1424950
Ref: Debug mode overhead-Footnote-2425026
Node: Other considerations425104
Ref: userman/performance other-considerations425222
Ref: 2dc425222
Ref: Other considerations-Footnote-1425677
Ref: Other considerations-Footnote-2425755
Ref: Other considerations-Footnote-3425838
Node: Installing Logtalk425883
Ref: userman/installing doc426038
Ref: 2dd426038
Ref: userman/installing installing-installing426038
Ref: 2de426038
Ref: userman/installing installing-logtalk426038
Ref: 2df426038
Node: Hardware and software requirements428010
Ref: userman/installing hardware-and-software-requirements428145
Ref: 2e0428145
Ref: userman/installing installing-requirements428145
Ref: 2e1428145
Node: Computer and operating system428294
Ref: userman/installing computer-and-operating-system428437
Ref: 2e2428437
Ref: userman/installing installing-computer428437
Ref: 2e3428437
Node: Prolog compiler428644
Ref: userman/installing installing-compiler428787
Ref: 2e4428787
Ref: userman/installing prolog-compiler428787
Ref: 2e5428787
Node: Logtalk installers430070
Ref: userman/installing installing-installers430233
Ref: 2e6430233
Ref: userman/installing logtalk-installers430233
Ref: 2e7430233
Node: Source distribution430531
Ref: userman/installing installing-sources430681
Ref: 2e8430681
Ref: userman/installing source-distribution430681
Ref: 2e9430681
Node: Distribution overview431329
Ref: userman/installing distribution-overview431452
Ref: 2ea431452
Ref: userman/installing installing-organization431452
Ref: 2eb431452
Node: Adapter files435413
Ref: userman/installing adapter-files435526
Ref: 2ec435526
Ref: userman/installing installing-adapters435526
Ref: 2ed435526
Ref: userman/installing flag-settings-file437065
Ref: 2ee437065
Ref: userman/installing flag-prolog-dialect437690
Ref: 2ef437690
Ref: userman/installing flag-prolog-version437874
Ref: 2f1437874
Ref: userman/installing flag-prolog-compatible-version438216
Ref: 2f2438216
Ref: userman/installing flag-prolog-conformance438614
Ref: 2f3438614
Ref: userman/installing flag-unicode438900
Ref: 2f4438900
Ref: userman/installing flag-encoding-directive439173
Ref: 23f439173
Ref: userman/installing flag-tabling439605
Ref: 2f5439605
Ref: userman/installing flag-engines439797
Ref: 2f6439797
Ref: userman/installing flag-threads440057
Ref: 1d7440057
Ref: userman/installing flag-modules440339
Ref: 2f8440339
Ref: userman/installing flag-coinduction440607
Ref: 139440607
Node: Settings files440888
Ref: userman/installing installing-settings441030
Ref: 2fa441030
Ref: userman/installing settings-files441030
Ref: 2fb441030
Node: Compiler and runtime443681
Ref: userman/installing compiler-and-runtime443817
Ref: 2fc443817
Ref: userman/installing installing-runtime443817
Ref: 2fd443817
Node: Library444177
Ref: userman/installing installing-library444307
Ref: 2fe444307
Ref: userman/installing library444307
Ref: 2ff444307
Node: Examples444538
Ref: userman/installing examples444668
Ref: 300444668
Ref: userman/installing installing-examples444668
Ref: 301444668
Node: Logtalk source files445227
Ref: userman/installing installing-entities445341
Ref: 302445341
Ref: userman/installing logtalk-source-files445341
Ref: 303445341
Node: Prolog integration and migration guide445993
Ref: userman/migration doc446125
Ref: 304446125
Ref: userman/migration migration-migration446125
Ref: 305446125
Ref: userman/migration prolog-integration-and-migration-guide446125
Ref: 306446125
Node: Source files with both Prolog code and Logtalk code447620
Ref: userman/migration migration-hybrid447816
Ref: 307447816
Ref: userman/migration source-files-with-both-prolog-code-and-logtalk-code447816
Ref: 308447816
Node: Encapsulating plain Prolog code in objects448683
Ref: userman/migration encapsulating-plain-prolog-code-in-objects448926
Ref: 309448926
Ref: userman/migration migration-encapsulating448926
Ref: 30a448926
Node: Prolog multifile predicates450884
Ref: userman/migration migration-multifile451009
Ref: 30b451009
Ref: userman/migration prolog-multifile-predicates451009
Ref: 30c451009
Node: Converting Prolog modules into objects452697
Ref: userman/migration converting-prolog-modules-into-objects452924
Ref: 30d452924
Ref: userman/migration migration-converting452924
Ref: 30e452924
Node: Compiling Prolog modules as objects457331
Ref: userman/migration compiling-prolog-modules-as-objects457573
Ref: 30f457573
Ref: userman/migration migration-compiling457573
Ref: 310457573
Node: Supported module directives458378
Ref: userman/migration migration-compatibility458540
Ref: 311458540
Ref: userman/migration supported-module-directives458540
Ref: 312458540
Node: Current limitations and workarounds462049
Ref: userman/migration current-limitations-and-workarounds462211
Ref: 313462211
Ref: userman/migration migration-limitations462211
Ref: 314462211
Node: Dealing with proprietary Prolog directives and predicates463850
Ref: userman/migration dealing-with-proprietary-prolog-directives-and-predicates464089
Ref: 316464089
Ref: userman/migration migration-proprietary464089
Ref: 317464089
Node: Calling Prolog module predicates<2>466425
Ref: userman/migration calling-prolog-module-predicates466620
Ref: 318466620
Ref: userman/migration migration-calling466620
Ref: 319466620
Node: Reference Manual469655
Ref: refman/index doc469767
Ref: 31a469767
Ref: refman/index reference-manual469767
Ref: 31b469767
Node: Grammar469925
Ref: refman/grammar doc470031
Ref: 31c470031
Ref: refman/grammar grammar470031
Ref: 31d470031
Ref: refman/grammar grammar-grammar470031
Ref: 31e470031
Node: Entities470667
Ref: refman/grammar entities470764
Ref: 31f470764
Ref: refman/grammar grammar-entities470764
Ref: 320470764
Node: Object definition470875
Ref: refman/grammar grammar-object-definition471000
Ref: 321471000
Ref: refman/grammar object-definition471000
Ref: 322471000
Node: Category definition472000
Ref: refman/grammar category-definition472136
Ref: 323472136
Ref: refman/grammar grammar-category-definition472136
Ref: 324472136
Node: Protocol definition472755
Ref: refman/grammar grammar-protocol-definition472890
Ref: 325472890
Ref: refman/grammar protocol-definition472890
Ref: 326472890
Node: Entity relations473264
Ref: refman/grammar entity-relations473398
Ref: 327473398
Ref: refman/grammar grammar-entity-relations473398
Ref: 328473398
Node: Implemented protocols474464
Ref: refman/grammar grammar-implemented-protocols474584
Ref: 329474584
Ref: refman/grammar implemented-protocols474584
Ref: 32a474584
Node: Extended protocols475166
Ref: refman/grammar extended-protocols475314
Ref: 32b475314
Ref: refman/grammar grammar-extended-protocols475314
Ref: 32c475314
Node: Imported categories475857
Ref: refman/grammar grammar-imported-categories476000
Ref: 32d476000
Ref: refman/grammar imported-categories476000
Ref: 32e476000
Node: Extended objects476546
Ref: refman/grammar extended-objects476690
Ref: 32f476690
Ref: refman/grammar grammar-extended-objects476690
Ref: 330476690
Node: Extended categories477203
Ref: refman/grammar extended-categories477348
Ref: 331477348
Ref: refman/grammar grammar-extended-categories477348
Ref: 332477348
Node: Instantiated objects477894
Ref: refman/grammar grammar-instantiated-objects478042
Ref: 333478042
Ref: refman/grammar instantiated-objects478042
Ref: 334478042
Node: Specialized objects478607
Ref: refman/grammar grammar-specialized-objects478756
Ref: 335478756
Ref: refman/grammar specialized-objects478756
Ref: 336478756
Node: Complemented objects479308
Ref: refman/grammar complemented-objects479463
Ref: 337479463
Ref: refman/grammar grammar-complemented-objects479463
Ref: 338479463
Node: Entity and predicate scope479910
Ref: refman/grammar entity-and-predicate-scope480037
Ref: 339480037
Ref: refman/grammar grammar-scope480037
Ref: 33a480037
Node: Entity identifiers480223
Ref: refman/grammar entity-identifiers480355
Ref: 33b480355
Ref: refman/grammar grammar-entity-identifiers480355
Ref: 33c480355
Node: Object identifiers481010
Ref: refman/grammar grammar-object-identifiers481131
Ref: 33d481131
Ref: refman/grammar object-identifiers481131
Ref: 33e481131
Node: Category identifiers481631
Ref: refman/grammar category-identifiers481781
Ref: 33f481781
Ref: refman/grammar grammar-category-identifiers481781
Ref: 340481781
Node: Protocol identifiers482307
Ref: refman/grammar grammar-protocol-identifiers482457
Ref: 341482457
Ref: refman/grammar protocol-identifiers482457
Ref: 342482457
Node: Module identifiers482970
Ref: refman/grammar grammar-module-identifiers483091
Ref: 343483091
Ref: refman/grammar module-identifiers483091
Ref: 344483091
Node: Source file names483193
Ref: refman/grammar grammar-source-file-names483314
Ref: 345483314
Ref: refman/grammar source-file-names483314
Ref: 346483314
Node: Terms483909
Ref: refman/grammar grammar-terms484022
Ref: 347484022
Ref: refman/grammar terms484022
Ref: 348484022
Node: Object terms484093
Ref: refman/grammar grammar-object-terms484189
Ref: 349484189
Ref: refman/grammar object-terms484189
Ref: 34a484189
Node: Category terms484414
Ref: refman/grammar category-terms484510
Ref: 34b484510
Ref: refman/grammar grammar-category-terms484510
Ref: 34c484510
Node: Directives484751
Ref: refman/grammar directives484864
Ref: 34d484864
Ref: refman/grammar grammar-directives484864
Ref: 34e484864
Node: Source file directives485161
Ref: refman/grammar grammar-source-file-directives485292
Ref: 34f485292
Ref: refman/grammar source-file-directives485292
Ref: 350485292
Node: Conditional compilation directives485762
Ref: refman/grammar conditional-compilation-directives485922
Ref: 351485922
Ref: refman/grammar grammar-conditional-compilation-directives485922
Ref: 352485922
Node: Object directives<2>486412
Ref: refman/grammar grammar-object-directives486572
Ref: 353486572
Ref: refman/grammar object-directives486572
Ref: 354486572
Node: Category directives<2>487266
Ref: refman/grammar category-directives487414
Ref: 355487414
Ref: refman/grammar grammar-category-directives487414
Ref: 356487414
Node: Protocol directives<2>488014
Ref: refman/grammar grammar-protocol-directives488165
Ref: 357488165
Ref: refman/grammar protocol-directives488165
Ref: 358488165
Node: Predicate directives<2>488698
Ref: refman/grammar grammar-predicate-directives488818
Ref: 359488818
Ref: refman/grammar predicate-directives488818
Ref: 35a488818
Node: Clauses and goals501478
Ref: refman/grammar clauses-and-goals501607
Ref: 35b501607
Ref: refman/grammar grammar-clauses501607
Ref: 35c501607
Node: Lambda expressions<2>503028
Ref: refman/grammar grammar-lambdas503164
Ref: 148503164
Ref: refman/grammar lambda-expressions503164
Ref: 35d503164
Node: Entity properties503717
Ref: refman/grammar entity-properties503859
Ref: 35e503859
Ref: refman/grammar grammar-entity-properties503859
Ref: a3503859
Node: Predicate properties<2>512297
Ref: refman/grammar grammar-predicate-properties512435
Ref: 35f512435
Ref: refman/grammar predicate-properties512435
Ref: 360512435
Node: Compiler flags<2>514332
Ref: refman/grammar compiler-flags514444
Ref: 361514444
Ref: refman/grammar grammar-compiler-flags514444
Ref: 362514444
Node: Control constructs514544
Ref: refman/control/index doc514672
Ref: 363514672
Ref: refman/control/index control-constructs514672
Ref: 364514672
Node: Message sending<2>514942
Ref: refman/control/message_sending doc515061
Ref: 365515061
Ref: refman/control/message_sending id1515061
Ref: 366515061
Ref: refman/control/message_sending message-sending515061
Ref: 367515061
Node: /2515140
Ref: refman/control/send_to_object_2 doc515227
Ref: 368515227
Ref: refman/control/send_to_object_2 control-send-to-object-2515227
Ref: 5e515227
Ref: refman/control/send_to_object_2 id1515227
Ref: 369515227
Node: Description515347
Ref: refman/control/send_to_object_2 description515451
Ref: 36a515451
Node: Modes and number of proofs516952
Ref: refman/control/send_to_object_2 modes-and-number-of-proofs517071
Ref: 36e517071
Node: Errors517245
Ref: refman/control/send_to_object_2 errors517364
Ref: 36f517364
Node: Examples<2>518541
Ref: refman/control/send_to_object_2 examples518625
Ref: 370518625
Node: /1518814
Ref: refman/control/send_to_self_1 doc518901
Ref: 371518901
Ref: refman/control/send_to_self_1 control-send-to-self-1518901
Ref: 3d518901
Ref: refman/control/send_to_self_1 id1518901
Ref: 372518901
Node: Description<2>519076
Ref: refman/control/send_to_self_1 description519186
Ref: 373519186
Node: Modes and number of proofs<2>520134
Ref: refman/control/send_to_self_1 modes-and-number-of-proofs520262
Ref: 374520262
Node: Errors<2>520366
Ref: refman/control/send_to_self_1 errors520491
Ref: 375520491
Node: Examples<3>520976
Ref: refman/control/send_to_self_1 examples521063
Ref: 376521063
Node: Message delegation521273
Ref: refman/control/message_delegation doc521445
Ref: 377521445
Ref: refman/control/message_delegation id1521445
Ref: 378521445
Ref: refman/control/message_delegation message-delegation521445
Ref: 379521445
Node: []/1521515
Ref: refman/control/delegate_message_1 doc521593
Ref: 37a521593
Ref: refman/control/delegate_message_1 control-delegate-message-1521593
Ref: 61521593
Ref: refman/control/delegate_message_1 id1521593
Ref: 37b521593
Node: Description<3>521768
Ref: refman/control/delegate_message_1 description521880
Ref: 37c521880
Node: Modes and number of proofs<3>522782
Ref: refman/control/delegate_message_1 modes-and-number-of-proofs522912
Ref: 37d522912
Node: Errors<3>523090
Ref: refman/control/delegate_message_1 errors523217
Ref: 37e523217
Node: Examples<4>524531
Ref: refman/control/delegate_message_1 examples524620
Ref: 37f524620
Node: Calling imported and inherited predicates<2>524855
Ref: refman/control/super_calls doc525036
Ref: 380525036
Ref: refman/control/super_calls calling-imported-and-inherited-predicates525036
Ref: 381525036
Ref: refman/control/super_calls super-calls525036
Ref: 382525036
Node: ^^/1525152
Ref: refman/control/call_super_1 doc525256
Ref: 383525256
Ref: refman/control/call_super_1 control-call-super-1525256
Ref: 3e525256
Ref: refman/control/call_super_1 id1525256
Ref: 384525256
Node: Description<4>525431
Ref: refman/control/call_super_1 description525543
Ref: 385525543
Node: Modes and number of proofs<4>527515
Ref: refman/control/call_super_1 modes-and-number-of-proofs527645
Ref: 386527645
Node: Errors<4>527749
Ref: refman/control/call_super_1 errors527876
Ref: 387527876
Node: Examples<5>528371
Ref: refman/control/call_super_1 examples528460
Ref: 388528460
Node: Calling external predicates528699
Ref: refman/control/external_calls doc528885
Ref: 389528885
Ref: refman/control/external_calls calling-external-predicates528885
Ref: 38a528885
Ref: refman/control/external_calls external-calls528885
Ref: 38b528885
Node: {}/1528973
Ref: refman/control/external_call_1 doc529060
Ref: 38c529060
Ref: refman/control/external_call_1 control-external-call-1529060
Ref: 14d529060
Ref: refman/control/external_call_1 id1529060
Ref: 38d529060
Node: Description<5>529235
Ref: refman/control/external_call_1 description529347
Ref: 38e529347
Node: Modes and number of proofs<5>530704
Ref: refman/control/external_call_1 modes-and-number-of-proofs530834
Ref: 390530834
Node: Errors<5>530938
Ref: refman/control/external_call_1 errors531065
Ref: 391531065
Node: Examples<6>531364
Ref: refman/control/external_call_1 examples531453
Ref: 392531453
Node: Context switching calls532003
Ref: refman/control/context_switching_calls doc532136
Ref: 393532136
Ref: refman/control/context_switching_calls context-switching-calls532136
Ref: 394532136
Ref: refman/control/context_switching_calls id1532136
Ref: 395532136
Node: <</2532216
Ref: refman/control/context_switch_2 doc532299
Ref: 396532299
Ref: refman/control/context_switch_2 control-context-switch-2532299
Ref: a2532299
Ref: refman/control/context_switch_2 id1532299
Ref: 397532299
Node: Description<6>532474
Ref: refman/control/context_switch_2 description532586
Ref: 398532586
Node: Modes and number of proofs<6>534015
Ref: refman/control/context_switch_2 modes-and-number-of-proofs534145
Ref: 399534145
Node: Errors<6>534319
Ref: refman/control/context_switch_2 errors534446
Ref: 39a534446
Node: Examples<7>535452
Ref: refman/control/context_switch_2 examples535541
Ref: 39b535541
Node: Directives<2>535710
Ref: refman/directives/index doc535850
Ref: 39c535850
Ref: refman/directives/index directives535850
Ref: 39d535850
Node: Source file directives<2>536113
Ref: refman/directives/source_file_directives doc536253
Ref: 39e536253
Ref: refman/directives/source_file_directives id1536253
Ref: 39f536253
Ref: refman/directives/source_file_directives source-file-directives536253
Ref: 3a0536253
Node: encoding/1536404
Ref: refman/directives/encoding_1 doc536513
Ref: 3a1536513
Ref: refman/directives/encoding_1 directives-encoding-1536513
Ref: 23e536513
Ref: refman/directives/encoding_1 encoding-1536513
Ref: 3a2536513
Node: Description<7>536641
Ref: refman/directives/encoding_1 description536748
Ref: 3a3536748
Ref: Description<7>-Footnote-1537955
Node: Template and modes538032
Ref: refman/directives/encoding_1 template-and-modes538159
Ref: 3a4538159
Node: Examples<8>538236
Ref: refman/directives/encoding_1 examples538340
Ref: 3a5538340
Node: include/1538403
Ref: refman/directives/include_1 doc538537
Ref: 3a6538537
Ref: refman/directives/include_1 directives-include-1538537
Ref: 92538537
Ref: refman/directives/include_1 include-1538537
Ref: 3a7538537
Node: Description<8>538685
Ref: refman/directives/include_1 description538794
Ref: 3a8538794
Node: Template and modes<2>540268
Ref: refman/directives/include_1 template-and-modes540397
Ref: 3a9540397
Node: Examples<9>540485
Ref: refman/directives/include_1 examples540591
Ref: 3aa540591
Node: initialization/1541084
Ref: refman/directives/initialization_1 doc541212
Ref: 3ab541212
Ref: refman/directives/initialization_1 directives-initialization-1541212
Ref: 88541212
Ref: refman/directives/initialization_1 initialization-1541212
Ref: 3ac541212
Node: Description<9>541375
Ref: refman/directives/initialization_1 description541491
Ref: 3ad541491
Node: Template and modes<3>542603
Ref: refman/directives/initialization_1 template-and-modes542740
Ref: 3ae542740
Node: Examples<10>542829
Ref: refman/directives/initialization_1 examples542943
Ref: 3af542943
Node: op/3543107
Ref: refman/directives/op_3 doc543244
Ref: 3b0543244
Ref: refman/directives/op_3 directives-op-3543244
Ref: 126543244
Ref: refman/directives/op_3 op-3543244
Ref: 3b1543244
Node: Description<10>543386
Ref: refman/directives/op_3 description543491
Ref: 3b2543491
Node: Template and modes<4>543837
Ref: refman/directives/op_3 template-and-modes543963
Ref: 3b3543963
Node: Examples<11>544075
Ref: refman/directives/op_3 examples544177
Ref: 3b4544177
Node: set_logtalk_flag/2544356
Ref: refman/directives/set_logtalk_flag_2 doc544468
Ref: 3b5544468
Ref: refman/directives/set_logtalk_flag_2 directives-set-logtalk-flag-2544468
Ref: 263544468
Ref: refman/directives/set_logtalk_flag_2 set-logtalk-flag-2544468
Ref: 3b6544468
Node: Description<11>544659
Ref: refman/directives/set_logtalk_flag_2 description544778
Ref: 3b7544778
Node: Template and modes<5>545227
Ref: refman/directives/set_logtalk_flag_2 template-and-modes545364
Ref: 3b8545364
Node: Errors<7>545460
Ref: refman/directives/set_logtalk_flag_2 errors545594
Ref: 3b9545594
Node: Examples<12>546105
Ref: refman/directives/set_logtalk_flag_2 examples546209
Ref: 3ba546209
Node: Conditional compilation directives<2>546547
Ref: refman/directives/conditional_compilation_directives doc546716
Ref: 3bb546716
Ref: refman/directives/conditional_compilation_directives conditional-compilation-directives546716
Ref: 2f0546716
Ref: refman/directives/conditional_compilation_directives id1546716
Ref: 3bc546716
Node: if/1546852
Ref: refman/directives/if_1 doc546964
Ref: 3bd546964
Ref: refman/directives/if_1 directives-if-1546964
Ref: 244546964
Ref: refman/directives/if_1 if-1546964
Ref: 3be546964
Node: Description<12>547104
Ref: refman/directives/if_1 description547209
Ref: 3bf547209
Node: Template and modes<6>547761
Ref: refman/directives/if_1 template-and-modes547887
Ref: 3c0547887
Node: Examples<13>547962
Ref: refman/directives/if_1 examples548064
Ref: 3c1548064
Node: elif/1548677
Ref: refman/directives/elif_1 doc548804
Ref: 3c2548804
Ref: refman/directives/elif_1 directives-elif-1548804
Ref: 245548804
Ref: refman/directives/elif_1 elif-1548804
Ref: 3c3548804
Node: Description<13>548948
Ref: refman/directives/elif_1 description549055
Ref: 3c4549055
Node: Template and modes<7>549597
Ref: refman/directives/elif_1 template-and-modes549725
Ref: 3c5549725
Node: Examples<14>549802
Ref: refman/directives/elif_1 examples549906
Ref: 3c6549906
Node: else/0550246
Ref: refman/directives/else_0 doc550376
Ref: 3c7550376
Ref: refman/directives/else_0 directives-else-0550376
Ref: 246550376
Ref: refman/directives/else_0 else-0550376
Ref: 3c8550376
Node: Description<14>550520
Ref: refman/directives/else_0 description550627
Ref: 3c9550627
Node: Template and modes<8>550860
Ref: refman/directives/else_0 template-and-modes550988
Ref: 3ca550988
Node: Examples<15>551056
Ref: refman/directives/else_0 examples551160
Ref: 3cb551160
Node: endif/0551747
Ref: refman/directives/endif_0 doc551862
Ref: 3cc551862
Ref: refman/directives/endif_0 directives-endif-0551862
Ref: 247551862
Ref: refman/directives/endif_0 endif-0551862
Ref: 3cd551862
Node: Description<15>552010
Ref: refman/directives/endif_0 description552118
Ref: 3ce552118
Node: Template and modes<9>552248
Ref: refman/directives/endif_0 template-and-modes552377
Ref: 3cf552377
Node: Examples<16>552446
Ref: refman/directives/endif_0 examples552551
Ref: 3d0552551
Node: Entity directives<2>552771
Ref: refman/directives/entity_directives doc552938
Ref: 3d1552938
Ref: refman/directives/entity_directives entity-directives552938
Ref: 3d2552938
Ref: refman/directives/entity_directives id1552938
Ref: 3d3552938
Node: built_in/0553167
Ref: refman/directives/built_in_0 doc553274
Ref: 3d4553274
Ref: refman/directives/built_in_0 built-in-0553274
Ref: 3d5553274
Ref: refman/directives/built_in_0 directives-built-in-0553274
Ref: 3d6553274
Node: Description<16>553427
Ref: refman/directives/built_in_0 description553539
Ref: 3d7553539
Node: Template and modes<10>553699
Ref: refman/directives/built_in_0 template-and-modes553832
Ref: 3d8553832
Node: Examples<17>553902
Ref: refman/directives/built_in_0 examples554011
Ref: 3d9554011
Node: category/1-3554065
Ref: refman/directives/category_1_3 doc554190
Ref: 3da554190
Ref: refman/directives/category_1_3 category-1-3554190
Ref: 3db554190
Ref: refman/directives/category_1_3 directives-category-1-3554190
Ref: e4554190
Node: Description<17>554347
Ref: refman/directives/category_1_3 description554461
Ref: 3dc554461
Node: Template and modes<11>555104
Ref: refman/directives/category_1_3 template-and-modes555239
Ref: 3dd555239
Node: Examples<18>556110
Ref: refman/directives/category_1_3 examples556221
Ref: 3de556221
Node: dynamic/0556621
Ref: refman/directives/dynamic_0 doc556750
Ref: 3df556750
Ref: refman/directives/dynamic_0 directives-dynamic-0556750
Ref: 8b556750
Ref: refman/directives/dynamic_0 dynamic-0556750
Ref: 3e0556750
Node: Description<18>556901
Ref: refman/directives/dynamic_0 description557012
Ref: 3e1557012
Node: Template and modes<12>557165
Ref: refman/directives/dynamic_0 template-and-modes557297
Ref: 3e2557297
Node: Examples<19>557368
Ref: refman/directives/dynamic_0 examples557476
Ref: 3e3557476
Node: end_category/0557665
Ref: refman/directives/end_category_0 doc557794
Ref: 3e4557794
Ref: refman/directives/end_category_0 directives-end-category-0557794
Ref: e5557794
Ref: refman/directives/end_category_0 end-category-0557794
Ref: 3e5557794
Node: Description<19>557957
Ref: refman/directives/end_category_0 description558073
Ref: 3e6558073
Node: Template and modes<13>558163
Ref: refman/directives/end_category_0 template-and-modes558300
Ref: 3e7558300
Node: Examples<20>558376
Ref: refman/directives/end_category_0 examples558489
Ref: 3e8558489
Node: end_object/0558593
Ref: refman/directives/end_object_0 doc558727
Ref: 3e9558727
Ref: refman/directives/end_object_0 directives-end-object-0558727
Ref: 76558727
Ref: refman/directives/end_object_0 end-object-0558727
Ref: 3ea558727
Node: Description<20>558886
Ref: refman/directives/end_object_0 description559000
Ref: 3eb559000
Node: Template and modes<14>559086
Ref: refman/directives/end_object_0 template-and-modes559221
Ref: 3ec559221
Node: Examples<21>559295
Ref: refman/directives/end_object_0 examples559406
Ref: 3ed559406
Node: end_protocol/0559506
Ref: refman/directives/end_protocol_0 doc559632
Ref: 3ee559632
Ref: refman/directives/end_protocol_0 directives-end-protocol-0559632
Ref: b4559632
Ref: refman/directives/end_protocol_0 end-protocol-0559632
Ref: 3ef559632
Node: Description<21>559795
Ref: refman/directives/end_protocol_0 description559911
Ref: 3f0559911
Node: Template and modes<15>560001
Ref: refman/directives/end_protocol_0 template-and-modes560138
Ref: 3f1560138
Node: Examples<22>560214
Ref: refman/directives/end_protocol_0 examples560327
Ref: 3f2560327
Node: info/1560431
Ref: refman/directives/info_1 doc560555
Ref: 3f3560555
Ref: refman/directives/info_1 directives-info-1560555
Ref: 8e560555
Ref: refman/directives/info_1 info-1560555
Ref: 3f4560555
Node: Description<22>560702
Ref: refman/directives/info_1 description560810
Ref: 3f5560810
Node: Template and modes<16>561111
Ref: refman/directives/info_1 template-and-modes561240
Ref: 3f6561240
Node: Examples<23>561327
Ref: refman/directives/info_1 examples561432
Ref: 3f7561432
Node: object/1-5561749
Ref: refman/directives/object_1_5 doc561871
Ref: 3f8561871
Ref: refman/directives/object_1_5 directives-object-1-5561871
Ref: 75561871
Ref: refman/directives/object_1_5 object-1-5561871
Ref: 3f9561871
Node: Description<23>562026
Ref: refman/directives/object_1_5 description562138
Ref: 3fa562138
Node: Template and modes<17>563979
Ref: refman/directives/object_1_5 template-and-modes564112
Ref: 3fb564112
Node: Examples<24>566663
Ref: refman/directives/object_1_5 examples566772
Ref: 3fc566772
Node: protocol/1-2567302
Ref: refman/directives/protocol_1_2 doc567428
Ref: 3fd567428
Ref: refman/directives/protocol_1_2 directives-protocol-1-2567428
Ref: b3567428
Ref: refman/directives/protocol_1_2 protocol-1-2567428
Ref: 3fe567428
Node: Description<24>567587
Ref: refman/directives/protocol_1_2 description567701
Ref: 3ff567701
Node: Template and modes<18>567853
Ref: refman/directives/protocol_1_2 template-and-modes567988
Ref: 400567988
Node: Examples<25>568158
Ref: refman/directives/protocol_1_2 examples568269
Ref: 401568269
Node: threaded/0568496
Ref: refman/directives/threaded_0 doc568618
Ref: 402568618
Ref: refman/directives/threaded_0 directives-threaded-0568618
Ref: 1da568618
Ref: refman/directives/threaded_0 threaded-0568618
Ref: 403568618
Node: Description<25>568773
Ref: refman/directives/threaded_0 description568885
Ref: 404568885
Node: Template and modes<19>569725
Ref: refman/directives/threaded_0 template-and-modes569858
Ref: 405569858
Node: Examples<26>569930
Ref: refman/directives/threaded_0 examples570039
Ref: 406570039
Node: uses/1570170
Ref: refman/directives/uses_1 doc570271
Ref: 407570271
Ref: refman/directives/uses_1 directives-uses-1570271
Ref: 95570271
Ref: refman/directives/uses_1 uses-1570271
Ref: 408570271
Node: Description<26>570418
Ref: refman/directives/uses_1 description570526
Ref: 409570526
Node: Template and modes<20>571616
Ref: refman/directives/uses_1 template-and-modes571745
Ref: 40a571745
Node: Examples<27>571833
Ref: refman/directives/uses_1 examples571938
Ref: 40b571938
Node: Predicate directives<3>572670
Ref: refman/directives/predicate_directives doc572791
Ref: 40c572791
Ref: refman/directives/predicate_directives id1572791
Ref: 40d572791
Ref: refman/directives/predicate_directives predicate-directives572791
Ref: 40e572791
Node: alias/2573093
Ref: refman/directives/alias_2 doc573201
Ref: 40f573201
Ref: refman/directives/alias_2 alias-2573201
Ref: 410573201
Ref: refman/directives/alias_2 directives-alias-2573201
Ref: 12d573201
Node: Description<27>573348
Ref: refman/directives/alias_2 description573457
Ref: 411573457
Node: Template and modes<21>574559
Ref: refman/directives/alias_2 template-and-modes574689
Ref: 412574689
Node: Examples<28>574878
Ref: refman/directives/alias_2 examples574984
Ref: 413574984
Node: coinductive/1575350
Ref: refman/directives/coinductive_1 doc575482
Ref: 414575482
Ref: refman/directives/coinductive_1 coinductive-1575482
Ref: 415575482
Ref: refman/directives/coinductive_1 directives-coinductive-1575482
Ref: 138575482
Node: Description<28>575641
Ref: refman/directives/coinductive_1 description575756
Ref: 416575756
Node: Template and modes<22>577374
Ref: refman/directives/coinductive_1 template-and-modes577510
Ref: 418577510
Node: Examples<29>577712
Ref: refman/directives/coinductive_1 examples577824
Ref: 419577824
Node: discontiguous/1578071
Ref: refman/directives/discontiguous_1 doc578205
Ref: 41a578205
Ref: refman/directives/discontiguous_1 directives-discontiguous-1578205
Ref: 120578205
Ref: refman/directives/discontiguous_1 discontiguous-1578205
Ref: 41b578205
Node: Description<29>578368
Ref: refman/directives/discontiguous_1 description578485
Ref: 41c578485
Node: Template and modes<23>579144
Ref: refman/directives/discontiguous_1 template-and-modes579282
Ref: 41d579282
Node: Examples<30>579435
Ref: refman/directives/discontiguous_1 examples579549
Ref: 41e579549
Node: dynamic/1579712
Ref: refman/directives/dynamic_1 doc579839
Ref: 41f579839
Ref: refman/directives/dynamic_1 directives-dynamic-1579839
Ref: 123579839
Ref: refman/directives/dynamic_1 dynamic-1579839
Ref: 420579839
Node: Description<30>579992
Ref: refman/directives/dynamic_1 description580103
Ref: 421580103
Node: Template and modes<24>581822
Ref: refman/directives/dynamic_1 template-and-modes581954
Ref: 422581954
Node: Examples<31>582115
Ref: refman/directives/dynamic_1 examples582223
Ref: 423582223
Node: info/2582442
Ref: refman/directives/info_2 doc582570
Ref: 424582570
Ref: refman/directives/info_2 directives-info-2582570
Ref: 131582570
Ref: refman/directives/info_2 info-2582570
Ref: 425582570
Node: Description<31>582717
Ref: refman/directives/info_2 description582825
Ref: 426582825
Node: Template and modes<25>583283
Ref: refman/directives/info_2 template-and-modes583412
Ref: 427583412
Node: Examples<32>583581
Ref: refman/directives/info_2 examples583686
Ref: 428583686
Node: meta_predicate/1584057
Ref: refman/directives/meta_predicate_1 doc584195
Ref: 429584195
Ref: refman/directives/meta_predicate_1 directives-meta-predicate-1584195
Ref: 11c584195
Ref: refman/directives/meta_predicate_1 meta-predicate-1584195
Ref: 42a584195
Node: Description<32>584362
Ref: refman/directives/meta_predicate_1 description584480
Ref: 42b584480
Node: Template and modes<26>586095
Ref: refman/directives/meta_predicate_1 template-and-modes586234
Ref: 42c586234
Node: Examples<33>586559
Ref: refman/directives/meta_predicate_1 examples586674
Ref: 42d586674
Node: meta_non_terminal/1587171
Ref: refman/directives/meta_non_terminal_1 doc587309
Ref: 42f587309
Ref: refman/directives/meta_non_terminal_1 directives-meta-non-terminal-1587309
Ref: 42e587309
Ref: refman/directives/meta_non_terminal_1 meta-non-terminal-1587309
Ref: 430587309
Node: Description<33>587482
Ref: refman/directives/meta_non_terminal_1 description587603
Ref: 431587603
Node: Template and modes<27>588868
Ref: refman/directives/meta_non_terminal_1 template-and-modes589010
Ref: 432589010
Node: Examples<34>589359
Ref: refman/directives/meta_non_terminal_1 examples589477
Ref: 433589477
Node: mode/2589672
Ref: refman/directives/mode_2 doc589805
Ref: 434589805
Ref: refman/directives/mode_2 directives-mode-2589805
Ref: 118589805
Ref: refman/directives/mode_2 mode-2589805
Ref: 435589805
Node: Description<34>589952
Ref: refman/directives/mode_2 description590060
Ref: 436590060
Node: Template and modes<28>590422
Ref: refman/directives/mode_2 template-and-modes590551
Ref: 437590551
Node: Examples<35>590714
Ref: refman/directives/mode_2 examples590819
Ref: 438590819
Node: multifile/1591142
Ref: refman/directives/multifile_1 doc591265
Ref: 439591265
Ref: refman/directives/multifile_1 directives-multifile-1591265
Ref: 134591265
Ref: refman/directives/multifile_1 multifile-1591265
Ref: 43a591265
Node: Description<35>591422
Ref: refman/directives/multifile_1 description591535
Ref: 43b591535
Node: Template and modes<29>593107
Ref: refman/directives/multifile_1 template-and-modes593241
Ref: 43c593241
Node: Examples<36>593406
Ref: refman/directives/multifile_1 examples593516
Ref: 43d593516
Node: private/1593735
Ref: refman/directives/private_1 doc593863
Ref: 43e593863
Ref: refman/directives/private_1 directives-private-1593863
Ref: 115593863
Ref: refman/directives/private_1 private-1593863
Ref: 43f593863
Node: Description<36>594016
Ref: refman/directives/private_1 description594127
Ref: 440594127
Node: Template and modes<30>594866
Ref: refman/directives/private_1 template-and-modes594998
Ref: 441594998
Node: Examples<37>595175
Ref: refman/directives/private_1 examples595283
Ref: 442595283
Node: protected/1595526
Ref: refman/directives/protected_1 doc595651
Ref: 443595651
Ref: refman/directives/protected_1 directives-protected-1595651
Ref: 114595651
Ref: refman/directives/protected_1 protected-1595651
Ref: 444595651
Node: Description<37>595808
Ref: refman/directives/protected_1 description595921
Ref: 445595921
Node: Template and modes<31>596882
Ref: refman/directives/protected_1 template-and-modes597016
Ref: 446597016
Node: Examples<38>597199
Ref: refman/directives/protected_1 examples597309
Ref: 447597309
Node: public/1597550
Ref: refman/directives/public_1 doc597680
Ref: 448597680
Ref: refman/directives/public_1 directives-public-1597680
Ref: 113597680
Ref: refman/directives/public_1 public-1597680
Ref: 449597680
Node: Description<38>597831
Ref: refman/directives/public_1 description597941
Ref: 44a597941
Node: Template and modes<32>598699
Ref: refman/directives/public_1 template-and-modes598830
Ref: 44b598830
Node: Examples<39>599004
Ref: refman/directives/public_1 examples599111
Ref: 44c599111
Node: synchronized/1599357
Ref: refman/directives/synchronized_1 doc599482
Ref: 44d599482
Ref: refman/directives/synchronized_1 directives-synchronized-1599482
Ref: 56599482
Ref: refman/directives/synchronized_1 synchronized-1599482
Ref: 44e599482
Node: Description<39>599645
Ref: refman/directives/synchronized_1 description599761
Ref: 44f599761
Node: Template and modes<33>601137
Ref: refman/directives/synchronized_1 template-and-modes601274
Ref: 450601274
Node: Examples<40>601425
Ref: refman/directives/synchronized_1 examples601538
Ref: 451601538
Node: uses/2601782
Ref: refman/directives/uses_2 doc601911
Ref: 452601911
Ref: refman/directives/uses_2 directives-uses-2601911
Ref: 12a601911
Ref: refman/directives/uses_2 uses-2601911
Ref: 453601911
Node: Description<40>602058
Ref: refman/directives/uses_2 description602166
Ref: 454602166
Node: Template and modes<34>604158
Ref: refman/directives/uses_2 template-and-modes604287
Ref: 455604287
Node: Examples<41>604639
Ref: refman/directives/uses_2 examples604744
Ref: 456604744
Node: use_module/2606149
Ref: refman/directives/use_module_2 doc606255
Ref: 457606255
Ref: refman/directives/use_module_2 directives-use-module-2606255
Ref: 16b606255
Ref: refman/directives/use_module_2 use-module-2606255
Ref: 458606255
Node: Description<41>606414
Ref: refman/directives/use_module_2 description606528
Ref: 459606528
Node: Template and modes<35>609477
Ref: refman/directives/use_module_2 template-and-modes609612
Ref: 45a609612
Node: Examples<42>609994
Ref: refman/directives/use_module_2 examples610105
Ref: 45b610105
Node: Built-in predicates610958
Ref: refman/predicates/index doc611096
Ref: 45c611096
Ref: refman/predicates/index built-in-predicates611096
Ref: 45d611096
Node: Enumerating objects categories and protocols611783
Ref: refman/predicates/enumerating_entity_predicates doc611966
Ref: 45e611966
Ref: refman/predicates/enumerating_entity_predicates enumerating-entity-predicates611966
Ref: 231611966
Ref: refman/predicates/enumerating_entity_predicates enumerating-objects-categories-and-protocols611966
Ref: 45f611966
Node: current_category/1612148
Ref: refman/predicates/current_category_1 doc612291
Ref: 460612291
Ref: refman/predicates/current_category_1 current-category-1612291
Ref: 461612291
Ref: refman/predicates/current_category_1 predicates-current-category-1612291
Ref: c8612291
Node: Description<42>612496
Ref: refman/predicates/current_category_1 description612623
Ref: 462612623
Node: Modes and number of proofs<7>612825
Ref: refman/predicates/current_category_1 modes-and-number-of-proofs612970
Ref: 463612970
Node: Errors<8>613101
Ref: refman/predicates/current_category_1 errors613243
Ref: 464613243
Node: Examples<43>613404
Ref: refman/predicates/current_category_1 examples613508
Ref: 465613508
Node: current_object/1613872
Ref: refman/predicates/current_object_1 doc614042
Ref: 466614042
Ref: refman/predicates/current_object_1 current-object-1614042
Ref: 467614042
Ref: refman/predicates/current_object_1 predicates-current-object-1614042
Ref: 7f614042
Node: Description<43>614243
Ref: refman/predicates/current_object_1 description614368
Ref: 468614368
Node: Modes and number of proofs<8>614559
Ref: refman/predicates/current_object_1 modes-and-number-of-proofs614702
Ref: 469614702
Node: Errors<9>614829
Ref: refman/predicates/current_object_1 errors614969
Ref: 46a614969
Node: Examples<44>615122
Ref: refman/predicates/current_object_1 examples615224
Ref: 46b615224
Node: current_protocol/1615622
Ref: refman/predicates/current_protocol_1 doc615765
Ref: 46c615765
Ref: refman/predicates/current_protocol_1 current-protocol-1615765
Ref: 46d615765
Ref: refman/predicates/current_protocol_1 predicates-current-protocol-1615765
Ref: b7615765
Node: Description<44>615973
Ref: refman/predicates/current_protocol_1 description616100
Ref: 46e616100
Node: Modes and number of proofs<9>616302
Ref: refman/predicates/current_protocol_1 modes-and-number-of-proofs616448
Ref: 46f616448
Node: Errors<10>616581
Ref: refman/predicates/current_protocol_1 errors616724
Ref: 470616724
Node: Examples<45>616887
Ref: refman/predicates/current_protocol_1 examples616992
Ref: 471616992
Node: Enumerating objects categories and protocols properties617417
Ref: refman/predicates/enumerating_entity_property_predicates doc617654
Ref: 472617654
Ref: refman/predicates/enumerating_entity_property_predicates enumerating-entity-property-predicates617654
Ref: 52617654
Ref: refman/predicates/enumerating_entity_property_predicates enumerating-objects-categories-and-protocols-properties617654
Ref: 473617654
Node: category_property/2617861
Ref: refman/predicates/category_property_2 doc618017
Ref: 474618017
Ref: refman/predicates/category_property_2 category-property-2618017
Ref: 475618017
Ref: refman/predicates/category_property_2 predicates-category-property-2618017
Ref: 100618017
Node: Description<45>618226
Ref: refman/predicates/category_property_2 description618355
Ref: 476618355
Node: Modes and number of proofs<10>618696
Ref: refman/predicates/category_property_2 modes-and-number-of-proofs618844
Ref: 477618844
Node: Errors<11>618996
Ref: refman/predicates/category_property_2 errors619141
Ref: 478619141
Node: Examples<46>619536
Ref: refman/predicates/category_property_2 examples619642
Ref: 479619642
Node: object_property/2620101
Ref: refman/predicates/object_property_2 doc620285
Ref: 47a620285
Ref: refman/predicates/object_property_2 object-property-2620285
Ref: 47b620285
Ref: refman/predicates/object_property_2 predicates-object-property-2620285
Ref: a1620285
Node: Description<46>620490
Ref: refman/predicates/object_property_2 description620617
Ref: 47c620617
Node: Modes and number of proofs<11>620949
Ref: refman/predicates/object_property_2 modes-and-number-of-proofs621095
Ref: 47d621095
Node: Errors<12>621241
Ref: refman/predicates/object_property_2 errors621384
Ref: 47e621384
Node: Examples<47>621767
Ref: refman/predicates/object_property_2 examples621871
Ref: 47f621871
Node: protocol_property/2622412
Ref: refman/predicates/protocol_property_2 doc622568
Ref: 480622568
Ref: refman/predicates/protocol_property_2 predicates-protocol-property-2622568
Ref: cb622568
Ref: refman/predicates/protocol_property_2 protocol-property-2622568
Ref: 481622568
Node: Description<47>622779
Ref: refman/predicates/protocol_property_2 description622908
Ref: 482622908
Node: Modes and number of proofs<12>623260
Ref: refman/predicates/protocol_property_2 modes-and-number-of-proofs623408
Ref: 483623408
Node: Errors<13>623562
Ref: refman/predicates/protocol_property_2 errors623707
Ref: 484623707
Node: Examples<48>624104
Ref: refman/predicates/protocol_property_2 examples624210
Ref: 485624210
Node: Creating new objects categories and protocols624672
Ref: refman/predicates/creating_entity_predicates doc624908
Ref: 486624908
Ref: refman/predicates/creating_entity_predicates creating-entity-predicates624908
Ref: 487624908
Ref: refman/predicates/creating_entity_predicates creating-new-objects-categories-and-protocols624908
Ref: 488624908
Node: create_category/4625089
Ref: refman/predicates/create_category_4 doc625231
Ref: 489625231
Ref: refman/predicates/create_category_4 create-category-4625231
Ref: 48a625231
Ref: refman/predicates/create_category_4 predicates-create-category-4625231
Ref: ee625231
Node: Description<48>625436
Ref: refman/predicates/create_category_4 description625563
Ref: 48b625563
Node: Modes and number of proofs<13>626303
Ref: refman/predicates/create_category_4 modes-and-number-of-proofs626449
Ref: 48c626449
Node: Errors<14>626638
Ref: refman/predicates/create_category_4 errors626781
Ref: 48d626781
Node: Examples<49>627824
Ref: refman/predicates/create_category_4 examples627928
Ref: 48e627928
Node: create_object/4628366
Ref: refman/predicates/create_object_4 doc628534
Ref: 48f628534
Ref: refman/predicates/create_object_4 create-object-4628534
Ref: 490628534
Ref: refman/predicates/create_object_4 predicates-create-object-4628534
Ref: 44628534
Node: Description<49>628735
Ref: refman/predicates/create_object_4 description628860
Ref: 491628860
Node: Modes and number of proofs<14>629730
Ref: refman/predicates/create_object_4 modes-and-number-of-proofs629874
Ref: 493629874
Node: Errors<15>630055
Ref: refman/predicates/create_object_4 errors630196
Ref: 494630196
Node: Examples<50>631380
Ref: refman/predicates/create_object_4 examples631482
Ref: 495631482
Node: create_protocol/3633004
Ref: refman/predicates/create_protocol_3 doc633146
Ref: 496633146
Ref: refman/predicates/create_protocol_3 create-protocol-3633146
Ref: 497633146
Ref: refman/predicates/create_protocol_3 predicates-create-protocol-3633146
Ref: ba633146
Node: Description<50>633353
Ref: refman/predicates/create_protocol_3 description633480
Ref: 498633480
Node: Modes and number of proofs<15>634215
Ref: refman/predicates/create_protocol_3 modes-and-number-of-proofs634361
Ref: 499634361
Node: Errors<16>634537
Ref: refman/predicates/create_protocol_3 errors634680
Ref: 49a634680
Node: Examples<51>635477
Ref: refman/predicates/create_protocol_3 examples635581
Ref: 49b635581
Node: Abolishing objects categories and protocols635988
Ref: refman/predicates/abolishing_entity_predicates doc636211
Ref: 49c636211
Ref: refman/predicates/abolishing_entity_predicates abolishing-entity-predicates636211
Ref: 49d636211
Ref: refman/predicates/abolishing_entity_predicates abolishing-objects-categories-and-protocols636211
Ref: 49e636211
Node: abolish_category/1636391
Ref: refman/predicates/abolish_category_1 doc636533
Ref: 49f636533
Ref: refman/predicates/abolish_category_1 abolish-category-1636533
Ref: 4a0636533
Ref: refman/predicates/abolish_category_1 predicates-abolish-category-1636533
Ref: cc636533
Node: Description<51>636740
Ref: refman/predicates/abolish_category_1 description636868
Ref: 4a1636868
Node: Modes and number of proofs<16>637047
Ref: refman/predicates/abolish_category_1 modes-and-number-of-proofs637194
Ref: 4a2637194
Node: Errors<17>637316
Ref: refman/predicates/abolish_category_1 errors637460
Ref: 4a3637460
Node: Examples<52>637895
Ref: refman/predicates/abolish_category_1 examples638000
Ref: 4a4638000
Node: abolish_object/1638283
Ref: refman/predicates/abolish_object_1 doc638452
Ref: 4a5638452
Ref: refman/predicates/abolish_object_1 abolish-object-1638452
Ref: 4a6638452
Ref: refman/predicates/abolish_object_1 predicates-abolish-object-1638452
Ref: 46638452
Node: Description<52>638655
Ref: refman/predicates/abolish_object_1 description638781
Ref: 4a7638781
Node: Modes and number of proofs<17>638950
Ref: refman/predicates/abolish_object_1 modes-and-number-of-proofs639095
Ref: 4a8639095
Node: Errors<18>639213
Ref: refman/predicates/abolish_object_1 errors639355
Ref: 4a9639355
Node: Examples<53>639766
Ref: refman/predicates/abolish_object_1 examples639869
Ref: 4aa639869
Node: abolish_protocol/1640172
Ref: refman/predicates/abolish_protocol_1 doc640314
Ref: 4ab640314
Ref: refman/predicates/abolish_protocol_1 abolish-protocol-1640314
Ref: 4ac640314
Ref: refman/predicates/abolish_protocol_1 predicates-abolish-protocol-1640314
Ref: bd640314
Node: Description<53>640523
Ref: refman/predicates/abolish_protocol_1 description640651
Ref: 4ad640651
Node: Modes and number of proofs<18>640832
Ref: refman/predicates/abolish_protocol_1 modes-and-number-of-proofs640979
Ref: 4ae640979
Node: Errors<19>641103
Ref: refman/predicates/abolish_protocol_1 errors641247
Ref: 4af641247
Node: Examples<54>641684
Ref: refman/predicates/abolish_protocol_1 examples641789
Ref: 4b0641789
Node: Objects categories and protocols relations642075
Ref: refman/predicates/entity_relation_predicates doc642270
Ref: 4b1642270
Ref: refman/predicates/entity_relation_predicates entity-relation-predicates642270
Ref: 232642270
Ref: refman/predicates/entity_relation_predicates objects-categories-and-protocols-relations642270
Ref: 4b2642270
Node: extends_object/2-3642616
Ref: refman/predicates/extends_object_2_3 doc642761
Ref: 4b3642761
Ref: refman/predicates/extends_object_2_3 extends-object-2-3642761
Ref: 4b4642761
Ref: refman/predicates/extends_object_2_3 predicates-extends-object-2-3642761
Ref: 9a642761
Node: Description<54>642968
Ref: refman/predicates/extends_object_2_3 description643096
Ref: 4b5643096
Node: Modes and number of proofs<19>643416
Ref: refman/predicates/extends_object_2_3 modes-and-number-of-proofs643563
Ref: 4b6643563
Node: Errors<20>643793
Ref: refman/predicates/extends_object_2_3 errors643937
Ref: 4b7643937
Node: Examples<55>644401
Ref: refman/predicates/extends_object_2_3 examples644506
Ref: 4b8644506
Node: extends_protocol/2-3644885
Ref: refman/predicates/extends_protocol_2_3 doc645059
Ref: 4b9645059
Ref: refman/predicates/extends_protocol_2_3 extends-protocol-2-3645059
Ref: 4ba645059
Ref: refman/predicates/extends_protocol_2_3 predicates-extends-protocol-2-3645059
Ref: c7645059
Node: Description<55>645270
Ref: refman/predicates/extends_protocol_2_3 description645400
Ref: 4bb645400
Node: Modes and number of proofs<20>645740
Ref: refman/predicates/extends_protocol_2_3 modes-and-number-of-proofs645889
Ref: 4bc645889
Node: Errors<21>646131
Ref: refman/predicates/extends_protocol_2_3 errors646277
Ref: 4bd646277
Node: Examples<56>646763
Ref: refman/predicates/extends_protocol_2_3 examples646870
Ref: 4be646870
Node: extends_category/2-3647261
Ref: refman/predicates/extends_category_2_3 doc647440
Ref: 4bf647440
Ref: refman/predicates/extends_category_2_3 extends-category-2-3647440
Ref: 4c0647440
Ref: refman/predicates/extends_category_2_3 predicates-extends-category-2-3647440
Ref: fd647440
Node: Description<56>647653
Ref: refman/predicates/extends_category_2_3 description647783
Ref: 4c1647783
Node: Modes and number of proofs<21>648126
Ref: refman/predicates/extends_category_2_3 modes-and-number-of-proofs648275
Ref: 4c2648275
Node: Errors<22>648519
Ref: refman/predicates/extends_category_2_3 errors648665
Ref: 4c3648665
Node: Examples<57>649153
Ref: refman/predicates/extends_category_2_3 examples649260
Ref: 4c4649260
Node: implements_protocol/2-3649658
Ref: refman/predicates/implements_protocol_2_3 doc649841
Ref: 4c5649841
Ref: refman/predicates/implements_protocol_2_3 implements-protocol-2-3649841
Ref: 4c6649841
Ref: refman/predicates/implements_protocol_2_3 predicates-implements-protocol-2-3649841
Ref: 9c649841
Node: Description<57>650060
Ref: refman/predicates/implements_protocol_2_3 description650193
Ref: 4c7650193
Node: Modes and number of proofs<22>650741
Ref: refman/predicates/implements_protocol_2_3 modes-and-number-of-proofs650893
Ref: 4c8650893
Node: Errors<23>651316
Ref: refman/predicates/implements_protocol_2_3 errors651465
Ref: 4c9651465
Node: Examples<58>652062
Ref: refman/predicates/implements_protocol_2_3 examples652172
Ref: 4ca652172
Node: conforms_to_protocol/2-3652887
Ref: refman/predicates/conforms_to_protocol_2_3 doc653070
Ref: 4cb653070
Ref: refman/predicates/conforms_to_protocol_2_3 conforms-to-protocol-2-3653070
Ref: 4cc653070
Ref: refman/predicates/conforms_to_protocol_2_3 predicates-conforms-to-protocol-2-3653070
Ref: 9d653070
Node: Description<58>653291
Ref: refman/predicates/conforms_to_protocol_2_3 description653425
Ref: 4cd653425
Node: Modes and number of proofs<23>653962
Ref: refman/predicates/conforms_to_protocol_2_3 modes-and-number-of-proofs654115
Ref: 4ce654115
Node: Errors<24>654542
Ref: refman/predicates/conforms_to_protocol_2_3 errors654692
Ref: 4cf654692
Node: Examples<59>655289
Ref: refman/predicates/conforms_to_protocol_2_3 examples655400
Ref: 4d0655400
Node: complements_object/2656148
Ref: refman/predicates/complements_object_2 doc656328
Ref: 4d1656328
Ref: refman/predicates/complements_object_2 complements-object-2656328
Ref: 4d2656328
Ref: refman/predicates/complements_object_2 predicates-complements-object-2656328
Ref: 9e656328
Node: Description<59>656541
Ref: refman/predicates/complements_object_2 description656671
Ref: 4d3656671
Node: Modes and number of proofs<24>656873
Ref: refman/predicates/complements_object_2 modes-and-number-of-proofs657022
Ref: 4d4657022
Node: Errors<25>657177
Ref: refman/predicates/complements_object_2 errors657323
Ref: 4d5657323
Node: Examples<60>657608
Ref: refman/predicates/complements_object_2 examples657715
Ref: 4d6657715
Node: imports_category/2-3657956
Ref: refman/predicates/imports_category_2_3 doc658134
Ref: 4d7658134
Ref: refman/predicates/imports_category_2_3 imports-category-2-3658134
Ref: 4d8658134
Ref: refman/predicates/imports_category_2_3 predicates-imports-category-2-3658134
Ref: 9b658134
Node: Description<60>658347
Ref: refman/predicates/imports_category_2_3 description658477
Ref: 4d9658477
Node: Modes and number of proofs<25>658791
Ref: refman/predicates/imports_category_2_3 modes-and-number-of-proofs658940
Ref: 4da658940
Node: Errors<26>659180
Ref: refman/predicates/imports_category_2_3 errors659326
Ref: 4db659326
Node: Examples<61>659794
Ref: refman/predicates/imports_category_2_3 examples659901
Ref: 4dc659901
Node: instantiates_class/2-3660272
Ref: refman/predicates/instantiates_class_2_3 doc660451
Ref: 4dd660451
Ref: refman/predicates/instantiates_class_2_3 instantiates-class-2-3660451
Ref: 4de660451
Ref: refman/predicates/instantiates_class_2_3 predicates-instantiates-class-2-3660451
Ref: 98660451
Node: Description<61>660668
Ref: refman/predicates/instantiates_class_2_3 description660800
Ref: 4df660800
Node: Modes and number of proofs<26>661131
Ref: refman/predicates/instantiates_class_2_3 modes-and-number-of-proofs661282
Ref: 4e0661282
Node: Errors<27>661522
Ref: refman/predicates/instantiates_class_2_3 errors661670
Ref: 4e1661670
Node: Examples<62>662132
Ref: refman/predicates/instantiates_class_2_3 examples662241
Ref: 4e2662241
Node: specializes_class/2-3662660
Ref: refman/predicates/specializes_class_2_3 doc662810
Ref: 4e3662810
Ref: refman/predicates/specializes_class_2_3 predicates-specializes-class-2-3662810
Ref: 99662810
Ref: refman/predicates/specializes_class_2_3 specializes-class-2-3662810
Ref: 4e4662810
Node: Description<62>663025
Ref: refman/predicates/specializes_class_2_3 description663156
Ref: 4e5663156
Node: Modes and number of proofs<27>663488
Ref: refman/predicates/specializes_class_2_3 modes-and-number-of-proofs663638
Ref: 4e6663638
Node: Errors<28>663876
Ref: refman/predicates/specializes_class_2_3 errors664023
Ref: 4e7664023
Node: Examples<63>664489
Ref: refman/predicates/specializes_class_2_3 examples664597
Ref: 4e8664597
Node: Event handling<2>665001
Ref: refman/predicates/event_handling_predicates doc665168
Ref: 4e9665168
Ref: refman/predicates/event_handling_predicates event-handling665168
Ref: 4ea665168
Ref: refman/predicates/event_handling_predicates event-handling-predicates665168
Ref: 54665168
Node: abolish_events/5665282
Ref: refman/predicates/abolish_events_5 doc665395
Ref: 4eb665395
Ref: refman/predicates/abolish_events_5 abolish-events-5665395
Ref: 4ec665395
Ref: refman/predicates/abolish_events_5 predicates-abolish-events-5665395
Ref: 1cd665395
Node: Description<63>665598
Ref: refman/predicates/abolish_events_5 description665724
Ref: 4ed665724
Node: Modes and number of proofs<28>666042
Ref: refman/predicates/abolish_events_5 modes-and-number-of-proofs666187
Ref: 4ee666187
Node: Errors<29>666320
Ref: refman/predicates/abolish_events_5 errors666462
Ref: 4ef666462
Node: Examples<64>667069
Ref: refman/predicates/abolish_events_5 examples667172
Ref: 4f0667172
Node: current_event/5667488
Ref: refman/predicates/current_event_5 doc667625
Ref: 4f1667625
Ref: refman/predicates/current_event_5 current-event-5667625
Ref: 4f2667625
Ref: refman/predicates/current_event_5 predicates-current-event-5667625
Ref: 1d0667625
Node: Description<64>667826
Ref: refman/predicates/current_event_5 description667951
Ref: 4f3667951
Node: Modes and number of proofs<29>668187
Ref: refman/predicates/current_event_5 modes-and-number-of-proofs668331
Ref: 4f4668331
Node: Errors<30>668486
Ref: refman/predicates/current_event_5 errors668627
Ref: 4f5668627
Node: Examples<65>669234
Ref: refman/predicates/current_event_5 examples669336
Ref: 4f6669336
Node: define_events/5669621
Ref: refman/predicates/define_events_5 doc669733
Ref: 4f7669733
Ref: refman/predicates/define_events_5 define-events-5669733
Ref: 4f8669733
Ref: refman/predicates/define_events_5 predicates-define-events-5669733
Ref: 1ca669733
Node: Description<65>669936
Ref: refman/predicates/define_events_5 description670061
Ref: 4f9670061
Node: Modes and number of proofs<30>670478
Ref: refman/predicates/define_events_5 modes-and-number-of-proofs670622
Ref: 4fa670622
Node: Errors<31>670769
Ref: refman/predicates/define_events_5 errors670910
Ref: 4fb670910
Node: Examples<66>671828
Ref: refman/predicates/define_events_5 examples671930
Ref: 4fc671930
Node: Multi-threading672240
Ref: refman/predicates/multi_threading_predicates doc672388
Ref: 4fd672388
Ref: refman/predicates/multi_threading_predicates multi-threading672388
Ref: 4fe672388
Ref: refman/predicates/multi_threading_predicates multi-threading-predicates672388
Ref: 4ff672388
Node: threaded/1672632
Ref: refman/predicates/threaded_1 doc672739
Ref: 500672739
Ref: refman/predicates/threaded_1 predicates-threaded-1672739
Ref: 1dd672739
Ref: refman/predicates/threaded_1 threaded-1672739
Ref: 501672739
Node: Description<66>672930
Ref: refman/predicates/threaded_1 description673050
Ref: 502673050
Node: Modes and number of proofs<31>674274
Ref: refman/predicates/threaded_1 modes-and-number-of-proofs674413
Ref: 503674413
Node: Errors<32>674524
Ref: refman/predicates/threaded_1 errors674660
Ref: 504674660
Node: Examples<67>675044
Ref: refman/predicates/threaded_1 examples675141
Ref: 505675141
Node: threaded_call/1-2675523
Ref: refman/predicates/threaded_call_1_2 doc675656
Ref: 506675656
Ref: refman/predicates/threaded_call_1_2 predicates-threaded-call-1-2675656
Ref: 1e2675656
Ref: refman/predicates/threaded_call_1_2 threaded-call-1-2675656
Ref: 507675656
Node: Description<67>675861
Ref: refman/predicates/threaded_call_1_2 description675988
Ref: 508675988
Node: Modes and number of proofs<32>676707
Ref: refman/predicates/threaded_call_1_2 modes-and-number-of-proofs676853
Ref: 509676853
Node: Errors<33>677007
Ref: refman/predicates/threaded_call_1_2 errors677150
Ref: 50a677150
Node: Examples<68>677416
Ref: refman/predicates/threaded_call_1_2 examples677520
Ref: 50b677520
Node: threaded_once/1-2678085
Ref: refman/predicates/threaded_once_1_2 doc678225
Ref: 50c678225
Ref: refman/predicates/threaded_once_1_2 predicates-threaded-once-1-2678225
Ref: 1e4678225
Ref: refman/predicates/threaded_once_1_2 threaded-once-1-2678225
Ref: 50d678225
Node: Description<68>678432
Ref: refman/predicates/threaded_once_1_2 description678559
Ref: 50e678559
Node: Modes and number of proofs<33>679207
Ref: refman/predicates/threaded_once_1_2 modes-and-number-of-proofs679353
Ref: 50f679353
Node: Errors<34>679509
Ref: refman/predicates/threaded_once_1_2 errors679652
Ref: 510679652
Node: Examples<69>679920
Ref: refman/predicates/threaded_once_1_2 examples680024
Ref: 511680024
Node: threaded_ignore/1680589
Ref: refman/predicates/threaded_ignore_1 doc680729
Ref: 512680729
Ref: refman/predicates/threaded_ignore_1 predicates-threaded-ignore-1680729
Ref: 1e9680729
Ref: refman/predicates/threaded_ignore_1 threaded-ignore-1680729
Ref: 513680729
Node: Description<69>680936
Ref: refman/predicates/threaded_ignore_1 description681063
Ref: 514681063
Node: Modes and number of proofs<34>681491
Ref: refman/predicates/threaded_ignore_1 modes-and-number-of-proofs681637
Ref: 515681637
Node: Errors<35>681749
Ref: refman/predicates/threaded_ignore_1 errors681892
Ref: 516681892
Node: Examples<70>682087
Ref: refman/predicates/threaded_ignore_1 examples682191
Ref: 517682191
Node: threaded_exit/1-2682732
Ref: refman/predicates/threaded_exit_1_2 doc682872
Ref: 518682872
Ref: refman/predicates/threaded_exit_1_2 predicates-threaded-exit-1-2682872
Ref: 1e3682872
Ref: refman/predicates/threaded_exit_1_2 threaded-exit-1-2682872
Ref: 519682872
Node: Description<70>683079
Ref: refman/predicates/threaded_exit_1_2 description683206
Ref: 51a683206
Node: Modes and number of proofs<35>684299
Ref: refman/predicates/threaded_exit_1_2 modes-and-number-of-proofs684445
Ref: 51b684445
Node: Errors<36>684618
Ref: refman/predicates/threaded_exit_1_2 errors684761
Ref: 51c684761
Node: Examples<71>685115
Ref: refman/predicates/threaded_exit_1_2 examples685219
Ref: 51d685219
Node: threaded_peek/1-2685734
Ref: refman/predicates/threaded_peek_1_2 doc685874
Ref: 51e685874
Ref: refman/predicates/threaded_peek_1_2 predicates-threaded-peek-1-2685874
Ref: 1e5685874
Ref: refman/predicates/threaded_peek_1_2 threaded-peek-1-2685874
Ref: 51f685874
Node: Description<71>686081
Ref: refman/predicates/threaded_peek_1_2 description686208
Ref: 520686208
Node: Modes and number of proofs<36>687133
Ref: refman/predicates/threaded_peek_1_2 modes-and-number-of-proofs687279
Ref: 521687279
Node: Errors<37>687450
Ref: refman/predicates/threaded_peek_1_2 errors687593
Ref: 522687593
Node: Examples<72>687850
Ref: refman/predicates/threaded_peek_1_2 examples687954
Ref: 523687954
Node: threaded_cancel/1688472
Ref: refman/predicates/threaded_cancel_1 doc688610
Ref: 524688610
Ref: refman/predicates/threaded_cancel_1 predicates-threaded-cancel-1688610
Ref: 1e6688610
Ref: refman/predicates/threaded_cancel_1 threaded-cancel-1688610
Ref: 525688610
Node: Description<72>688817
Ref: refman/predicates/threaded_cancel_1 description688944
Ref: 526688944
Node: Modes and number of proofs<37>689415
Ref: refman/predicates/threaded_cancel_1 modes-and-number-of-proofs689561
Ref: 527689561
Node: Errors<38>689671
Ref: refman/predicates/threaded_cancel_1 errors689814
Ref: 528689814
Node: Examples<73>689910
Ref: refman/predicates/threaded_cancel_1 examples690014
Ref: 529690014
Node: threaded_wait/1690222
Ref: refman/predicates/threaded_wait_1 doc690360
Ref: 52a690360
Ref: refman/predicates/threaded_wait_1 predicates-threaded-wait-1690360
Ref: 1ed690360
Ref: refman/predicates/threaded_wait_1 threaded-wait-1690360
Ref: 52b690360
Node: Description<73>690563
Ref: refman/predicates/threaded_wait_1 description690688
Ref: 52c690688
Node: Modes and number of proofs<38>691245
Ref: refman/predicates/threaded_wait_1 modes-and-number-of-proofs691389
Ref: 52d691389
Node: Errors<39>691533
Ref: refman/predicates/threaded_wait_1 errors691674
Ref: 52e691674
Node: Examples<74>691715
Ref: refman/predicates/threaded_wait_1 examples691817
Ref: 52f691817
Node: threaded_notify/1692015
Ref: refman/predicates/threaded_notify_1 doc692127
Ref: 530692127
Ref: refman/predicates/threaded_notify_1 predicates-threaded-notify-1692127
Ref: 1ee692127
Ref: refman/predicates/threaded_notify_1 threaded-notify-1692127
Ref: 531692127
Node: Description<74>692334
Ref: refman/predicates/threaded_notify_1 description692461
Ref: 532692461
Node: Modes and number of proofs<39>693018
Ref: refman/predicates/threaded_notify_1 modes-and-number-of-proofs693164
Ref: 533693164
Node: Errors<40>693312
Ref: refman/predicates/threaded_notify_1 errors693455
Ref: 534693455
Node: Examples<75>693496
Ref: refman/predicates/threaded_notify_1 examples693600
Ref: 535693600
Node: Multi-threading engines693778
Ref: refman/predicates/engine_predicates doc693943
Ref: 536693943
Ref: refman/predicates/engine_predicates engine-predicates693943
Ref: 537693943
Ref: refman/predicates/engine_predicates multi-threading-engines693943
Ref: 538693943
Node: threaded_engine_create/3694267
Ref: refman/predicates/threaded_engine_create_3 doc694404
Ref: 539694404
Ref: refman/predicates/threaded_engine_create_3 predicates-threaded-engine-create-3694404
Ref: 1f1694404
Ref: refman/predicates/threaded_engine_create_3 threaded-engine-create-3694404
Ref: 53a694404
Node: Description<75>694623
Ref: refman/predicates/threaded_engine_create_3 description694757
Ref: 53b694757
Node: Modes and number of proofs<40>695221
Ref: refman/predicates/threaded_engine_create_3 modes-and-number-of-proofs695374
Ref: 53c695374
Node: Errors<41>695569
Ref: refman/predicates/threaded_engine_create_3 errors695719
Ref: 53d695719
Node: Examples<76>696018
Ref: refman/predicates/threaded_engine_create_3 examples696129
Ref: 53e696129
Node: threaded_engine_destroy/1696491
Ref: refman/predicates/threaded_engine_destroy_1 doc696654
Ref: 541696654
Ref: refman/predicates/threaded_engine_destroy_1 predicates-threaded-engine-destroy-1696654
Ref: 1f4696654
Ref: refman/predicates/threaded_engine_destroy_1 threaded-engine-destroy-1696654
Ref: 542696654
Node: Description<76>696875
Ref: refman/predicates/threaded_engine_destroy_1 description697010
Ref: 543697010
Node: Modes and number of proofs<41>697120
Ref: refman/predicates/threaded_engine_destroy_1 modes-and-number-of-proofs697274
Ref: 544697274
Node: Errors<42>697390
Ref: refman/predicates/threaded_engine_destroy_1 errors697541
Ref: 545697541
Node: Examples<77>697758
Ref: refman/predicates/threaded_engine_destroy_1 examples697870
Ref: 546697870
Node: threaded_engine/1698250
Ref: refman/predicates/threaded_engine_1 doc698411
Ref: 547698411
Ref: refman/predicates/threaded_engine_1 predicates-threaded-engine-1698411
Ref: 540698411
Ref: refman/predicates/threaded_engine_1 threaded-engine-1698411
Ref: 548698411
Node: Description<77>698618
Ref: refman/predicates/threaded_engine_1 description698745
Ref: 549698745
Node: Modes and number of proofs<42>698953
Ref: refman/predicates/threaded_engine_1 modes-and-number-of-proofs699099
Ref: 54a699099
Node: Errors<43>699218
Ref: refman/predicates/threaded_engine_1 errors699361
Ref: 54b699361
Node: Examples<78>699402
Ref: refman/predicates/threaded_engine_1 examples699506
Ref: 54c699506
Node: threaded_engine_self/1699911
Ref: refman/predicates/threaded_engine_self_1 doc700069
Ref: 54d700069
Ref: refman/predicates/threaded_engine_self_1 predicates-threaded-engine-self-1700069
Ref: 53f700069
Ref: refman/predicates/threaded_engine_self_1 threaded-engine-self-1700069
Ref: 54e700069
Node: Description<78>700286
Ref: refman/predicates/threaded_engine_self_1 description700418
Ref: 54f700418
Node: Modes and number of proofs<43>700547
Ref: refman/predicates/threaded_engine_self_1 modes-and-number-of-proofs700698
Ref: 550700698
Node: Errors<44>700821
Ref: refman/predicates/threaded_engine_self_1 errors700969
Ref: 551700969
Node: Examples<79>701010
Ref: refman/predicates/threaded_engine_self_1 examples701119
Ref: 552701119
Node: threaded_engine_next/2701487
Ref: refman/predicates/threaded_engine_next_2 doc701658
Ref: 553701658
Ref: refman/predicates/threaded_engine_next_2 predicates-threaded-engine-next-2701658
Ref: 1f2701658
Ref: refman/predicates/threaded_engine_next_2 threaded-engine-next-2701658
Ref: 554701658
Node: Description<79>701875
Ref: refman/predicates/threaded_engine_next_2 description702007
Ref: 555702007
Node: Modes and number of proofs<44>702434
Ref: refman/predicates/threaded_engine_next_2 modes-and-number-of-proofs702585
Ref: 556702585
Node: Errors<45>702715
Ref: refman/predicates/threaded_engine_next_2 errors702863
Ref: 557702863
Node: Examples<80>703082
Ref: refman/predicates/threaded_engine_next_2 examples703191
Ref: 558703191
Node: threaded_engine_next_reified/2703468
Ref: refman/predicates/threaded_engine_next_reified_2 doc703640
Ref: 559703640
Ref: refman/predicates/threaded_engine_next_reified_2 predicates-threaded-engine-next-reified-2703640
Ref: 1f3703640
Ref: refman/predicates/threaded_engine_next_reified_2 threaded-engine-next-reified-2703640
Ref: 55a703640
Node: Description<80>703873
Ref: refman/predicates/threaded_engine_next_reified_2 description704013
Ref: 55b704013
Node: Modes and number of proofs<45>704367
Ref: refman/predicates/threaded_engine_next_reified_2 modes-and-number-of-proofs704526
Ref: 55c704526
Node: Errors<46>704658
Ref: refman/predicates/threaded_engine_next_reified_2 errors704814
Ref: 55d704814
Node: Examples<81>705033
Ref: refman/predicates/threaded_engine_next_reified_2 examples705150
Ref: 55e705150
Node: threaded_engine_yield/1705435
Ref: refman/predicates/threaded_engine_yield_1 doc705607
Ref: 55f705607
Ref: refman/predicates/threaded_engine_yield_1 predicates-threaded-engine-yield-1705607
Ref: 1f7705607
Ref: refman/predicates/threaded_engine_yield_1 threaded-engine-yield-1705607
Ref: 560705607
Node: Description<81>705826
Ref: refman/predicates/threaded_engine_yield_1 description705959
Ref: 561705959
Node: Modes and number of proofs<46>706639
Ref: refman/predicates/threaded_engine_yield_1 modes-and-number-of-proofs706791
Ref: 562706791
Node: Errors<47>706913
Ref: refman/predicates/threaded_engine_yield_1 errors707062
Ref: 563707062
Node: Examples<82>707103
Ref: refman/predicates/threaded_engine_yield_1 examples707213
Ref: 564707213
Node: threaded_engine_post/2707483
Ref: refman/predicates/threaded_engine_post_2 doc707648
Ref: 565707648
Ref: refman/predicates/threaded_engine_post_2 predicates-threaded-engine-post-2707648
Ref: 1f6707648
Ref: refman/predicates/threaded_engine_post_2 threaded-engine-post-2707648
Ref: 566707648
Node: Description<82>707865
Ref: refman/predicates/threaded_engine_post_2 description707997
Ref: 567707997
Node: Modes and number of proofs<47>708121
Ref: refman/predicates/threaded_engine_post_2 modes-and-number-of-proofs708272
Ref: 568708272
Node: Errors<48>708394
Ref: refman/predicates/threaded_engine_post_2 errors708542
Ref: 569708542
Node: Examples<83>708761
Ref: refman/predicates/threaded_engine_post_2 examples708870
Ref: 56a708870
Node: threaded_engine_fetch/1709072
Ref: refman/predicates/threaded_engine_fetch_1 doc709205
Ref: 56b709205
Ref: refman/predicates/threaded_engine_fetch_1 predicates-threaded-engine-fetch-1709205
Ref: 1f5709205
Ref: refman/predicates/threaded_engine_fetch_1 threaded-engine-fetch-1709205
Ref: 56c709205
Node: Description<83>709424
Ref: refman/predicates/threaded_engine_fetch_1 description709557
Ref: 56d709557
Node: Modes and number of proofs<48>709757
Ref: refman/predicates/threaded_engine_fetch_1 modes-and-number-of-proofs709909
Ref: 56e709909
Node: Errors<49>710031
Ref: refman/predicates/threaded_engine_fetch_1 errors710180
Ref: 56f710180
Node: Examples<84>710221
Ref: refman/predicates/threaded_engine_fetch_1 examples710331
Ref: 570710331
Node: Compiling and loading source files710515
Ref: refman/predicates/compiling_predicates doc710670
Ref: 571710670
Ref: refman/predicates/compiling_predicates compiling-and-loading-source-files710670
Ref: 572710670
Ref: refman/predicates/compiling_predicates compiling-predicates710670
Ref: 573710670
Node: logtalk_compile/1710970
Ref: refman/predicates/logtalk_compile_1 doc711103
Ref: 574711103
Ref: refman/predicates/logtalk_compile_1 logtalk-compile-1711103
Ref: 575711103
Ref: refman/predicates/logtalk_compile_1 predicates-logtalk-compile-1711103
Ref: 252711103
Node: Description<84>711308
Ref: refman/predicates/logtalk_compile_1 description711435
Ref: 576711435
Node: Modes and number of proofs<49>712568
Ref: refman/predicates/logtalk_compile_1 modes-and-number-of-proofs712714
Ref: 578712714
Node: Errors<50>712900
Ref: refman/predicates/logtalk_compile_1 errors713043
Ref: 579713043
Node: Examples<85>713655
Ref: refman/predicates/logtalk_compile_1 examples713759
Ref: 57a713759
Node: logtalk_compile/2714358
Ref: refman/predicates/logtalk_compile_2 doc714514
Ref: 57b714514
Ref: refman/predicates/logtalk_compile_2 logtalk-compile-2714514
Ref: 57c714514
Ref: refman/predicates/logtalk_compile_2 predicates-logtalk-compile-2714514
Ref: 261714514
Node: Description<85>714719
Ref: refman/predicates/logtalk_compile_2 description714846
Ref: 57d714846
Node: Modes and number of proofs<50>716458
Ref: refman/predicates/logtalk_compile_2 modes-and-number-of-proofs716604
Ref: 57e716604
Node: Errors<51>716834
Ref: refman/predicates/logtalk_compile_2 errors716977
Ref: 57f716977
Node: Examples<86>718190
Ref: refman/predicates/logtalk_compile_2 examples718294
Ref: 580718294
Node: logtalk_load/1719039
Ref: refman/predicates/logtalk_load_1 doc719192
Ref: 581719192
Ref: refman/predicates/logtalk_load_1 logtalk-load-1719192
Ref: 582719192
Ref: refman/predicates/logtalk_load_1 predicates-logtalk-load-1719192
Ref: 253719192
Node: Description<86>719393
Ref: refman/predicates/logtalk_load_1 description719517
Ref: 583719517
Node: Modes and number of proofs<51>720970
Ref: refman/predicates/logtalk_load_1 modes-and-number-of-proofs721113
Ref: 584721113
Node: Errors<52>721295
Ref: refman/predicates/logtalk_load_1 errors721435
Ref: 585721435
Node: Examples<87>722055
Ref: refman/predicates/logtalk_load_1 examples722156
Ref: 586722156
Node: logtalk_load/2722757
Ref: refman/predicates/logtalk_load_2 doc722907
Ref: 587722907
Ref: refman/predicates/logtalk_load_2 logtalk-load-2722907
Ref: 588722907
Ref: refman/predicates/logtalk_load_2 predicates-logtalk-load-2722907
Ref: 25a722907
Node: Description<87>723108
Ref: refman/predicates/logtalk_load_2 description723232
Ref: 589723232
Node: Modes and number of proofs<52>724960
Ref: refman/predicates/logtalk_load_2 modes-and-number-of-proofs725103
Ref: 58a725103
Node: Errors<53>725329
Ref: refman/predicates/logtalk_load_2 errors725469
Ref: 58b725469
Node: Examples<88>726684
Ref: refman/predicates/logtalk_load_2 examples726785
Ref: 58c726785
Node: logtalk_make/0727508
Ref: refman/predicates/logtalk_make_0 doc727658
Ref: 58d727658
Ref: refman/predicates/logtalk_make_0 logtalk-make-0727658
Ref: 58e727658
Ref: refman/predicates/logtalk_make_0 predicates-logtalk-make-0727658
Ref: 254727658
Node: Description<88>727859
Ref: refman/predicates/logtalk_make_0 description727983
Ref: 58f727983
Node: Modes and number of proofs<53>729315
Ref: refman/predicates/logtalk_make_0 modes-and-number-of-proofs729458
Ref: 591729458
Node: Errors<54>729556
Ref: refman/predicates/logtalk_make_0 errors729696
Ref: 592729696
Node: Examples<89>729737
Ref: refman/predicates/logtalk_make_0 examples729838
Ref: 593729838
Node: logtalk_make/1730154
Ref: refman/predicates/logtalk_make_1 doc730318
Ref: 594730318
Ref: refman/predicates/logtalk_make_1 logtalk-make-1730318
Ref: 595730318
Ref: refman/predicates/logtalk_make_1 predicates-logtalk-make-1730318
Ref: 256730318
Node: Description<89>730519
Ref: refman/predicates/logtalk_make_1 description730643
Ref: 596730643
Ref: Description<89>-Footnote-1734221
Node: Modes and number of proofs<54>734288
Ref: refman/predicates/logtalk_make_1 modes-and-number-of-proofs734431
Ref: 597734431
Node: Errors<55>734544
Ref: refman/predicates/logtalk_make_1 errors734684
Ref: 598734684
Node: Examples<90>734725
Ref: refman/predicates/logtalk_make_1 examples734826
Ref: 599734826
Node: logtalk_make_target_action/1735365
Ref: refman/predicates/logtalk_make_target_action_1 doc735537
Ref: 59a735537
Ref: refman/predicates/logtalk_make_target_action_1 logtalk-make-target-action-1735537
Ref: 59b735537
Ref: refman/predicates/logtalk_make_target_action_1 predicates-logtalk-make-target-action-1735537
Ref: 590735537
Node: Description<90>735766
Ref: refman/predicates/logtalk_make_target_action_1 description735904
Ref: 59c735904
Node: Modes and number of proofs<55>736190
Ref: refman/predicates/logtalk_make_target_action_1 modes-and-number-of-proofs736347
Ref: 59d736347
Node: Errors<56>736475
Ref: refman/predicates/logtalk_make_target_action_1 errors736629
Ref: 59e736629
Node: Examples<91>736670
Ref: refman/predicates/logtalk_make_target_action_1 examples736785
Ref: 59f736785
Node: logtalk_library_path/2737134
Ref: refman/predicates/logtalk_library_path_2 doc737314
Ref: 5a0737314
Ref: refman/predicates/logtalk_library_path_2 logtalk-library-path-2737314
Ref: 5a1737314
Ref: refman/predicates/logtalk_library_path_2 predicates-logtalk-library-path-2737314
Ref: 25d737314
Node: Description<91>737531
Ref: refman/predicates/logtalk_library_path_2 description737663
Ref: 5a2737663
Ref: Description<91>-Footnote-1739565
Node: Modes and number of proofs<56>739649
Ref: refman/predicates/logtalk_library_path_2 modes-and-number-of-proofs739800
Ref: 5a4739800
Node: Errors<57>739988
Ref: refman/predicates/logtalk_library_path_2 errors740136
Ref: 5a5740136
Node: Examples<92>740177
Ref: refman/predicates/logtalk_library_path_2 examples740286
Ref: 5a6740286
Node: logtalk_load_context/2740966
Ref: refman/predicates/logtalk_load_context_2 doc741109
Ref: 5a7741109
Ref: refman/predicates/logtalk_load_context_2 logtalk-load-context-2741109
Ref: 5a8741109
Ref: refman/predicates/logtalk_load_context_2 predicates-logtalk-load-context-2741109
Ref: 2a4741109
Node: Description<92>741326
Ref: refman/predicates/logtalk_load_context_2 description741458
Ref: 5a9741458
Node: Modes and number of proofs<57>743784
Ref: refman/predicates/logtalk_load_context_2 modes-and-number-of-proofs743935
Ref: 5ab743935
Node: Errors<58>744066
Ref: refman/predicates/logtalk_load_context_2 errors744214
Ref: 5ac744214
Node: Examples<93>744255
Ref: refman/predicates/logtalk_load_context_2 examples744364
Ref: 5ad744364
Node: Flags744753
Ref: refman/predicates/flag_predicates doc744876
Ref: 5ae744876
Ref: refman/predicates/flag_predicates flag-predicates744876
Ref: 5af744876
Ref: refman/predicates/flag_predicates flags744876
Ref: 5b0744876
Node: current_logtalk_flag/2745011
Ref: refman/predicates/current_logtalk_flag_2 doc745124
Ref: 5b1745124
Ref: refman/predicates/current_logtalk_flag_2 current-logtalk-flag-2745124
Ref: 5b2745124
Ref: refman/predicates/current_logtalk_flag_2 predicates-current-logtalk-flag-2745124
Ref: 262745124
Node: Description<93>745341
Ref: refman/predicates/current_logtalk_flag_2 description745473
Ref: 5b3745473
Node: Modes and number of proofs<58>745742
Ref: refman/predicates/current_logtalk_flag_2 modes-and-number-of-proofs745893
Ref: 5b4745893
Node: Errors<59>746022
Ref: refman/predicates/current_logtalk_flag_2 errors746170
Ref: 5b5746170
Node: Examples<94>746376
Ref: refman/predicates/current_logtalk_flag_2 examples746485
Ref: 5b6746485
Node: set_logtalk_flag/2<2>746714
Ref: refman/predicates/set_logtalk_flag_2 doc746857
Ref: 5b7746857
Ref: refman/predicates/set_logtalk_flag_2 predicates-set-logtalk-flag-2746857
Ref: 259746857
Ref: refman/predicates/set_logtalk_flag_2 set-logtalk-flag-2746857
Ref: 5b8746857
Node: Description<94>747066
Ref: refman/predicates/set_logtalk_flag_2 description747197
Ref: 5b9747197
Node: Modes and number of proofs<59>747680
Ref: refman/predicates/set_logtalk_flag_2 modes-and-number-of-proofs747830
Ref: 5ba747830
Node: Errors<60>747948
Ref: refman/predicates/set_logtalk_flag_2 errors748095
Ref: 5bb748095
Node: Examples<95>748617
Ref: refman/predicates/set_logtalk_flag_2 examples748725
Ref: 5bc748725
Node: create_logtalk_flag/3748995
Ref: refman/predicates/create_logtalk_flag_3 doc749107
Ref: 5bd749107
Ref: refman/predicates/create_logtalk_flag_3 create-logtalk-flag-3749107
Ref: 5be749107
Ref: refman/predicates/create_logtalk_flag_3 predicates-create-logtalk-flag-3749107
Ref: 284749107
Node: Description<95>749324
Ref: refman/predicates/create_logtalk_flag_3 description749455
Ref: 5bf749455
Node: Modes and number of proofs<60>750656
Ref: refman/predicates/create_logtalk_flag_3 modes-and-number-of-proofs750806
Ref: 5c0750806
Node: Errors<61>750944
Ref: refman/predicates/create_logtalk_flag_3 errors751091
Ref: 5c1751091
Node: Examples<96>751929
Ref: refman/predicates/create_logtalk_flag_3 examples752037
Ref: 5c2752037
Node: Built-in methods752292
Ref: refman/methods/index doc752408
Ref: 5c3752408
Ref: refman/methods/index built-in-methods752408
Ref: 5c4752408
Node: Execution context752840
Ref: refman/methods/context_methods doc752951
Ref: 5c5752951
Ref: refman/methods/context_methods context-methods752951
Ref: 5c6752951
Ref: refman/methods/context_methods execution-context752951
Ref: 5c7752951
Node: context/1753075
Ref: refman/methods/context_1 doc753177
Ref: 5c8753177
Ref: refman/methods/context_1 context-1753177
Ref: 5c9753177
Ref: refman/methods/context_1 methods-context-1753177
Ref: 153753177
Node: Description<96>753366
Ref: refman/methods/context_1 description753485
Ref: 5ca753485
Ref: Description<96>-Footnote-1754075
Node: Modes and number of proofs<61>754157
Ref: refman/methods/context_1 modes-and-number-of-proofs754295
Ref: 5cb754295
Node: Errors<62>754398
Ref: refman/methods/context_1 errors754533
Ref: 5cc754533
Node: Examples<97>754640
Ref: refman/methods/context_1 examples754736
Ref: 5cd754736
Node: parameter/2755087
Ref: refman/methods/parameter_2 doc755204
Ref: 5ce755204
Ref: refman/methods/parameter_2 methods-parameter-2755204
Ref: 7b755204
Ref: refman/methods/parameter_2 parameter-2755204
Ref: 5cf755204
Node: Description<97>755397
Ref: refman/methods/parameter_2 description755518
Ref: 5d0755518
Node: Modes and number of proofs<62>756554
Ref: refman/methods/parameter_2 modes-and-number-of-proofs756694
Ref: 5d2756694
Node: Errors<63>756812
Ref: refman/methods/parameter_2 errors756949
Ref: 5d3756949
Node: Examples<98>757383
Ref: refman/methods/parameter_2 examples757481
Ref: 5d4757481
Node: self/1758185
Ref: refman/methods/self_1 doc758301
Ref: 5d5758301
Ref: refman/methods/self_1 methods-self-1758301
Ref: 49758301
Ref: refman/methods/self_1 self-1758301
Ref: 5d6758301
Node: Description<98>758486
Ref: refman/methods/self_1 description758602
Ref: 5d7758602
Node: Modes and number of proofs<63>758998
Ref: refman/methods/self_1 modes-and-number-of-proofs759133
Ref: 5d8759133
Node: Errors<64>759251
Ref: refman/methods/self_1 errors759383
Ref: 5d9759383
Node: Examples<99>759424
Ref: refman/methods/self_1 examples759517
Ref: 5da759517
Node: sender/1759863
Ref: refman/methods/sender_1 doc759974
Ref: 5db759974
Ref: refman/methods/sender_1 methods-sender-1759974
Ref: 152759974
Ref: refman/methods/sender_1 sender-1759974
Ref: 5dc759974
Node: Description<99>760164
Ref: refman/methods/sender_1 description760282
Ref: 5dd760282
Node: Modes and number of proofs<64>760680
Ref: refman/methods/sender_1 modes-and-number-of-proofs760817
Ref: 5de760817
Node: Errors<65>760937
Ref: refman/methods/sender_1 errors761072
Ref: 5df761072
Node: Examples<100>761113
Ref: refman/methods/sender_1 examples761209
Ref: 5e0761209
Node: this/1761574
Ref: refman/methods/this_1 doc761670
Ref: 5e1761670
Ref: refman/methods/this_1 methods-this-1761670
Ref: 4a761670
Ref: refman/methods/this_1 this-1761670
Ref: 5e2761670
Node: Description<100>761857
Ref: refman/methods/this_1 description761974
Ref: 5e3761974
Node: Modes and number of proofs<65>762688
Ref: refman/methods/this_1 modes-and-number-of-proofs762824
Ref: 5e4762824
Node: Errors<66>762942
Ref: refman/methods/this_1 errors763075
Ref: 5e5763075
Node: Examples<101>763116
Ref: refman/methods/this_1 examples763210
Ref: 5e6763210
Node: Reflection<2>763563
Ref: refman/methods/reflection_methods doc763691
Ref: 5e7763691
Ref: refman/methods/reflection_methods reflection763691
Ref: 5e8763691
Ref: refman/methods/reflection_methods reflection-methods763691
Ref: 53763691
Node: current_op/3763802
Ref: refman/methods/current_op_3 doc763911
Ref: 5e9763911
Ref: refman/methods/current_op_3 current-op-3763911
Ref: 5ea763911
Ref: refman/methods/current_op_3 methods-current-op-3763911
Ref: 127763911
Node: Description<101>764108
Ref: refman/methods/current_op_3 description764231
Ref: 5eb764231
Node: Modes and number of proofs<66>764464
Ref: refman/methods/current_op_3 modes-and-number-of-proofs764606
Ref: 5ec764606
Node: Errors<67>764757
Ref: refman/methods/current_op_3 errors764896
Ref: 5ed764896
Node: Examples<102>765465
Ref: refman/methods/current_op_3 examples765565
Ref: 5ee765565
Node: current_predicate/1766183
Ref: refman/methods/current_predicate_1 doc766321
Ref: 5ef766321
Ref: refman/methods/current_predicate_1 current-predicate-1766321
Ref: 5f0766321
Ref: refman/methods/current_predicate_1 methods-current-predicate-1766321
Ref: 111766321
Node: Description<102>766532
Ref: refman/methods/current_predicate_1 description766662
Ref: 5f1766662
Node: Modes and number of proofs<67>767254
Ref: refman/methods/current_predicate_1 modes-and-number-of-proofs767403
Ref: 5f2767403
Node: Errors<68>767535
Ref: refman/methods/current_predicate_1 errors767681
Ref: 5f3767681
Node: Examples<103>768224
Ref: refman/methods/current_predicate_1 examples768331
Ref: 5f4768331
Node: predicate_property/2768966
Ref: refman/methods/predicate_property_2 doc769083
Ref: 5f5769083
Ref: refman/methods/predicate_property_2 methods-predicate-property-2769083
Ref: 112769083
Ref: refman/methods/predicate_property_2 predicate-property-2769083
Ref: 5f6769083
Node: Description<103>769298
Ref: refman/methods/predicate_property_2 description769429
Ref: 5f7769429
Node: Modes and number of proofs<68>770287
Ref: refman/methods/predicate_property_2 modes-and-number-of-proofs770437
Ref: 5f8770437
Node: Errors<69>770582
Ref: refman/methods/predicate_property_2 errors770729
Ref: 5f9770729
Node: Examples<104>771068
Ref: refman/methods/predicate_property_2 examples771176
Ref: 5fa771176
Node: Database771873
Ref: refman/methods/database_methods doc771994
Ref: 5fb771994
Ref: refman/methods/database_methods database771994
Ref: 5fc771994
Ref: refman/methods/database_methods database-methods771994
Ref: 5fd771994
Node: abolish/1772121
Ref: refman/methods/abolish_1 doc772212
Ref: 5fe772212
Ref: refman/methods/abolish_1 abolish-1772212
Ref: 5ff772212
Ref: refman/methods/abolish_1 methods-abolish-1772212
Ref: 165772212
Node: Description<104>772403
Ref: refman/methods/abolish_1 description772523
Ref: 600772523
Node: Modes and number of proofs<69>773012
Ref: refman/methods/abolish_1 modes-and-number-of-proofs773151
Ref: 601773151
Node: Errors<70>773264
Ref: refman/methods/abolish_1 errors773400
Ref: 602773400
Node: Examples<105>774543
Ref: refman/methods/abolish_1 examples774640
Ref: 603774640
Node: asserta/1775244
Ref: refman/methods/asserta_1 doc775353
Ref: 604775353
Ref: refman/methods/asserta_1 asserta-1775353
Ref: 605775353
Ref: refman/methods/asserta_1 methods-asserta-1775353
Ref: 166775353
Node: Description<105>775544
Ref: refman/methods/asserta_1 description775664
Ref: 606775664
Node: Modes and number of proofs<70>776556
Ref: refman/methods/asserta_1 modes-and-number-of-proofs776695
Ref: 607776695
Node: Errors<71>776795
Ref: refman/methods/asserta_1 errors776931
Ref: 608776931
Node: Examples<106>777955
Ref: refman/methods/asserta_1 examples778052
Ref: 609778052
Node: assertz/1778740
Ref: refman/methods/assertz_1 doc778848
Ref: 60a778848
Ref: refman/methods/assertz_1 assertz-1778848
Ref: 60b778848
Ref: refman/methods/assertz_1 methods-assertz-1778848
Ref: 167778848
Node: Description<106>779041
Ref: refman/methods/assertz_1 description779161
Ref: 60c779161
Node: Modes and number of proofs<71>780046
Ref: refman/methods/assertz_1 modes-and-number-of-proofs780185
Ref: 60d780185
Node: Errors<72>780287
Ref: refman/methods/assertz_1 errors780423
Ref: 60e780423
Node: Examples<107>781446
Ref: refman/methods/assertz_1 examples781543
Ref: 60f781543
Node: clause/2782228
Ref: refman/methods/clause_2 doc782336
Ref: 610782336
Ref: refman/methods/clause_2 clause-2782336
Ref: 611782336
Ref: refman/methods/clause_2 methods-clause-2782336
Ref: 168782336
Node: Description<107>782527
Ref: refman/methods/clause_2 description782646
Ref: 612782646
Node: Modes and number of proofs<72>783146
Ref: refman/methods/clause_2 modes-and-number-of-proofs783284
Ref: 613783284
Node: Errors<73>783403
Ref: refman/methods/clause_2 errors783538
Ref: 614783538
Node: Examples<108>784413
Ref: refman/methods/clause_2 examples784509
Ref: 615784509
Node: retract/1785182
Ref: refman/methods/retract_1 doc785293
Ref: 616785293
Ref: refman/methods/retract_1 methods-retract-1785293
Ref: 169785293
Ref: refman/methods/retract_1 retract-1785293
Ref: 617785293
Node: Description<108>785486
Ref: refman/methods/retract_1 description785606
Ref: 618785606
Node: Modes and number of proofs<73>786166
Ref: refman/methods/retract_1 modes-and-number-of-proofs786305
Ref: 619786305
Node: Errors<74>786416
Ref: refman/methods/retract_1 errors786552
Ref: 61a786552
Node: Examples<109>787353
Ref: refman/methods/retract_1 examples787450
Ref: 61b787450
Node: retractall/1788081
Ref: refman/methods/retractall_1 doc788175
Ref: 61c788175
Ref: refman/methods/retractall_1 methods-retractall-1788175
Ref: 16a788175
Ref: refman/methods/retractall_1 retractall-1788175
Ref: 61d788175
Node: Description<109>788374
Ref: refman/methods/retractall_1 description788497
Ref: 61e788497
Node: Modes and number of proofs<74>788992
Ref: refman/methods/retractall_1 modes-and-number-of-proofs789134
Ref: 61f789134
Node: Errors<75>789241
Ref: refman/methods/retractall_1 errors789380
Ref: 620789380
Node: Examples<110>790181
Ref: refman/methods/retractall_1 examples790281
Ref: 621790281
Node: Meta-calls790957
Ref: refman/methods/meta_call_methods doc791082
Ref: 622791082
Ref: refman/methods/meta_call_methods meta-call-methods791082
Ref: 623791082
Ref: refman/methods/meta_call_methods meta-calls791082
Ref: 624791082
Node: call/1-N791173
Ref: refman/methods/call_N doc791264
Ref: 625791264
Ref: refman/methods/call_N call-1-n791264
Ref: 626791264
Ref: refman/methods/call_N methods-call-n791264
Ref: 144791264
Node: Description<110>791453
Ref: refman/methods/call_N description791572
Ref: 627791572
Node: Modes and number of proofs<75>792284
Ref: refman/methods/call_N modes-and-number-of-proofs792422
Ref: 628792422
Node: Errors<76>792632
Ref: refman/methods/call_N errors792767
Ref: 629792767
Node: Examples<111>793130
Ref: refman/methods/call_N examples793226
Ref: 62a793226
Node: ignore/1793867
Ref: refman/methods/ignore_1 doc793973
Ref: 62b793973
Ref: refman/methods/ignore_1 ignore-1793973
Ref: 62c793973
Ref: refman/methods/ignore_1 methods-ignore-1793973
Ref: 16f793973
Node: Description<111>794162
Ref: refman/methods/ignore_1 description794281
Ref: 62d794281
Node: Modes and number of proofs<76>794603
Ref: refman/methods/ignore_1 modes-and-number-of-proofs794741
Ref: 62e794741
Node: Errors<77>794842
Ref: refman/methods/ignore_1 errors794977
Ref: 62f794977
Node: Examples<112>795170
Ref: refman/methods/ignore_1 examples795266
Ref: 630795266
Node: once/1795679
Ref: refman/methods/once_1 doc795781
Ref: 631795781
Ref: refman/methods/once_1 methods-once-1795781
Ref: 170795781
Ref: refman/methods/once_1 once-1795781
Ref: 632795781
Node: Description<112>795968
Ref: refman/methods/once_1 description796085
Ref: 633796085
Node: Modes and number of proofs<77>796386
Ref: refman/methods/once_1 modes-and-number-of-proofs796522
Ref: 634796522
Node: Errors<78>796631
Ref: refman/methods/once_1 errors796764
Ref: 635796764
Node: Examples<113>796959
Ref: refman/methods/once_1 examples797053
Ref: 636797053
Node: \+/1797507
Ref: refman/methods/not_1 doc797592
Ref: 637797592
Ref: refman/methods/not_1 id1797592
Ref: 638797592
Ref: refman/methods/not_1 methods-not-1797592
Ref: 171797592
Node: Description<113>797775
Ref: refman/methods/not_1 description797890
Ref: 639797890
Node: Modes and number of proofs<78>798127
Ref: refman/methods/not_1 modes-and-number-of-proofs798261
Ref: 63a798261
Node: Errors<79>798367
Ref: refman/methods/not_1 errors798498
Ref: 63b798498
Node: Examples<114>798693
Ref: refman/methods/not_1 examples798785
Ref: 63c798785
Node: Error handling<2>799202
Ref: refman/methods/error_handling_methods doc799332
Ref: 63d799332
Ref: refman/methods/error_handling_methods error-handling799332
Ref: 63e799332
Ref: refman/methods/error_handling_methods error-handling-methods799332
Ref: 1fe799332
Node: catch/3799625
Ref: refman/methods/catch_3 doc799721
Ref: 63f799721
Ref: refman/methods/catch_3 catch-3799721
Ref: 640799721
Ref: refman/methods/catch_3 methods-catch-3799721
Ref: 156799721
Node: Description<114>799908
Ref: refman/methods/catch_3 description800026
Ref: 641800026
Node: Modes and number of proofs<79>800296
Ref: refman/methods/catch_3 modes-and-number-of-proofs800433
Ref: 642800433
Node: Errors<80>800556
Ref: refman/methods/catch_3 errors800690
Ref: 643800690
Node: Examples<115>800883
Ref: refman/methods/catch_3 examples800978
Ref: 644800978
Node: throw/1801379
Ref: refman/methods/throw_1 doc801505
Ref: 645801505
Ref: refman/methods/throw_1 methods-throw-1801505
Ref: 157801505
Ref: refman/methods/throw_1 throw-1801505
Ref: 646801505
Node: Description<115>801692
Ref: refman/methods/throw_1 description801810
Ref: 647801810
Node: Modes and number of proofs<80>801989
Ref: refman/methods/throw_1 modes-and-number-of-proofs802126
Ref: 648802126
Node: Errors<81>802226
Ref: refman/methods/throw_1 errors802360
Ref: 649802360
Node: Examples<116>802582
Ref: refman/methods/throw_1 examples802677
Ref: 64a802677
Node: instantiation_error/0803080
Ref: refman/methods/instantiation_error_0 doc803211
Ref: 64b803211
Ref: refman/methods/instantiation_error_0 instantiation-error-0803211
Ref: 64c803211
Ref: refman/methods/instantiation_error_0 methods-instantiation-error-0803211
Ref: 158803211
Node: Description<116>803428
Ref: refman/methods/instantiation_error_0 description803560
Ref: 64d803560
Node: Modes and number of proofs<81>803992
Ref: refman/methods/instantiation_error_0 modes-and-number-of-proofs804143
Ref: 64e804143
Node: Errors<82>804250
Ref: refman/methods/instantiation_error_0 errors804398
Ref: 64f804398
Node: Examples<117>804488
Ref: refman/methods/instantiation_error_0 examples804597
Ref: 650804597
Node: type_error/2805034
Ref: refman/methods/type_error_2 doc805172
Ref: 651805172
Ref: refman/methods/type_error_2 methods-type-error-2805172
Ref: 159805172
Ref: refman/methods/type_error_2 type-error-2805172
Ref: 652805172
Node: Description<117>805371
Ref: refman/methods/type_error_2 description805494
Ref: 653805494
Node: Modes and number of proofs<82>805927
Ref: refman/methods/type_error_2 modes-and-number-of-proofs806069
Ref: 654806069
Node: Errors<83>806183
Ref: refman/methods/type_error_2 errors806322
Ref: 655806322
Node: Examples<118>806418
Ref: refman/methods/type_error_2 examples806518
Ref: 656806518
Node: domain_error/2806968
Ref: refman/methods/domain_error_2 doc807102
Ref: 657807102
Ref: refman/methods/domain_error_2 domain-error-2807102
Ref: 658807102
Ref: refman/methods/domain_error_2 methods-domain-error-2807102
Ref: 15a807102
Node: Description<118>807305
Ref: refman/methods/domain_error_2 description807430
Ref: 659807430
Node: Modes and number of proofs<83>807873
Ref: refman/methods/domain_error_2 modes-and-number-of-proofs808017
Ref: 65a808017
Node: Errors<84>808133
Ref: refman/methods/domain_error_2 errors808274
Ref: 65b808274
Node: Examples<119>808374
Ref: refman/methods/domain_error_2 examples808476
Ref: 65c808476
Node: existence_error/2808948
Ref: refman/methods/existence_error_2 doc809088
Ref: 65d809088
Ref: refman/methods/existence_error_2 existence-error-2809088
Ref: 65e809088
Ref: refman/methods/existence_error_2 methods-existence-error-2809088
Ref: 15b809088
Node: Description<119>809297
Ref: refman/methods/existence_error_2 description809425
Ref: 65f809425
Node: Modes and number of proofs<84>809876
Ref: refman/methods/existence_error_2 modes-and-number-of-proofs810023
Ref: 660810023
Node: Errors<85>810144
Ref: refman/methods/existence_error_2 errors810288
Ref: 661810288
Node: Examples<120>810390
Ref: refman/methods/existence_error_2 examples810495
Ref: 662810495
Node: permission_error/3810963
Ref: refman/methods/permission_error_3 doc811111
Ref: 663811111
Ref: refman/methods/permission_error_3 methods-permission-error-3811111
Ref: 15c811111
Ref: refman/methods/permission_error_3 permission-error-3811111
Ref: 664811111
Node: Description<120>811322
Ref: refman/methods/permission_error_3 description811451
Ref: 665811451
Node: Modes and number of proofs<85>811936
Ref: refman/methods/permission_error_3 modes-and-number-of-proofs812084
Ref: 666812084
Node: Errors<86>812215
Ref: refman/methods/permission_error_3 errors812360
Ref: 667812360
Node: Examples<121>812479
Ref: refman/methods/permission_error_3 examples812585
Ref: 668812585
Node: representation_error/1813047
Ref: refman/methods/representation_error_1 doc813196
Ref: 669813196
Ref: refman/methods/representation_error_1 methods-representation-error-1813196
Ref: 15d813196
Ref: refman/methods/representation_error_1 representation-error-1813196
Ref: 66a813196
Node: Description<121>813415
Ref: refman/methods/representation_error_1 description813548
Ref: 66b813548
Node: Modes and number of proofs<86>813994
Ref: refman/methods/representation_error_1 modes-and-number-of-proofs814146
Ref: 66c814146
Node: Errors<87>814261
Ref: refman/methods/representation_error_1 errors814410
Ref: 66d814410
Node: Examples<122>814507
Ref: refman/methods/representation_error_1 examples814617
Ref: 66e814617
Node: evaluation_error/1815068
Ref: refman/methods/evaluation_error_1 doc815215
Ref: 66f815215
Ref: refman/methods/evaluation_error_1 evaluation-error-1815215
Ref: 670815215
Ref: refman/methods/evaluation_error_1 methods-evaluation-error-1815215
Ref: 15e815215
Node: Description<122>815426
Ref: refman/methods/evaluation_error_1 description815555
Ref: 671815555
Node: Modes and number of proofs<87>816000
Ref: refman/methods/evaluation_error_1 modes-and-number-of-proofs816148
Ref: 672816148
Node: Errors<88>816261
Ref: refman/methods/evaluation_error_1 errors816406
Ref: 673816406
Node: Examples<123>816504
Ref: refman/methods/evaluation_error_1 examples816610
Ref: 674816610
Node: resource_error/1817062
Ref: refman/methods/resource_error_1 doc817201
Ref: 675817201
Ref: refman/methods/resource_error_1 methods-resource-error-1817201
Ref: 15f817201
Ref: refman/methods/resource_error_1 resource-error-1817201
Ref: 676817201
Node: Description<123>817408
Ref: refman/methods/resource_error_1 description817535
Ref: 677817535
Node: Modes and number of proofs<88>817971
Ref: refman/methods/resource_error_1 modes-and-number-of-proofs818117
Ref: 678818117
Node: Errors<89>818228
Ref: refman/methods/resource_error_1 errors818371
Ref: 679818371
Node: Examples<124>818466
Ref: refman/methods/resource_error_1 examples818570
Ref: 67a818570
Node: syntax_error/1819014
Ref: refman/methods/syntax_error_1 doc819149
Ref: 67b819149
Ref: refman/methods/syntax_error_1 methods-syntax-error-1819149
Ref: 160819149
Ref: refman/methods/syntax_error_1 syntax-error-1819149
Ref: 67c819149
Node: Description<124>819352
Ref: refman/methods/syntax_error_1 description819477
Ref: 67d819477
Node: Modes and number of proofs<89>819913
Ref: refman/methods/syntax_error_1 modes-and-number-of-proofs820057
Ref: 67e820057
Node: Errors<90>820166
Ref: refman/methods/syntax_error_1 errors820307
Ref: 67f820307
Node: Examples<125>820403
Ref: refman/methods/syntax_error_1 examples820505
Ref: 680820505
Node: system_error/0820904
Ref: refman/methods/system_error_0 doc821014
Ref: 681821014
Ref: refman/methods/system_error_0 methods-system-error-0821014
Ref: 161821014
Ref: refman/methods/system_error_0 system-error-0821014
Ref: 682821014
Node: Description<125>821217
Ref: refman/methods/system_error_0 description821342
Ref: 683821342
Node: Modes and number of proofs<90>821752
Ref: refman/methods/system_error_0 modes-and-number-of-proofs821896
Ref: 684821896
Node: Errors<91>821996
Ref: refman/methods/system_error_0 errors822137
Ref: 685822137
Node: Examples<126>822220
Ref: refman/methods/system_error_0 examples822322
Ref: 686822322
Node: All solutions822718
Ref: refman/methods/solution_methods doc822855
Ref: 687822855
Ref: refman/methods/solution_methods all-solutions822855
Ref: 688822855
Ref: refman/methods/solution_methods solutions-methods822855
Ref: 689822855
Node: bagof/3822971
Ref: refman/methods/bagof_3 doc823065
Ref: 68a823065
Ref: refman/methods/bagof_3 bagof-3823065
Ref: 68b823065
Ref: refman/methods/bagof_3 methods-bagof-3823065
Ref: 174823065
Node: Description<126>823252
Ref: refman/methods/bagof_3 description823370
Ref: 68c823370
Node: Modes and number of proofs<91>824268
Ref: refman/methods/bagof_3 modes-and-number-of-proofs824405
Ref: 68d824405
Node: Errors<92>824528
Ref: refman/methods/bagof_3 errors824662
Ref: 68e824662
Node: Examples<127>824960
Ref: refman/methods/bagof_3 examples825055
Ref: 68f825055
Node: findall/3825593
Ref: refman/methods/findall_3 doc825705
Ref: 690825705
Ref: refman/methods/findall_3 findall-3825705
Ref: 691825705
Ref: refman/methods/findall_3 methods-findall-3825705
Ref: 175825705
Node: Description<127>825896
Ref: refman/methods/findall_3 description826016
Ref: 692826016
Node: Modes and number of proofs<92>826399
Ref: refman/methods/findall_3 modes-and-number-of-proofs826538
Ref: 693826538
Node: Errors<93>826662
Ref: refman/methods/findall_3 errors826798
Ref: 694826798
Node: Examples<128>827096
Ref: refman/methods/findall_3 examples827193
Ref: 695827193
Node: findall/4827722
Ref: refman/methods/findall_4 doc827835
Ref: 696827835
Ref: refman/methods/findall_4 findall-4827835
Ref: 697827835
Ref: refman/methods/findall_4 methods-findall-4827835
Ref: 176827835
Node: Description<128>828028
Ref: refman/methods/findall_4 description828148
Ref: 698828148
Node: Modes and number of proofs<93>828514
Ref: refman/methods/findall_4 modes-and-number-of-proofs828653
Ref: 699828653
Node: Errors<94>828786
Ref: refman/methods/findall_4 errors828922
Ref: 69a828922
Node: Examples<129>829222
Ref: refman/methods/findall_4 examples829319
Ref: 69b829319
Node: forall/2829866
Ref: refman/methods/forall_2 doc829977
Ref: 69c829977
Ref: refman/methods/forall_2 forall-2829977
Ref: 69d829977
Ref: refman/methods/forall_2 methods-forall-2829977
Ref: 178829977
Node: Description<129>830168
Ref: refman/methods/forall_2 description830287
Ref: 69e830287
Node: Modes and number of proofs<94>830655
Ref: refman/methods/forall_2 modes-and-number-of-proofs830793
Ref: 69f830793
Node: Errors<95>830915
Ref: refman/methods/forall_2 errors831050
Ref: 6a0831050
Node: Examples<130>831373
Ref: refman/methods/forall_2 examples831469
Ref: 6a1831469
Node: setof/3831958
Ref: refman/methods/setof_3 doc832051
Ref: 6a2832051
Ref: refman/methods/setof_3 methods-setof-3832051
Ref: 177832051
Ref: refman/methods/setof_3 setof-3832051
Ref: 6a3832051
Node: Description<130>832240
Ref: refman/methods/setof_3 description832358
Ref: 6a4832358
Node: Modes and number of proofs<95>833232
Ref: refman/methods/setof_3 modes-and-number-of-proofs833369
Ref: 6a5833369
Node: Errors<96>833494
Ref: refman/methods/setof_3 errors833628
Ref: 6a6833628
Node: Examples<131>833928
Ref: refman/methods/setof_3 examples834023
Ref: 6a7834023
Node: Event handling<3>834563
Ref: refman/methods/event_methods doc834701
Ref: 6a8834701
Ref: refman/methods/event_methods event-handling834701
Ref: 6a9834701
Ref: refman/methods/event_methods event-methods834701
Ref: 6aa834701
Node: before/3834779
Ref: refman/methods/before_3 doc834876
Ref: 6ab834876
Ref: refman/methods/before_3 before-3834876
Ref: 6ac834876
Ref: refman/methods/before_3 methods-before-3834876
Ref: d8834876
Node: Description<131>835065
Ref: refman/methods/before_3 description835184
Ref: 6ad835184
Ref: Description<131>-Footnote-1835790
Node: Modes and number of proofs<96>835857
Ref: refman/methods/before_3 modes-and-number-of-proofs835995
Ref: 6ae835995
Node: Errors<97>836145
Ref: refman/methods/before_3 errors836280
Ref: 6af836280
Node: Examples<132>836319
Ref: refman/methods/before_3 examples836415
Ref: 6b0836415
Node: after/3836852
Ref: refman/methods/after_3 doc836949
Ref: 6b1836949
Ref: refman/methods/after_3 after-3836949
Ref: 6b2836949
Ref: refman/methods/after_3 methods-after-3836949
Ref: d9836949
Node: Description<132>837136
Ref: refman/methods/after_3 description837254
Ref: 6b3837254
Ref: Description<132>-Footnote-1837858
Node: Modes and number of proofs<97>837925
Ref: refman/methods/after_3 modes-and-number-of-proofs838062
Ref: 6b4838062
Node: Errors<98>838211
Ref: refman/methods/after_3 errors838345
Ref: 6b5838345
Node: Examples<133>838384
Ref: refman/methods/after_3 examples838479
Ref: 6b6838479
Node: Message forwarding838924
Ref: refman/methods/forwarding_methods doc839081
Ref: 6b7839081
Ref: refman/methods/forwarding_methods forwarding-methods839081
Ref: 6b8839081
Ref: refman/methods/forwarding_methods message-forwarding839081
Ref: 6b9839081
Node: forward/1839156
Ref: refman/methods/forward_1 doc839239
Ref: 6ba839239
Ref: refman/methods/forward_1 forward-1839239
Ref: 6bb839239
Ref: refman/methods/forward_1 methods-forward-1839239
Ref: dc839239
Node: Description<133>839430
Ref: refman/methods/forward_1 description839550
Ref: 6bc839550
Ref: Description<133>-Footnote-1840077
Node: Modes and number of proofs<98>840144
Ref: refman/methods/forward_1 modes-and-number-of-proofs840283
Ref: 6bd840283
Node: Errors<99>840394
Ref: refman/methods/forward_1 errors840530
Ref: 6be840530
Node: Examples<134>840569
Ref: refman/methods/forward_1 examples840666
Ref: 6bf840666
Node: Definite clause grammar rules<2>840930
Ref: refman/methods/dcg_methods doc841096
Ref: 6c0841096
Ref: refman/methods/dcg_methods dcg-methods841096
Ref: 6c1841096
Ref: refman/methods/dcg_methods definite-clause-grammar-rules841096
Ref: 6c2841096
Node: call//1-N841244
Ref: refman/methods/call_1 doc841356
Ref: 6c3841356
Ref: refman/methods/call_1 call-1-n841356
Ref: 6c4841356
Ref: refman/methods/call_1 methods-call-1841356
Ref: 17e841356
Node: Description<134>841548
Ref: refman/methods/call_1 description841668
Ref: 6c5841668
Node: Modes and number of proofs<99>842868
Ref: refman/methods/call_1 modes-and-number-of-proofs843008
Ref: 6c6843008
Node: Errors<100>843218
Ref: refman/methods/call_1 errors843355
Ref: 6c7843355
Node: Examples<135>843557
Ref: refman/methods/call_1 examples843655
Ref: 6c8843655
Node: eos//0844430
Ref: refman/methods/eos_0 doc844560
Ref: 6c9844560
Ref: refman/methods/eos_0 eos-0844560
Ref: 6ca844560
Ref: refman/methods/eos_0 methods-eos-0844560
Ref: 17f844560
Node: Description<135>844747
Ref: refman/methods/eos_0 description844865
Ref: 6cb844865
Node: Modes and number of proofs<100>845052
Ref: refman/methods/eos_0 modes-and-number-of-proofs845190
Ref: 6cc845190
Node: Errors<101>845285
Ref: refman/methods/eos_0 errors845420
Ref: 6cd845420
Node: Examples<136>845459
Ref: refman/methods/eos_0 examples845554
Ref: 6ce845554
Node: phrase//1845725
Ref: refman/methods/phrase_1 doc845854
Ref: 6cf845854
Ref: refman/methods/phrase_1 methods-phrase-1845854
Ref: 17d845854
Ref: refman/methods/phrase_1 phrase-1845854
Ref: 6d0845854
Node: Description<136>846049
Ref: refman/methods/phrase_1 description846170
Ref: 6d1846170
Node: Modes and number of proofs<101>846452
Ref: refman/methods/phrase_1 modes-and-number-of-proofs846593
Ref: 6d2846593
Node: Errors<102>846705
Ref: refman/methods/phrase_1 errors846843
Ref: 6d3846843
Node: Examples<137>847059
Ref: refman/methods/phrase_1 examples847157
Ref: 6d4847157
Node: phrase/2847291
Ref: refman/methods/phrase_2 doc847422
Ref: 6d5847422
Ref: refman/methods/phrase_2 methods-phrase-2847422
Ref: 14b847422
Ref: refman/methods/phrase_2 phrase-2847422
Ref: 6d6847422
Node: Description<137>847615
Ref: refman/methods/phrase_2 description847735
Ref: 6d7847735
Node: Modes and number of proofs<102>848697
Ref: refman/methods/phrase_2 modes-and-number-of-proofs848837
Ref: 6d8848837
Node: Errors<103>848956
Ref: refman/methods/phrase_2 errors849093
Ref: 6d9849093
Node: Examples<138>849309
Ref: refman/methods/phrase_2 examples849406
Ref: 6da849406
Node: phrase/3849904
Ref: refman/methods/phrase_3 doc850017
Ref: 6db850017
Ref: refman/methods/phrase_3 methods-phrase-3850017
Ref: 14c850017
Ref: refman/methods/phrase_3 phrase-3850017
Ref: 6dc850017
Node: Description<138>850210
Ref: refman/methods/phrase_3 description850330
Ref: 6dd850330
Node: Modes and number of proofs<103>851345
Ref: refman/methods/phrase_3 modes-and-number-of-proofs851485
Ref: 6de851485
Node: Errors<104>851611
Ref: refman/methods/phrase_3 errors851748
Ref: 6df851748
Node: Examples<139>851964
Ref: refman/methods/phrase_3 examples852061
Ref: 6e0852061
Node: Term and goal expansion<2>852576
Ref: refman/methods/expansion_methods doc852741
Ref: 6e1852741
Ref: refman/methods/expansion_methods expansion-methods852741
Ref: 6e2852741
Ref: refman/methods/expansion_methods term-and-goal-expansion852741
Ref: 6e3852741
Node: expand_term/2852892
Ref: refman/methods/expand_term_2 doc853012
Ref: 6e4853012
Ref: refman/methods/expand_term_2 expand-term-2853012
Ref: 6e5853012
Ref: refman/methods/expand_term_2 methods-expand-term-2853012
Ref: 16c853012
Node: Description<139>853215
Ref: refman/methods/expand_term_2 description853340
Ref: 6e6853340
Node: Modes and number of proofs<104>854776
Ref: refman/methods/expand_term_2 modes-and-number-of-proofs854921
Ref: 6e7854921
Node: Errors<105>855032
Ref: refman/methods/expand_term_2 errors855174
Ref: 6e8855174
Node: Examples<140>855215
Ref: refman/methods/expand_term_2 examples855317
Ref: 6e9855317
Node: term_expansion/2855464
Ref: refman/methods/term_expansion_2 doc855606
Ref: 6ea855606
Ref: refman/methods/term_expansion_2 methods-term-expansion-2855606
Ref: d3855606
Ref: refman/methods/term_expansion_2 term-expansion-2855606
Ref: 6eb855606
Node: Description<140>855815
Ref: refman/methods/term_expansion_2 description855943
Ref: 6ec855943
Ref: Description<140>-Footnote-1857367
Node: Modes and number of proofs<105>857432
Ref: refman/methods/term_expansion_2 modes-and-number-of-proofs857580
Ref: 6ed857580
Node: Errors<106>857764
Ref: refman/methods/term_expansion_2 errors857909
Ref: 6ee857909
Node: Examples<141>857950
Ref: refman/methods/term_expansion_2 examples858055
Ref: 6ef858055
Node: expand_goal/2858381
Ref: refman/methods/expand_goal_2 doc858526
Ref: 6f0858526
Ref: refman/methods/expand_goal_2 expand-goal-2858526
Ref: 6f1858526
Ref: refman/methods/expand_goal_2 methods-expand-goal-2858526
Ref: 2a1858526
Node: Description<141>858731
Ref: refman/methods/expand_goal_2 description858856
Ref: 6f2858856
Node: Modes and number of proofs<106>859748
Ref: refman/methods/expand_goal_2 modes-and-number-of-proofs859893
Ref: 6f3859893
Node: Errors<107>860006
Ref: refman/methods/expand_goal_2 errors860148
Ref: 6f4860148
Node: Examples<142>860191
Ref: refman/methods/expand_goal_2 examples860293
Ref: 6f5860293
Node: goal_expansion/2860442
Ref: refman/methods/goal_expansion_2 doc860562
Ref: 6f6860562
Ref: refman/methods/goal_expansion_2 goal-expansion-2860562
Ref: 6f7860562
Ref: refman/methods/goal_expansion_2 methods-goal-expansion-2860562
Ref: d4860562
Node: Description<142>860773
Ref: refman/methods/goal_expansion_2 description860901
Ref: 6f8860901
Ref: Description<142>-Footnote-1862370
Node: Modes and number of proofs<107>862435
Ref: refman/methods/goal_expansion_2 modes-and-number-of-proofs862583
Ref: 6f9862583
Node: Errors<108>862715
Ref: refman/methods/goal_expansion_2 errors862860
Ref: 6fa862860
Node: Examples<143>862903
Ref: refman/methods/goal_expansion_2 examples863008
Ref: 6fb863008
Node: Coinduction hooks863312
Ref: refman/methods/coinduction_methods doc863461
Ref: 6fc863461
Ref: refman/methods/coinduction_methods coinduction-hooks863461
Ref: 6fd863461
Ref: refman/methods/coinduction_methods coinduction-methods863461
Ref: 6fe863461
Node: coinductive_success_hook/1-2863555
Ref: refman/methods/coinductive_success_hook_1_2 doc863656
Ref: 6ff863656
Ref: refman/methods/coinductive_success_hook_1_2 coinductive-success-hook-1-2863656
Ref: 700863656
Ref: refman/methods/coinductive_success_hook_1_2 methods-coinductive-success-hook-1-2863656
Ref: 417863656
Node: Description<143>863889
Ref: refman/methods/coinductive_success_hook_1_2 description864029
Ref: 701864029
Node: Modes and number of proofs<108>864906
Ref: refman/methods/coinductive_success_hook_1_2 modes-and-number-of-proofs865066
Ref: 702865066
Node: Errors<109>865261
Ref: refman/methods/coinductive_success_hook_1_2 errors865418
Ref: 703865418
Node: Examples<144>865459
Ref: refman/methods/coinductive_success_hook_1_2 examples865576
Ref: 704865576
Node: Message printing866153
Ref: refman/methods/printing_methods doc866291
Ref: 705866291
Ref: refman/methods/printing_methods message-printing866291
Ref: 706866291
Ref: refman/methods/printing_methods printing-methods866291
Ref: 707866291
Node: print_message/3866492
Ref: refman/methods/print_message_3 doc866605
Ref: 708866605
Ref: refman/methods/print_message_3 methods-print-message-3866605
Ref: 291866605
Ref: refman/methods/print_message_3 print-message-3866605
Ref: 709866605
Node: Description<144>866812
Ref: refman/methods/print_message_3 description866939
Ref: 70a866939
Ref: Description<144>-Footnote-1867820
Node: Modes and number of proofs<109>867881
Ref: refman/methods/print_message_3 modes-and-number-of-proofs868028
Ref: 70b868028
Node: Errors<110>868154
Ref: refman/methods/print_message_3 errors868298
Ref: 70c868298
Node: Examples<145>868339
Ref: refman/methods/print_message_3 examples868443
Ref: 70d868443
Node: message_tokens//2868844
Ref: refman/methods/message_tokens_2 doc868980
Ref: 711868980
Ref: refman/methods/message_tokens_2 message-tokens-2868980
Ref: 712868980
Ref: refman/methods/message_tokens_2 methods-message-tokens-2868980
Ref: 293868980
Node: Description<145>869191
Ref: refman/methods/message_tokens_2 description869320
Ref: 713869320
Ref: Description<145>-Footnote-1869806
Node: Modes and number of proofs<110>869867
Ref: refman/methods/message_tokens_2 modes-and-number-of-proofs870016
Ref: 714870016
Node: Errors<111>870143
Ref: refman/methods/message_tokens_2 errors870289
Ref: 715870289
Node: Examples<146>870330
Ref: refman/methods/message_tokens_2 examples870436
Ref: 716870436
Node: message_hook/4870963
Ref: refman/methods/message_hook_4 doc871107
Ref: 717871107
Ref: refman/methods/message_hook_4 message-hook-4871107
Ref: 718871107
Ref: refman/methods/message_hook_4 methods-message-hook-4871107
Ref: 297871107
Node: Description<146>871314
Ref: refman/methods/message_hook_4 description871440
Ref: 719871440
Ref: Description<146>-Footnote-1871930
Node: Modes and number of proofs<111>871991
Ref: refman/methods/message_hook_4 modes-and-number-of-proofs872137
Ref: 71a872137
Node: Errors<112>872287
Ref: refman/methods/message_hook_4 errors872430
Ref: 71b872430
Node: Examples<147>872473
Ref: refman/methods/message_hook_4 examples872576
Ref: 71c872576
Node: message_prefix_stream/4873235
Ref: refman/methods/message_prefix_stream_4 doc873384
Ref: 71d873384
Ref: refman/methods/message_prefix_stream_4 message-prefix-stream-4873384
Ref: 71e873384
Ref: refman/methods/message_prefix_stream_4 methods-message-prefix-stream-4873384
Ref: 298873384
Node: Description<147>873609
Ref: refman/methods/message_prefix_stream_4 description873744
Ref: 71f873744
Ref: Description<147>-Footnote-1874129
Node: Modes and number of proofs<112>874190
Ref: refman/methods/message_prefix_stream_4 modes-and-number-of-proofs874345
Ref: 720874345
Node: Errors<113>874506
Ref: refman/methods/message_prefix_stream_4 errors874658
Ref: 721874658
Node: Examples<148>874701
Ref: refman/methods/message_prefix_stream_4 examples874813
Ref: 722874813
Node: print_message_tokens/3875299
Ref: refman/methods/print_message_tokens_3 doc875455
Ref: 723875455
Ref: refman/methods/print_message_tokens_3 methods-print-message-tokens-3875455
Ref: 70e875455
Ref: refman/methods/print_message_tokens_3 print-message-tokens-3875455
Ref: 724875455
Node: Description<148>875678
Ref: refman/methods/print_message_tokens_3 description875812
Ref: 725875812
Ref: Description<148>-Footnote-1876573
Node: Modes and number of proofs<113>876634
Ref: refman/methods/print_message_tokens_3 modes-and-number-of-proofs876788
Ref: 726876788
Node: Errors<114>876944
Ref: refman/methods/print_message_tokens_3 errors877095
Ref: 727877095
Node: Examples<149>877138
Ref: refman/methods/print_message_tokens_3 examples877249
Ref: 728877249
Node: print_message_token/4877668
Ref: refman/methods/print_message_token_4 doc877792
Ref: 729877792
Ref: refman/methods/print_message_token_4 methods-print-message-token-4877792
Ref: 70f877792
Ref: refman/methods/print_message_token_4 print-message-token-4877792
Ref: 72a877792
Node: Description<149>878013
Ref: refman/methods/print_message_token_4 description878146
Ref: 72b878146
Ref: Description<149>-Footnote-1878612
Node: Modes and number of proofs<114>878673
Ref: refman/methods/print_message_token_4 modes-and-number-of-proofs878826
Ref: 72c878826
Node: Errors<115>878990
Ref: refman/methods/print_message_token_4 errors879140
Ref: 72d879140
Node: Examples<150>879183
Ref: refman/methods/print_message_token_4 examples879293
Ref: 72e879293
Node: Question asking879802
Ref: refman/methods/asking_methods doc879914
Ref: 72f879914
Ref: refman/methods/asking_methods asking-methods879914
Ref: 730879914
Ref: refman/methods/asking_methods question-asking879914
Ref: 731879914
Node: ask_question/5880039
Ref: refman/methods/ask_question_5 doc880148
Ref: 732880148
Ref: refman/methods/ask_question_5 ask-question-5880148
Ref: 733880148
Ref: refman/methods/ask_question_5 methods-ask-question-5880148
Ref: 29b880148
Node: Description<150>880381
Ref: refman/methods/ask_question_5 description880507
Ref: 734880507
Node: Modes and number of proofs<115>881583
Ref: refman/methods/ask_question_5 modes-and-number-of-proofs881741
Ref: 735881741
Node: Meta-predicate template881884
Ref: refman/methods/ask_question_5 meta-predicate-template882037
Ref: 736882037
Node: Errors<116>882138
Ref: refman/methods/ask_question_5 errors882273
Ref: 737882273
Node: Examples<151>882314
Ref: refman/methods/ask_question_5 examples882417
Ref: 738882417
Node: question_hook/6882820
Ref: refman/methods/question_hook_6 doc882962
Ref: 739882962
Ref: refman/methods/question_hook_6 methods-question-hook-6882962
Ref: 29d882962
Ref: refman/methods/question_hook_6 question-hook-6882962
Ref: 73a882962
Node: Description<151>883224
Ref: refman/methods/question_hook_6 description883351
Ref: 73b883351
Ref: Description<151>-Footnote-1883861
Node: Modes and number of proofs<116>883922
Ref: refman/methods/question_hook_6 modes-and-number-of-proofs884084
Ref: 73c884084
Node: Meta-predicate template<2>884251
Ref: refman/methods/question_hook_6 meta-predicate-template884408
Ref: 73d884408
Node: Errors<117>884515
Ref: refman/methods/question_hook_6 errors884654
Ref: 73e884654
Node: Examples<152>884697
Ref: refman/methods/question_hook_6 examples884801
Ref: 73f884801
Node: question_prompt_stream/4885338
Ref: refman/methods/question_prompt_stream_4 doc885457
Ref: 740885457
Ref: refman/methods/question_prompt_stream_4 methods-question-prompt-stream-4885457
Ref: 710885457
Ref: refman/methods/question_prompt_stream_4 question-prompt-stream-4885457
Ref: 741885457
Node: Description<152>885684
Ref: refman/methods/question_prompt_stream_4 description885820
Ref: 742885820
Ref: Description<152>-Footnote-1886210
Node: Modes and number of proofs<117>886271
Ref: refman/methods/question_prompt_stream_4 modes-and-number-of-proofs886427
Ref: 743886427
Node: Errors<118>886589
Ref: refman/methods/question_prompt_stream_4 errors886742
Ref: 744886742
Node: Examples<153>886785
Ref: refman/methods/question_prompt_stream_4 examples886898
Ref: 745886898
Node: Tutorial887390
Ref: tutorial/index doc887494
Ref: 746887494
Ref: tutorial/index tutorial887494
Ref: 747887494
Node: List predicates887636
Ref: tutorial/lists doc887749
Ref: 748887749
Ref: tutorial/lists list-predicates887749
Ref: 749887749
Node: Defining a list object887989
Ref: tutorial/lists defining-a-list-object888115
Ref: 74a888115
Ref: tutorial/lists object888115
Ref: 74b888115
Node: Defining a list protocol890657
Ref: tutorial/lists defining-a-list-protocol890799
Ref: 74c890799
Ref: tutorial/lists protocol890799
Ref: 74d890799
Node: Summary892998
Ref: tutorial/lists summary893109
Ref: 74e893109
Node: Dynamic object attributes893559
Ref: tutorial/attributes doc893712
Ref: 74f893712
Ref: tutorial/attributes dynamic-object-attributes893712
Ref: 750893712
Node: Defining a category894074
Ref: tutorial/attributes category894205
Ref: 751894205
Ref: tutorial/attributes defining-a-category894205
Ref: 752894205
Node: Importing the category897891
Ref: tutorial/attributes importing898041
Ref: 753898041
Ref: tutorial/attributes importing-the-category898041
Ref: 754898041
Node: Summary<2>898603
Ref: tutorial/attributes summary898725
Ref: 755898725
Node: A reflective class-based system899358
Ref: tutorial/reflection doc899514
Ref: 756899514
Ref: tutorial/reflection a-reflective-class-based-system899514
Ref: 757899514
Node: Defining the base classes900628
Ref: tutorial/reflection classes900759
Ref: 758900759
Ref: tutorial/reflection defining-the-base-classes900759
Ref: 759900759
Node: Summary<3>902142
Ref: tutorial/reflection summary902273
Ref: 75a902273
Node: Profiling programs902871
Ref: tutorial/profiling doc902993
Ref: 75b902993
Ref: tutorial/profiling profiling-programs902993
Ref: 75c902993
Node: Messages as events903315
Ref: tutorial/profiling events903437
Ref: 75d903437
Ref: tutorial/profiling messages-as-events903437
Ref: 75e903437
Node: Profilers as monitors904569
Ref: tutorial/profiling monitors904710
Ref: 75f904710
Ref: tutorial/profiling profilers-as-monitors904710
Ref: 760904710
Node: Summary<4>907691
Ref: tutorial/profiling summary907805
Ref: 761907805
Node: FAQ908664
Ref: faq/index doc908767
Ref: 762908767
Ref: faq/index faq908767
Ref: 763908767
Node: General908975
Ref: faq/general doc909063
Ref: 764909063
Ref: faq/general faq-general909063
Ref: 765909063
Ref: faq/general general909063
Ref: 766909063
Node: Why are all versions of Logtalk numbered 2 x or 3 x?909655
Ref: faq/general faq-general-versions909826
Ref: 767909826
Ref: faq/general why-are-all-versions-of-logtalk-numbered-2-x-or-3-x909826
Ref: 76b909826
Node: Why do I need a Prolog compiler to use Logtalk?910493
Ref: faq/general faq-general-prolog910727
Ref: 768910727
Ref: faq/general why-do-i-need-a-prolog-compiler-to-use-logtalk910727
Ref: 76c910727
Node: Is the Logtalk implementation based on Prolog modules?911352
Ref: faq/general faq-general-modules911585
Ref: 769911585
Ref: faq/general is-the-logtalk-implementation-based-on-prolog-modules911585
Ref: 76d911585
Node: Does the Logtalk implementation use term-expansion?912245
Ref: faq/general does-the-logtalk-implementation-use-term-expansion912422
Ref: 76e912422
Ref: faq/general faq-general-expansion912422
Ref: 76a912422
Node: Compatibility912645
Ref: faq/compatibility doc912754
Ref: 76f912754
Ref: faq/compatibility compatibility912754
Ref: 770912754
Ref: faq/compatibility faq-compatibility912754
Ref: 771912754
Node: What are the backend Prolog compiler requirements to run Logtalk?913235
Ref: faq/compatibility faq-compatibility-requirements913427
Ref: 772913427
Ref: faq/compatibility what-are-the-backend-prolog-compiler-requirements-to-run-logtalk913427
Ref: 775913427
Ref: What are the backend Prolog compiler requirements to run Logtalk?-Footnote-1913664
Node: Can I use constraint-based packages with Logtalk?913718
Ref: faq/compatibility can-i-use-constraint-based-packages-with-logtalk913981
Ref: 776913981
Ref: faq/compatibility faq-compatibility-constraints913981
Ref: 773913981
Node: Can I use Logtalk objects and Prolog modules at the same time?914622
Ref: faq/compatibility can-i-use-logtalk-objects-and-prolog-modules-at-the-same-time914811
Ref: 777914811
Ref: faq/compatibility faq-compatibility-modules914811
Ref: 774914811
Node: Installation915406
Ref: faq/installation doc915519
Ref: 778915519
Ref: faq/installation faq-installation915519
Ref: 779915519
Ref: faq/installation installation915519
Ref: 77a915519
Node: The integration scripts/shortcuts are not working!915869
Ref: faq/installation faq-installation-scripts916072
Ref: 77b916072
Ref: faq/installation the-integration-scripts-shortcuts-are-not-working916072
Ref: 77d916072
Node: I get errors when starting up Logtalk after upgrading to the latest version!917022
Ref: faq/installation faq-installation-startup-errors917225
Ref: 77c917225
Ref: faq/installation i-get-errors-when-starting-up-logtalk-after-upgrading-to-the-latest-version917225
Ref: 77e917225
Node: Portability917794
Ref: faq/portability doc917905
Ref: 77f917905
Ref: faq/portability faq-portability917905
Ref: 780917905
Ref: faq/portability portability917905
Ref: 781917905
Node: Are my Logtalk applications portable across Prolog compilers?918252
Ref: faq/portability are-my-logtalk-applications-portable-across-prolog-compilers918451
Ref: 784918451
Ref: faq/portability faq-portability-prolog918451
Ref: 782918451
Node: Are my Logtalk applications portable across operating systems?919241
Ref: faq/portability are-my-logtalk-applications-portable-across-operating-systems919440
Ref: 785919440
Ref: faq/portability faq-portability-os919440
Ref: 783919440
Node: Programming920000
Ref: faq/programming doc920114
Ref: 786920114
Ref: faq/programming faq-programming920114
Ref: 787920114
Ref: faq/programming programming920114
Ref: 788920114
Node: Should I use prototypes or classes in my application?921063
Ref: faq/programming faq-programming-either-prototypes-classes921254
Ref: 789921254
Ref: faq/programming should-i-use-prototypes-or-classes-in-my-application921254
Ref: 78f921254
Node: Can I use both classes and prototypes in the same application?921757
Ref: faq/programming can-i-use-both-classes-and-prototypes-in-the-same-application922012
Ref: 790922012
Ref: faq/programming faq-programming-both-prototypes-classes922012
Ref: 78a922012
Node: Can I mix classes and prototypes in the same hierarchy?922248
Ref: faq/programming can-i-mix-classes-and-prototypes-in-the-same-hierarchy922518
Ref: 791922518
Ref: faq/programming faq-programming-hierarchy922518
Ref: 78b922518
Node: Can I use a protocol or a category with both prototypes and classes?922768
Ref: faq/programming can-i-use-a-protocol-or-a-category-with-both-prototypes-and-classes923046
Ref: 792923046
Ref: faq/programming faq-programming-protocols-categories923046
Ref: 78c923046
Node: What support is provided in Logtalk for defining and using components?923384
Ref: faq/programming faq-programming-components923670
Ref: 78d923670
Ref: faq/programming what-support-is-provided-in-logtalk-for-defining-and-using-components923670
Ref: 793923670
Node: What support is provided in Logtalk for reflective programming?924313
Ref: faq/programming faq-programming-reflection924522
Ref: 78e924522
Ref: faq/programming what-support-is-provided-in-logtalk-for-reflective-programming924522
Ref: 794924522
Node: Troubleshooting924958
Ref: faq/troubleshooting doc925070
Ref: 795925070
Ref: faq/troubleshooting faq-troubleshooting925070
Ref: 796925070
Ref: faq/troubleshooting troubleshooting925070
Ref: 797925070
Node: Using compiler options on calls to the Logtalk compiling and loading predicates do not work!926002
Ref: faq/troubleshooting faq-troubleshooting-options926275
Ref: 798926275
Ref: faq/troubleshooting using-compiler-options-on-calls-to-the-logtalk-compiling-and-loading-predicates-do-not-work926275
Ref: 79b926275
Node: Gecko-based browsers e g Firefox show non-rendered HTML entities when browsing XML documenting files!926962
Ref: faq/troubleshooting faq-troubleshooting-gecko927391
Ref: 799927391
Ref: faq/troubleshooting gecko-based-browsers-e-g-firefox-show-non-rendered-html-entities-when-browsing-xml-documenting-files927391
Ref: 79c927391
Node: Compiling a source file results in errors or warnings but the Logtalk compiler reports a successful compilation with zero errors and zero warnings!928188
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-warnings928516
Ref: 79d928516
Ref: faq/troubleshooting faq-troubleshooting-warnings928516
Ref: 79a928516
Node: Usability929546
Ref: faq/usability doc929657
Ref: 79e929657
Ref: faq/usability faq-usability929657
Ref: 79f929657
Ref: faq/usability usability929657
Ref: 7a0929657
Node: Is there a shortcut for compiling and loading source files?930136
Ref: faq/usability faq-usability-shortcuts930342
Ref: 7a1930342
Ref: faq/usability is-there-a-shortcut-for-compiling-and-loading-source-files930342
Ref: 7a4930342
Node: Is there an equivalent directive to the ensure_loaded/1 Prolog directive?930747
Ref: faq/usability faq-usability-ensure-loaded931009
Ref: 7a2931009
Ref: faq/usability is-there-an-equivalent-directive-to-the-ensure-loaded-1-prolog-directive931009
Ref: 7a5931009
Node: Are there shortcuts for the make functionality?931368
Ref: faq/usability are-there-shortcuts-for-the-make-functionality931562
Ref: 7a6931562
Ref: faq/usability faq-usability-make931562
Ref: 7a3931562
Node: Deployment932254
Ref: faq/deployment doc932364
Ref: 7a7932364
Ref: faq/deployment deployment932364
Ref: 7a8932364
Ref: faq/deployment faq-deployment932364
Ref: 7a9932364
Node: Can I create standalone applications with Logtalk?932529
Ref: faq/deployment can-i-create-standalone-applications-with-logtalk932645
Ref: 7ab932645
Ref: faq/deployment faq-deployment-create932645
Ref: 7aa932645
Ref: Can I create standalone applications with Logtalk?-Footnote-1933250
Node: Performance<3>933293
Ref: faq/performance doc933403
Ref: 7ac933403
Ref: faq/performance id1933403
Ref: 7ad933403
Ref: faq/performance performance933403
Ref: 7ae933403
Node: Is Logtalk implemented as a meta-interpreter?934241
Ref: faq/performance is-logtalk-implemented-as-a-meta-interpreter934451
Ref: 7b3934451
Ref: faq/performance performance-meta-interpreter934451
Ref: 7af934451
Node: What kind of code Logtalk generates when compiling objects? Dynamic code? Static code?934801
Ref: faq/performance performance-code-generated935110
Ref: 7b0935110
Ref: faq/performance what-kind-of-code-logtalk-generates-when-compiling-objects-dynamic-code-static-code935110
Ref: 7b4935110
Node: How about message-sending performance? Does Logtalk use static binding or dynamic binding?935673
Ref: faq/performance how-about-message-sending-performance-does-logtalk-use-static-binding-or-dynamic-binding936014
Ref: 7b5936014
Ref: faq/performance performance-binding936014
Ref: 7b1936014
Node: Which Prolog-dependent factors are most crucial for good Logtalk performance?937070
Ref: faq/performance which-prolog-dependent-factors-are-most-crucial-for-good-logtalk-performance937404
Ref: 7b6937404
Node: How does Logtalk performance compare with plain Prolog and with Prolog modules?938169
Ref: faq/performance how-does-logtalk-performance-compare-with-plain-prolog-and-with-prolog-modules938404
Ref: 7b7938404
Ref: faq/performance performance-prolog938404
Ref: 7b2938404
Ref: How does Logtalk performance compare with plain Prolog and with Prolog modules?-Footnote-1939209
Node: Licensing939254
Ref: faq/licensing doc939361
Ref: 7b8939361
Ref: faq/licensing faq-licensing939361
Ref: 7b9939361
Ref: faq/licensing licensing939361
Ref: 7ba939361
Node: What’s the Logtalk distribution license?939815
Ref: faq/licensing faq-licensing-license939978
Ref: 7bb939978
Ref: faq/licensing what-s-the-logtalk-distribution-license939978
Ref: 7be939978
Ref: What’s the Logtalk distribution license?-Footnote-1940157
Node: Can Logtalk be used in commercial applications?940231
Ref: faq/licensing can-logtalk-be-used-in-commercial-applications940482
Ref: 7bf940482
Ref: faq/licensing faq-licensing-commercial940482
Ref: 7bc940482
Ref: Can Logtalk be used in commercial applications?-Footnote-1940736
Node: What’s the final license for a combination of Logtalk with a Prolog compiler?940794
Ref: faq/licensing faq-licensing-combining940994
Ref: 7bd940994
Ref: faq/licensing what-s-the-final-license-for-a-combination-of-logtalk-with-a-prolog-compiler940994
Ref: 7c0940994
Ref: What’s the final license for a combination of Logtalk with a Prolog compiler?-Footnote-1941267
Node: Support941310
Ref: faq/support doc941394
Ref: 7c1941394
Ref: faq/support faq-support941394
Ref: 7c2941394
Ref: faq/support support941394
Ref: 7c3941394
Node: Are there professional consulting training and supporting services?941664
Ref: faq/support are-there-professional-consulting-training-and-supporting-services941794
Ref: 7c5941794
Ref: faq/support faq-support-professional941794
Ref: 7c4941794
Ref: Are there professional consulting training and supporting services?-Footnote-1942099
Node: Developer Tools942126
Ref: devtools/index doc942229
Ref: 7c6942229
Ref: devtools/index developer-tools942229
Ref: 7c7942229
Node: asdf942590
Ref: devtools/asdf doc942684
Ref: 7c8942684
Ref: devtools/asdf asdf942684
Ref: 7c9942684
Node: assertions943072
Ref: devtools/assertions doc943187
Ref: 7ca943187
Ref: devtools/assertions assertions943187
Ref: 7cb943187
Node: API documentation943961
Ref: devtools/assertions api-documentation944060
Ref: 7cc944060
Ref: API documentation-Footnote-1944257
Node: Loading944320
Ref: devtools/assertions loading944465
Ref: 7cd944465
Node: Adding assertions to your source code944581
Ref: devtools/assertions adding-assertions-to-your-source-code944777
Ref: 7ce944777
Node: Automatically adding file and line context information to assertions945500
Ref: devtools/assertions automatically-adding-file-and-line-context-information-to-assertions945733
Ref: 7cf945733
Node: Suppressing assertion calls from source code946529
Ref: devtools/assertions suppressing-assertion-calls-from-source-code946763
Ref: 7d0946763
Node: Redirecting assertion failure messages947259
Ref: devtools/assertions redirecting-assertion-failure-messages947466
Ref: 7d1947466
Node: Converting assertion failures into errors948072
Ref: devtools/assertions converting-assertion-failures-into-errors948246
Ref: 7d2948246
Node: Other notes949031
Ref: devtools/assertions other-notes949158
Ref: 7d3949158
Node: code_metrics949303
Ref: devtools/code_metrics doc949431
Ref: 7d4949431
Ref: devtools/code_metrics code-metrics949431
Ref: 7d5949431
Node: API documentation<2>949894
Ref: devtools/code_metrics api-documentation950001
Ref: 7d6950001
Ref: API documentation<2>-Footnote-1950281
Node: Loading<2>950346
Ref: devtools/code_metrics loading950479
Ref: 7d7950479
Node: Available metrics950597
Ref: devtools/code_metrics available-metrics950730
Ref: 7d8950730
Node: Defining new metrics954412
Ref: devtools/code_metrics defining-new-metrics954552
Ref: 7d9954552
Node: Third-party tools954859
Ref: devtools/code_metrics third-party-tools954973
Ref: 7da954973
Node: dead_code_scanner955696
Ref: devtools/dead_code_scanner doc955828
Ref: 7db955828
Ref: devtools/dead_code_scanner dead-code-scanner955828
Ref: 7dc955828
Node: API documentation<3>957506
Ref: devtools/dead_code_scanner api-documentation957618
Ref: 7dd957618
Ref: API documentation<3>-Footnote-1957903
Node: Loading<3>957973
Ref: devtools/dead_code_scanner loading958106
Ref: 7de958106
Node: Known issues958229
Ref: devtools/dead_code_scanner known-issues958356
Ref: 7df958356
Node: Other notes<2>958827
Ref: devtools/dead_code_scanner other-notes958935
Ref: 7e0958935
Node: debug_messages959080
Ref: devtools/debug_messages doc959208
Ref: 7e1959208
Ref: devtools/debug_messages debug-messages959208
Ref: 7e2959208
Node: API documentation<4>959695
Ref: devtools/debug_messages api-documentation959804
Ref: 7e3959804
Ref: API documentation<4>-Footnote-1960174
Ref: API documentation<4>-Footnote-2960241
Node: Loading<4>960300
Ref: devtools/debug_messages loading960423
Ref: 7e4960423
Node: Usage960543
Ref: devtools/debug_messages usage960660
Ref: 7e5960660
Node: Other notes<3>961117
Ref: devtools/debug_messages other-notes961215
Ref: 7e6961215
Node: debugger961360
Ref: devtools/debugger doc961479
Ref: 7e7961479
Ref: devtools/debugger debugger961479
Ref: 7e8961479
Node: API documentation<5>961736
Ref: devtools/debugger api-documentation961839
Ref: 7e9961839
Ref: API documentation<5>-Footnote-1962164
Ref: API documentation<5>-Footnote-2962225
Node: Loading<5>962284
Ref: devtools/debugger loading962404
Ref: 7ea962404
Node: Usage<2>962851
Ref: devtools/debugger usage962966
Ref: 7eb962966
Node: Known issues<2>963910
Ref: devtools/debugger known-issues964029
Ref: 7ec964029
Node: Other notes<4>964800
Ref: devtools/debugger other-notes964902
Ref: 7ed964902
Node: diagrams965047
Ref: devtools/diagrams doc965158
Ref: 7ee965158
Ref: devtools/diagrams diagrams965158
Ref: 7ef965158
Node: API documentation<6>967104
Ref: devtools/diagrams api-documentation967207
Ref: 7f0967207
Ref: API documentation<6>-Footnote-1967483
Node: Loading<6>967544
Ref: devtools/diagrams loading967674
Ref: 7f1967674
Node: Supported diagrams967788
Ref: devtools/diagrams supported-diagrams967912
Ref: 7f2967912
Node: Graph elements970257
Ref: devtools/diagrams graph-elements970396
Ref: 7f3970396
Node: Supported graph languages973332
Ref: devtools/diagrams supported-graph-languages973466
Ref: 7f4973466
Node: Customization976381
Ref: devtools/diagrams customization976517
Ref: 7f5976517
Node: Linking diagrams986551
Ref: devtools/diagrams linking-diagrams986710
Ref: 7f6986710
Node: Creating diagrams for Prolog module applications988003
Ref: devtools/diagrams creating-diagrams-for-prolog-module-applications988189
Ref: 7f7988189
Node: Creating diagrams for plain Prolog files988821
Ref: devtools/diagrams creating-diagrams-for-plain-prolog-files989005
Ref: 7f8989005
Node: Other notes<5>989563
Ref: devtools/diagrams other-notes989690
Ref: 7f9989690
Node: doclet990642
Ref: devtools/doclet doc990749
Ref: 7fa990749
Ref: devtools/doclet doclet990749
Ref: 7fb990749
Node: API documentation<7>991890
Ref: devtools/doclet api-documentation991991
Ref: 7fc991991
Ref: API documentation<7>-Footnote-1992265
Node: Loading<7>992324
Ref: devtools/doclet loading992460
Ref: 7fd992460
Node: Automating running doclets992572
Ref: devtools/doclet automating-running-doclets992718
Ref: 7fe992718
Node: Integration with the make tool993062
Ref: devtools/doclet integration-with-the-make-tool993212
Ref: 7ff993212
Node: Other notes<6>993537
Ref: devtools/doclet other-notes993652
Ref: 800993652
Node: help993797
Ref: devtools/help doc993902
Ref: 801993902
Ref: devtools/help help993902
Ref: 802993902
Node: API documentation<8>994204
Ref: devtools/help api-documentation994303
Ref: 803994303
Ref: API documentation<8>-Footnote-1994575
Node: Loading<8>994632
Ref: devtools/help loading994767
Ref: 804994767
Node: Supported operating-systems994835
Ref: devtools/help supported-operating-systems994965
Ref: 805994965
Node: Known issues<3>995330
Ref: devtools/help known-issues995464
Ref: 806995464
Node: Other notes<7>995859
Ref: devtools/help other-notes995957
Ref: 807995957
Node: lgtdoc996102
Ref: devtools/lgtdoc doc996208
Ref: 808996208
Ref: devtools/lgtdoc lgtdoc996208
Ref: 809996208
Ref: lgtdoc-Footnote-1997371
Node: API documentation<9>997432
Ref: devtools/lgtdoc api-documentation997533
Ref: 80a997533
Ref: API documentation<9>-Footnote-1997728
Node: Loading<9>997787
Ref: devtools/lgtdoc loading997920
Ref: 80b997920
Node: Documenting source code998034
Ref: devtools/lgtdoc documenting-source-code998171
Ref: 80c998171
Node: Generating documentation998936
Ref: devtools/lgtdoc generating-documentation999077
Ref: 80d999077
Node: Other notes<8>999936
Ref: devtools/lgtdoc other-notes1000045
Ref: 80e1000045
Node: lgtunit1000192
Ref: devtools/lgtunit doc1000298
Ref: 80f1000298
Ref: devtools/lgtunit lgtunit1000298
Ref: 8101000298
Node: Main files1002007
Ref: devtools/lgtunit main-files1002110
Ref: 8111002110
Node: API documentation<10>1002660
Ref: devtools/lgtunit api-documentation1002783
Ref: 8121002783
Ref: API documentation<10>-Footnote-11002979
Node: Loading<10>1003039
Ref: devtools/lgtunit loading1003192
Ref: 8131003192
Node: Writing compiling and loading unit tests1003307
Ref: devtools/lgtunit id11003457
Ref: 8141003457
Ref: devtools/lgtunit writing-compiling-and-loading-unit-tests1003457
Ref: 8151003457
Node: Running unit tests1004751
Ref: devtools/lgtunit running-unit-tests1004908
Ref: 8161004908
Node: Unit test dialects1006847
Ref: devtools/lgtunit unit-test-dialects1006995
Ref: 8171006995
Node: User-defined unit test dialects1012333
Ref: devtools/lgtunit user-defined-unit-test-dialects1012473
Ref: 8181012473
Node: QuickCheck1014487
Ref: devtools/lgtunit quickcheck1014628
Ref: 8191014628
Node: Skipping unit tests1019133
Ref: devtools/lgtunit skipping-unit-tests1019279
Ref: 81a1019279
Node: Testing non-deterministic predicates1020237
Ref: devtools/lgtunit testing-non-deterministic-predicates1020391
Ref: 81b1020391
Node: Testing generators1020983
Ref: devtools/lgtunit testing-generators1021149
Ref: 81c1021149
Node: Testing input/output predicates1021644
Ref: devtools/lgtunit id21021810
Ref: 81d1021810
Ref: devtools/lgtunit testing-input-output-predicates1021810
Ref: 81e1021810
Node: Suppressing tested predicates output1022572
Ref: devtools/lgtunit suppressing-tested-predicates-output1022750
Ref: 81f1022750
Node: Unit tests with timeout limits1023170
Ref: devtools/lgtunit unit-tests-with-timeout-limits1023340
Ref: 8201023340
Node: Setup and cleanup goals1024071
Ref: devtools/lgtunit setup-and-cleanup-goals1024221
Ref: 8211024221
Node: Test annotations1024924
Ref: devtools/lgtunit test-annotations1025071
Ref: 8221025071
Node: Debugging failed unit tests1026058
Ref: devtools/lgtunit debugging-failed-unit-tests1026195
Ref: 8231026195
Node: Code coverage1027801
Ref: devtools/lgtunit code-coverage1027951
Ref: 8241027951
Node: Automating running unit tests1029583
Ref: devtools/lgtunit automating-running-unit-tests1029724
Ref: 8251029724
Node: Utility predicates1030391
Ref: devtools/lgtunit utility-predicates1030566
Ref: 8261030566
Node: Exporting unit test results in xUnit XML format1033639
Ref: devtools/lgtunit exporting-unit-test-results-in-xunit-xml-format1033837
Ref: 8271033837
Node: Exporting unit test results in the TAP output format1034621
Ref: devtools/lgtunit exporting-unit-test-results-in-the-tap-output-format1034846
Ref: 8281034846
Node: Exporting code coverage results in XML format1035881
Ref: devtools/lgtunit exporting-code-coverage-results-in-xml-format1036074
Ref: 8291036074
Node: Known issues<4>1038200
Ref: devtools/lgtunit known-issues1038355
Ref: 82a1038355
Node: Other notes<9>1039134
Ref: devtools/lgtunit other-notes1039235
Ref: 82b1039235
Node: make1039384
Ref: devtools/make doc1039498
Ref: 82c1039498
Ref: devtools/make make1039498
Ref: 82d1039498
Node: API documentation<11>1039692
Ref: devtools/make api-documentation1039773
Ref: 82e1039773
Ref: API documentation<11>-Footnote-11040120
Ref: API documentation<11>-Footnote-21040183
Ref: API documentation<11>-Footnote-31040246
Node: ports_profiler1040324
Ref: devtools/ports_profiler doc1040439
Ref: 82f1040439
Ref: devtools/ports_profiler ports-profiler1040439
Ref: 8301040439
Node: API documentation<12>1041581
Ref: devtools/ports_profiler api-documentation1041692
Ref: 8311041692
Ref: API documentation<12>-Footnote-11041976
Node: Loading<11>1042043
Ref: devtools/ports_profiler loading1042204
Ref: 8321042204
Node: Compiling source files for port profiling1042453
Ref: devtools/ports_profiler compiling-source-files-for-port-profiling1042618
Ref: 8331042618
Node: Generating profiling data1043361
Ref: devtools/ports_profiler generating-profiling-data1043546
Ref: 8341043546
Node: Printing profiling data reports1043747
Ref: devtools/ports_profiler printing-profiling-data-reports1043918
Ref: 8351043918
Node: Interpreting profiling data1044431
Ref: devtools/ports_profiler interpreting-profiling-data1044592
Ref: 8361044592
Node: Known issues<5>1045351
Ref: devtools/ports_profiler known-issues1045496
Ref: 8371045496
Node: Other notes<10>1045652
Ref: devtools/ports_profiler other-notes1045761
Ref: 8381045761
Node: profiler1045908
Ref: devtools/profiler doc1046026
Ref: 8391046026
Ref: devtools/profiler profiler1046026
Ref: 83a1046026
Node: Loading<12>1046280
Ref: devtools/profiler loading1046398
Ref: 83b1046398
Node: Supported backend Prolog compilers1046595
Ref: devtools/profiler supported-backend-prolog-compilers1046757
Ref: 83c1046757
Node: Compiling source code for profiling1048271
Ref: devtools/profiler compiling-source-code-for-profiling1048437
Ref: 83d1048437
Node: Other notes<11>1048895
Ref: devtools/profiler other-notes1049018
Ref: 83e1049018
Node: wrapper1049165
Ref: devtools/wrapper doc1049260
Ref: 83f1049260
Ref: devtools/wrapper wrapper1049260
Ref: 8401049260
Node: API documentation<13>1050399
Ref: devtools/wrapper api-documentation1050503
Ref: 8411050503
Ref: API documentation<13>-Footnote-11050699
Node: Loading<13>1050759
Ref: devtools/wrapper loading1050881
Ref: 8421050881
Node: Workflows1050996
Ref: devtools/wrapper workflows1051113
Ref: 8431051113
Node: Customization<2>1051381
Ref: devtools/wrapper customization1051506
Ref: 8441051506
Node: Current limitations1052875
Ref: devtools/wrapper current-limitations1053006
Ref: 8451053006
Node: Other notes<12>1054018
Ref: devtools/wrapper other-notes1054124
Ref: 8461054124
Node: Glossary1054271
Ref: glossary doc1054379
Ref: 8471054379
Ref: glossary glossary1054379
Ref: 8481054379
Ref: glossary term-abstract-class1054402
Ref: 8491054402
Ref: glossary term-abstract-method1054556
Ref: 84b1054556
Ref: glossary term-adapter-file1054761
Ref: 11d1054761
Ref: glossary term-ancestor1054936
Ref: 84e1054936
Ref: glossary term-backend-prolog-compiler1055335
Ref: 321055335
Ref: glossary term-built-in-method1055558
Ref: 8501055558
Ref: glossary term-built-in-predicate1055728
Ref: 8511055728
Ref: glossary term-category1055901
Ref: 84d1055901
Ref: glossary term-class1056237
Ref: 84a1056237
Ref: glossary term-closed-world-assumption1056506
Ref: 4c1056506
Ref: glossary term-coinductive-predicate1056837
Ref: 2f91056837
Ref: glossary term-complementing-category1057061
Ref: 8531057061
Ref: glossary term-component1057182
Ref: 2cc1057182
Ref: glossary term-directive1057495
Ref: 8541057495
Ref: glossary term-doclet-file1057644
Ref: 8551057644
Ref: glossary term-doclet-object1057792
Ref: 8561057792
Ref: glossary term-dynamic-binding1057969
Ref: 341057969
Ref: glossary term-early-binding1058347
Ref: 8591058347
Ref: glossary term-encapsulation1058398
Ref: 85a1058398
Ref: glossary term-entity1058655
Ref: 85b1058655
Ref: glossary term-entity-directive1058886
Ref: 85d1058886
Ref: glossary term-event1059057
Ref: 85e1059057
Ref: glossary term-grammar-rule1059367
Ref: 85f1059367
Ref: glossary term-grammar-rule-non-terminal1059790
Ref: 8601059790
Ref: glossary term-grammar-rule-terminal1060018
Ref: 8611060018
Ref: glossary term-hook-object1060085
Ref: 3151060085
Ref: glossary term-hot-patching1060478
Ref: e11060478
Ref: glossary term-identity1060739
Ref: 85c1060739
Ref: glossary term-inheritance1061141
Ref: 8621061141
Ref: glossary term-instance1061579
Ref: 8661061579
Ref: glossary term-instantiation1061774
Ref: 8671061774
Ref: glossary term-interface1062012
Ref: 8681062012
Ref: glossary term-lambda-expression1062053
Ref: 1451062053
Ref: glossary term-lambda-free-variable1062394
Ref: 21e1062394
Ref: glossary term-lambda-parameter1062570
Ref: 21f1062570
Ref: glossary term-late-binding1062788
Ref: 8691062788
Ref: glossary term-library1062839
Ref: 511062839
Ref: glossary term-library-alias1062964
Ref: 5aa1062964
Ref: glossary term-library-notation1063229
Ref: ad1063229
Ref: glossary term-loader-file1063590
Ref: 18e1063590
Ref: glossary term-local-predicate1063693
Ref: 86a1063693
Ref: glossary term-message1064089
Ref: 8521064089
Ref: glossary term-message-lookup1064282
Ref: 351064282
Ref: glossary term-message-to-self1064660
Ref: 1401064660
Ref: glossary term-meta-argument1064874
Ref: 86b1064874
Ref: glossary term-meta-interpreter1065097
Ref: 86c1065097
Ref: glossary term-meta-predicate1065200
Ref: 86d1065200
Ref: glossary term-metaclass1065379
Ref: 501065379
Ref: glossary term-method1065614
Ref: 84c1065614
Ref: glossary term-module1065865
Ref: 86e1065865
Ref: glossary term-monitor1066143
Ref: 86f1066143
Ref: glossary term-multifile-predicate1066381
Ref: 8701066381
Ref: glossary term-object1066797
Ref: 4921066797
Ref: glossary term-object-database1067141
Ref: 1641067141
Ref: glossary term-parameter1067220
Ref: 8711067220
Ref: glossary term-parameter-variable1067410
Ref: 7c1067410
Ref: glossary term-parametric-category1067686
Ref: 8721067686
Ref: glossary term-parametric-entity1067747
Ref: 5d11067747
Ref: glossary term-parametric-object1068308
Ref: 38f1068308
Ref: glossary term-parametric-object-proxy1068367
Ref: 36d1068367
Ref: glossary term-parent1068554
Ref: 8731068554
Ref: glossary term-polymorphism1068619
Ref: 8741068619
Ref: glossary term-predicate1069425
Ref: 431069425
Ref: glossary term-predicate-alias1069784
Ref: a41069784
Ref: glossary term-predicate-declaration1070253
Ref: 8571070253
Ref: glossary term-predicate-definition1070420
Ref: 8581070420
Ref: glossary term-predicate-directive1070609
Ref: 8751070609
Ref: glossary term-predicate-scope-container1070741
Ref: 36c1070741
Ref: glossary term-predicate-scope-directive1070921
Ref: 1951070921
Ref: glossary term-primary-predicate-declaration1071066
Ref: 1351071066
Ref: glossary term-private-inheritance1071139
Ref: 8651071139
Ref: glossary term-private-predicate1071328
Ref: 1ab1071328
Ref: glossary term-profiler1071456
Ref: 8761071456
Ref: glossary term-protected-inheritance1071534
Ref: 8641071534
Ref: glossary term-protected-predicate1071754
Ref: 1aa1071754
Ref: glossary term-protocol1071933
Ref: 411071933
Ref: glossary term-prototype1072435
Ref: 84f1072435
Ref: glossary term-public-inheritance1072654
Ref: 8631072654
Ref: glossary term-public-predicate1072826
Ref: 1a91072826
Ref: glossary term-scratch-directory1072898
Ref: 5a31072898
Ref: glossary term-self1073051
Ref: 4b1073051
Ref: glossary term-sender1073130
Ref: 36b1073130
Ref: glossary term-settings-file1073324
Ref: 2b81073324
Ref: glossary term-singleton-method1073566
Ref: 8771073566
Ref: glossary term-source-file1073777
Ref: 5771073777
Ref: glossary term-source-file-directive1074191
Ref: 8781074191
Ref: glossary term-specialization1074289
Ref: 8791074289
Ref: glossary term-static-binding1074429
Ref: 331074429
Ref: glossary term-steadfastness1074892
Ref: 26b1074892
Ref: glossary term-subclass1075175
Ref: 451075175
Ref: glossary term-super-call1075282
Ref: e91075282
Ref: glossary term-superclass1075627
Ref: 421075627
Ref: glossary term-synchronized-predicate1075805
Ref: 87a1075805
Ref: glossary term-template-method1075994
Ref: 87b1075994
Ref: glossary term-tester-file1076049
Ref: 87c1076049
Ref: glossary term-this1076160
Ref: 1411076160
Ref: glossary term-threaded-engine1076424
Ref: 2f71076424
Ref: glossary term-visible-predicate1076741
Ref: 87d1076741
Ref: bibliography alexiev931076933
Ref: 87e1076933
Ref: bibliography belli-et-al-921077117
Ref: 87f1077117
Ref: bibliography block891077394
Ref: 8801077394
Ref: bibliography bobrow-et-al-881077498
Ref: 1af1077498
Ref: bibliography bratko901077668
Ref: 8811077668
Ref: bibliography champaux921077772
Ref: 23b1077772
Ref: bibliography clocksin871077925
Ref: 8821077925
Ref: bibliography cointe871078023
Ref: 771078023
Ref: bibliography cordes911078134
Ref: 8831078134
Ref: bibliography covington941078233
Ref: 8841078233
Ref: bibliography cox861078367
Ref: 1b1078367
Ref: bibliography davison891078497
Ref: 8851078497
Ref: bibliography davison921078608
Ref: 8861078608
Ref: bibliography davison931078831
Ref: 8871078831
Ref: bibliography delzanno971079043
Ref: 8881079043
Ref: bibliography dony901079210
Ref: 8891079210
Ref: bibliography fornarino-et-al-891079337
Ref: 101079337
Ref: bibliography fromherz931079602
Ref: 271079602
Ref: bibliography fukunaga861079707
Ref: 88a1079707
Ref: bibliography goldberg831079849
Ref: 1a1079849
Ref: bibliography joy-et-al-001079979
Ref: 1c1079979
Ref: bibliography iso951080109
Ref: 2f1080109
Ref: bibliography knuth841080280
Ref: 88b1080280
Ref: bibliography lieberman861080364
Ref: 171080364
Ref: bibliography maes871080513
Ref: 121080513
Ref: bibliography mccabe921080613
Ref: 261080613
Ref: bibliography moon861080698
Ref: e01080698
Ref: bibliography moss941080788
Ref: 1ae1080788
Ref: bibliography moura941080930
Ref: 781080930
Ref: bibliography moura991081121
Ref: 88c1081121
Ref: bibliography moura001081296
Ref: 88d1081296
Ref: bibliography razek921081410
Ref: 111081410
Ref: bibliography rumbaugh871081502
Ref: e1081502
Ref: bibliography rumbaugh881081629
Ref: f1081629
Ref: bibliography schachte951081760
Ref: 88e1081760
Ref: bibliography sicstus951082018
Ref: 281082018
Ref: bibliography shan-et-al-931082107
Ref: 1b11082107
Ref: bibliography stefik-et-al-861082270
Ref: 1b41082270
Ref: bibliography stroustrup861082438
Ref: 211082438
Ref: bibliography taenzer891082540
Ref: 1b01082540
Ref: bibliography tanzer951082723
Ref: 88f1082723
Ref: bibliography tanenbaum871082871
Ref: 1b51082871
Ref: bibliography welsch891082982
Ref: 8901082982
Ref: Glossary-Footnote-11083248
Ref: Glossary-Footnote-21083333
Ref: Glossary-Footnote-31083418
Ref: Glossary-Footnote-41083483
Node: Index<2>1083550
Ref: genindex doc1083648
Ref: 8911083648
Ref: genindex index1083648
Ref: 8921083648
Node: Index1083665

End Tag Table


Local Variables:
coding: utf-8
End:
